diff options
Diffstat (limited to 'Documentation')
858 files changed, 33249 insertions, 13953 deletions
diff --git a/Documentation/ABI/obsolete/procfs-i8k b/Documentation/ABI/obsolete/procfs-i8k new file mode 100644 index 000000000000..32df4d5bdd15 --- /dev/null +++ b/Documentation/ABI/obsolete/procfs-i8k @@ -0,0 +1,10 @@ +What: /proc/i8k +Date: November 2001 +KernelVersion: 2.4.14 +Contact: Pali Rohár <pali@kernel.org> +Description: Legacy interface for getting/setting sensor information like + fan speed, temperature, serial number, hotkey status etc + on Dell Laptops. + Since the driver is now using the standard hwmon sysfs interface, + the procfs interface is deprecated. +Users: https://github.com/vitorafsr/i8kutils diff --git a/Documentation/ABI/obsolete/sysfs-class-dax b/Documentation/ABI/obsolete/sysfs-class-dax deleted file mode 100644 index 5bcce27458e3..000000000000 --- a/Documentation/ABI/obsolete/sysfs-class-dax +++ /dev/null @@ -1,22 +0,0 @@ -What: /sys/class/dax/ -Date: May, 2016 -KernelVersion: v4.7 -Contact: nvdimm@lists.linux.dev -Description: Device DAX is the device-centric analogue of Filesystem - DAX (CONFIG_FS_DAX). It allows memory ranges to be - allocated and mapped without need of an intervening file - system. Device DAX is strict, precise and predictable. - Specifically this interface: - - 1. Guarantees fault granularity with respect to a given - page size (pte, pmd, or pud) set at configuration time. - - 2. Enforces deterministic behavior by being strict about - what fault scenarios are supported. - - The /sys/class/dax/ interface enumerates all the - device-dax instances in the system. The ABI is - deprecated and will be removed after 2020. It is - replaced with the DAX bus interface /sys/bus/dax/ where - device-dax instances can be found under - /sys/bus/dax/devices/ diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block new file mode 100644 index 000000000000..e8797cd09aff --- /dev/null +++ b/Documentation/ABI/stable/sysfs-block @@ -0,0 +1,725 @@ +What: /sys/block/<disk>/alignment_offset +Date: April 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Storage devices may report a physical block size that is + bigger than the logical block size (for instance a drive + with 4KB physical sectors exposing 512-byte logical + blocks to the operating system). This parameter + indicates how many bytes the beginning of the device is + offset from the disk's natural alignment. + + +What: /sys/block/<disk>/discard_alignment +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may + internally allocate space in units that are bigger than + the exported logical block size. The discard_alignment + parameter indicates how many bytes the beginning of the + device is offset from the internal allocation unit's + natural alignment. + + +What: /sys/block/<disk>/diskseq +Date: February 2021 +Contact: Matteo Croce <mcroce@microsoft.com> +Description: + The /sys/block/<disk>/diskseq files reports the disk + sequence number, which is a monotonically increasing + number assigned to every drive. + Some devices, like the loop device, refresh such number + every time the backing file is changed. + The value type is 64 bit unsigned. + + +What: /sys/block/<disk>/inflight +Date: October 2009 +Contact: Jens Axboe <axboe@kernel.dk>, Nikanth Karthikesan <knikanth@suse.de> +Description: + Reports the number of I/O requests currently in progress + (pending / in flight) in a device driver. This can be less + than the number of requests queued in the block device queue. + The report contains 2 fields: one for read requests + and one for write requests. + The value type is unsigned int. + Cf. Documentation/block/stat.rst which contains a single value for + requests in flight. + This is related to /sys/block/<disk>/queue/nr_requests + and for SCSI device also its queue_depth. + + +What: /sys/block/<disk>/integrity/device_is_integrity_capable +Date: July 2014 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Indicates whether a storage device is capable of storing + integrity metadata. Set if the device is T10 PI-capable. + + +What: /sys/block/<disk>/integrity/format +Date: June 2008 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Metadata format for integrity capable block device. + E.g. T10-DIF-TYPE1-CRC. + + +What: /sys/block/<disk>/integrity/protection_interval_bytes +Date: July 2015 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Describes the number of data bytes which are protected + by one integrity tuple. Typically the device's logical + block size. + + +What: /sys/block/<disk>/integrity/read_verify +Date: June 2008 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Indicates whether the block layer should verify the + integrity of read requests serviced by devices that + support sending integrity metadata. + + +What: /sys/block/<disk>/integrity/tag_size +Date: June 2008 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Number of bytes of integrity tag space available per + 512 bytes of data. + + +What: /sys/block/<disk>/integrity/write_generate +Date: June 2008 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Indicates whether the block layer should automatically + generate checksums for write requests bound for + devices that support receiving integrity metadata. + + +What: /sys/block/<disk>/<partition>/alignment_offset +Date: April 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Storage devices may report a physical block size that is + bigger than the logical block size (for instance a drive + with 4KB physical sectors exposing 512-byte logical + blocks to the operating system). This parameter + indicates how many bytes the beginning of the partition + is offset from the disk's natural alignment. + + +What: /sys/block/<disk>/<partition>/discard_alignment +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may + internally allocate space in units that are bigger than + the exported logical block size. The discard_alignment + parameter indicates how many bytes the beginning of the + partition is offset from the internal allocation unit's + natural alignment. + + +What: /sys/block/<disk>/<partition>/stat +Date: February 2008 +Contact: Jerome Marchand <jmarchan@redhat.com> +Description: + The /sys/block/<disk>/<partition>/stat files display the + I/O statistics of partition <partition>. The format is the + same as the format of /sys/block/<disk>/stat. + + +What: /sys/block/<disk>/queue/add_random +Date: June 2010 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file allows to turn off the disk entropy contribution. + Default value of this file is '1'(on). + + +What: /sys/block/<disk>/queue/chunk_sectors +Date: September 2016 +Contact: Hannes Reinecke <hare@suse.com> +Description: + [RO] chunk_sectors has different meaning depending on the type + of the disk. For a RAID device (dm-raid), chunk_sectors + indicates the size in 512B sectors of the RAID volume stripe + segment. For a zoned block device, either host-aware or + host-managed, chunk_sectors indicates the size in 512B sectors + of the zones of the device, with the eventual exception of the + last zone of the device which may be smaller. + + +What: /sys/block/<disk>/queue/crypto/ +Date: February 2022 +Contact: linux-block@vger.kernel.org +Description: + The presence of this subdirectory of /sys/block/<disk>/queue/ + indicates that the device supports inline encryption. This + subdirectory contains files which describe the inline encryption + capabilities of the device. For more information about inline + encryption, refer to Documentation/block/inline-encryption.rst. + + +What: /sys/block/<disk>/queue/crypto/max_dun_bits +Date: February 2022 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file shows the maximum length, in bits, of data unit + numbers accepted by the device in inline encryption requests. + + +What: /sys/block/<disk>/queue/crypto/modes/<mode> +Date: February 2022 +Contact: linux-block@vger.kernel.org +Description: + [RO] For each crypto mode (i.e., encryption/decryption + algorithm) the device supports with inline encryption, a file + will exist at this location. It will contain a hexadecimal + number that is a bitmask of the supported data unit sizes, in + bytes, for that crypto mode. + + Currently, the crypto modes that may be supported are: + + * AES-256-XTS + * AES-128-CBC-ESSIV + * Adiantum + + For example, if a device supports AES-256-XTS inline encryption + with data unit sizes of 512 and 4096 bytes, the file + /sys/block/<disk>/queue/crypto/modes/AES-256-XTS will exist and + will contain "0x1200". + + +What: /sys/block/<disk>/queue/crypto/num_keyslots +Date: February 2022 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file shows the number of keyslots the device has for + use with inline encryption. + + +What: /sys/block/<disk>/queue/dax +Date: June 2016 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file indicates whether the device supports Direct + Access (DAX), used by CPU-addressable storage to bypass the + pagecache. It shows '1' if true, '0' if not. + + +What: /sys/block/<disk>/queue/discard_granularity +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] Devices that support discard functionality may internally + allocate space using units that are bigger than the logical + block size. The discard_granularity parameter indicates the size + of the internal allocation unit in bytes if reported by the + device. Otherwise the discard_granularity will be set to match + the device's physical block size. A discard_granularity of 0 + means that the device does not support discard functionality. + + +What: /sys/block/<disk>/queue/discard_max_bytes +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RW] While discard_max_hw_bytes is the hardware limit for the + device, this setting is the software limit. Some devices exhibit + large latencies when large discards are issued, setting this + value lower will make Linux issue smaller discards and + potentially help reduce latencies induced by large discard + operations. + + +What: /sys/block/<disk>/queue/discard_max_hw_bytes +Date: July 2015 +Contact: linux-block@vger.kernel.org +Description: + [RO] Devices that support discard functionality may have + internal limits on the number of bytes that can be trimmed or + unmapped in a single operation. The `discard_max_hw_bytes` + parameter is set by the device driver to the maximum number of + bytes that can be discarded in a single operation. Discard + requests issued to the device must not exceed this limit. A + `discard_max_hw_bytes` value of 0 means that the device does not + support discard functionality. + + +What: /sys/block/<disk>/queue/discard_zeroes_data +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] Will always return 0. Don't rely on any specific behavior + for discards, and don't read this file. + + +What: /sys/block/<disk>/queue/fua +Date: May 2018 +Contact: linux-block@vger.kernel.org +Description: + [RO] Whether or not the block driver supports the FUA flag for + write requests. FUA stands for Force Unit Access. If the FUA + flag is set that means that write requests must bypass the + volatile cache of the storage device. + + +What: /sys/block/<disk>/queue/hw_sector_size +Date: January 2008 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the hardware sector size of the device, in bytes. + + +What: /sys/block/<disk>/queue/independent_access_ranges/ +Date: October 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] The presence of this sub-directory of the + /sys/block/xxx/queue/ directory indicates that the device is + capable of executing requests targeting different sector ranges + in parallel. For instance, single LUN multi-actuator hard-disks + will have an independent_access_ranges directory if the device + correctly advertizes the sector ranges of its actuators. + + The independent_access_ranges directory contains one directory + per access range, with each range described using the sector + (RO) attribute file to indicate the first sector of the range + and the nr_sectors (RO) attribute file to indicate the total + number of sectors in the range starting from the first sector of + the range. For example, a dual-actuator hard-disk will have the + following independent_access_ranges entries.:: + + $ tree /sys/block/<disk>/queue/independent_access_ranges/ + /sys/block/<disk>/queue/independent_access_ranges/ + |-- 0 + | |-- nr_sectors + | `-- sector + `-- 1 + |-- nr_sectors + `-- sector + + The sector and nr_sectors attributes use 512B sector unit, + regardless of the actual block size of the device. Independent + access ranges do not overlap and include all sectors within the + device capacity. The access ranges are numbered in increasing + order of the range start sector, that is, the sector attribute + of range 0 always has the value 0. + + +What: /sys/block/<disk>/queue/io_poll +Date: November 2015 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file shows whether polling is enabled (1) + or disabled (0). Writing '0' to this file will disable polling + for this device. Writing any non-zero value will enable this + feature. + + +What: /sys/block/<disk>/queue/io_poll_delay +Date: November 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] If polling is enabled, this controls what kind of polling + will be performed. It defaults to -1, which is classic polling. + In this mode, the CPU will repeatedly ask for completions + without giving up any time. If set to 0, a hybrid polling mode + is used, where the kernel will attempt to make an educated guess + at when the IO will complete. Based on this guess, the kernel + will put the process issuing IO to sleep for an amount of time, + before entering a classic poll loop. This mode might be a little + slower than pure classic polling, but it will be more efficient. + If set to a value larger than 0, the kernel will put the process + issuing IO to sleep for this amount of microseconds before + entering classic polling. + + +What: /sys/block/<disk>/queue/io_timeout +Date: November 2018 +Contact: Weiping Zhang <zhangweiping@didiglobal.com> +Description: + [RW] io_timeout is the request timeout in milliseconds. If a + request does not complete in this time then the block driver + timeout handler is invoked. That timeout handler can decide to + retry the request, to fail it or to start a device recovery + strategy. + + +What: /sys/block/<disk>/queue/iostats +Date: January 2009 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file is used to control (on/off) the iostats + accounting of the disk. + + +What: /sys/block/<disk>/queue/logical_block_size +Date: May 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] This is the smallest unit the storage device can address. + It is typically 512 bytes. + + +What: /sys/block/<disk>/queue/max_active_zones +Date: July 2020 +Contact: Niklas Cassel <niklas.cassel@wdc.com> +Description: + [RO] For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, + is limited by this value. If this value is 0, there is no limit. + + If the host attempts to exceed this limit, the driver should + report this error with BLK_STS_ZONE_ACTIVE_RESOURCE, which user + space may see as the EOVERFLOW errno. + + +What: /sys/block/<disk>/queue/max_discard_segments +Date: February 2017 +Contact: linux-block@vger.kernel.org +Description: + [RO] The maximum number of DMA scatter/gather entries in a + discard request. + + +What: /sys/block/<disk>/queue/max_hw_sectors_kb +Date: September 2004 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the maximum number of kilobytes supported in a + single data transfer. + + +What: /sys/block/<disk>/queue/max_integrity_segments +Date: September 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum number of elements in a DMA scatter/gather list + with integrity data that will be submitted by the block layer + core to the associated block driver. + + +What: /sys/block/<disk>/queue/max_open_zones +Date: July 2020 +Contact: Niklas Cassel <niklas.cassel@wdc.com> +Description: + [RO] For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, is + limited by this value. If this value is 0, there is no limit. + + +What: /sys/block/<disk>/queue/max_sectors_kb +Date: September 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] This is the maximum number of kilobytes that the block + layer will allow for a filesystem request. Must be smaller than + or equal to the maximum size allowed by the hardware. + + +What: /sys/block/<disk>/queue/max_segment_size +Date: March 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum size in bytes of a single element in a DMA + scatter/gather list. + + +What: /sys/block/<disk>/queue/max_segments +Date: March 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum number of elements in a DMA scatter/gather list + that is submitted to the associated block driver. + + +What: /sys/block/<disk>/queue/minimum_io_size +Date: April 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] Storage devices may report a granularity or preferred + minimum I/O size which is the smallest request the device can + perform without incurring a performance penalty. For disk + drives this is often the physical block size. For RAID arrays + it is often the stripe chunk size. A properly aligned multiple + of minimum_io_size is the preferred request size for workloads + where a high number of I/O operations is desired. + + +What: /sys/block/<disk>/queue/nomerges +Date: January 2010 +Contact: linux-block@vger.kernel.org +Description: + [RW] Standard I/O elevator operations include attempts to merge + contiguous I/Os. For known random I/O loads these attempts will + always fail and result in extra cycles being spent in the + kernel. This allows one to turn off this behavior on one of two + ways: When set to 1, complex merge checks are disabled, but the + simple one-shot merges with the previous I/O request are + enabled. When set to 2, all merge tries are disabled. The + default value is 0 - which enables all types of merge tries. + + +What: /sys/block/<disk>/queue/nr_requests +Date: July 2003 +Contact: linux-block@vger.kernel.org +Description: + [RW] This controls how many requests may be allocated in the + block layer for read or write requests. Note that the total + allocated number may be twice this amount, since it applies only + to reads or writes (not the accumulated sum). + + To avoid priority inversion through request starvation, a + request queue maintains a separate request pool per each cgroup + when CONFIG_BLK_CGROUP is enabled, and this parameter applies to + each such per-block-cgroup request pool. IOW, if there are N + block cgroups, each request queue may have up to N request + pools, each independently regulated by nr_requests. + + +What: /sys/block/<disk>/queue/nr_zones +Date: November 2018 +Contact: Damien Le Moal <damien.lemoal@wdc.com> +Description: + [RO] nr_zones indicates the total number of zones of a zoned + block device ("host-aware" or "host-managed" zone model). For + regular block devices, the value is always 0. + + +What: /sys/block/<disk>/queue/optimal_io_size +Date: April 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] Storage devices may report an optimal I/O size, which is + the device's preferred unit for sustained I/O. This is rarely + reported for disk drives. For RAID arrays it is usually the + stripe width or the internal track size. A properly aligned + multiple of optimal_io_size is the preferred request size for + workloads where sustained throughput is desired. If no optimal + I/O size is reported this file contains 0. + + +What: /sys/block/<disk>/queue/physical_block_size +Date: May 2009 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] This is the smallest unit a physical storage device can + write atomically. It is usually the same as the logical block + size but may be bigger. One example is SATA drives with 4KB + sectors that expose a 512-byte logical block size to the + operating system. For stacked block devices the + physical_block_size variable contains the maximum + physical_block_size of the component devices. + + +What: /sys/block/<disk>/queue/read_ahead_kb +Date: May 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] Maximum number of kilobytes to read-ahead for filesystems + on this block device. + + +What: /sys/block/<disk>/queue/rotational +Date: January 2009 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file is used to stat if the device is of rotational + type or non-rotational type. + + +What: /sys/block/<disk>/queue/rq_affinity +Date: September 2008 +Contact: linux-block@vger.kernel.org +Description: + [RW] If this option is '1', the block layer will migrate request + completions to the cpu "group" that originally submitted the + request. For some workloads this provides a significant + reduction in CPU cycles due to caching effects. + + For storage configurations that need to maximize distribution of + completion processing setting this option to '2' forces the + completion to run on the requesting cpu (bypassing the "group" + aggregation logic). + + +What: /sys/block/<disk>/queue/scheduler +Date: October 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file will display the current and available + IO schedulers for this block device. The currently active IO + scheduler will be enclosed in [] brackets. Writing an IO + scheduler name to this file will switch control of this block + device to that new IO scheduler. Note that writing an IO + scheduler name to this file will attempt to load that IO + scheduler module, if it isn't already present in the system. + + +What: /sys/block/<disk>/queue/stable_writes +Date: September 2020 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file will contain '1' if memory must not be modified + while it is being used in a write request to this device. When + this is the case and the kernel is performing writeback of a + page, the kernel will wait for writeback to complete before + allowing the page to be modified again, rather than allowing + immediate modification as is normally the case. This + restriction arises when the device accesses the memory multiple + times where the same data must be seen every time -- for + example, once to calculate a checksum and once to actually write + the data. If no such restriction exists, this file will contain + '0'. This file is writable for testing purposes. + + +What: /sys/block/<disk>/queue/throttle_sample_time +Date: March 2017 +Contact: linux-block@vger.kernel.org +Description: + [RW] This is the time window that blk-throttle samples data, in + millisecond. blk-throttle makes decision based on the + samplings. Lower time means cgroups have more smooth throughput, + but higher CPU overhead. This exists only when + CONFIG_BLK_DEV_THROTTLING_LOW is enabled. + + +What: /sys/block/<disk>/queue/virt_boundary_mask +Date: April 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file shows the I/O segment memory alignment mask for + the block device. I/O requests to this device will be split + between segments wherever either the memory address of the end + of the previous segment or the memory address of the beginning + of the current segment is not aligned to virt_boundary_mask + 1 + bytes. + + +What: /sys/block/<disk>/queue/wbt_lat_usec +Date: November 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] If the device is registered for writeback throttling, then + this file shows the target minimum read latency. If this latency + is exceeded in a given window of time (see wb_window_usec), then + the writeback throttling will start scaling back writes. Writing + a value of '0' to this file disables the feature. Writing a + value of '-1' to this file resets the value to the default + setting. + + +What: /sys/block/<disk>/queue/write_cache +Date: April 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file will display whether the device has + write back caching enabled or not. It will return "write back" + for the former case, and "write through" for the latter. Writing + to this file can change the kernels view of the device, but it + doesn't alter the device state. This means that it might not be + safe to toggle the setting from "write back" to "write through", + since that will also eliminate cache flushes issued by the + kernel. + + +What: /sys/block/<disk>/queue/write_same_max_bytes +Date: January 2012 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + [RO] Some devices support a write same operation in which a + single data block can be written to a range of several + contiguous blocks on storage. This can be used to wipe areas on + disk or to initialize drives in a RAID configuration. + write_same_max_bytes indicates how many bytes can be written in + a single write same command. If write_same_max_bytes is 0, write + same is not supported by the device. + + +What: /sys/block/<disk>/queue/write_zeroes_max_bytes +Date: November 2016 +Contact: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com> +Description: + [RO] Devices that support write zeroes operation in which a + single request can be issued to zero out the range of contiguous + blocks on storage without having any payload in the request. + This can be used to optimize writing zeroes to the devices. + write_zeroes_max_bytes indicates how many bytes can be written + in a single write zeroes command. If write_zeroes_max_bytes is + 0, write zeroes is not supported by the device. + + +What: /sys/block/<disk>/queue/zone_append_max_bytes +Date: May 2020 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the maximum number of bytes that can be written to + a sequential zone of a zoned block device using a zone append + write operation (REQ_OP_ZONE_APPEND). This value is always 0 for + regular block devices. + + +What: /sys/block/<disk>/queue/zone_write_granularity +Date: January 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] This indicates the alignment constraint, in bytes, for + write operations in sequential zones of zoned block devices + (devices with a zoned attributed that reports "host-managed" or + "host-aware"). This value is always 0 for regular block devices. + + +What: /sys/block/<disk>/queue/zoned +Date: September 2016 +Contact: Damien Le Moal <damien.lemoal@wdc.com> +Description: + [RO] zoned indicates if the device is a zoned block device and + the zone model of the device if it is indeed zoned. The + possible values indicated by zoned are "none" for regular block + devices and "host-aware" or "host-managed" for zoned block + devices. The characteristics of host-aware and host-managed + zoned block devices are described in the ZBC (Zoned Block + Commands) and ZAC (Zoned Device ATA Command Set) standards. + These standards also define the "drive-managed" zone model. + However, since drive-managed zoned block devices do not support + zone commands, they will be treated as regular block devices and + zoned will report "none". + + +What: /sys/block/<disk>/stat +Date: February 2008 +Contact: Jerome Marchand <jmarchan@redhat.com> +Description: + The /sys/block/<disk>/stat files displays the I/O + statistics of disk <disk>. They contain 11 fields: + + == ============================================== + 1 reads completed successfully + 2 reads merged + 3 sectors read + 4 time spent reading (ms) + 5 writes completed + 6 writes merged + 7 sectors written + 8 time spent writing (ms) + 9 I/Os currently in progress + 10 time spent doing I/Os (ms) + 11 weighted time spent doing I/Os (ms) + 12 discards completed + 13 discards merged + 14 sectors discarded + 15 time spent discarding (ms) + 16 flush requests completed + 17 time spent flushing (ms) + == ============================================== + + For more details refer Documentation/admin-guide/iostats.rst diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu b/Documentation/ABI/stable/sysfs-devices-system-cpu index 3965ce504484..902392d7eddf 100644 --- a/Documentation/ABI/stable/sysfs-devices-system-cpu +++ b/Documentation/ABI/stable/sysfs-devices-system-cpu @@ -86,6 +86,10 @@ What: /sys/devices/system/cpu/cpuX/topology/die_cpus Description: internal kernel map of CPUs within the same die. Values: hexadecimal bitmask. +What: /sys/devices/system/cpu/cpuX/topology/ppin +Description: per-socket protected processor inventory number +Values: hexadecimal. + What: /sys/devices/system/cpu/cpuX/topology/die_cpus_list Description: human-readable list of CPUs within the same die. The format is like 0-3, 8-11, 14,17. diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index df4afbccf037..0c2b613f2373 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -41,14 +41,14 @@ KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The maximum number of groups can be created under this device. -What: /sys/bus/dsa/devices/dsa<m>/max_tokens -Date: Oct 25, 2019 -KernelVersion: 5.6.0 +What: /sys/bus/dsa/devices/dsa<m>/max_read_buffers +Date: Dec 10, 2021 +KernelVersion: 5.17.0 Contact: dmaengine@vger.kernel.org -Description: The total number of bandwidth tokens supported by this device. - The bandwidth tokens represent resources within the DSA +Description: The total number of read buffers supported by this device. + The read buffers represent resources within the DSA implementation, and these resources are allocated by engines to - support operations. + support operations. See DSA spec v1.2 9.2.4 Total Read Buffers. What: /sys/bus/dsa/devices/dsa<m>/max_transfer_size Date: Oct 25, 2019 @@ -115,13 +115,13 @@ KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: To indicate if this device is configurable or not. -What: /sys/bus/dsa/devices/dsa<m>/token_limit -Date: Oct 25, 2019 -KernelVersion: 5.6.0 +What: /sys/bus/dsa/devices/dsa<m>/read_buffer_limit +Date: Dec 10, 2021 +KernelVersion: 5.17.0 Contact: dmaengine@vger.kernel.org -Description: The maximum number of bandwidth tokens that may be in use at +Description: The maximum number of read buffers that may be in use at one time by operations that access low bandwidth memory in the - device. + device. See DSA spec v1.2 9.2.8 GENCFG on Global Read Buffer Limit. What: /sys/bus/dsa/devices/dsa<m>/cmd_status Date: Aug 28, 2020 @@ -220,8 +220,38 @@ Contact: dmaengine@vger.kernel.org Description: Show the current number of entries in this WQ if WQ Occupancy Support bit WQ capabilities is 1. +What: /sys/bus/dsa/devices/wq<m>.<n>/enqcmds_retries +Date Oct 29, 2021 +KernelVersion: 5.17.0 +Contact: dmaengine@vger.kernel.org +Description: Indicate the number of retires for an enqcmds submission on a sharedwq. + A max value to set attribute is capped at 64. + What: /sys/bus/dsa/devices/engine<m>.<n>/group_id Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The group that this engine belongs to. + +What: /sys/bus/dsa/devices/group<m>.<n>/use_read_buffer_limit +Date: Dec 10, 2021 +KernelVersion: 5.17.0 +Contact: dmaengine@vger.kernel.org +Description: Enable the use of global read buffer limit for the group. See DSA + spec v1.2 9.2.18 GRPCFG Use Global Read Buffer Limit. + +What: /sys/bus/dsa/devices/group<m>.<n>/read_buffers_allowed +Date: Dec 10, 2021 +KernelVersion: 5.17.0 +Contact: dmaengine@vger.kernel.org +Description: Indicates max number of read buffers that may be in use at one time + by all engines in the group. See DSA spec v1.2 9.2.18 GRPCFG Read + Buffers Allowed. + +What: /sys/bus/dsa/devices/group<m>.<n>/read_buffers_reserved +Date: Dec 10, 2021 +KernelVersion: 5.17.0 +Contact: dmaengine@vger.kernel.org +Description: Indicates the number of Read Buffers reserved for the use of + engines in the group. See DSA spec v1.2 9.2.18 GRPCFG Read Buffers + Reserved. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1 index b576b3d6ea6d..d4b8cf40a9e4 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac1 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1 @@ -27,6 +27,6 @@ Description: (in 1/256 dB) p_volume_res playback volume control resolution (in 1/256 dB) - req_number the number of pre-allocated request + req_number the number of pre-allocated requests for both capture and playback ===================== ======================================= diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 index 244d96650123..7fb3dbe26857 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac2 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2 @@ -30,4 +30,6 @@ Description: (in 1/256 dB) p_volume_res playback volume control resolution (in 1/256 dB) + req_number the number of pre-allocated requests + for both capture and playback ===================== ======================================= diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index 63c46d9d538f..2667cbf940f3 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -21,11 +21,11 @@ Description: Allow the root user to disable/enable in runtime the clock a different engine to disable/enable its clock gating feature. The bitmask is composed of 20 bits: - ======= ============ + ======= ============ 0 - 7 DMA channels 8 - 11 MME engines 12 - 19 TPC engines - ======= ============ + ======= ============ The bit's location of a specific engine can be determined using (1 << GAUDI_ENGINE_ID_*). GAUDI_ENGINE_ID_* values @@ -155,6 +155,13 @@ Description: Triggers an I2C transaction that is generated by the device's CPU. Writing to this file generates a write transaction while reading from the file generates a read transaction +What: /sys/kernel/debug/habanalabs/hl<n>/i2c_len +Date: Dec 2021 +KernelVersion: 5.17 +Contact: obitton@habana.ai +Description: Sets I2C length in bytes for I2C transaction that is generated by + the device's CPU + What: /sys/kernel/debug/habanalabs/hl<n>/i2c_reg Date: Jan 2019 KernelVersion: 5.1 @@ -226,12 +233,6 @@ Description: Gets the state dump occurring on a CS timeout or failure. Writing an integer X discards X state dumps, so that the next read would return X+1-st newest state dump. -What: /sys/kernel/debug/habanalabs/hl<n>/timeout_locked -Date: Sep 2021 -KernelVersion: 5.16 -Contact: obitton@habana.ai -Description: Sets the command submission timeout value in seconds. - What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err Date: Mar 2020 KernelVersion: 5.6 @@ -239,6 +240,12 @@ Contact: ogabbay@kernel.org Description: Sets the stop-on_error option for the device engines. Value of "0" is for disable, otherwise enable. +What: /sys/kernel/debug/habanalabs/hl<n>/timeout_locked +Date: Sep 2021 +KernelVersion: 5.16 +Contact: obitton@habana.ai +Description: Sets the command submission timeout value in seconds. + What: /sys/kernel/debug/habanalabs/hl<n>/userptr Date: Jan 2019 KernelVersion: 5.1 diff --git a/Documentation/ABI/testing/debugfs-hisi-hpre b/Documentation/ABI/testing/debugfs-hisi-hpre index b4be5f1db4b7..396de7bc735d 100644 --- a/Documentation/ABI/testing/debugfs-hisi-hpre +++ b/Documentation/ABI/testing/debugfs-hisi-hpre @@ -1,140 +1,150 @@ -What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/regs -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: Dump debug registers from the HPRE cluster. +What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/regs +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: Dump debug registers from the HPRE cluster. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/cluster_ctrl -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: Write the HPRE core selection in the cluster into this file, +What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/cluster_ctrl +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: Write the HPRE core selection in the cluster into this file, and then we can read the debug information of the core. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/rdclr_en -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: HPRE cores debug registers read clear control. 1 means enable +What: /sys/kernel/debug/hisi_hpre/<bdf>/rdclr_en +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: HPRE cores debug registers read clear control. 1 means enable register read clear, otherwise 0. Writing to this file has no functional effect, only enable or disable counters clear after reading of these registers. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/current_qm -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: One HPRE controller has one PF and multiple VFs, each function +What: /sys/kernel/debug/hisi_hpre/<bdf>/current_qm +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: One HPRE controller has one PF and multiple VFs, each function has a QM. Select the QM which below qm refers to. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/regs -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: Dump debug registers from the HPRE. +What: /sys/kernel/debug/hisi_hpre/<bdf>/alg_qos +Date: Jun 2021 +Contact: linux-crypto@vger.kernel.org +Description: The <bdf> is related the function for PF and VF. + HPRE driver supports to configure each function's QoS, the driver + supports to write <bdf> value to alg_qos in the host. Such as + "echo <bdf> value > alg_qos". The qos value is 1~1000, means + 1/1000~1000/1000 of total QoS. The driver reading alg_qos to + get related QoS in the host and VM, Such as "cat alg_qos". + +What: /sys/kernel/debug/hisi_hpre/<bdf>/regs +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: Dump debug registers from the HPRE. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/regs -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: Dump debug registers from the QM. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/regs +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: Dump debug registers from the QM. Available for PF and VF in host. VF in guest currently only has one debug register. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/current_q -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: One QM may contain multiple queues. Select specific queue to +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/current_q +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: One QM may contain multiple queues. Select specific queue to show its debug registers in above regs. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/clear_enable -Date: Sep 2019 -Contact: linux-crypto@vger.kernel.org -Description: QM debug registers(regs) read clear control. 1 means enable +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/clear_enable +Date: Sep 2019 +Contact: linux-crypto@vger.kernel.org +Description: QM debug registers(regs) read clear control. 1 means enable register read clear, otherwise 0. Writing to this file has no functional effect, only enable or disable counters clear after reading of these registers. Only available for PF. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/err_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of invalid interrupts for +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/err_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of invalid interrupts for QM task completion. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/aeq_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of QM async event queue interrupts. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/aeq_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of QM async event queue interrupts. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/abnormal_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of interrupts for QM abnormal event. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/abnormal_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of interrupts for QM abnormal event. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/create_qp_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of queue allocation errors. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/create_qp_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of queue allocation errors. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/mb_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of failed QM mailbox commands. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/mb_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of failed QM mailbox commands. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/status -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the status of the QM. +What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/status +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the status of the QM. Four states: initiated, started, stopped and closed. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of sent requests. +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of sent requests. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/recv_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of received requests. +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/recv_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of received requests. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_busy_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of requests sent +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_busy_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of requests sent with returning busy. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_fail_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of completed but error requests. +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_fail_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of completed but error requests. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/invalid_req_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of invalid requests being received. +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/invalid_req_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of invalid requests being received. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/overtime_thrhld -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Set the threshold time for counting the request which is +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/overtime_thrhld +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Set the threshold time for counting the request which is processed longer than the threshold. 0: disable(default), 1: 1 microsecond. Available for both PF and VF, and take no other effect on HPRE. -What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/over_thrhld_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of time out requests. +What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/over_thrhld_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of time out requests. Available for both PF and VF, and take no other effect on HPRE. diff --git a/Documentation/ABI/testing/debugfs-hisi-sec b/Documentation/ABI/testing/debugfs-hisi-sec index 85feb4408e0f..2bf84ced484b 100644 --- a/Documentation/ABI/testing/debugfs-hisi-sec +++ b/Documentation/ABI/testing/debugfs-hisi-sec @@ -1,113 +1,123 @@ -What: /sys/kernel/debug/hisi_sec2/<bdf>/clear_enable -Date: Oct 2019 -Contact: linux-crypto@vger.kernel.org -Description: Enabling/disabling of clear action after reading +What: /sys/kernel/debug/hisi_sec2/<bdf>/clear_enable +Date: Oct 2019 +Contact: linux-crypto@vger.kernel.org +Description: Enabling/disabling of clear action after reading the SEC debug registers. 0: disable, 1: enable. Only available for PF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/current_qm -Date: Oct 2019 -Contact: linux-crypto@vger.kernel.org -Description: One SEC controller has one PF and multiple VFs, each function +What: /sys/kernel/debug/hisi_sec2/<bdf>/current_qm +Date: Oct 2019 +Contact: linux-crypto@vger.kernel.org +Description: One SEC controller has one PF and multiple VFs, each function has a QM. This file can be used to select the QM which below qm refers to. Only available for PF. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/qm_regs -Date: Oct 2019 -Contact: linux-crypto@vger.kernel.org -Description: Dump of QM related debug registers. +What: /sys/kernel/debug/hisi_sec2/<bdf>/alg_qos +Date: Jun 2021 +Contact: linux-crypto@vger.kernel.org +Description: The <bdf> is related the function for PF and VF. + SEC driver supports to configure each function's QoS, the driver + supports to write <bdf> value to alg_qos in the host. Such as + "echo <bdf> value > alg_qos". The qos value is 1~1000, means + 1/1000~1000/1000 of total QoS. The driver reading alg_qos to + get related QoS in the host and VM, Such as "cat alg_qos". + +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/qm_regs +Date: Oct 2019 +Contact: linux-crypto@vger.kernel.org +Description: Dump of QM related debug registers. Available for PF and VF in host. VF in guest currently only has one debug register. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/current_q -Date: Oct 2019 -Contact: linux-crypto@vger.kernel.org -Description: One QM of SEC may contain multiple queues. Select specific +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/current_q +Date: Oct 2019 +Contact: linux-crypto@vger.kernel.org +Description: One QM of SEC may contain multiple queues. Select specific queue to show its debug registers in above 'regs'. Only available for PF. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/clear_enable -Date: Oct 2019 -Contact: linux-crypto@vger.kernel.org -Description: Enabling/disabling of clear action after reading +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/clear_enable +Date: Oct 2019 +Contact: linux-crypto@vger.kernel.org +Description: Enabling/disabling of clear action after reading the SEC's QM debug registers. 0: disable, 1: enable. Only available for PF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/err_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of invalid interrupts for +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/err_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of invalid interrupts for QM task completion. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/aeq_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of QM async event queue interrupts. +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/aeq_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of QM async event queue interrupts. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/abnormal_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of interrupts for QM abnormal event. +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/abnormal_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of interrupts for QM abnormal event. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/create_qp_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of queue allocation errors. +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/create_qp_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of queue allocation errors. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/mb_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of failed QM mailbox commands. +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/mb_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of failed QM mailbox commands. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/status -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the status of the QM. +What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/status +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the status of the QM. Four states: initiated, started, stopped and closed. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of sent requests. +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of sent requests. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/recv_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of received requests. +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/recv_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of received requests. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_busy_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of requests sent with returning busy. +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_busy_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of requests sent with returning busy. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/err_bd_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of BD type error requests +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/err_bd_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of BD type error requests to be received. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/invalid_req_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of invalid requests being received. +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/invalid_req_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of invalid requests being received. Available for both PF and VF, and take no other effect on SEC. -What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/done_flag_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of completed but marked error requests +What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/done_flag_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of completed but marked error requests to be received. Available for both PF and VF, and take no other effect on SEC. diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip index 3034a2bf99ca..bf1258bc6495 100644 --- a/Documentation/ABI/testing/debugfs-hisi-zip +++ b/Documentation/ABI/testing/debugfs-hisi-zip @@ -1,114 +1,124 @@ -What: /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: Dump of compression cores related debug registers. +What: /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of compression cores related debug registers. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: Dump of decompression cores related debug registers. +What: /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of decompression cores related debug registers. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/clear_enable -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: Compression/decompression core debug registers read clear +What: /sys/kernel/debug/hisi_zip/<bdf>/clear_enable +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Compression/decompression core debug registers read clear control. 1 means enable register read clear, otherwise 0. Writing to this file has no functional effect, only enable or disable counters clear after reading of these registers. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/current_qm -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: One ZIP controller has one PF and multiple VFs, each function +What: /sys/kernel/debug/hisi_zip/<bdf>/current_qm +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: One ZIP controller has one PF and multiple VFs, each function has a QM. Select the QM which below qm refers to. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/regs -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: Dump of QM related debug registers. +What: /sys/kernel/debug/hisi_zip/<bdf>/alg_qos +Date: Jun 2021 +Contact: linux-crypto@vger.kernel.org +Description: The <bdf> is related the function for PF and VF. + ZIP driver supports to configure each function's QoS, the driver + supports to write <bdf> value to alg_qos in the host. Such as + "echo <bdf> value > alg_qos". The qos value is 1~1000, means + 1/1000~1000/1000 of total QoS. The driver reading alg_qos to + get related QoS in the host and VM, Such as "cat alg_qos". + +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of QM related debug registers. Available for PF and VF in host. VF in guest currently only has one debug register. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: One QM may contain multiple queues. Select specific queue to +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: One QM may contain multiple queues. Select specific queue to show its debug registers in above regs. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable -Date: Nov 2018 -Contact: linux-crypto@vger.kernel.org -Description: QM debug registers(regs) read clear control. 1 means enable +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: QM debug registers(regs) read clear control. 1 means enable register read clear, otherwise 0. Writing to this file has no functional effect, only enable or disable counters clear after reading of these registers. Only available for PF. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/err_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of invalid interrupts for +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/err_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of invalid interrupts for QM task completion. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/aeq_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of QM async event queue interrupts. +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/aeq_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of QM async event queue interrupts. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/abnormal_irq -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of interrupts for QM abnormal event. +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/abnormal_irq +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of interrupts for QM abnormal event. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/create_qp_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of queue allocation errors. +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/create_qp_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of queue allocation errors. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/mb_err -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the number of failed QM mailbox commands. +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/mb_err +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the number of failed QM mailbox commands. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/qm/status -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the status of the QM. +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/status +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the status of the QM. Four states: initiated, started, stopped and closed. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of sent requests. +What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of sent requests. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/recv_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of received requests. +What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/recv_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of received requests. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_busy_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of requests received +What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_busy_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of requests received with returning busy. Available for both PF and VF, and take no other effect on ZIP. -What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/err_bd_cnt -Date: Apr 2020 -Contact: linux-crypto@vger.kernel.org -Description: Dump the total number of BD type error requests +What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/err_bd_cnt +Date: Apr 2020 +Contact: linux-crypto@vger.kernel.org +Description: Dump the total number of BD type error requests to be received. Available for both PF and VF, and take no other effect on ZIP. diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block deleted file mode 100644 index b16b0c45a272..000000000000 --- a/Documentation/ABI/testing/sysfs-block +++ /dev/null @@ -1,346 +0,0 @@ -What: /sys/block/<disk>/stat -Date: February 2008 -Contact: Jerome Marchand <jmarchan@redhat.com> -Description: - The /sys/block/<disk>/stat files displays the I/O - statistics of disk <disk>. They contain 11 fields: - - == ============================================== - 1 reads completed successfully - 2 reads merged - 3 sectors read - 4 time spent reading (ms) - 5 writes completed - 6 writes merged - 7 sectors written - 8 time spent writing (ms) - 9 I/Os currently in progress - 10 time spent doing I/Os (ms) - 11 weighted time spent doing I/Os (ms) - 12 discards completed - 13 discards merged - 14 sectors discarded - 15 time spent discarding (ms) - 16 flush requests completed - 17 time spent flushing (ms) - == ============================================== - - For more details refer Documentation/admin-guide/iostats.rst - - -What: /sys/block/<disk>/inflight -Date: October 2009 -Contact: Jens Axboe <axboe@kernel.dk>, Nikanth Karthikesan <knikanth@suse.de> -Description: - Reports the number of I/O requests currently in progress - (pending / in flight) in a device driver. This can be less - than the number of requests queued in the block device queue. - The report contains 2 fields: one for read requests - and one for write requests. - The value type is unsigned int. - Cf. Documentation/block/stat.rst which contains a single value for - requests in flight. - This is related to nr_requests in Documentation/block/queue-sysfs.rst - and for SCSI device also its queue_depth. - - -What: /sys/block/<disk>/diskseq -Date: February 2021 -Contact: Matteo Croce <mcroce@microsoft.com> -Description: - The /sys/block/<disk>/diskseq files reports the disk - sequence number, which is a monotonically increasing - number assigned to every drive. - Some devices, like the loop device, refresh such number - every time the backing file is changed. - The value type is 64 bit unsigned. - - -What: /sys/block/<disk>/<part>/stat -Date: February 2008 -Contact: Jerome Marchand <jmarchan@redhat.com> -Description: - The /sys/block/<disk>/<part>/stat files display the - I/O statistics of partition <part>. The format is the - same as the above-written /sys/block/<disk>/stat - format. - - -What: /sys/block/<disk>/integrity/format -Date: June 2008 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Metadata format for integrity capable block device. - E.g. T10-DIF-TYPE1-CRC. - - -What: /sys/block/<disk>/integrity/read_verify -Date: June 2008 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Indicates whether the block layer should verify the - integrity of read requests serviced by devices that - support sending integrity metadata. - - -What: /sys/block/<disk>/integrity/tag_size -Date: June 2008 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Number of bytes of integrity tag space available per - 512 bytes of data. - - -What: /sys/block/<disk>/integrity/device_is_integrity_capable -Date: July 2014 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Indicates whether a storage device is capable of storing - integrity metadata. Set if the device is T10 PI-capable. - -What: /sys/block/<disk>/integrity/protection_interval_bytes -Date: July 2015 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Describes the number of data bytes which are protected - by one integrity tuple. Typically the device's logical - block size. - -What: /sys/block/<disk>/integrity/write_generate -Date: June 2008 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Indicates whether the block layer should automatically - generate checksums for write requests bound for - devices that support receiving integrity metadata. - -What: /sys/block/<disk>/alignment_offset -Date: April 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Storage devices may report a physical block size that is - bigger than the logical block size (for instance a drive - with 4KB physical sectors exposing 512-byte logical - blocks to the operating system). This parameter - indicates how many bytes the beginning of the device is - offset from the disk's natural alignment. - -What: /sys/block/<disk>/<partition>/alignment_offset -Date: April 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Storage devices may report a physical block size that is - bigger than the logical block size (for instance a drive - with 4KB physical sectors exposing 512-byte logical - blocks to the operating system). This parameter - indicates how many bytes the beginning of the partition - is offset from the disk's natural alignment. - -What: /sys/block/<disk>/queue/logical_block_size -Date: May 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - This is the smallest unit the storage device can - address. It is typically 512 bytes. - -What: /sys/block/<disk>/queue/physical_block_size -Date: May 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - This is the smallest unit a physical storage device can - write atomically. It is usually the same as the logical - block size but may be bigger. One example is SATA - drives with 4KB sectors that expose a 512-byte logical - block size to the operating system. For stacked block - devices the physical_block_size variable contains the - maximum physical_block_size of the component devices. - -What: /sys/block/<disk>/queue/minimum_io_size -Date: April 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Storage devices may report a granularity or preferred - minimum I/O size which is the smallest request the - device can perform without incurring a performance - penalty. For disk drives this is often the physical - block size. For RAID arrays it is often the stripe - chunk size. A properly aligned multiple of - minimum_io_size is the preferred request size for - workloads where a high number of I/O operations is - desired. - -What: /sys/block/<disk>/queue/optimal_io_size -Date: April 2009 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Storage devices may report an optimal I/O size, which is - the device's preferred unit for sustained I/O. This is - rarely reported for disk drives. For RAID arrays it is - usually the stripe width or the internal track size. A - properly aligned multiple of optimal_io_size is the - preferred request size for workloads where sustained - throughput is desired. If no optimal I/O size is - reported this file contains 0. - -What: /sys/block/<disk>/queue/nomerges -Date: January 2010 -Contact: -Description: - Standard I/O elevator operations include attempts to - merge contiguous I/Os. For known random I/O loads these - attempts will always fail and result in extra cycles - being spent in the kernel. This allows one to turn off - this behavior on one of two ways: When set to 1, complex - merge checks are disabled, but the simple one-shot merges - with the previous I/O request are enabled. When set to 2, - all merge tries are disabled. The default value is 0 - - which enables all types of merge tries. - -What: /sys/block/<disk>/discard_alignment -Date: May 2011 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Devices that support discard functionality may - internally allocate space in units that are bigger than - the exported logical block size. The discard_alignment - parameter indicates how many bytes the beginning of the - device is offset from the internal allocation unit's - natural alignment. - -What: /sys/block/<disk>/<partition>/discard_alignment -Date: May 2011 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Devices that support discard functionality may - internally allocate space in units that are bigger than - the exported logical block size. The discard_alignment - parameter indicates how many bytes the beginning of the - partition is offset from the internal allocation unit's - natural alignment. - -What: /sys/block/<disk>/queue/discard_granularity -Date: May 2011 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Devices that support discard functionality may - internally allocate space using units that are bigger - than the logical block size. The discard_granularity - parameter indicates the size of the internal allocation - unit in bytes if reported by the device. Otherwise the - discard_granularity will be set to match the device's - physical block size. A discard_granularity of 0 means - that the device does not support discard functionality. - -What: /sys/block/<disk>/queue/discard_max_bytes -Date: May 2011 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Devices that support discard functionality may have - internal limits on the number of bytes that can be - trimmed or unmapped in a single operation. Some storage - protocols also have inherent limits on the number of - blocks that can be described in a single command. The - discard_max_bytes parameter is set by the device driver - to the maximum number of bytes that can be discarded in - a single operation. Discard requests issued to the - device must not exceed this limit. A discard_max_bytes - value of 0 means that the device does not support - discard functionality. - -What: /sys/block/<disk>/queue/discard_zeroes_data -Date: May 2011 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Will always return 0. Don't rely on any specific behavior - for discards, and don't read this file. - -What: /sys/block/<disk>/queue/write_same_max_bytes -Date: January 2012 -Contact: Martin K. Petersen <martin.petersen@oracle.com> -Description: - Some devices support a write same operation in which a - single data block can be written to a range of several - contiguous blocks on storage. This can be used to wipe - areas on disk or to initialize drives in a RAID - configuration. write_same_max_bytes indicates how many - bytes can be written in a single write same command. If - write_same_max_bytes is 0, write same is not supported - by the device. - -What: /sys/block/<disk>/queue/write_zeroes_max_bytes -Date: November 2016 -Contact: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com> -Description: - Devices that support write zeroes operation in which a - single request can be issued to zero out the range of - contiguous blocks on storage without having any payload - in the request. This can be used to optimize writing zeroes - to the devices. write_zeroes_max_bytes indicates how many - bytes can be written in a single write zeroes command. If - write_zeroes_max_bytes is 0, write zeroes is not supported - by the device. - -What: /sys/block/<disk>/queue/zoned -Date: September 2016 -Contact: Damien Le Moal <damien.lemoal@wdc.com> -Description: - zoned indicates if the device is a zoned block device - and the zone model of the device if it is indeed zoned. - The possible values indicated by zoned are "none" for - regular block devices and "host-aware" or "host-managed" - for zoned block devices. The characteristics of - host-aware and host-managed zoned block devices are - described in the ZBC (Zoned Block Commands) and ZAC - (Zoned Device ATA Command Set) standards. These standards - also define the "drive-managed" zone model. However, - since drive-managed zoned block devices do not support - zone commands, they will be treated as regular block - devices and zoned will report "none". - -What: /sys/block/<disk>/queue/nr_zones -Date: November 2018 -Contact: Damien Le Moal <damien.lemoal@wdc.com> -Description: - nr_zones indicates the total number of zones of a zoned block - device ("host-aware" or "host-managed" zone model). For regular - block devices, the value is always 0. - -What: /sys/block/<disk>/queue/max_active_zones -Date: July 2020 -Contact: Niklas Cassel <niklas.cassel@wdc.com> -Description: - For zoned block devices (zoned attribute indicating - "host-managed" or "host-aware"), the sum of zones belonging to - any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, - is limited by this value. If this value is 0, there is no limit. - -What: /sys/block/<disk>/queue/max_open_zones -Date: July 2020 -Contact: Niklas Cassel <niklas.cassel@wdc.com> -Description: - For zoned block devices (zoned attribute indicating - "host-managed" or "host-aware"), the sum of zones belonging to - any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, - is limited by this value. If this value is 0, there is no limit. - -What: /sys/block/<disk>/queue/chunk_sectors -Date: September 2016 -Contact: Hannes Reinecke <hare@suse.com> -Description: - chunk_sectors has different meaning depending on the type - of the disk. For a RAID device (dm-raid), chunk_sectors - indicates the size in 512B sectors of the RAID volume - stripe segment. For a zoned block device, either - host-aware or host-managed, chunk_sectors indicates the - size in 512B sectors of the zones of the device, with - the eventual exception of the last zone of the device - which may be smaller. - -What: /sys/block/<disk>/queue/io_timeout -Date: November 2018 -Contact: Weiping Zhang <zhangweiping@didiglobal.com> -Description: - io_timeout is the request timeout in milliseconds. If a request - does not complete in this time then the block driver timeout - handler is invoked. That timeout handler can decide to retry - the request, to fail it or to start a device recovery strategy. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 new file mode 100644 index 000000000000..f6c035752639 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 @@ -0,0 +1,16 @@ +What: /sys/bus/iio/devices/iio:deviceX/filter_mode_available +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Reading this returns the valid values that can be written to the + on_altvoltage0_mode attribute: + + - auto -> Adjust bandpass filter to track changes in input clock rate. + - manual -> disable/unregister the clock rate notifier / input clock tracking. + +What: /sys/bus/iio/devices/iio:deviceX/filter_mode +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + This attribute configures the filter mode. + Reading returns the actual mode. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013 new file mode 100644 index 000000000000..de1e323e5d47 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013 @@ -0,0 +1,38 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0-1_i_calibphase +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write unscaled value for the Local Oscillatior path quadrature I phase shift. + +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0-1_q_calibphase +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write unscaled value for the Local Oscillatior path quadrature Q phase shift. + +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_i_calibbias +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write value for the Local Oscillatior Feedthrough Offset Calibration I Positive + side. + +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_q_calibbias +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write value for the Local Oscillatior Feedthrough Offset Calibration Q Positive side. + +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage1_i_calibbias +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write raw value for the Local Oscillatior Feedthrough Offset Calibration I Negative + side. + +What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage1_q_calibbias +KernelVersion: +Contact: linux-iio@vger.kernel.org +Description: + Read/write raw value for the Local Oscillatior Feedthrough Offset Calibration Q Negative + side. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 2ebe5708b4bc..7efe31ed3a25 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -244,6 +244,15 @@ Description: is permitted, "u2" if only u2 is permitted, "u1_u2" if both u1 and u2 are permitted. +What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/connector +Date: December 2021 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Link to the USB Type-C connector when available. This link is + only created when USB Type-C Connector Class is enabled, and + only if the system firmware is capable of describing the + connection between a port and its connector. + What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout Date: May 2013 Contact: Mathias Nyman <mathias.nyman@linux.intel.com> diff --git a/Documentation/ABI/testing/sysfs-bus-vdpa b/Documentation/ABI/testing/sysfs-bus-vdpa new file mode 100644 index 000000000000..28a6111202ba --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-vdpa @@ -0,0 +1,57 @@ +What: /sys/bus/vdpa/driver_autoprobe +Date: March 2020 +Contact: virtualization@lists.linux-foundation.org +Description: + This file determines whether new devices are immediately bound + to a driver after the creation. It initially contains 1, which + means the kernel automatically binds devices to a compatible + driver immediately after they are created. + + Writing "0" to this file disable this feature, any other string + enable it. + +What: /sys/bus/vdpa/driver_probe +Date: March 2020 +Contact: virtualization@lists.linux-foundation.org +Description: + Writing a device name to this file will cause the kernel binds + devices to a compatible driver. + + This can be useful when /sys/bus/vdpa/driver_autoprobe is + disabled. + +What: /sys/bus/vdpa/drivers/.../bind +Date: March 2020 +Contact: virtualization@lists.linux-foundation.org +Description: + Writing a device name to this file will cause the driver to + attempt to bind to the device. This is useful for overriding + default bindings. + +What: /sys/bus/vdpa/drivers/.../unbind +Date: March 2020 +Contact: virtualization@lists.linux-foundation.org +Description: + Writing a device name to this file will cause the driver to + attempt to unbind from the device. This may be useful when + overriding default bindings. + +What: /sys/bus/vdpa/devices/.../driver_override +Date: November 2021 +Contact: virtualization@lists.linux-foundation.org +Description: + This file allows the driver for a device to be specified. + When specified, only a driver with a name matching the value + written to driver_override will have an opportunity to bind to + the device. The override is specified by writing a string to the + driver_override file (echo vhost-vdpa > driver_override) and may + be cleared with an empty string (echo > driver_override). + This returns the device to standard matching rules binding. + Writing to driver_override does not automatically unbind the + device from its current driver or make any attempt to + automatically load the specified driver. If no driver with a + matching name is currently loaded in the kernel, the device will + not bind to any driver. This also allows devices to opt-out of + driver binding using a driver_override name such as "none". + Only a single driver may be specified in the override, there is + no support for parsing delimiters. diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 90fdf935aa5e..13e31c6a0e9c 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -161,6 +161,15 @@ Description: power-on: Representing a password required to use the system + system-mgmt: + Representing System Management password. + See Lenovo extensions section for details + HDD: + Representing HDD password + See Lenovo extensions section for details + NVMe: + Representing NVMe password + See Lenovo extensions section for details mechanism: The means of authentication. This attribute is mandatory. @@ -207,6 +216,13 @@ Description: On Lenovo systems the following additional settings are available: + role: system-mgmt This gives the same authority as the bios-admin password to control + security related features. The authorities allocated can be set via + the BIOS menu SMP Access Control Policy + + role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see + 'level' and 'index' extensions below. + lenovo_encoding: The encoding method that is used. This can be either "ascii" or "scancode". Default is set to "ascii" @@ -216,6 +232,22 @@ Description: two char code (e.g. "us", "fr", "gr") and may vary per platform. Default is set to "us" + level: + Available for HDD and NVMe authentication to set 'user' or 'master' + privilege level. + If only the user password is configured then this should be used to + unlock the drive at boot. If both master and user passwords are set + then either can be used. If a master password is set a user password + is required. + This attribute defaults to 'user' level + + index: + Used with HDD and NVME authentication to set the drive index + that is being referenced (e.g hdd0, hdd1 etc) + This attribute defaults to device 0. + + + What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 KernelVersion: 5.11 diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon index 1f20687def44..653d4c75eddb 100644 --- a/Documentation/ABI/testing/sysfs-class-hwmon +++ b/Documentation/ABI/testing/sysfs-class-hwmon @@ -9,6 +9,14 @@ Description: RO +What: /sys/class/hwmon/hwmonX/label +Description: + A descriptive label that allows to uniquely identify a + device within the system. + The contents of the label are free-form. + + RO + What: /sys/class/hwmon/hwmonX/update_interval Description: The interval at which the chip will update readings. diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index f7904efc4cfa..859501366777 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -413,7 +413,7 @@ Description: "Over voltage", "Unspecified failure", "Cold", "Watchdog timer expire", "Safety timer expire", "Over current", "Calibration required", "Warm", - "Cool", "Hot" + "Cool", "Hot", "No battery" What: /sys/class/power_supply/<supply_name>/precharge_current Date: June 2017 @@ -455,6 +455,21 @@ Description: "Unknown", "Charging", "Discharging", "Not charging", "Full" +What: /sys/class/power_supply/<supply_name>/charge_behaviour +Date: November 2021 +Contact: linux-pm@vger.kernel.org +Description: + Represents the charging behaviour. + + Access: Read, Write + + Valid values: + ================ ==================================== + auto: Charge normally, respect thresholds + inhibit-charge: Do not charge while AC is attached + force-discharge: Force discharge while AC is attached + ================ ==================================== + What: /sys/class/power_supply/<supply_name>/technology Date: May 2007 Contact: linux-pm@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-thermal b/Documentation/ABI/testing/sysfs-class-thermal index 2c52bb1f864c..8eee37982b2a 100644 --- a/Documentation/ABI/testing/sysfs-class-thermal +++ b/Documentation/ABI/testing/sysfs-class-thermal @@ -203,7 +203,7 @@ Description: - for generic ACPI: should be "Fan", "Processor" or "LCD" - for memory controller device on intel_menlow platform: - should be "Memory controller". + should be "Memory controller". RO, Required diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 69c65da16dff..2ad01cad7f1c 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -73,6 +73,7 @@ What: /sys/devices/system/cpu/cpuX/topology/core_id /sys/devices/system/cpu/cpuX/topology/physical_package_id /sys/devices/system/cpu/cpuX/topology/thread_siblings /sys/devices/system/cpu/cpuX/topology/thread_siblings_list + /sys/devices/system/cpu/cpuX/topology/ppin Date: December 2008 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: CPU topology files that describe a logical CPU's relationship @@ -103,6 +104,11 @@ Description: CPU topology files that describe a logical CPU's relationship thread_siblings_list: human-readable list of cpuX's hardware threads within the same core as cpuX + ppin: human-readable Protected Processor Identification + Number of the socket the cpu# belongs to. There should be + one per physical_package_id. File is readable only to + admin. + See Documentation/admin-guide/cputopology.rst for more information. @@ -662,7 +668,23 @@ Description: Preferred MTE tag checking mode ================ ============================================== "sync" Prefer synchronous mode + "asymm" Prefer asymmetric mode "async" Prefer asynchronous mode ================ ============================================== See also: Documentation/arm64/memory-tagging-extension.rst + +What: /sys/devices/system/cpu/nohz_full +Date: Apr 2015 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: + (RO) the list of CPUs that are in nohz_full mode. + These CPUs are set by boot parameter "nohz_full=". + +What: /sys/devices/system/cpu/isolated +Date: Apr 2015 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: + (RO) the list of CPUs that are isolated and don't + participate in load balancing. These CPUs are set by + boot parameter "isolcpus=". diff --git a/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing b/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing index b363827da437..910df0e5815a 100644 --- a/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing +++ b/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing @@ -1,4 +1,4 @@ -What: /sys/bus/platform/drivers/aspeed-uart-routing/*/uart* +What: /sys/bus/platform/drivers/aspeed-uart-routing/\*/uart\* Date: September 2021 Contact: Oskar Senft <osk@google.com> Chia-Wei Wang <chiawei_wang@aspeedtech.com> @@ -9,7 +9,7 @@ Description: Selects the RX source of the UARTx device. depends on the selected file. e.g. - cat /sys/bus/platform/drivers/aspeed-uart-routing/*.uart_routing/uart1 + cat /sys/bus/platform/drivers/aspeed-uart-routing/\*.uart_routing/uart1 [io1] io2 io3 io4 uart2 uart3 uart4 io6 In this case, UART1 gets its input from IO1 (physical serial port 1). @@ -17,7 +17,7 @@ Description: Selects the RX source of the UARTx device. Users: OpenBMC. Proposed changes should be mailed to openbmc@lists.ozlabs.org -What: /sys/bus/platform/drivers/aspeed-uart-routing/*/io* +What: /sys/bus/platform/drivers/aspeed-uart-routing/\*/io\* Date: September 2021 Contact: Oskar Senft <osk@google.com> Chia-Wei Wang <chiawei_wang@aspeedtech.com> diff --git a/Documentation/ABI/testing/sysfs-fs-erofs b/Documentation/ABI/testing/sysfs-fs-erofs new file mode 100644 index 000000000000..05482374a741 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-erofs @@ -0,0 +1,16 @@ +What: /sys/fs/erofs/features/ +Date: November 2021 +Contact: "Huang Jianan" <huangjianan@oppo.com> +Description: Shows all enabled kernel features. + Supported features: + zero_padding, compr_cfgs, big_pcluster, chunked_file, + device_table, compr_head2, sb_chksum. + +What: /sys/fs/erofs/<disk>/sync_decompress +Date: November 2021 +Contact: "Huang Jianan" <huangjianan@oppo.com> +Description: Control strategy of sync decompression + - 0 (default, auto): enable for readpage, and enable for + readahead on atomic contexts only, + - 1 (force on): enable for readpage and readahead. + - 2 (force off): disable for all situations. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index b268e3e18b4a..9b583dd0298b 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -55,8 +55,9 @@ Description: Controls the in-place-update policy. 0x04 F2FS_IPU_UTIL 0x08 F2FS_IPU_SSR_UTIL 0x10 F2FS_IPU_FSYNC - 0x20 F2FS_IPU_ASYNC, + 0x20 F2FS_IPU_ASYNC 0x40 F2FS_IPU_NOCACHE + 0x80 F2FS_IPU_HONOR_OPU_WRITE ==== ================= Refer segment.h for details. @@ -98,6 +99,33 @@ Description: Controls the issue rate of discard commands that consist of small checkpoint is triggered, and issued during the checkpoint. By default, it is disabled with 0. +What: /sys/fs/f2fs/<disk>/max_discard_request +Date: December 2021 +Contact: "Konstantin Vyshetsky" <vkon@google.com> +Description: Controls the number of discards a thread will issue at a time. + Higher number will allow the discard thread to finish its work + faster, at the cost of higher latency for incomming I/O. + +What: /sys/fs/f2fs/<disk>/min_discard_issue_time +Date: December 2021 +Contact: "Konstantin Vyshetsky" <vkon@google.com> +Description: Controls the interval the discard thread will wait between + issuing discard requests when there are discards to be issued and + no I/O aware interruptions occur. + +What: /sys/fs/f2fs/<disk>/mid_discard_issue_time +Date: December 2021 +Contact: "Konstantin Vyshetsky" <vkon@google.com> +Description: Controls the interval the discard thread will wait between + issuing discard requests when there are discards to be issued and + an I/O aware interruption occurs. + +What: /sys/fs/f2fs/<disk>/max_discard_issue_time +Date: December 2021 +Contact: "Konstantin Vyshetsky" <vkon@google.com> +Description: Controls the interval the discard thread will wait when there are + no discard operations to be issued. + What: /sys/fs/f2fs/<disk>/discard_granularity Date: July 2017 Contact: "Chao Yu" <yuchao0@huawei.com> @@ -112,6 +140,11 @@ Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Set timeout to issue discard commands during umount. Default: 5 secs +What: /sys/fs/f2fs/<disk>/pending_discard +Date: November 2021 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: Shows the number of pending discard commands in the queue. + What: /sys/fs/f2fs/<disk>/max_victim_search Date: January 2014 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> @@ -264,11 +297,16 @@ Description: Shows current reserved blocks in system, it may be temporarily What: /sys/fs/f2fs/<disk>/gc_urgent Date: August 2017 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> -Description: Do background GC aggressively when set. When gc_urgent = 1, - background thread starts to do GC by given gc_urgent_sleep_time - interval. When gc_urgent = 2, F2FS will lower the bar of - checking idle in order to process outstanding discard commands - and GC a little bit aggressively. It is set to 0 by default. +Description: Do background GC aggressively when set. Set to 0 by default. + gc urgent high(1): does GC forcibly in a period of given + gc_urgent_sleep_time and ignores I/O idling check. uses greedy + GC approach and turns SSR mode on. + gc urgent low(2): lowers the bar of checking I/O idling in + order to process outstanding discard commands and GC a + little bit aggressively. uses cost benefit GC approach. + gc urgent mid(3): does GC forcibly in a period of given + gc_urgent_sleep_time and executes a mid level of I/O idling check. + uses cost benefit GC approach. What: /sys/fs/f2fs/<disk>/gc_urgent_sleep_time Date: August 2017 @@ -425,6 +463,7 @@ Description: Show status of f2fs superblock in real time. 0x800 SBI_QUOTA_SKIP_FLUSH skip flushing quota in current CP 0x1000 SBI_QUOTA_NEED_REPAIR quota file may be corrupted 0x2000 SBI_IS_RESIZEFS resizefs is in process + 0x4000 SBI_IS_FREEZING freefs is in process ====== ===================== ================================= What: /sys/fs/f2fs/<disk>/ckpt_thread_ioprio @@ -498,7 +537,7 @@ Date: July 2021 Contact: "Daeho Jeong" <daehojeong@google.com> Description: Show how many segments have been reclaimed by GC during a specific GC mode (0: GC normal, 1: GC idle CB, 2: GC idle greedy, - 3: GC idle AT, 4: GC urgent high, 5: GC urgent low) + 3: GC idle AT, 4: GC urgent high, 5: GC urgent low 6: GC urgent mid) You can re-initialize this value to "0". What: /sys/fs/f2fs/<disk>/gc_segment_mode @@ -528,3 +567,16 @@ Description: With "mode=fragment:block" mount options, we can scatter block allo f2fs will allocate 1..<max_fragment_chunk> blocks in a chunk and make a hole in the length of 1..<max_fragment_hole> by turns. This value can be set between 1..512 and the default value is 4. + +What: /sys/fs/f2fs/<disk>/gc_urgent_high_remaining +Date: December 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: You can set the trial count limit for GC urgent high mode with this value. + If GC thread gets to the limit, the mode will turn back to GC normal mode. + By default, the value is zero, which means there is no limit like before. + +What: /sys/fs/f2fs/<disk>/max_roll_forward_node_blocks +Date: January 2022 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: Controls max # of node block writes to be used for roll forward + recovery. This can limit the roll forward recovery time. diff --git a/Documentation/ABI/testing/sysfs-fs-ubifs b/Documentation/ABI/testing/sysfs-fs-ubifs new file mode 100644 index 000000000000..af5afda30220 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-ubifs @@ -0,0 +1,35 @@ +What: /sys/fs/ubifsX_Y/error_magic +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes magic errors: every node starts with a magic number. + + This counter keeps track of the number of accesses of nodes + with a corrupted magic number. + + The counter is reset to 0 with a remount. + +What: /sys/fs/ubifsX_Y/error_node +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes node errors. Every node embeds its type. + + This counter keeps track of the number of accesses of nodes + with a corrupted node type. + + The counter is reset to 0 with a remount. + +What: /sys/fs/ubifsX_Y/error_crc +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes crc errors: every node embeds a crc checksum. + + This counter keeps track of the number of accesses of nodes + with a bad crc checksum. + + The counter is reset to 0 with a remount. diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon new file mode 100644 index 000000000000..9e282065cbcf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -0,0 +1,274 @@ +what: /sys/kernel/mm/damon/ +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Interface for Data Access MONitoring (DAMON). Contains files + for controlling DAMON. For more details on DAMON itself, + please refer to Documentation/admin-guide/mm/damon/index.rst. + +What: /sys/kernel/mm/damon/admin/ +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Interface for privileged users of DAMON. Contains files for + controlling DAMON that aimed to be used by privileged users. + +What: /sys/kernel/mm/damon/admin/kdamonds/nr_kdamonds +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for controlling each DAMON worker thread (kdamond) + named '0' to 'N-1' under the kdamonds/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/state +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing 'on' or 'off' to this file makes the kdamond starts or + stops, respectively. Reading the file returns the keywords + based on the current status. Writing 'update_schemes_stats' to + the file updates contents of schemes stats files of the + kdamond. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/pid +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the pid of the kdamond if it is + running. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/nr_contexts +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for controlling each DAMON context named '0' to + 'N-1' under the contexts/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/operations +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a keyword for a monitoring operations set ('vaddr' for + virtual address spaces monitoring, and 'paddr' for the physical + address space monitoring) to this file makes the context to use + the operations set. Reading the file returns the keyword for + the operations set the context is set to use. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/sample_us +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the sampling interval of the + DAMON context in microseconds as the value. Reading this file + returns the value. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/aggr_us +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the aggregation interval of + the DAMON context in microseconds as the value. Reading this + file returns the value. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/update_us +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the update interval of the + DAMON context in microseconds as the value. Reading this file + returns the value. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min + +WDate: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the minimum number of + monitoring regions of the DAMON context as the value. Reading + this file returns the value. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/max +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the maximum number of + monitoring regions of the DAMON context as the value. Reading + this file returns the value. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/nr_targets +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for controlling each DAMON target of the context + named '0' to 'N-1' under the contexts/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/pid_target +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the pid of + the target process if the context is for virtual address spaces + monitoring, respectively. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/nr_regions +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for setting each DAMON target memory region of the + context named '0' to 'N-1' under the regions/ directory. In + case of the virtual address space monitoring, DAMON + automatically sets the target memory region based on the target + processes' mappings. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/start +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the start + address of the monitoring region. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/end +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the end + address of the monitoring region. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/nr_schemes +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for controlling each DAMON-based operation scheme + of the context named '0' to 'N-1' under the schemes/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/action +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the action + of the scheme. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the mimimum + size of the scheme's target regions in bytes. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the maximum + size of the scheme's target regions in bytes. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/min +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the manimum + 'nr_accesses' of the scheme's target regions. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the maximum + 'nr_accesses' of the scheme's target regions. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/min +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the minimum + 'age' of the scheme's target regions. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the maximum + 'age' of the scheme's target regions. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the time + quota of the scheme in milliseconds. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the size + quota of the scheme in bytes. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the quotas + charge reset interval of the scheme in milliseconds. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the + under-quota limit regions prioritization weight for 'size' in + permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_permil +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the + under-quota limit regions prioritization weight for + 'nr_accesses' in permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the + under-quota limit regions prioritization weight for 'age' in + permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the metric + of the watermarks for the scheme. The writable/readable + keywords for this file are 'none' for disabling the watermarks + feature, or 'free_mem_rate' for the system's global free memory + rate in permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the metric + check interval of the watermarks for the scheme in + microseconds. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the high + watermark of the scheme in permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the mid + watermark of the scheme in permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing to and reading from this file sets and gets the low + watermark of the scheme in permil. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the number of regions that the action + of the scheme has tried to be applied. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the total size of regions that the + action of the scheme has tried to be applied in bytes. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the number of regions that the action + of the scheme has successfully applied. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the total size of regions that the + action of the scheme has successfully applied in bytes. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds +Date: Mar 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the number of the exceed events of + the scheme's quotas. diff --git a/Documentation/Makefile b/Documentation/Makefile index c3feb657b654..64d44c1ecad3 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -19,12 +19,14 @@ endif SPHINXBUILD = sphinx-build SPHINXOPTS = SPHINXDIRS = . +DOCS_THEME = +DOCS_CSS = _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output PDFLATEX = xelatex -LATEXOPTS = -interaction=batchmode +LATEXOPTS = -interaction=batchmode -no-shell-escape ifeq ($(KBUILD_VERBOSE),0) SPHINXOPTS += "-q" @@ -84,7 +86,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ $(ALLSPHINXOPTS) \ $(abspath $(srctree)/$(src)/$5) \ - $(abspath $(BUILDDIR)/$3/$4) + $(abspath $(BUILDDIR)/$3/$4) && \ + if [ "x$(DOCS_CSS)" != "x" ]; then \ + cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ + fi htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @@ -154,4 +159,8 @@ dochelp: @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' @echo ' configuration. This is e.g. useful to build with nit-picking config.' @echo + @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' + @echo + @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' + @echo @echo ' Default location for the generated documents is Documentation/output' diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg index 98af66557908..16b1ff0ad38c 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg index e0184a37aec7..684a4b969725 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg index 1bc3fed54d58..8fb2454d9544 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg index 6d8a1bffb3e4..5d4f22d5662c 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg index 44018fd6342b..b89b02869914 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg index e5eef50454fb..90f1c77bea2f 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg index fbd2c1892886..3e5651da031a 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg index 502e159ed278..9483f08d345e 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg index 677401551c7d..1101ec30e604 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg index 4b4014fda770..87851a8fac1e 100644 --- a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg +++ b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg @@ -88,7 +88,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -103,7 +103,7 @@ id="text2993" y="-261.66608" x="412.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -135,7 +135,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="268.18076" id="text4429" @@ -146,7 +146,7 @@ y="268.18076">WRITE_ONCE(a, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="439.13766" id="text4441" @@ -157,7 +157,7 @@ y="439.13766">WRITE_ONCE(b, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.60869" y="309.29346" id="text4445" @@ -168,7 +168,7 @@ y="309.29346">r1 = READ_ONCE(a);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.14423" y="520.61786" id="text4449" @@ -179,7 +179,7 @@ y="520.61786">WRITE_ONCE(c, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="384.71124" id="text4453" @@ -190,7 +190,7 @@ y="384.71124">r2 = READ_ONCE(b);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="582.13617" id="text4457" @@ -201,7 +201,7 @@ y="582.13617">r3 = READ_ONCE(c);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.08231" y="213.91006" id="text4461" @@ -212,7 +212,7 @@ y="213.91006">thread0()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="252.34512" y="213.91006" id="text4461-6" @@ -223,7 +223,7 @@ y="213.91006">thread1()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.42557" y="213.91006" id="text4461-2" @@ -251,7 +251,7 @@ inkscape:connector-curvature="0" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="251.53981" id="text4429-8" @@ -262,7 +262,7 @@ y="251.53981">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="367.91556" id="text4429-8-9" @@ -273,7 +273,7 @@ y="367.91556">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="597.40289" id="text4429-8-9-3" @@ -284,7 +284,7 @@ y="597.40289">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="453.15311" id="text4429-8-9-3-1" @@ -300,7 +300,7 @@ inkscape:connector-curvature="0" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="394.94427" y="345.66351" id="text4648" @@ -324,7 +324,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.11968" y="475.77856" id="text4648-4" @@ -361,7 +361,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="254.85066" y="348.96619" id="text4648-4-3" diff --git a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg index 48cd1623d4d4..e2a8af592bab 100644 --- a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg +++ b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -131,7 +131,7 @@ id="text2993" y="-261.66608" x="436.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -163,7 +163,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="268.18076" id="text4429" @@ -174,7 +174,7 @@ y="268.18076">WRITE_ONCE(a, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="487.13766" id="text4441" @@ -185,7 +185,7 @@ y="487.13766">WRITE_ONCE(b, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.60869" y="297.29346" id="text4445" @@ -196,7 +196,7 @@ y="297.29346">r1 = READ_ONCE(a);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.14423" y="554.61786" id="text4449" @@ -207,7 +207,7 @@ y="554.61786">WRITE_ONCE(c, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="370.71124" id="text4453" @@ -218,7 +218,7 @@ y="370.71124">WRITE_ONCE(d, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="572.13617" id="text4457" @@ -229,7 +229,7 @@ y="572.13617">r2 = READ_ONCE(c);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.08231" y="213.91006" id="text4461" @@ -240,7 +240,7 @@ y="213.91006">thread0()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="252.34512" y="213.91006" id="text4461-6" @@ -251,7 +251,7 @@ y="213.91006">thread1()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.42557" y="213.91006" id="text4461-2" @@ -281,7 +281,7 @@ sodipodi:nodetypes="cc" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="251.53981" id="text4429-8" @@ -292,7 +292,7 @@ y="251.53981">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="353.91556" id="text4429-8-9" @@ -303,7 +303,7 @@ y="353.91556">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="587.40289" id="text4429-8-9-3" @@ -314,7 +314,7 @@ y="587.40289">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="501.15311" id="text4429-8-9-3-1" @@ -331,7 +331,7 @@ sodipodi:nodetypes="cc" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="394.94427" y="331.66351" id="text4648" @@ -355,7 +355,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.11968" y="523.77856" id="text4648-4" @@ -392,7 +392,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="254.85066" y="336.96619" id="text4648-4-3" @@ -421,7 +421,7 @@ id="text2993-7" y="-261.66608" x="440.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -453,7 +453,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="541.70508" y="387.6217" id="text4445-0" @@ -464,7 +464,7 @@ y="387.6217">r3 = READ_ONCE(d);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="541.2406" y="646.94611" id="text4449-6" @@ -488,7 +488,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="540.94702" y="427.29443" id="text4648-4-3-1" @@ -499,7 +499,7 @@ y="427.29443">QS</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="461.83929" id="text4453-7" @@ -510,7 +510,7 @@ y="461.83929">r4 = READ_ONCE(b);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="669.26422" id="text4457-9" @@ -521,7 +521,7 @@ y="669.26422">r5 = READ_ONCE(e);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="445.04358" id="text4429-8-9-33" @@ -532,7 +532,7 @@ y="445.04358">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="684.53094" id="text4429-8-9-3-8" @@ -543,7 +543,7 @@ y="684.53094">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="685.11914" y="422.79153" id="text4648-9" @@ -567,7 +567,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="397.85934" y="609.59003" id="text4648-5" @@ -591,7 +591,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="256.75986" y="586.99133" id="text4648-5-2" @@ -615,7 +615,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="546.22791" y="213.91006" id="text4461-2-5" @@ -626,7 +626,7 @@ y="213.91006">thread3()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="684.00067" y="213.91006" id="text4461-2-1" diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index 28f8ad16db25..78404625bad2 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -254,17 +254,6 @@ period (in this case 2603), the grace-period sequence number (7075), and an estimate of the total number of RCU callbacks queued across all CPUs (625 in this case). -In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed -for each CPU:: - - 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1 - -The "last_accelerate:" prints the low-order 16 bits (in hex) of the -jiffies counter when this CPU last invoked rcu_try_advance_all_cbs() -from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from -rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle -processing is enabled. - If the grace period ends just as the stall warning starts printing, there will be a spurious stall-warning message, which will include the following:: diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 17e95ab2a201..c34d2212eaca 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -39,9 +39,11 @@ different paths, as follows: :ref:`6. ANALOGY WITH READER-WRITER LOCKING <6_whatisRCU>` -:ref:`7. FULL LIST OF RCU APIs <7_whatisRCU>` +:ref:`7. ANALOGY WITH REFERENCE COUNTING <7_whatisRCU>` -:ref:`8. ANSWERS TO QUICK QUIZZES <8_whatisRCU>` +:ref:`8. FULL LIST OF RCU APIs <8_whatisRCU>` + +:ref:`9. ANSWERS TO QUICK QUIZZES <9_whatisRCU>` People who prefer starting with a conceptual overview should focus on Section 1, though most readers will profit by reading this section at @@ -677,7 +679,7 @@ Quick Quiz #1: occur when using this algorithm in a real-world Linux kernel? How could this deadlock be avoided? -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` 5B. "TOY" EXAMPLE #2: CLASSIC RCU ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -732,7 +734,7 @@ Quick Quiz #2: Give an example where Classic RCU's read-side overhead is **negative**. -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` .. _quiz_3: @@ -741,7 +743,7 @@ Quick Quiz #3: critical section, what the heck do you do in CONFIG_PREEMPT_RT, where normal spinlocks can block??? -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` .. _6_whatisRCU: @@ -872,7 +874,79 @@ be used in place of synchronize_rcu(). .. _7_whatisRCU: -7. FULL LIST OF RCU APIs +7. ANALOGY WITH REFERENCE COUNTING +----------------------------------- + +The reader-writer analogy (illustrated by the previous section) is not +always the best way to think about using RCU. Another helpful analogy +considers RCU an effective reference count on everything which is +protected by RCU. + +A reference count typically does not prevent the referenced object's +values from changing, but does prevent changes to type -- particularly the +gross change of type that happens when that object's memory is freed and +re-allocated for some other purpose. Once a type-safe reference to the +object is obtained, some other mechanism is needed to ensure consistent +access to the data in the object. This could involve taking a spinlock, +but with RCU the typical approach is to perform reads with SMP-aware +operations such as smp_load_acquire(), to perform updates with atomic +read-modify-write operations, and to provide the necessary ordering. +RCU provides a number of support functions that embed the required +operations and ordering, such as the list_for_each_entry_rcu() macro +used in the previous section. + +A more focused view of the reference counting behavior is that, +between rcu_read_lock() and rcu_read_unlock(), any reference taken with +rcu_dereference() on a pointer marked as ``__rcu`` can be treated as +though a reference-count on that object has been temporarily increased. +This prevents the object from changing type. Exactly what this means +will depend on normal expectations of objects of that type, but it +typically includes that spinlocks can still be safely locked, normal +reference counters can be safely manipulated, and ``__rcu`` pointers +can be safely dereferenced. + +Some operations that one might expect to see on an object for +which an RCU reference is held include: + + - Copying out data that is guaranteed to be stable by the object's type. + - Using kref_get_unless_zero() or similar to get a longer-term + reference. This may fail of course. + - Acquiring a spinlock in the object, and checking if the object still + is the expected object and if so, manipulating it freely. + +The understanding that RCU provides a reference that only prevents a +change of type is particularly visible with objects allocated from a +slab cache marked ``SLAB_TYPESAFE_BY_RCU``. RCU operations may yield a +reference to an object from such a cache that has been concurrently +freed and the memory reallocated to a completely different object, +though of the same type. In this case RCU doesn't even protect the +identity of the object from changing, only its type. So the object +found may not be the one expected, but it will be one where it is safe +to take a reference or spinlock and then confirm that the identity +matches the expectations. + +With traditional reference counting -- such as that implemented by the +kref library in Linux -- there is typically code that runs when the last +reference to an object is dropped. With kref, this is the function +passed to kref_put(). When RCU is being used, such finalization code +must not be run until all ``__rcu`` pointers referencing the object have +been updated, and then a grace period has passed. Every remaining +globally visible pointer to the object must be considered to be a +potential counted reference, and the finalization code is typically run +using call_rcu() only after all those pointers have been changed. + +To see how to choose between these two analogies -- of RCU as a +reader-writer lock and RCU as a reference counting system -- it is useful +to reflect on the scale of the thing being protected. The reader-writer +lock analogy looks at larger multi-part objects such as a linked list +and shows how RCU can facilitate concurrency while elements are added +to, and removed from, the list. The reference-count analogy looks at +the individual objects and looks at how they can be accessed safely +within whatever whole they are a part of. + +.. _8_whatisRCU: + +8. FULL LIST OF RCU APIs ------------------------- The RCU APIs are documented in docbook-format header comments in the @@ -1035,9 +1109,9 @@ g. Otherwise, use RCU. Of course, this all assumes that you have determined that RCU is in fact the right tool for your job. -.. _8_whatisRCU: +.. _9_whatisRCU: -8. ANSWERS TO QUICK QUIZZES +9. ANSWERS TO QUICK QUIZZES ---------------------------- Quick Quiz #1: diff --git a/Documentation/accounting/delay-accounting.rst b/Documentation/accounting/delay-accounting.rst index 1b8b46deeb29..197fe319cbec 100644 --- a/Documentation/accounting/delay-accounting.rst +++ b/Documentation/accounting/delay-accounting.rst @@ -13,6 +13,8 @@ a) waiting for a CPU (while being runnable) b) completion of synchronous block I/O initiated by the task c) swapping in pages d) memory reclaim +e) thrashing page cache +f) direct compact and makes these statistics available to userspace through the taskstats interface. @@ -41,11 +43,12 @@ generic data structure to userspace corresponding to per-pid and per-tgid statistics. The delay accounting functionality populates specific fields of this structure. See - include/linux/taskstats.h + include/uapi/linux/taskstats.h for a description of the fields pertaining to delay accounting. It will generally be in the form of counters returning the cumulative -delay seen for cpu, sync block I/O, swapin, memory reclaim etc. +delay seen for cpu, sync block I/O, swapin, memory reclaim, thrash page +cache, direct compact etc. Taking the difference of two successive readings of a given counter (say cpu_delay_total) for a task will give the delay @@ -88,41 +91,37 @@ seen. General format of the getdelays command:: - getdelays [-t tgid] [-p pid] [-c cmd...] - + getdelays [-dilv] [-t tgid] [-p pid] Get delays, since system boot, for pid 10:: - # ./getdelays -p 10 + # ./getdelays -d -p 10 (output similar to next case) Get sum of delays, since system boot, for all pids with tgid 5:: - # ./getdelays -t 5 - - - CPU count real total virtual total delay total - 7876 92005750 100000000 24001500 - IO count delay total - 0 0 - SWAP count delay total - 0 0 - RECLAIM count delay total - 0 0 + # ./getdelays -d -t 5 + print delayacct stats ON + TGID 5 -Get delays seen in executing a given simple command:: - # ./getdelays -c ls / + CPU count real total virtual total delay total delay average + 8 7000000 6872122 3382277 0.423ms + IO count delay total delay average + 0 0 0ms + SWAP count delay total delay average + 0 0 0ms + RECLAIM count delay total delay average + 0 0 0ms + THRASHING count delay total delay average + 0 0 0ms + COMPACT count delay total delay average + 0 0 0ms - bin data1 data3 data5 dev home media opt root srv sys usr - boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var +Get IO accounting for pid 1, it works only with -p:: + # ./getdelays -i -p 1 + printing IO accounting + linuxrc: read=65536, write=0, cancelled_write=0 - CPU count real total virtual total delay total - 6 4000250 4000000 0 - IO count delay total - 0 0 - SWAP count delay total - 0 0 - RECLAIM count delay total - 0 0 +The above command can be used with -v to get more debug information. diff --git a/Documentation/accounting/psi.rst b/Documentation/accounting/psi.rst index f2b3439edcc2..860fe651d645 100644 --- a/Documentation/accounting/psi.rst +++ b/Documentation/accounting/psi.rst @@ -92,7 +92,8 @@ Triggers can be set on more than one psi metric and more than one trigger for the same psi metric can be specified. However for each trigger a separate file descriptor is required to be able to poll it separately from others, therefore for each trigger a separate open() syscall should be made even -when opening the same psi interface file. +when opening the same psi interface file. Write operations to a file descriptor +with an already existing psi trigger will fail with EBUSY. Monitors activate only when system enters stall state for the monitored psi metric and deactivates upon exit from the stall state. While system is diff --git a/Documentation/admin-guide/acpi/fan_performance_states.rst b/Documentation/admin-guide/acpi/fan_performance_states.rst index 98fe5c333121..b9e4b4d146c1 100644 --- a/Documentation/admin-guide/acpi/fan_performance_states.rst +++ b/Documentation/admin-guide/acpi/fan_performance_states.rst @@ -60,3 +60,31 @@ For example:: When a given field is not populated or its value provided by the platform firmware is invalid, the "not-defined" string is shown instead of the value. + +ACPI Fan Fine Grain Control +============================= + +When _FIF object specifies support for fine grain control, then fan speed +can be set from 0 to 100% with the recommended minimum "step size" via +_FSL object. User can adjust fan speed using thermal sysfs cooling device. + +Here use can look at fan performance states for a reference speed (speed_rpm) +and set it by changing cooling device cur_state. If the fine grain control +is supported then user can also adjust to some other speeds which are +not defined in the performance states. + +The support of fine grain control is presented via sysfs attribute +"fine_grain_control". If fine grain control is present, this attribute +will show "1" otherwise "0". + +This sysfs attribute is presented in the same directory as performance states. + +ACPI Fan Performance Feedback +============================= + +The optional _FST object provides status information for the fan device. +This includes field to provide current fan speed in revolutions per minute +at which the fan is rotating. + +This speed is presented in the sysfs using the attribute "fan_speed_rpm", +in the same directory as performance states. diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst index 3e11926a4df9..54fe63745ed8 100644 --- a/Documentation/admin-guide/blockdev/zram.rst +++ b/Documentation/admin-guide/blockdev/zram.rst @@ -315,8 +315,8 @@ To use the feature, admin should set up backing device via:: echo /dev/sda5 > /sys/block/zramX/backing_dev -before disksize setting. It supports only partition at this moment. -If admin wants to use incompressible page writeback, they could do via:: +before disksize setting. It supports only partitions at this moment. +If admin wants to use incompressible page writeback, they could do it via:: echo huge > /sys/block/zramX/writeback @@ -341,9 +341,9 @@ Admin can request writeback of those idle pages at right timing via:: echo idle > /sys/block/zramX/writeback -With the command, zram writeback idle pages from memory to the storage. +With the command, zram will writeback idle pages from memory to the storage. -If admin want to write a specific page in zram device to backing device, +If an admin wants to write a specific page in zram device to the backing device, they could write a page index into the interface. echo "page_index=1251" > /sys/block/zramX/writeback @@ -354,7 +354,7 @@ to guarantee storage health for entire product life. To overcome the concern, zram supports "writeback_limit" feature. The "writeback_limit_enable"'s default value is 0 so that it doesn't limit -any writeback. IOW, if admin wants to apply writeback budget, he should +any writeback. IOW, if admin wants to apply writeback budget, they should enable writeback_limit_enable via:: $ echo 1 > /sys/block/zramX/writeback_limit_enable @@ -365,7 +365,7 @@ until admin sets the budget via /sys/block/zramX/writeback_limit. (If admin doesn't enable writeback_limit_enable, writeback_limit's value assigned via /sys/block/zramX/writeback_limit is meaningless.) -If admin want to limit writeback as per-day 400M, he could do it +If admin wants to limit writeback as per-day 400M, they could do it like below:: $ MB_SHIFT=20 @@ -375,16 +375,16 @@ like below:: $ echo 1 > /sys/block/zram0/writeback_limit_enable If admins want to allow further write again once the budget is exhausted, -he could do it like below:: +they could do it like below:: $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ /sys/block/zram0/writeback_limit -If admin wants to see remaining writeback budget since last set:: +If an admin wants to see the remaining writeback budget since last set:: $ cat /sys/block/zramX/writeback_limit -If admin want to disable writeback limit, he could do:: +If an admin wants to disable writeback limit, they could do:: $ echo 0 > /sys/block/zramX/writeback_limit_enable @@ -393,7 +393,7 @@ system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of writeback happened until you reset the zram to allocate extra writeback budget in next setting is user's job. -If admin wants to measure writeback count in a certain period, he could +If admin wants to measure writeback count in a certain period, they could know it via /sys/block/zram0/bd_stat's 3rd column. memory tracking diff --git a/Documentation/admin-guide/cgroup-v1/hugetlb.rst b/Documentation/admin-guide/cgroup-v1/hugetlb.rst index 338f2c7d7a1c..0fa724d82abb 100644 --- a/Documentation/admin-guide/cgroup-v1/hugetlb.rst +++ b/Documentation/admin-guide/cgroup-v1/hugetlb.rst @@ -29,12 +29,14 @@ Brief summary of control files:: hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB usage limit + hugetlb.<hugepagesize>.numa_stat # show the numa information of the hugetlb memory charged to this cgroup For a system supporting three hugepage sizes (64k, 32M and 1G), the control files include:: hugetlb.1GB.limit_in_bytes hugetlb.1GB.max_usage_in_bytes + hugetlb.1GB.numa_stat hugetlb.1GB.usage_in_bytes hugetlb.1GB.failcnt hugetlb.1GB.rsvd.limit_in_bytes @@ -43,6 +45,7 @@ files include:: hugetlb.1GB.rsvd.failcnt hugetlb.64KB.limit_in_bytes hugetlb.64KB.max_usage_in_bytes + hugetlb.64KB.numa_stat hugetlb.64KB.usage_in_bytes hugetlb.64KB.failcnt hugetlb.64KB.rsvd.limit_in_bytes @@ -51,6 +54,7 @@ files include:: hugetlb.64KB.rsvd.failcnt hugetlb.32MB.limit_in_bytes hugetlb.32MB.max_usage_in_bytes + hugetlb.32MB.numa_stat hugetlb.32MB.usage_in_bytes hugetlb.32MB.failcnt hugetlb.32MB.rsvd.limit_in_bytes diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index faac50149a22..2cc502a75ef6 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -64,6 +64,7 @@ Brief summary of control files. threads cgroup.procs show list of processes cgroup.event_control an interface for event_fd() + This knob is not available on CONFIG_PREEMPT_RT systems. memory.usage_in_bytes show current usage for memory (See 5.5 for details) memory.memsw.usage_in_bytes show current usage for memory+Swap @@ -75,6 +76,7 @@ Brief summary of control files. memory.max_usage_in_bytes show max memory usage recorded memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded memory.soft_limit_in_bytes set/show soft limit of memory usage + This knob is not available on CONFIG_PREEMPT_RT systems. memory.stat show various statistics memory.use_hierarchy set/show hierarchical account enabled This knob is deprecated and shouldn't be diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 2aeb7ae8b393..69d7a6983f78 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1268,6 +1268,9 @@ PAGE_SIZE multiple when read back. The number of processes belonging to this cgroup killed by any kind of OOM killer. + oom_group_kill + The number of times a group OOM has occurred. + memory.events.local Similar to memory.events but the fields in the file are local to the cgroup i.e. not hierarchical. The file modified event @@ -1298,6 +1301,11 @@ PAGE_SIZE multiple when read back. Amount of memory used to cache filesystem data, including tmpfs and shared memory. + kernel (npn) + Amount of total kernel memory, including + (kernel_stack, pagetables, percpu, vmalloc, slab) in + addition to other kernel memory use cases. + kernel_stack Amount of memory allocated to kernel stacks. @@ -1311,6 +1319,9 @@ PAGE_SIZE multiple when read back. sock (npn) Amount of memory used in network transmission buffers + vmalloc (npn) + Amount of memory used for vmap backed memory. + shmem Amount of cached filesystem data that is swap-backed, such as tmpfs, shm segments, shared anonymous mmap()s @@ -2260,6 +2271,11 @@ HugeTLB Interface Files are local to the cgroup i.e. not hierarchical. The file modified event generated on this file reflects only the local events. + hugetlb.<hugepagesize>.numa_stat + Similar to memory.numa_stat, it shows the numa information of the + hugetlb pages of <hugepagesize> in this cgroup. Only active in + use hugetlb pages are included. The per-node values are in bytes. + Misc ---- diff --git a/Documentation/admin-guide/cputopology.rst b/Documentation/admin-guide/cputopology.rst index 6b62e182baf4..d29cacc9b3c3 100644 --- a/Documentation/admin-guide/cputopology.rst +++ b/Documentation/admin-guide/cputopology.rst @@ -8,11 +8,9 @@ to /proc/cpuinfo output of some architectures. They reside in Documentation/ABI/stable/sysfs-devices-system-cpu. Architecture-neutral, drivers/base/topology.c, exports these attributes. -However, the book and drawer related sysfs files will only be created if -CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively. - -CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390, -where they reflect the cpu and cache hierarchy. +However the die, cluster, book, and drawer hierarchy related sysfs files will +only be created if an architecture provides the related macros as described +below. For an architecture to support this feature, it must define some of these macros in include/asm-XXX/topology.h:: @@ -43,15 +41,14 @@ not defined by include/asm-XXX/topology.h: 2) topology_die_id: -1 3) topology_cluster_id: -1 4) topology_core_id: 0 -5) topology_sibling_cpumask: just the given CPU -6) topology_core_cpumask: just the given CPU -7) topology_cluster_cpumask: just the given CPU -8) topology_die_cpumask: just the given CPU - -For architectures that don't support books (CONFIG_SCHED_BOOK) there are no -default definitions for topology_book_id() and topology_book_cpumask(). -For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are -no default definitions for topology_drawer_id() and topology_drawer_cpumask(). +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: just the given CPU +8) topology_core_cpumask: just the given CPU +9) topology_cluster_cpumask: just the given CPU +10) topology_die_cpumask: just the given CPU +11) topology_book_cpumask: just the given CPU +12) topology_drawer_cpumask: just the given CPU Additionally, CPU topology information is provided under /sys/devices/system/cpu and includes these files. The internal diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst new file mode 100644 index 000000000000..d8a90c81b9ee --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-sim.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Configfs GPIO Simulator +======================= + +The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO +chips for testing purposes. The lines exposed by these chips can be accessed +using the standard GPIO character device interface as well as manipulated +using sysfs attributes. + +Creating simulated chips +------------------------ + +The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For +details of the configfs filesystem, please refer to the configfs documentation. + +The user can create a hierarchy of configfs groups and items as well as modify +values of exposed attributes. Once the chip is instantiated, this hierarchy +will be translated to appropriate device properties. The general structure is: + +**Group:** ``/config/gpio-sim`` + +This is the top directory of the gpio-sim configfs tree. + +**Group:** ``/config/gpio-sim/gpio-device`` + +**Attribute:** ``/config/gpio-sim/gpio-device/dev_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/live`` + +This is a directory representing a GPIO platform device. The ``'dev_name'`` +attribute is read-only and allows the user-space to read the platform device +name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the +actual creation of the device once it's fully configured. The accepted values +are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear +it down. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines`` + +This group represents a bank of GPIOs under the top platform device. The +``'chip_name'`` attribute is read-only and allows the user-space to read the +device name of the bank device. The ``'num_lines'`` attribute allows to specify +the number of lines exposed by this bank. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name`` + +This group represents a single line at the offset Y. The 'name' attribute +allows to set the line name as represented by the 'gpio-line-names' property. + +**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction`` + +This item makes the gpio-sim module hog the associated line. The ``'name'`` +attribute specifies the in-kernel consumer name to use. The ``'direction'`` +attribute specifies the hog direction and must be one of: ``'input'``, +``'output-high'`` and ``'output-low'``. + +Inside each bank directory, there's a set of attributes that can be used to +configure the new chip. Additionally the user can ``mkdir()`` subdirectories +inside the chip's directory that allow to pass additional configuration for +specific lines. The name of those subdirectories must take the form of: +``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be +used by the module to assign the config to the specific line at given offset. + +Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in +order to instantiate the chip. It can be set back to 0 to destroy the simulated +chip. The module will synchronously wait for the new simulated device to be +successfully probed and if this doesn't happen, writing to ``'live'`` will +result in an error. + +Simulated GPIO chips can also be defined in device-tree. The compatible string +must be: ``"gpio-simulator"``. Supported properties are: + + ``"gpio-sim,label"`` - chip label + +Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or +``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for +details. + +An example device-tree code defining a GPIO simulator: + +.. code-block :: none + + gpio-sim { + compatible = "gpio-simulator"; + + bank0 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <16>; + gpio-sim,label = "dt-bank0"; + gpio-line-names = "", "sim-foo", "", "sim-bar"; + }; + + bank1 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <8>; + gpio-sim,label = "dt-bank1"; + + line3 { + gpio-hog; + gpios = <3 0>; + output-high; + line-name = "sim-hog-from-dt"; + }; + }; + }; + +Manipulating simulated lines +---------------------------- + +Each simulated GPIO chip creates a separate sysfs group under its device +directory for each exposed line +(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group +is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each +group there are two attibutes: + + ``pull`` - allows to read and set the current simulated pull setting for + every line, when writing the value must be one of: ``'pull-up'``, + ``'pull-down'`` + + ``value`` - allows to read the current value of the line which may be + different from the pull if the line is being driven from + user-space diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index 7db367572f30..f6861ca16ffe 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -10,6 +10,7 @@ gpio gpio-aggregator sysfs gpio-mockup + gpio-sim .. only:: subproject and html diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index ab7d402c1677..9e9556826450 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -60,8 +60,8 @@ privileged data touched during the speculative execution. Spectre variant 1 attacks take advantage of speculative execution of conditional branches, while Spectre variant 2 attacks use speculative execution of indirect branches to leak privileged memory. -See :ref:`[1] <spec_ref1>` :ref:`[5] <spec_ref5>` :ref:`[7] <spec_ref7>` -:ref:`[10] <spec_ref10>` :ref:`[11] <spec_ref11>`. +See :ref:`[1] <spec_ref1>` :ref:`[5] <spec_ref5>` :ref:`[6] <spec_ref6>` +:ref:`[7] <spec_ref7>` :ref:`[10] <spec_ref10>` :ref:`[11] <spec_ref11>`. Spectre variant 1 (Bounds Check Bypass) --------------------------------------- @@ -131,6 +131,19 @@ steer its indirect branch speculations to gadget code, and measure the speculative execution's side effects left in level 1 cache to infer the victim's data. +Yet another variant 2 attack vector is for the attacker to poison the +Branch History Buffer (BHB) to speculatively steer an indirect branch +to a specific Branch Target Buffer (BTB) entry, even if the entry isn't +associated with the source address of the indirect branch. Specifically, +the BHB might be shared across privilege levels even in the presence of +Enhanced IBRS. + +Currently the only known real-world BHB attack vector is via +unprivileged eBPF. Therefore, it's highly recommended to not enable +unprivileged eBPF, especially when eIBRS is used (without retpolines). +For a full mitigation against BHB attacks, it's recommended to use +retpolines (or eIBRS combined with retpolines). + Attack scenarios ---------------- @@ -364,13 +377,15 @@ The possible values in this file are: - Kernel status: - ==================================== ================================= - 'Not affected' The processor is not vulnerable - 'Vulnerable' Vulnerable, no mitigation - 'Mitigation: Full generic retpoline' Software-focused mitigation - 'Mitigation: Full AMD retpoline' AMD-specific software mitigation - 'Mitigation: Enhanced IBRS' Hardware-focused mitigation - ==================================== ================================= + ======================================== ================================= + 'Not affected' The processor is not vulnerable + 'Mitigation: None' Vulnerable, no mitigation + 'Mitigation: Retpolines' Use Retpoline thunks + 'Mitigation: LFENCE' Use LFENCE instructions + 'Mitigation: Enhanced IBRS' Hardware-focused mitigation + 'Mitigation: Enhanced IBRS + Retpolines' Hardware-focused + Retpolines + 'Mitigation: Enhanced IBRS + LFENCE' Hardware-focused + LFENCE + ======================================== ================================= - Firmware status: Show if Indirect Branch Restricted Speculation (IBRS) is used to protect against Spectre variant 2 attacks when calling firmware (x86 only). @@ -468,7 +483,7 @@ Spectre variant 2 before invoking any firmware code to prevent Spectre variant 2 exploits using the firmware. - Using kernel address space randomization (CONFIG_RANDOMIZE_SLAB=y + Using kernel address space randomization (CONFIG_RANDOMIZE_BASE=y and CONFIG_SLAB_FREELIST_RANDOM=y in the kernel configuration) makes attacks on the kernel generally more difficult. @@ -583,12 +598,13 @@ kernel command line. Specific mitigations can also be selected manually: - retpoline - replace indirect branches - retpoline,generic - google's original retpoline - retpoline,amd - AMD-specific minimal thunk + retpoline auto pick between generic,lfence + retpoline,generic Retpolines + retpoline,lfence LFENCE; indirect branch + retpoline,amd alias for retpoline,lfence + eibrs enhanced IBRS + eibrs,retpoline enhanced IBRS + Retpolines + eibrs,lfence enhanced IBRS + LFENCE Not specifying this option is equivalent to spectre_v2=auto. @@ -599,7 +615,7 @@ kernel command line. spectre_v2=off. Spectre variant 1 mitigations cannot be disabled. -For spectre_v2_user see :doc:`/admin-guide/kernel-parameters`. +For spectre_v2_user see Documentation/admin-guide/kernel-parameters.txt Mitigation selection guide -------------------------- @@ -681,7 +697,7 @@ AMD white papers: .. _spec_ref6: -[6] `Software techniques for managing speculation on AMD processors <https://developer.amd.com/wp-content/resources/90343-B_SoftwareTechniquesforManagingSpeculation_WP_7-18Update_FNL.pdf>`_. +[6] `Software techniques for managing speculation on AMD processors <https://developer.amd.com/wp-content/resources/Managing-Speculation-on-AMD-Processors.pdf>`_. ARM white papers: diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 1bedab498104..5bfafcbb9562 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -35,6 +35,7 @@ problems and bugs in particular. :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect diff --git a/Documentation/admin-guide/iostats.rst b/Documentation/admin-guide/iostats.rst index 9b14b0c2c9c4..609a3201fd4e 100644 --- a/Documentation/admin-guide/iostats.rst +++ b/Documentation/admin-guide/iostats.rst @@ -76,7 +76,7 @@ Field 3 -- # of sectors read (unsigned long) Field 4 -- # of milliseconds spent reading (unsigned int) This is the total number of milliseconds spent by all reads (as - measured from __make_request() to end_that_request_last()). + measured from blk_mq_alloc_request() to __blk_mq_end_request()). Field 5 -- # of writes completed (unsigned long) This is the total number of writes completed successfully. @@ -89,7 +89,7 @@ Field 7 -- # of sectors written (unsigned long) Field 8 -- # of milliseconds spent writing (unsigned int) This is the total number of milliseconds spent by all writes (as - measured from __make_request() to end_that_request_last()). + measured from blk_mq_alloc_request() to __blk_mq_end_request()). Field 9 -- # of I/Os currently in progress (unsigned int) The only field that should go to zero. Incremented as requests are @@ -120,7 +120,7 @@ Field 14 -- # of sectors discarded (unsigned long) Field 15 -- # of milliseconds spent discarding (unsigned int) This is the total number of milliseconds spent by all discards (as - measured from __make_request() to end_that_request_last()). + measured from blk_mq_alloc_request() to __blk_mq_end_request()). Field 16 -- # of flush requests completed This is the total number of flush requests completed successfully. diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 3861a25faae1..8419019b6a88 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -494,6 +494,14 @@ architecture which is used to lookup the page-tables for the Virtual addresses in the higher VA range (refer to ARMv8 ARM document for more details). +MODULES_VADDR|MODULES_END|VMALLOC_START|VMALLOC_END|VMEMMAP_START|VMEMMAP_END +----------------------------------------------------------------------------- + +Used to get the correct ranges: + MODULES_VADDR ~ MODULES_END-1 : Kernel module space. + VMALLOC_START ~ VMALLOC_END-1 : vmalloc() / ioremap() space. + VMEMMAP_START ~ VMEMMAP_END-1 : vmemmap region, used for struct page array. + arm === diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 86e2b586c171..1a9f89a835b3 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -612,8 +612,8 @@ clocksource.max_cswd_read_retries= [KNL] Number of clocksource_watchdog() retries due to external delays before the clock will be marked - unstable. Defaults to three retries, that is, - four attempts to read the clock under test. + unstable. Defaults to two retries, that is, + three attempts to read the clock under test. clocksource.verify_n_cpus= [KNL] Limit the number of CPUs checked for clocksources @@ -950,6 +950,30 @@ dump out devices still on the deferred probe list after retrying. + dell_smm_hwmon.ignore_dmi= + [HW] Continue probing hardware even if DMI data + indicates that the driver is running on unsupported + hardware. + + dell_smm_hwmon.force= + [HW] Activate driver even if SMM BIOS signature does + not match list of supported models and enable otherwise + blacklisted features. + + dell_smm_hwmon.power_status= + [HW] Report power status in /proc/i8k + (disabled by default). + + dell_smm_hwmon.restricted= + [HW] Allow controlling fans only if SYS_ADMIN + capability is set. + + dell_smm_hwmon.fan_mult= + [HW] Factor to multiply fan speed with. + + dell_smm_hwmon.fan_max= + [HW] Maximum configurable fan speed. + dfltcc= [HW,S390] Format: { on | off | def_only | inf_only | always } on: s390 zlib hardware support for compression on @@ -1631,7 +1655,7 @@ [KNL] Reguires CONFIG_HUGETLB_PAGE_FREE_VMEMMAP enabled. Allows heavy hugetlb users to free up some more - memory (6 * PAGE_SIZE for each 2MB hugetlb page). + memory (7 * PAGE_SIZE for each 2MB hugetlb page). Format: { on | off (default) } on: enable the feature @@ -1709,17 +1733,6 @@ i810= [HW,DRM] - i8k.ignore_dmi [HW] Continue probing hardware even if DMI data - indicates that the driver is running on unsupported - hardware. - i8k.force [HW] Activate i8k driver even if SMM BIOS signature - does not match list of supported models. - i8k.power_status - [HW] Report power status in /proc/i8k - (disabled by default) - i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN - capability is set. - i915.invert_brightness= [DRM] Invert the sense of the variable that is used to set the brightness of the panel backlight. Normally a @@ -2833,6 +2846,9 @@ For details see: Documentation/admin-guide/hw-vuln/mds.rst + mem=nn[KMG] [HEXAGON] Set the memory size. + Must be specified, otherwise memory size will be 0. + mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory Amount of memory to be used in cases as follows: @@ -2840,6 +2856,13 @@ 2 when the kernel is not able to see the whole system memory; 3 memory that lies after 'mem=' boundary is excluded from the hypervisor, then assigned to KVM guests. + 4 to limit the memory available for kdump kernel. + + [ARC,MICROBLAZE] - the limit applies only to low memory, + high memory is not affected. + + [ARM64] - only limits memory covered by the linear + mapping. The NOMAP regions are not affected. [X86] Work as limiting max address. Use together with memmap= to avoid physical address space collisions. @@ -2850,6 +2873,14 @@ in above case 3, memory may need be hot added after boot if system memory of hypervisor is not sufficient. + mem=nn[KMG]@ss[KMG] + [ARM,MIPS] - override the memory layout reported by + firmware. + Define a memory region of size nn[KMG] starting at + ss[KMG]. + Multiple different regions can be specified with + multiple mem= parameters on the command line. + mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel memory. @@ -3399,7 +3430,7 @@ Disable SMAP (Supervisor Mode Access Prevention) even if it is supported by processor. - nosmep [X86,PPC] + nosmep [X86,PPC64s] Disable SMEP (Supervisor Mode Execution Prevention) even if it is supported by processor. @@ -4171,6 +4202,14 @@ Override pmtimer IOPort with a hex value. e.g. pmtmr=0x508 + pmu_override= [PPC] Override the PMU. + This option takes over the PMU facility, so it is no + longer usable by perf. Setting this option starts the + PMU counters by setting MMCR0 to 0 (the FC bit is + cleared). If a number is given, then MMCR1 is set to + that number, otherwise (e.g., 'pmu_override=on'), MMCR1 + remains 0. + pm_debug_messages [SUSPEND,KNL] Enable suspend/resume debug messages during boot up. @@ -4370,19 +4409,30 @@ Disable the Correctable Errors Collector, see CONFIG_RAS_CEC help text. - rcu_nocbs= [KNL] - The argument is a cpu list, as described above. - - In kernels built with CONFIG_RCU_NOCB_CPU=y, set - the specified list of CPUs to be no-callback CPUs. - Invocation of these CPUs' RCU callbacks will be - offloaded to "rcuox/N" kthreads created for that - purpose, where "x" is "p" for RCU-preempt, and - "s" for RCU-sched, and "N" is the CPU number. - This reduces OS jitter on the offloaded CPUs, - which can be useful for HPC and real-time - workloads. It can also improve energy efficiency - for asymmetric multiprocessors. + rcu_nocbs[=cpu-list] + [KNL] The optional argument is a cpu list, + as described above. + + In kernels built with CONFIG_RCU_NOCB_CPU=y, + enable the no-callback CPU mode, which prevents + such CPUs' callbacks from being invoked in + softirq context. Invocation of such CPUs' RCU + callbacks will instead be offloaded to "rcuox/N" + kthreads created for that purpose, where "x" is + "p" for RCU-preempt, "s" for RCU-sched, and "g" + for the kthreads that mediate grace periods; and + "N" is the CPU number. This reduces OS jitter on + the offloaded CPUs, which can be useful for HPC + and real-time workloads. It can also improve + energy efficiency for asymmetric multiprocessors. + + If a cpulist is passed as an argument, the specified + list of CPUs is set to no-callback mode from boot. + + Otherwise, if the '=' sign and the cpulist + arguments are omitted, no CPU will be set to + no-callback mode from boot but the mode may be + toggled at runtime via cpusets. rcu_nocb_poll [KNL] Rather than requiring that offloaded CPUs @@ -4490,6 +4540,8 @@ (the least-favored priority). Otherwise, when RCU_BOOST is not set, valid values are 0-99 and the default is zero (non-realtime operation). + When RCU_NOCB_CPU is set, also adjust the + priority of NOCB callback kthreads. rcutree.rcu_nocb_gp_stride= [KNL] Set the number of NOCB callback kthreads in @@ -4516,10 +4568,6 @@ on rcutree.qhimark at boot time and to zero to disable more aggressive help enlistment. - rcutree.rcu_idle_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - RCU callbacks (RCU_FAST_NO_HZ=y). - rcutree.rcu_kick_kthreads= [KNL] Cause the grace-period kthread to get an extra wake_up() if it sleeps three times longer than @@ -4630,8 +4678,12 @@ in seconds. rcutorture.fwd_progress= [KNL] - Enable RCU grace-period forward-progress testing + Specifies the number of kthreads to be used + for RCU grace-period forward-progress testing for the types of RCU supporting this notion. + Defaults to 1 kthread, values less than zero or + greater than the number of CPUs cause the number + of CPUs to be used. rcutorture.fwd_progress_div= [KNL] Specify the fraction of a CPU-stall-warning @@ -4832,6 +4884,29 @@ period to instead use normal non-expedited grace-period processing. + rcupdate.rcu_task_collapse_lim= [KNL] + Set the maximum number of callbacks present + at the beginning of a grace period that allows + the RCU Tasks flavors to collapse back to using + a single callback queue. This switching only + occurs when rcupdate.rcu_task_enqueue_lim is + set to the default value of -1. + + rcupdate.rcu_task_contend_lim= [KNL] + Set the minimum number of callback-queuing-time + lock-contention events per jiffy required to + cause the RCU Tasks flavors to switch to per-CPU + callback queuing. This switching only occurs + when rcupdate.rcu_task_enqueue_lim is set to + the default value of -1. + + rcupdate.rcu_task_enqueue_lim= [KNL] + Set the number of callback queues to use for the + RCU Tasks family of RCU flavors. The default + of -1 allows this to be automatically (and + dynamically) adjusted. This parameter is intended + for use in testing. + rcupdate.rcu_task_ipi_delay= [KNL] Set time in jiffies during which RCU tasks will avoid sending IPIs, starting with the beginning @@ -5324,8 +5399,12 @@ Specific mitigations can also be selected manually: retpoline - replace indirect branches - retpoline,generic - google's original retpoline - retpoline,amd - AMD-specific minimal thunk + retpoline,generic - Retpolines + retpoline,lfence - LFENCE; indirect branch + retpoline,amd - alias for retpoline,lfence + eibrs - enhanced IBRS + eibrs,retpoline - enhanced IBRS + Retpolines + eibrs,lfence - enhanced IBRS + LFENCE Not specifying this option is equivalent to spectre_v2=auto. @@ -6465,6 +6544,12 @@ controller on both pseries and powernv platforms. Only useful on POWER9 and above. + xive.store-eoi=off [PPC] + By default on POWER10 and above, the kernel will use + stores for EOI handling when the XIVE interrupt mode + is active. This option allows the XIVE driver to use + loads instead, as on POWER9. + xhci-hcd.quirks [USB,KNL] A hex value specifying bitmask with supplemental xhci host controller quirks. Meaning of each bit can be diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 5e51ee5b0358..e4a5fc26f1a9 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -208,7 +208,7 @@ Do at least one of the following: 2. Enable RCU to do its processing remotely via dyntick-idle by doing all of the following: - a. Build with CONFIG_NO_HZ=y and CONFIG_RCU_FAST_NO_HZ=y. + a. Build with CONFIG_NO_HZ=y. b. Ensure that the CPU goes idle frequently, allowing other CPUs to detect that it has passed through an RCU quiescent state. If the kernel is built with CONFIG_NO_HZ_FULL=y, diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst index fb9def3a7355..0af51a9705b1 100644 --- a/Documentation/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/admin-guide/mm/damon/reclaim.rst @@ -208,6 +208,31 @@ PID of the DAMON thread. If DAMON_RECLAIM is enabled, this becomes the PID of the worker thread. Else, -1. +nr_reclaim_tried_regions +------------------------ + +Number of memory regions that tried to be reclaimed by DAMON_RECLAIM. + +bytes_reclaim_tried_regions +--------------------------- + +Total bytes of memory regions that tried to be reclaimed by DAMON_RECLAIM. + +nr_reclaimed_regions +-------------------- + +Number of memory regions that successfully be reclaimed by DAMON_RECLAIM. + +bytes_reclaimed_regions +----------------------- + +Total bytes of memory regions that successfully be reclaimed by DAMON_RECLAIM. + +nr_quota_exceeds +---------------- + +Number of times that the time/space quota limits have exceeded. + Example ======= diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index ed96bbf0daff..592ea9a50881 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -4,47 +4,388 @@ Detailed Usages =============== -DAMON provides below three interfaces for different users. +DAMON provides below interfaces for different users. - *DAMON user space tool.* - This is for privileged people such as system administrators who want a - just-working human-friendly interface. Using this, users can use the DAMON’s - major features in a human-friendly way. It may not be highly tuned for - special cases, though. It supports both virtual and physical address spaces - monitoring. + `This <https://github.com/awslabs/damo>`_ is for privileged people such as + system administrators who want a just-working human-friendly interface. + Using this, users can use the DAMON’s major features in a human-friendly way. + It may not be highly tuned for special cases, though. It supports both + virtual and physical address spaces monitoring. For more detail, please + refer to its `usage document + <https://github.com/awslabs/damo/blob/next/USAGE.md>`_. +- *sysfs interface.* + :ref:`This <sysfs_interface>` is for privileged user space programmers who + want more optimized use of DAMON. Using this, users can use DAMON’s major + features by reading from and writing to special sysfs files. Therefore, + you can write and use your personalized DAMON sysfs wrapper programs that + reads/writes the sysfs files instead of you. The `DAMON user space tool + <https://github.com/awslabs/damo>`_ is one example of such programs. It + supports both virtual and physical address spaces monitoring. Note that this + interface provides only simple :ref:`statistics <damos_stats>` for the + monitoring results. For detailed monitoring results, DAMON provides a + :ref:`tracepoint <tracepoint>`. - *debugfs interface.* - This is for privileged user space programmers who want more optimized use of - DAMON. Using this, users can use DAMON’s major features by reading - from and writing to special debugfs files. Therefore, you can write and use - your personalized DAMON debugfs wrapper programs that reads/writes the - debugfs files instead of you. The DAMON user space tool is also a reference - implementation of such programs. It supports both virtual and physical - address spaces monitoring. + :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface + <sysfs_interface>`. This will be removed after next LTS kernel is released, + so users should move to the :ref:`sysfs interface <sysfs_interface>`. - *Kernel Space Programming Interface.* - This is for kernel space programmers. Using this, users can utilize every - feature of DAMON most flexibly and efficiently by writing kernel space - DAMON application programs for you. You can even extend DAMON for various - address spaces. + :doc:`This </vm/damon/api>` is for kernel space programmers. Using this, + users can utilize every feature of DAMON most flexibly and efficiently by + writing kernel space DAMON application programs for you. You can even extend + DAMON for various address spaces. For detail, please refer to the interface + :doc:`document </vm/damon/api>`. -Nevertheless, you could write your own user space tool using the debugfs -interface. A reference implementation is available at -https://github.com/awslabs/damo. If you are a kernel programmer, you could -refer to :doc:`/vm/damon/api` for the kernel space programming interface. For -the reason, this document describes only the debugfs interface +.. _sysfs_interface: + +sysfs Interface +=============== + +DAMON sysfs interface is built when ``CONFIG_DAMON_SYSFS`` is defined. It +creates multiple directories and files under its sysfs directory, +``<sysfs>/kernel/mm/damon/``. You can control DAMON by writing to and reading +from the files under the directory. + +For a short example, users can monitor the virtual address space of a given +workload as below. :: + + # cd /sys/kernel/mm/damon/admin/ + # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # echo vaddr > kdamonds/0/contexts/0/operations + # echo 1 > kdamonds/0/contexts/0/targets/nr + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # echo on > kdamonds/0/state + +Files Hierarchy +--------------- + +The files hierarchy of DAMON sysfs interface is shown below. In the below +figure, parents-children relations are represented with indentations, each +directory is having ``/`` suffix, and files in each directory are separated by +comma (","). :: + + /sys/kernel/mm/damon/admin + │ kdamonds/nr_kdamonds + │ │ 0/state,pid + │ │ │ contexts/nr_contexts + │ │ │ │ 0/operations + │ │ │ │ │ monitoring_attrs/ + │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us + │ │ │ │ │ │ nr_regions/min,max + │ │ │ │ │ targets/nr_targets + │ │ │ │ │ │ 0/pid_target + │ │ │ │ │ │ │ regions/nr_regions + │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ │ schemes/nr_schemes + │ │ │ │ │ │ 0/action + │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ │ │ │ sz/min,max + │ │ │ │ │ │ │ │ nr_accesses/min,max + │ │ │ │ │ │ │ │ age/min,max + │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil + │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ ... + │ │ │ │ ... + │ │ ... + +Root +---- + +The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it +has one directory named ``admin``. The directory contains the files for +privileged user space programs' control of DAMON. User space tools or deamons +having the root permission could use this directory. + +kdamonds/ +--------- + +The monitoring-related information including request specifications and results +are called DAMON context. DAMON executes each context with a kernel thread +called kdamond, and multiple kdamonds could run in parallel. + +Under the ``admin`` directory, one directory, ``kdamonds``, which has files for +controlling the kdamonds exist. In the beginning, this directory has only one +file, ``nr_kdamonds``. Writing a number (``N``) to the file creates the number +of child directories named ``0`` to ``N-1``. Each directory represents each +kdamond. + +kdamonds/<N>/ +------------- + +In each kdamond directory, two files (``state`` and ``pid``) and one directory +(``contexts``) exist. + +Reading ``state`` returns ``on`` if the kdamond is currently running, or +``off`` if it is not running. Writing ``on`` or ``off`` makes the kdamond be +in the state. Writing ``update_schemes_stats`` to ``state`` file updates the +contents of stats files for each DAMON-based operation scheme of the kdamond. +For details of the stats, please refer to :ref:`stats section +<sysfs_schemes_stats>`. + +If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. + +``contexts`` directory contains files for controlling the monitoring contexts +that this kdamond will execute. + +kdamonds/<N>/contexts/ +---------------------- + +In the beginning, this directory has only one file, ``nr_contexts``. Writing a +number (``N``) to the file creates the number of child directories named as +``0`` to ``N-1``. Each directory represents each monitoring context. At the +moment, only one context per kdamond is supported, so only ``0`` or ``1`` can +be written to the file. + +contexts/<N>/ +------------- + +In each context directory, one file (``operations``) and three directories +(``monitoring_attrs``, ``targets``, and ``schemes``) exist. + +DAMON supports multiple types of monitoring operations, including those for +virtual address space and the physical address space. You can set and get what +type of monitoring operations DAMON will use for the context by writing one of +below keywords to, and reading from the file. + + - vaddr: Monitor virtual address spaces of specific processes + - paddr: Monitor the physical address space of the system + +contexts/<N>/monitoring_attrs/ +------------------------------ + +Files for specifying attributes of the monitoring including required quality +and efficiency of the monitoring are in ``monitoring_attrs`` directory. +Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this +directory. + +Under ``intervals`` directory, three files for DAMON's sampling interval +(``sample_us``), aggregation interval (``aggr_us``), and update interval +(``update_us``) exist. You can set and get the values in micro-seconds by +writing to and reading from the files. + +Under ``nr_regions`` directory, two files for the lower-bound and upper-bound +of DAMON's monitoring regions (``min`` and ``max``, respectively), which +controls the monitoring overhead, exist. You can set and get the values by +writing to and rading from the files. + +For more details about the intervals and monitoring regions range, please refer +to the Design document (:doc:`/vm/damon/design`). + +contexts/<N>/targets/ +--------------------- + +In the beginning, this directory has only one file, ``nr_targets``. Writing a +number (``N``) to the file creates the number of child directories named ``0`` +to ``N-1``. Each directory represents each monitoring target. + +targets/<N>/ +------------ + +In each target directory, one file (``pid_target``) and one directory +(``regions``) exist. + +If you wrote ``vaddr`` to the ``contexts/<N>/operations``, each target should +be a process. You can specify the process to DAMON by writing the pid of the +process to the ``pid_target`` file. + +targets/<N>/regions +------------------- + +When ``vaddr`` monitoring operations set is being used (``vaddr`` is written to +the ``contexts/<N>/operations`` file), DAMON automatically sets and updates the +monitoring target regions so that entire memory mappings of target processes +can be covered. However, users could want to set the initial monitoring region +to specific address ranges. + +In contrast, DAMON do not automatically sets and updates the monitoring target +regions when ``paddr`` monitoring operations set is being used (``paddr`` is +written to the ``contexts/<N>/operations``). Therefore, users should set the +monitoring target regions by themselves in the case. + +For such cases, users can explicitly set the initial monitoring target regions +as they want, by writing proper values to the files under this directory. + +In the beginning, this directory has only one file, ``nr_regions``. Writing a +number (``N``) to the file creates the number of child directories named ``0`` +to ``N-1``. Each directory represents each initial monitoring target region. + +regions/<N>/ +------------ + +In each region directory, you will find two files (``start`` and ``end``). You +can set and get the start and end addresses of the initial monitoring target +region by writing to and reading from the files, respectively. + +contexts/<N>/schemes/ +--------------------- + +For usual DAMON-based data access aware memory management optimizations, users +would normally want the system to apply a memory management action to a memory +region of a specific access pattern. DAMON receives such formalized operation +schemes from the user and applies those to the target memory regions. Users +can get and set the schemes by reading from and writing to files under this +directory. + +In the beginning, this directory has only one file, ``nr_schemes``. Writing a +number (``N``) to the file creates the number of child directories named ``0`` +to ``N-1``. Each directory represents each DAMON-based operation scheme. + +schemes/<N>/ +------------ + +In each scheme directory, four directories (``access_pattern``, ``quotas``, +``watermarks``, and ``stats``) and one file (``action``) exist. + +The ``action`` file is for setting and getting what action you want to apply to +memory regions having specific access pattern of the interest. The keywords +that can be written to and read from the file and their meaning are as below. + + - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED`` + - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD`` + - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` + - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` + - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` + - ``stat``: Do nothing but count the statistics + +schemes/<N>/access_pattern/ +--------------------------- + +The target access pattern of each DAMON-based operation scheme is constructed +with three ranges including the size of the region in bytes, number of +monitored accesses per aggregate interval, and number of aggregated intervals +for the age of the region. + +Under the ``access_pattern`` directory, three directories (``sz``, +``nr_accesses``, and ``age``) each having two files (``min`` and ``max``) +exist. You can set and get the access pattern for the given scheme by writing +to and reading from the ``min`` and ``max`` files under ``sz``, +``nr_accesses``, and ``age`` directories, respectively. + +schemes/<N>/quotas/ +------------------- + +Optimal ``target access pattern`` for each ``action`` is workload dependent, so +not easy to find. Worse yet, setting a scheme of some action too aggressive +can cause severe overhead. To avoid such overhead, users can limit time and +size quota for each scheme. In detail, users can ask DAMON to try to use only +up to specific time (``time quota``) for applying the action, and to apply the +action to only up to specific amount (``size quota``) of memory regions having +the target access pattern within a given time interval (``reset interval``). + +When the quota limit is expected to be exceeded, DAMON prioritizes found memory +regions of the ``target access pattern`` based on their size, access frequency, +and age. For personalized prioritization, users can set the weights for the +three properties. + +Under ``quotas`` directory, three files (``ms``, ``bytes``, +``reset_interval_ms``) and one directory (``weights``) having three files +(``sz_permil``, ``nr_accesses_permil``, and ``age_permil``) in it exist. + +You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and +``reset interval`` in milliseconds by writing the values to the three files, +respectively. You can also set the prioritization weights for size, access +frequency, and age in per-thousand unit by writing the values to the three +files under the ``weights`` directory. + +schemes/<N>/watermarks/ +----------------------- + +To allow easy activation and deactivation of each scheme based on system +status, DAMON provides a feature called watermarks. The feature receives five +values called ``metric``, ``interval``, ``high``, ``mid``, and ``low``. The +``metric`` is the system metric such as free memory ratio that can be measured. +If the metric value of the system is higher than the value in ``high`` or lower +than ``low`` at the memoent, the scheme is deactivated. If the value is lower +than ``mid``, the scheme is activated. + +Under the watermarks directory, five files (``metric``, ``interval_us``, +``high``, ``mid``, and ``low``) for setting each value exist. You can set and +get the five values by writing to the files, respectively. + +Keywords and meanings of those that can be written to the ``metric`` file are +as below. + + - none: Ignore the watermarks + - free_mem_rate: System's free memory rate (per thousand) + +The ``interval`` should written in microseconds unit. + +.. _sysfs_schemes_stats: + +schemes/<N>/stats/ +------------------ + +DAMON counts the total number and bytes of regions that each scheme is tried to +be applied, the two numbers for the regions that each scheme is successfully +applied, and the total number of the quota limit exceeds. This statistics can +be used for online analysis or tuning of the schemes. + +The statistics can be retrieved by reading the files under ``stats`` directory +(``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``, and +``qt_exceeds``), respectively. The files are not updated in real time, so you +should ask DAMON sysfs interface to updte the content of the files for the +stats by writing a special keyword, ``update_schemes_stats`` to the relevant +``kdamonds/<N>/state`` file. + +Example +~~~~~~~ + +Below commands applies a scheme saying "If a memory region of size in [4KiB, +8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate +interval in [10, 20], page out the region. For the paging out, use only up to +10ms per second, and also don't page out more than 1GiB per second. Under the +limitation, page out memory regions having longer age first. Also, check the +free memory rate of the system every 5 seconds, start the monitoring and paging +out when the free memory rate becomes lower than 50%, but stop it if the free +memory rate becomes larger than 60%, or lower than 30%". :: + + # cd <sysfs>/kernel/mm/damon/admin + # # populate directories + # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; + # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes + # cd kdamonds/0/contexts/0/schemes/0 + # # set the basic access pattern and the action + # echo 4096 > access_patterns/sz/min + # echo 8192 > access_patterns/sz/max + # echo 0 > access_patterns/nr_accesses/min + # echo 5 > access_patterns/nr_accesses/max + # echo 10 > access_patterns/age/min + # echo 20 > access_patterns/age/max + # echo pageout > action + # # set quotas + # echo 10 > quotas/ms + # echo $((1024*1024*1024)) > quotas/bytes + # echo 1000 > quotas/reset_interval_ms + # # set watermark + # echo free_mem_rate > watermarks/metric + # echo 5000000 > watermarks/interval_us + # echo 600 > watermarks/high + # echo 500 > watermarks/mid + # echo 300 > watermarks/low + +Please note that it's highly recommended to use user space tools like `damo +<https://github.com/awslabs/damo>`_ rather than manually reading and writing +the files as above. Above is only for an example. + +.. _debugfs_interface: debugfs Interface ================= -DAMON exports five files, ``attrs``, ``target_ids``, ``init_regions``, -``schemes`` and ``monitor_on`` under its debugfs directory, -``<debugfs>/damon/``. +DAMON exports eight files, ``attrs``, ``target_ids``, ``init_regions``, +``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` and +``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. Attributes ---------- Users can get and set the ``sampling interval``, ``aggregation interval``, -``regions update interval``, and min/max number of monitoring target regions by +``update interval``, and min/max number of monitoring target regions by reading from and writing to the ``attrs`` file. To know about the monitoring attributes in detail, please refer to the :doc:`/vm/damon/design`. For example, below commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and @@ -105,24 +446,28 @@ In such cases, users can explicitly set the initial monitoring target regions as they want, by writing proper values to the ``init_regions`` file. Each line of the input should represent one region in below form.:: - <target id> <start address> <end address> + <target idx> <start address> <end address> -The ``target id`` should already in ``target_ids`` file, and the regions should -be passed in address order. For example, below commands will set a couple of -address ranges, ``1-100`` and ``100-200`` as the initial monitoring target -region of process 42, and another couple of address ranges, ``20-40`` and -``50-100`` as that of process 4242.:: +The ``target idx`` should be the index of the target in ``target_ids`` file, +starting from ``0``, and the regions should be passed in address order. For +example, below commands will set a couple of address ranges, ``1-100`` and +``100-200`` as the initial monitoring target region of pid 42, which is the +first one (index ``0``) in ``target_ids``, and another couple of address +ranges, ``20-40`` and ``50-100`` as that of pid 4242, which is the second one +(index ``1``) in ``target_ids``.:: # cd <debugfs>/damon - # echo "42 1 100 - 42 100 200 - 4242 20 40 - 4242 50 100" > init_regions + # cat target_ids + 42 4242 + # echo "0 1 100 + 0 100 200 + 1 20 40 + 1 50 100" > init_regions Note that this sets the initial monitoring target regions only. In case of virtual memory monitoring, DAMON will automatically updates the boundary of the -regions after one ``regions update interval``. Therefore, users should set the -``regions update interval`` large enough in this case, if they don't want the +regions after one ``update interval``. Therefore, users should set the +``update interval`` large enough in this case, if they don't want the update. @@ -131,24 +476,38 @@ Schemes For usual DAMON-based data access aware memory management optimizations, users would simply want the system to apply a memory management action to a memory -region of a specific size having a specific access frequency for a specific -time. DAMON receives such formalized operation schemes from the user and -applies those to the target processes. It also counts the total number and -size of regions that each scheme is applied. This statistics can be used for -online analysis or tuning of the schemes. +region of a specific access pattern. DAMON receives such formalized operation +schemes from the user and applies those to the target processes. Users can get and set the schemes by reading from and writing to ``schemes`` debugfs file. Reading the file also shows the statistics of each scheme. To -the file, each of the schemes should be represented in each line in below form: +the file, each of the schemes should be represented in each line in below +form:: + + <target access pattern> <action> <quota> <watermarks> + +You can disable schemes by simply writing an empty string to the file. + +Target Access Pattern +~~~~~~~~~~~~~~~~~~~~~ + +The ``<target access pattern>`` is constructed with three ranges in below +form:: + + min-size max-size min-acc max-acc min-age max-age + +Specifically, bytes for the size of regions (``min-size`` and ``max-size``), +number of monitored accesses per aggregate interval for access frequency +(``min-acc`` and ``max-acc``), number of aggregate intervals for the age of +regions (``min-age`` and ``max-age``) are specified. Note that the ranges are +closed interval. - min-size max-size min-acc max-acc min-age max-age action +Action +~~~~~~ -Note that the ranges are closed interval. Bytes for the size of regions -(``min-size`` and ``max-size``), number of monitored accesses per aggregate -interval for access frequency (``min-acc`` and ``max-acc``), number of -aggregate intervals for the age of regions (``min-age`` and ``max-age``), and a -predefined integer for memory management actions should be used. The supported -numbers and their meanings are as below. +The ``<action>`` is a predefined integer for memory management actions, which +DAMON will apply to the regions having the target access pattern. The +supported numbers and their meanings are as below. - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` - 1: Call ``madvise()`` for the region with ``MADV_COLD`` @@ -157,20 +516,82 @@ numbers and their meanings are as below. - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` - 5: Do nothing but count the statistics -You can disable schemes by simply writing an empty string to the file. For -example, below commands applies a scheme saying "If a memory region of size in -[4KiB, 8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate -interval in [10, 20], page out the region", check the entered scheme again, and -finally remove the scheme. :: +Quota +~~~~~ - # cd <debugfs>/damon - # echo "4096 8192 0 5 10 20 2" > schemes - # cat schemes - 4096 8192 0 5 10 20 2 0 0 - # echo > schemes +Optimal ``target access pattern`` for each ``action`` is workload dependent, so +not easy to find. Worse yet, setting a scheme of some action too aggressive +can cause severe overhead. To avoid such overhead, users can limit time and +size quota for the scheme via the ``<quota>`` in below form:: + + <ms> <sz> <reset interval> <priority weights> + +This makes DAMON to try to use only up to ``<ms>`` milliseconds for applying +the action to memory regions of the ``target access pattern`` within the +``<reset interval>`` milliseconds, and to apply the action to only up to +``<sz>`` bytes of memory regions within the ``<reset interval>``. Setting both +``<ms>`` and ``<sz>`` zero disables the quota limits. + +When the quota limit is expected to be exceeded, DAMON prioritizes found memory +regions of the ``target access pattern`` based on their size, access frequency, +and age. For personalized prioritization, users can set the weights for the +three properties in ``<priority weights>`` in below form:: + + <size weight> <access frequency weight> <age weight> + +Watermarks +~~~~~~~~~~ + +Some schemes would need to run based on current value of the system's specific +metrics like free memory ratio. For such cases, users can specify watermarks +for the condition.:: -The last two integers in the 4th line of above example is the total number and -the total size of the regions that the scheme is applied. + <metric> <check interval> <high mark> <middle mark> <low mark> + +``<metric>`` is a predefined integer for the metric to be checked. The +supported numbers and their meanings are as below. + + - 0: Ignore the watermarks + - 1: System's free memory rate (per thousand) + +The value of the metric is checked every ``<check interval>`` microseconds. + +If the value is higher than ``<high mark>`` or lower than ``<low mark>``, the +scheme is deactivated. If the value is lower than ``<mid mark>``, the scheme +is activated. + +.. _damos_stats: + +Statistics +~~~~~~~~~~ + +It also counts the total number and bytes of regions that each scheme is tried +to be applied, the two numbers for the regions that each scheme is successfully +applied, and the total number of the quota limit exceeds. This statistics can +be used for online analysis or tuning of the schemes. + +The statistics can be shown by reading the ``schemes`` file. Reading the file +will show each scheme you entered in each line, and the five numbers for the +statistics will be added at the end of each line. + +Example +~~~~~~~ + +Below commands applies a scheme saying "If a memory region of size in [4KiB, +8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate +interval in [10, 20], page out the region. For the paging out, use only up to +10ms per second, and also don't page out more than 1GiB per second. Under the +limitation, page out memory regions having longer age first. Also, check the +free memory rate of the system every 5 seconds, start the monitoring and paging +out when the free memory rate becomes lower than 50%, but stop it if the free +memory rate becomes larger than 60%, or lower than 30%".:: + + # cd <debugfs>/damon + # scheme="4096 8192 0 5 10 20 2" # target access pattern and action + # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas + # scheme+=" 0 0 100" # prioritization weights + # scheme+=" 1 5000000 600 500 300" # watermarks + # echo "$scheme" > schemes Turning On/Off @@ -195,6 +616,54 @@ the monitoring is turned on. If you write to the files while DAMON is running, an error code such as ``-EBUSY`` will be returned. +Monitoring Thread PID +--------------------- + +DAMON does requested monitoring with a kernel thread called ``kdamond``. You +can get the pid of the thread by reading the ``kdamond_pid`` file. When the +monitoring is turned off, reading the file returns ``none``. :: + + # cd <debugfs>/damon + # cat monitor_on + off + # cat kdamond_pid + none + # echo on > monitor_on + # cat kdamond_pid + 18594 + + +Using Multiple Monitoring Threads +--------------------------------- + +One ``kdamond`` thread is created for each monitoring context. You can create +and remove monitoring contexts for multiple ``kdamond`` required use case using +the ``mk_contexts`` and ``rm_contexts`` files. + +Writing the name of the new context to the ``mk_contexts`` file creates a +directory of the name on the DAMON debugfs directory. The directory will have +DAMON debugfs files for the context. :: + + # cd <debugfs>/damon + # ls foo + # ls: cannot access 'foo': No such file or directory + # echo foo > mk_contexts + # ls foo + # attrs init_regions kdamond_pid schemes target_ids + +If the context is not needed anymore, you can remove it and the corresponding +directory by putting the name of the context to the ``rm_contexts`` file. :: + + # echo foo > rm_contexts + # ls foo + # ls: cannot access 'foo': No such file or directory + +Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on`` files are in the +root directory only. + + +.. _tracepoint: + Tracepoint for Monitoring Results ================================= diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 64fd0ba0d057..5a6afecbb0d0 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -408,7 +408,7 @@ follows: Memory Policy APIs ================== -Linux supports 3 system calls for controlling memory policy. These APIS +Linux supports 4 system calls for controlling memory policy. These APIS always affect only the calling task, the calling task's address space, or some shared object mapped into the calling task's address space. @@ -460,6 +460,20 @@ requested via the 'flags' argument. See the mbind(2) man page for more details. +Set home node for a Range of Task's Address Spacec:: + + long sys_set_mempolicy_home_node(unsigned long start, unsigned long len, + unsigned long home_node, + unsigned long flags); + +sys_set_mempolicy_home_node set the home node for a VMA policy present in the +task's address range. The system call updates the home node only for the existing +mempolicy range. Other address ranges are ignored. A home node is the NUMA node +closest to which page allocation will come from. Specifying the home node override +the default allocation policy to allocate memory close to the local node for an +executing CPU. + + Memory Policy Command Line Interface ==================================== diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index bfc28704856c..6e2e416af783 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -23,7 +23,7 @@ There are four components to pagemap: * Bit 56 page exclusively mapped (since 4.2) * Bit 57 pte is uffd-wp write-protected (since 5.13) (see :ref:`Documentation/admin-guide/mm/userfaultfd.rst <userfaultfd>`) - * Bits 57-60 zero + * Bits 58-60 zero * Bit 61 page is file-page or shared-anon (since 3.5) * Bit 62 page swapped * Bit 63 page present diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index 8edb8d578caf..6e6f7b0d6562 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -130,9 +130,25 @@ attribute, e.g.:: echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled When zswap same-filled page identification is disabled at runtime, it will stop -checking for the same-value filled pages during store operation. However, the -existing pages which are marked as same-value filled pages remain stored -unchanged in zswap until they are either loaded or invalidated. +checking for the same-value filled pages during store operation. +In other words, every page will be then considered non-same-value filled. +However, the existing pages which are marked as same-value filled pages remain +stored unchanged in zswap until they are either loaded or invalidated. + +In some circumstances it might be advantageous to make use of just the zswap +ability to efficiently store same-filled pages without enabling the whole +compressed page storage. +In this case the handling of non-same-value pages by zswap (enabled by default) +can be disabled by setting the ``non_same_filled_pages_enabled`` attribute +to 0, e.g. ``zswap.non_same_filled_pages_enabled=0``. +It can also be enabled and disabled at runtime using the sysfs +``non_same_filled_pages_enabled`` attribute, e.g.:: + + echo 1 > /sys/module/zswap/parameters/non_same_filled_pages_enabled + +Disabling both ``zswap.same_filled_pages_enabled`` and +``zswap.non_same_filled_pages_enabled`` effectively disables accepting any new +pages by zswap. To prevent zswap from shrinking pool when zswap is full and there's a high pressure on swap (this will result in flipping pages in and out zswap pool diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index 5a8f2529a033..69b23f087c05 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -8,6 +8,7 @@ Performance monitor support :maxdepth: 1 hisi-pmu + hisi-pcie-pmu imx-ddr qcom_l2_pmu qcom_l3_pmu diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst index 2f066df4ee9c..1923cb25073b 100644 --- a/Documentation/admin-guide/pm/amd-pstate.rst +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -369,6 +369,32 @@ governor (for the policies it is attached to), or by the ``CPUFreq`` core (for t policies with other scaling governors). +Tracer Tool +------------- + +``amd_pstate_tracer.py`` can record and parse ``amd-pstate`` trace log, then +generate performance plots. This utility can be used to debug and tune the +performance of ``amd-pstate`` driver. The tracer tool needs to import intel +pstate tracer. + +Tracer tool located in ``linux/tools/power/x86/amd_pstate_tracer``. It can be +used in two ways. If trace file is available, then directly parse the file +with command :: + + ./amd_pstate_trace.py [-c cpus] -t <trace_file> -n <test_name> + +Or generate trace file with root privilege, then parse and plot with command :: + + sudo ./amd_pstate_trace.py [-c cpus] -n <test_name> -i <interval> [-m kbytes] + +The test result can be found in ``results/test_name``. Following is the example +about part of the output. :: + + common_cpu common_secs common_usecs min_perf des_perf max_perf freq mperf apef tsc load duration_ms sample_num elapsed_time common_comm + CPU_005 712 116384 39 49 166 0.7565 9645075 2214891 38431470 25.1 11.646 469 2.496 kworker/5:0-40 + CPU_006 712 116408 39 49 166 0.6769 8950227 1839034 37192089 24.06 11.272 470 2.496 kworker/6:0-1264 + + Reference =========== diff --git a/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst new file mode 100644 index 000000000000..09169d935835 --- /dev/null +++ b/Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +============================== +Intel Uncore Frequency Scaling +============================== + +:Copyright: |copy| 2022 Intel Corporation + +:Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> + +Introduction +------------ + +The uncore can consume significant amount of power in Intel's Xeon servers based +on the workload characteristics. To optimize the total power and improve overall +performance, SoCs have internal algorithms for scaling uncore frequency. These +algorithms monitor workload usage of uncore and set a desirable frequency. + +It is possible that users have different expectations of uncore performance and +want to have control over it. The objective is similar to allowing users to set +the scaling min/max frequencies via cpufreq sysfs to improve CPU performance. +Users may have some latency sensitive workloads where they do not want any +change to uncore frequency. Also, users may have workloads which require +different core and uncore performance at distinct phases and they may want to +use both cpufreq and the uncore scaling interface to distribute power and +improve overall performance. + +Sysfs Interface +--------------- + +To control uncore frequency, a sysfs interface is provided in the directory: +`/sys/devices/system/cpu/intel_uncore_frequency/`. + +There is one directory for each package and die combination as the scope of +uncore scaling control is per die in multiple die/package SoCs or per +package for single die per package SoCs. The name represents the +scope of control. For example: 'package_00_die_00' is for package id 0 and +die 0. + +Each package_*_die_* contains the following attributes: + +``initial_max_freq_khz`` + Out of reset, this attribute represent the maximum possible frequency. + This is a read-only attribute. If users adjust max_freq_khz, + they can always go back to maximum using the value from this attribute. + +``initial_min_freq_khz`` + Out of reset, this attribute represent the minimum possible frequency. + This is a read-only attribute. If users adjust min_freq_khz, + they can always go back to minimum using the value from this attribute. + +``max_freq_khz`` + This attribute is used to set the maximum uncore frequency. + +``min_freq_khz`` + This attribute is used to set the minimum uncore frequency. + +``current_freq_khz`` + This attribute is used to get the current uncore frequency. diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index 5d2757e2de65..ee45887811ff 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -15,3 +15,4 @@ Working-State Power Management cpufreq_drivers intel_epb intel-speed-select + intel_uncore_frequency_scaling diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index d7ac13f789cc..ec62151fe672 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -1,14 +1,5 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. - +.. See the bottom of this file for additional redistribution information. Reporting issues ++++++++++++++++ @@ -395,22 +386,16 @@ fixed as soon as possible, hence there are 'issues of high priority' that get handled slightly differently in the reporting process. Three type of cases qualify: regressions, security issues, and really severe problems. -You deal with a 'regression' if something that worked with an older version of -the Linux kernel does not work with a newer one or somehow works worse with it. -It thus is a regression when a WiFi driver that did a fine job with Linux 5.7 -somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if -an application shows erratic behavior with a newer kernel, which might happen -due to incompatible changes in the interface between the kernel and the -userland (like procfs and sysfs). Significantly reduced performance or -increased power consumption also qualify as regression. But keep in mind: the -new kernel needs to be built with a configuration that is similar to the one -from the old kernel (see below how to achieve that). That's because the kernel -developers sometimes can not avoid incompatibilities when implementing new -features; but to avoid regressions such features have to be enabled explicitly -during build time configuration. +You deal with a regression if some application or practical use case running +fine with one Linux kernel works worse or not at all with a newer version +compiled using a similar configuration. The document +Documentation/admin-guide/reporting-regressions.rst explains this in more +detail. It also provides a good deal of other information about regressions you +might want to be aware of; it for example explains how to add your issue to the +list of tracked regressions, to ensure it won't fall through the cracks. What qualifies as security issue is left to your judgment. Consider reading -'Documentation/admin-guide/security-bugs.rst' before proceeding, as it +Documentation/admin-guide/security-bugs.rst before proceeding, as it provides additional details how to best handle security issues. An issue is a 'really severe problem' when something totally unacceptably bad @@ -517,7 +502,7 @@ line starting with 'CPU:'. It should end with 'Not tainted' if the kernel was not tainted when it noticed the problem; it was tainted if you see 'Tainted:' followed by a few spaces and some letters. -If your kernel is tainted, study 'Documentation/admin-guide/tainted-kernels.rst' +If your kernel is tainted, study Documentation/admin-guide/tainted-kernels.rst to find out why. Try to eliminate the reason. Often it's caused by one these three things: @@ -1043,7 +1028,7 @@ down the culprit, as maintainers often won't have the time or setup at hand to reproduce it themselves. To find the change there is a process called 'bisection' which the document -'Documentation/admin-guide/bug-bisect.rst' describes in detail. That process +Documentation/admin-guide/bug-bisect.rst describes in detail. That process will often require you to build about ten to twenty kernel images, trying to reproduce the issue with each of them before building the next. Yes, that takes some time, but don't worry, it works a lot quicker than most people assume. @@ -1073,10 +1058,11 @@ When dealing with regressions make sure the issue you face is really caused by the kernel and not by something else, as outlined above already. In the whole process keep in mind: an issue only qualifies as regression if the -older and the newer kernel got built with a similar configuration. The best way -to archive this: copy the configuration file (``.config``) from the old working -kernel freshly to each newer kernel version you try. Afterwards run ``make -olddefconfig`` to adjust it for the needs of the new version. +older and the newer kernel got built with a similar configuration. This can be +achieved by using ``make olddefconfig``, as explained in more detail by +Documentation/admin-guide/reporting-regressions.rst; that document also +provides a good deal of other information about regressions you might want to be +aware of. Write and send the report @@ -1283,7 +1269,7 @@ them when sending the report by mail. If you filed it in a bug tracker, forward the report's text to these addresses; but on top of it put a small note where you mention that you filed it with a link to the ticket. -See 'Documentation/admin-guide/security-bugs.rst' for more information. +See Documentation/admin-guide/security-bugs.rst for more information. Duties after the report went out @@ -1571,7 +1557,7 @@ Once your report is out your might get asked to do a proper one, as it allows to pinpoint the exact change that causes the issue (which then can easily get reverted to fix the issue quickly). Hence consider to do a proper bisection right away if time permits. See the section 'Special care for regressions' and -the document 'Documentation/admin-guide/bug-bisect.rst' for details how to +the document Documentation/admin-guide/bug-bisect.rst for details how to perform one. In case of a successful bisection add the author of the culprit to the recipients; also CC everyone in the signed-off-by chain, which you find at the end of its commit message. @@ -1594,7 +1580,7 @@ Some fixes are too complex Even small and seemingly obvious code-changes sometimes introduce new and totally unexpected problems. The maintainers of the stable and longterm kernels are very aware of that and thus only apply changes to these kernels that are -within rules outlined in 'Documentation/process/stable-kernel-rules.rst'. +within rules outlined in Documentation/process/stable-kernel-rules.rst. Complex or risky changes for example do not qualify and thus only get applied to mainline. Other fixes are easy to get backported to the newest stable and @@ -1756,10 +1742,23 @@ art will lay some groundwork to improve the situation over time. .. - This text is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If you - spot a typo or small mistake, feel free to let him know directly and he'll - fix it. You are free to do the same in a mostly informal way if you want - to contribute changes to the text, but for copyright reasons please CC + end-of-content +.. + This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If + you spot a typo or small mistake, feel free to let him know directly and + he'll fix it. You are free to do the same in a mostly informal way if you + want to contribute changes to the text, but for copyright reasons please CC linux-doc@vger.kernel.org and "sign-off" your contribution as Documentation/process/submitting-patches.rst outlines in the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..d8adccdae23f --- /dev/null +++ b/Documentation/admin-guide/reporting-regressions.rst @@ -0,0 +1,451 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. [see the bottom of this file for redistribution information] + +Reporting regressions ++++++++++++++++++++++ + +"*We don't cause regressions*" is the first rule of Linux kernel development; +Linux founder and lead developer Linus Torvalds established it himself and +ensures it's obeyed. + +This document describes what the rule means for users and how the Linux kernel's +development model ensures to address all reported regressions; aspects relevant +for kernel developers are left to Documentation/process/handling-regressions.rst. + + +The important bits (aka "TL;DR") +================================ + +#. It's a regression if something running fine with one Linux kernel works worse + or not at all with a newer version. Note, the newer kernel has to be compiled + using a similar configuration; the detailed explanations below describes this + and other fine print in more detail. + +#. Report your issue as outlined in Documentation/admin-guide/reporting-issues.rst, + it already covers all aspects important for regressions and repeated + below for convenience. Two of them are important: start your report's subject + with "[REGRESSION]" and CC or forward it to `the regression mailing list + <https://lore.kernel.org/regressions/>`_ (regressions@lists.linux.dev). + +#. Optional, but recommended: when sending or forwarding your report, make the + Linux kernel regression tracking bot "regzbot" track the issue by specifying + when the regression started like this:: + + #regzbot introduced v5.13..v5.14-rc1 + + +All the details on Linux kernel regressions relevant for users +============================================================== + + +The important basics +-------------------- + + +What is a "regression" and what is the "no regressions rule"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's a regression if some application or practical use case running fine with +one Linux kernel works worse or not at all with a newer version compiled using a +similar configuration. The "no regressions rule" forbids this to take place; if +it happens by accident, developers that caused it are expected to quickly fix +the issue. + +It thus is a regression when a WiFi driver from Linux 5.13 works fine, but with +5.14 doesn't work at all, works significantly slower, or misbehaves somehow. +It's also a regression if a perfectly working application suddenly shows erratic +behavior with a newer kernel version; such issues can be caused by changes in +procfs, sysfs, or one of the many other interfaces Linux provides to userland +software. But keep in mind, as mentioned earlier: 5.14 in this example needs to +be built from a configuration similar to the one from 5.13. This can be achieved +using ``make olddefconfig``, as explained in more detail below. + +Note the "practical use case" in the first sentence of this section: developers +despite the "no regressions" rule are free to change any aspect of the kernel +and even APIs or ABIs to userland, as long as no existing application or use +case breaks. + +Also be aware the "no regressions" rule covers only interfaces the kernel +provides to the userland. It thus does not apply to kernel-internal interfaces +like the module API, which some externally developed drivers use to hook into +the kernel. + +How do I report a regression? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just report the issue as outlined in +Documentation/admin-guide/reporting-issues.rst, it already describes the +important points. The following aspects outlined there are especially relevant +for regressions: + + * When checking for existing reports to join, also search the `archives of the + Linux regressions mailing list <https://lore.kernel.org/regressions/>`_ and + `regzbot's web-interface <https://linux-regtracking.leemhuis.info/regzbot/>`_. + + * Start your report's subject with "[REGRESSION]". + + * In your report, clearly mention the last kernel version that worked fine and + the first broken one. Ideally try to find the exact change causing the + regression using a bisection, as explained below in more detail. + + * Remember to let the Linux regressions mailing list + (regressions@lists.linux.dev) know about your report: + + * If you report the regression by mail, CC the regressions list. + + * If you report your regression to some bug tracker, forward the submitted + report by mail to the regressions list while CCing the maintainer and the + mailing list for the subsystem in question. + + If it's a regression within a stable or longterm series (e.g. + v5.15.3..v5.15.5), remember to CC the `Linux stable mailing list + <https://lore.kernel.org/stable/>`_ (stable@vger.kernel.org). + + In case you performed a successful bisection, add everyone to the CC the + culprit's commit message mentions in lines starting with "Signed-off-by:". + +When CCing for forwarding your report to the list, consider directly telling the +aforementioned Linux kernel regression tracking bot about your report. To do +that, include a paragraph like this in your mail:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbot will then consider your mail a report for a regression introduced in the +specified version range. In above case Linux v5.13 still worked fine and Linux +v5.14-rc1 was the first version where you encountered the issue. If you +performed a bisection to find the commit that caused the regression, specify the +culprit's commit-id instead:: + + #regzbot introduced: 1f2e3d4c5d + +Placing such a "regzbot command" is in your interest, as it will ensure the +report won't fall through the cracks unnoticed. If you omit this, the Linux +kernel's regressions tracker will take care of telling regzbot about your +regression, as long as you send a copy to the regressions mailing lists. But the +regression tracker is just one human which sometimes has to rest or occasionally +might even enjoy some time away from computers (as crazy as that might sound). +Relying on this person thus will result in an unnecessary delay before the +regressions becomes mentioned `on the list of tracked and unresolved Linux +kernel regressions <https://linux-regtracking.leemhuis.info/regzbot/>`_ and the +weekly regression reports sent by regzbot. Such delays can result in Linus +Torvalds being unaware of important regressions when deciding between "continue +development or call this finished and release the final?". + +Are really all regressions fixed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nearly all of them are, as long as the change causing the regression (the +"culprit commit") is reliably identified. Some regressions can be fixed without +this, but often it's required. + +Who needs to find the root cause of a regression? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers of the affected code area should try to locate the culprit on their +own. But for them that's often impossible to do with reasonable effort, as quite +a lot of issues only occur in a particular environment outside the developer's +reach -- for example, a specific hardware platform, firmware, Linux distro, +system's configuration, or application. That's why in the end it's often up to +the reporter to locate the culprit commit; sometimes users might even need to +run additional tests afterwards to pinpoint the exact root cause. Developers +should offer advice and reasonably help where they can, to make this process +relatively easy and achievable for typical users. + +How can I find the culprit? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Perform a bisection, as roughly outlined in +Documentation/admin-guide/reporting-issues.rst and described in more detail by +Documentation/admin-guide/bug-bisect.rst. It might sound like a lot of work, but +in many cases finds the culprit relatively quickly. If it's hard or +time-consuming to reliably reproduce the issue, consider teaming up with other +affected users to narrow down the search range together. + +Who can I ask for advice when it comes to regressions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Send a mail to the regressions mailing list (regressions@lists.linux.dev) while +CCing the Linux kernel's regression tracker (regressions@leemhuis.info); if the +issue might better be dealt with in private, feel free to omit the list. + + +Additional details about regressions +------------------------------------ + + +What is the goal of the "no regressions rule"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users should feel safe when updating kernel versions and not have to worry +something might break. This is in the interest of the kernel developers to make +updating attractive: they don't want users to stay on stable or longterm Linux +series that are either abandoned or more than one and a half years old. That's +in everybody's interest, as `those series might have known bugs, security +issues, or other problematic aspects already fixed in later versions +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_. +Additionally, the kernel developers want to make it simple and appealing for +users to test the latest pre-release or regular release. That's also in +everybody's interest, as it's a lot easier to track down and fix problems, if +they are reported shortly after being introduced. + +Is the "no regressions" rule really adhered in practice? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's taken really seriously, as can be seen by many mailing list posts from +Linux creator and lead developer Linus Torvalds, some of which are quoted in +Documentation/process/handling-regressions.rst. + +Exceptions to this rule are extremely rare; in the past developers almost always +turned out to be wrong when they assumed a particular situation was warranting +an exception. + +Who ensures the "no regressions" is actually followed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The subsystem maintainers should take care of that, which are watched and +supported by the tree maintainers -- e.g. Linus Torvalds for mainline and +Greg Kroah-Hartman et al. for various stable/longterm series. + +All of them are helped by people trying to ensure no regression report falls +through the cracks. One of them is Thorsten Leemhuis, who's currently acting as +the Linux kernel's "regressions tracker"; to facilitate this work he relies on +regzbot, the Linux kernel regression tracking bot. That's why you want to bring +your report on the radar of these people by CCing or forwarding each report to +the regressions mailing list, ideally with a "regzbot command" in your mail to +get it tracked immediately. + +How quickly are regressions normally fixed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers should fix any reported regression as quickly as possible, to provide +affected users with a solution in a timely manner and prevent more users from +running into the issue; nevertheless developers need to take enough time and +care to ensure regression fixes do not cause additional damage. + +The answer thus depends on various factors like the impact of a regression, its +age, or the Linux series in which it occurs. In the end though, most regressions +should be fixed within two weeks. + +Is it a regression, if the issue can be avoided by updating some software? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Almost always: yes. If a developer tells you otherwise, ask the regression +tracker for advice as outlined above. + +Is it a regression, if a newer kernel works slower or consumes more energy? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes, but the difference has to be significant. A five percent slow-down in a +micro-benchmark thus is unlikely to qualify as regression, unless it also +influences the results of a broad benchmark by more than one percent. If in +doubt, ask for advice. + +Is it a regression, if an external kernel module breaks when updating Linux? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No, as the "no regression" rule is about interfaces and services the Linux +kernel provides to the userland. It thus does not cover building or running +externally developed kernel modules, as they run in kernel-space and hook into +the kernel using internal interfaces occasionally changed. + +How are regressions handled that are caused by security fixes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In extremely rare situations security issues can't be fixed without causing +regressions; those fixes are given way, as they are the lesser evil in the end. +Luckily this middling almost always can be avoided, as key developers for the +affected area and often Linus Torvalds himself try very hard to fix security +issues without causing regressions. + +If you nevertheless face such a case, check the mailing list archives if people +tried their best to avoid the regression. If not, report it; if in doubt, ask +for advice as outlined above. + +What happens if fixing a regression is impossible without causing another? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sadly these things happen, but luckily not very often; if they occur, expert +developers of the affected code area should look into the issue to find a fix +that avoids regressions or at least their impact. If you run into such a +situation, do what was outlined already for regressions caused by security +fixes: check earlier discussions if people already tried their best and ask for +advice if in doubt. + +A quick note while at it: these situations could be avoided, if people would +regularly give mainline pre-releases (say v5.15-rc1 or -rc3) from each +development cycle a test run. This is best explained by imagining a change +integrated between Linux v5.14 and v5.15-rc1 which causes a regression, but at +the same time is a hard requirement for some other improvement applied for +5.15-rc1. All these changes often can simply be reverted and the regression thus +solved, if someone finds and reports it before 5.15 is released. A few days or +weeks later this solution can become impossible, as some software might have +started to rely on aspects introduced by one of the follow-up changes: reverting +all changes would then cause a regression for users of said software and thus is +out of the question. + +Is it a regression, if some feature I relied on was removed months ago? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is, but often it's hard to fix such regressions due to the aspects outlined +in the previous section. It hence needs to be dealt with on a case-by-case +basis. This is another reason why it's in everybody's interest to regularly test +mainline pre-releases. + +Does the "no regression" rule apply if I seem to be the only affected person? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It does, but only for practical usage: the Linux developers want to be free to +remove support for hardware only to be found in attics and museums anymore. + +Note, sometimes regressions can't be avoided to make progress -- and the latter +is needed to prevent Linux from stagnation. Hence, if only very few users seem +to be affected by a regression, it for the greater good might be in their and +everyone else's interest to lettings things pass. Especially if there is an +easy way to circumvent the regression somehow, for example by updating some +software or using a kernel parameter created just for this purpose. + +Does the regression rule apply for code in the staging tree as well? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Not according to the `help text for the configuration option covering all +staging code <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_, +which since its early days states:: + + Please note that these drivers are under heavy development, may or + may not work, and may contain userspace interfaces that most likely + will be changed in the near future. + +The staging developers nevertheless often adhere to the "no regressions" rule, +but sometimes bend it to make progress. That's for example why some users had to +deal with (often negligible) regressions when a WiFi driver from the staging +tree was replaced by a totally different one written from scratch. + +Why do later versions have to be "compiled with a similar configuration"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because the Linux kernel developers sometimes integrate changes known to cause +regressions, but make them optional and disable them in the kernel's default +configuration. This trick allows progress, as the "no regressions" rule +otherwise would lead to stagnation. + +Consider for example a new security feature blocking access to some kernel +interfaces often abused by malware, which at the same time are required to run a +few rarely used applications. The outlined approach makes both camps happy: +people using these applications can leave the new security feature off, while +everyone else can enable it without running into trouble. + +How to create a configuration similar to the one of an older kernel? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start your machine with a known-good kernel and configure the newer Linux +version with ``make olddefconfig``. This makes the kernel's build scripts pick +up the configuration file (the ".config" file) from the running kernel as base +for the new one you are about to compile; afterwards they set all new +configuration options to their default value, which should disable new features +that might cause regressions. + +Can I report a regression I found with pre-compiled vanilla kernels? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to ensure the newer kernel was compiled with a similar configuration +file as the older one (see above), as those that built them might have enabled +some known-to-be incompatible feature for the newer kernel. If in doubt, report +the matter to the kernel's provider and ask for advice. + + +More about regression tracking with "regzbot" +--------------------------------------------- + +What is regression tracking and why should I care about it? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rules like "no regressions" need someone to ensure they are followed, otherwise +they are broken either accidentally or on purpose. History has shown this to be +true for Linux kernel development as well. That's why Thorsten Leemhuis, the +Linux Kernel's regression tracker, and some people try to ensure all regression +are fixed by keeping an eye on them until they are resolved. Neither of them are +paid for this, that's why the work is done on a best effort basis. + +Why and how are Linux kernel regressions tracked using a bot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tracking regressions completely manually has proven to be quite hard due to the +distributed and loosely structured nature of Linux kernel development process. +That's why the Linux kernel's regression tracker developed regzbot to facilitate +the work, with the long term goal to automate regression tracking as much as +possible for everyone involved. + +Regzbot works by watching for replies to reports of tracked regressions. +Additionally, it's looking out for posted or committed patches referencing such +reports with "Link:" tags; replies to such patch postings are tracked as well. +Combined this data provides good insights into the current state of the fixing +process. + +How to see which regressions regzbot tracks currently? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check out `regzbot's web-interface <https://linux-regtracking.leemhuis.info/regzbot/>`_. + +What kind of issues are supposed to be tracked by regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bot is meant to track regressions, hence please don't involve regzbot for +regular issues. But it's okay for the Linux kernel's regression tracker if you +involve regzbot to track severe issues, like reports about hangs, corrupted +data, or internal errors (Panic, Oops, BUG(), warning, ...). + +How to change aspects of a tracked regression? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By using a 'regzbot command' in a direct or indirect reply to the mail with the +report. The easiest way to do that: find the report in your "Sent" folder or the +mailing list archive and reply to it using your mailer's "Reply-all" function. +In that mail, use one of the following commands in a stand-alone paragraph (IOW: +use blank lines to separate one or multiple of these commands from the rest of +the mail's text). + + * Update when the regression started to happen, for example after performing a + bisection:: + + #regzbot introduced: 1f2e3d4c5d + + * Set or update the title:: + + #regzbot title: foo + + * Monitor a discussion or bugzilla.kernel.org ticket where additions aspects of + the issue or a fix are discussed::: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * Point to a place with further details of interest, like a mailing list post + or a ticket in a bug tracker that are slightly related, but about a different + topic:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * Mark a regression as invalid:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot supports a few other commands primarily used by developers or people +tracking regressions. They and more details about the aforementioned regzbot +commands can be found in the `getting started guide +<https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ and +the `reference documentation <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ +for regzbot. + +.. + end-of-content +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-regressions.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index d359bcfadd39..803c60bf21d3 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -595,65 +595,33 @@ Documentation/admin-guide/kernel-parameters.rst). numa_balancing ============== -Enables/disables automatic page fault based NUMA memory -balancing. Memory is moved automatically to nodes -that access it often. +Enables/disables and configures automatic page fault based NUMA memory +balancing. Memory is moved automatically to nodes that access it often. +The value to set can be the result of ORing the following: -Enables/disables automatic NUMA memory balancing. On NUMA machines, there -is a performance penalty if remote memory is accessed by a CPU. When this -feature is enabled the kernel samples what task thread is accessing memory -by periodically unmapping pages and later trapping a page fault. At the -time of the page fault, it is determined if the data being accessed should -be migrated to a local memory node. += ================================= +0 NUMA_BALANCING_DISABLED +1 NUMA_BALANCING_NORMAL +2 NUMA_BALANCING_MEMORY_TIERING += ================================= + +Or NUMA_BALANCING_NORMAL to optimize page placement among different +NUMA nodes to reduce remote accessing. On NUMA machines, there is a +performance penalty if remote memory is accessed by a CPU. When this +feature is enabled the kernel samples what task thread is accessing +memory by periodically unmapping pages and later trapping a page +fault. At the time of the page fault, it is determined if the data +being accessed should be migrated to a local memory node. The unmapping of pages and trapping faults incur additional overhead that ideally is offset by improved memory locality but there is no universal guarantee. If the target workload is already bound to NUMA nodes then this -feature should be disabled. Otherwise, if the system overhead from the -feature is too high then the rate the kernel samples for NUMA hinting -faults may be controlled by the `numa_balancing_scan_period_min_ms, -numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, -numa_balancing_scan_size_mb`_, and numa_balancing_settle_count sysctls. - - -numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb -=============================================================================================================================== - - -Automatic NUMA balancing scans tasks address space and unmaps pages to -detect if pages are properly placed or if the data should be migrated to a -memory node local to where the task is running. Every "scan delay" the task -scans the next "scan size" number of pages in its address space. When the -end of the address space is reached the scanner restarts from the beginning. - -In combination, the "scan delay" and "scan size" determine the scan rate. -When "scan delay" decreases, the scan rate increases. The scan delay and -hence the scan rate of every task is adaptive and depends on historical -behaviour. If pages are properly placed then the scan delay increases, -otherwise the scan delay decreases. The "scan size" is not adaptive but -the higher the "scan size", the higher the scan rate. - -Higher scan rates incur higher system overhead as page faults must be -trapped and potentially data must be migrated. However, the higher the scan -rate, the more quickly a tasks memory is migrated to a local node if the -workload pattern changes and minimises performance impact due to remote -memory accesses. These sysctls control the thresholds for scan delays and -the number of pages scanned. - -``numa_balancing_scan_period_min_ms`` is the minimum time in milliseconds to -scan a tasks virtual memory. It effectively controls the maximum scanning -rate for each task. - -``numa_balancing_scan_delay_ms`` is the starting "scan delay" used for a task -when it initially forks. - -``numa_balancing_scan_period_max_ms`` is the maximum time in milliseconds to -scan a tasks virtual memory. It effectively controls the minimum scanning -rate for each task. - -``numa_balancing_scan_size_mb`` is how many megabytes worth of pages are -scanned for a given scan. +feature should be disabled. +Or NUMA_BALANCING_MEMORY_TIERING to optimize page placement among +different types of memory (represented as different NUMA nodes) to +place the hot pages in the fast memory. This is implemented based on +unmapping and page fault too. oops_all_cpu_backtrace ====================== @@ -1029,23 +997,17 @@ This is a directory, with the following entries: * ``poolsize``: the entropy pool size, in bits; * ``urandom_min_reseed_secs``: obsolete (used to determine the minimum - number of seconds between urandom pool reseeding). + number of seconds between urandom pool reseeding). This file is + writable for compatibility purposes, but writing to it has no effect + on any RNG behavior. * ``uuid``: a UUID generated every time this is retrieved (this can thus be used to generate UUIDs at will); * ``write_wakeup_threshold``: when the entropy count drops below this (as a number of bits), processes waiting to write to ``/dev/random`` - are woken up. - -If ``drivers/char/random.c`` is built with ``ADD_INTERRUPT_BENCH`` -defined, these additional entries are present: - -* ``add_interrupt_avg_cycles``: the average number of cycles between - interrupts used to feed the pool; - -* ``add_interrupt_avg_deviation``: the standard deviation seen on the - number of cycles between interrupts used to feed the pool. + are woken up. This file is writable for compatibility purposes, but + writing to it has no effect on any RNG behavior. randomize_va_space diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 5e795202111f..f4804ce37c58 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -948,7 +948,7 @@ how much memory needs to be free before kswapd goes back to sleep. The unit is in fractions of 10,000. The default value of 10 means the distances between watermarks are 0.1% of the available memory in the -node/system. The maximum value is 1000, or 10% of memory. +node/system. The maximum value is 3000, or 30% of memory. A high rate of threads entering direct reclaim (allocstall) or kswapd going to sleep prematurely (kswapd_low_wmark_hit_quickly) can indicate diff --git a/Documentation/arc/arc.rst b/Documentation/arc/arc.rst new file mode 100644 index 000000000000..6c4d978f3f4e --- /dev/null +++ b/Documentation/arc/arc.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel for ARC processors +******************************* + +Other sources of information +############################ + +Below are some resources where more information can be found on +ARC processors and relevant open source projects. + +- `<https://embarc.org>`_ - Community portal for open source on ARC. + Good place to start to find relevant FOSS projects, toolchain releases, + news items and more. + +- `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ - + Home for all development activities regarding open source projects for + ARC processors. Some of the projects are forks of various upstream projects, + where "work in progress" is hosted prior to submission to upstream projects. + Other projects are developed by Synopsys and made available to community + as open source for use on ARC Processors. + +- `Official Synopsys ARC Processors website + <https://www.synopsys.com/designware-ip/processor-solutions.html>`_ - + location, with access to some IP documentation (`Programmer's Reference + Manual, AKA PRM for ARC HS processors + <https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_) + and free versions of some commercial tools (`Free nSIM + <https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and + `MetaWare Light Edition <https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_). + Please note though, registration is required to access both the documentation and + the tools. + +Important note on ARC processors configurability +################################################ + +ARC processors are highly configurable and several configurable options +are supported in Linux. Some options are transparent to software +(i.e cache geometries, some can be detected at runtime and configured +and used accordingly, while some need to be explicitly selected or configured +in the kernel's configuration utility (AKA "make menuconfig"). + +However not all configurable options are supported when an ARC processor +is to run Linux. SoC design teams should refer to "Appendix E: +Configuration for ARC Linux" in the ARC HS Databook for configurability +guidelines. + +Following these guidelines and selecting valid configuration options +up front is critical to help prevent any unwanted issues during +SoC bringup and software development in general. + +Building the Linux kernel for ARC processors +############################################ + +The process of kernel building for ARC processors is the same as for any other +architecture and could be done in 2 ways: + +- Cross-compilation: process of compiling for ARC targets on a development + host with a different processor architecture (generally x86_64/amd64). +- Native compilation: process of compiling for ARC on a ARC platform + (hardware board or a simulator like QEMU) with complete development environment + (GNU toolchain, dtc, make etc) installed on the platform. + +In both cases, up-to-date GNU toolchain for ARC for the host is needed. +Synopsys offers prebuilt toolchain releases which can be used for this purpose, +available from: + +- Synopsys GNU toolchain releases: + `<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_ + +- Linux kernel compilers collection: + `<https://mirrors.edge.kernel.org/pub/tools/crosstool>`_ + +- Bootlin's toolchain collection: `<https://toolchains.bootlin.com>`_ + +Once the toolchain is installed in the system, make sure its "bin" folder +is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` & +``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix) +and then as usual ``make defconfig && make``. + +This will produce "vmlinux" file in the root of the kernel source tree +usable for loading on the target system via JTAG. +If you need to get an image usable with U-Boot bootloader, +type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot`` +folder. diff --git a/Documentation/arc/features.rst b/Documentation/arc/features.rst new file mode 100644 index 000000000000..b793583d688a --- /dev/null +++ b/Documentation/arc/features.rst @@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features arc diff --git a/Documentation/arc/index.rst b/Documentation/arc/index.rst new file mode 100644 index 000000000000..7b098d4a5e3e --- /dev/null +++ b/Documentation/arc/index.rst @@ -0,0 +1,17 @@ +=================== +ARC architecture +=================== + +.. toctree:: + :maxdepth: 1 + + arc + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/arch.rst b/Documentation/arch.rst index f10bd32a5972..14bcd8294b93 100644 --- a/Documentation/arch.rst +++ b/Documentation/arch.rst @@ -9,6 +9,7 @@ implementation. .. toctree:: :maxdepth: 2 + arc/index arm/index arm64/index ia64/index diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 9485a5a2e2e9..2f41caa0096c 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -266,10 +266,12 @@ Avanta family ------------- Flavors: + - 88F6500 - 88F6510 - 88F6530P - 88F6550 - 88F6560 + - 88F6601 Homepage: https://web.archive.org/web/20181005145041/http://www.marvell.com/broadband/ diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index 52d060caf8bb..29884b261aa9 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -10,9 +10,9 @@ This document is based on the ARM booting document by Russell King and is relevant to all public releases of the AArch64 Linux kernel. The AArch64 exception model is made up of a number of exception levels -(EL0 - EL3), with EL0 and EL1 having a secure and a non-secure -counterpart. EL2 is the hypervisor level and exists only in non-secure -mode. EL3 is the highest priority level and exists only in secure mode. +(EL0 - EL3), with EL0, EL1 and EL2 having a secure and a non-secure +counterpart. EL2 is the hypervisor level, EL3 is the highest priority +level and exists only in secure mode. Both are architecturally optional. For the purposes of this document, we will use the term `boot loader` simply to define all software that executes on the CPU(s) before control @@ -167,8 +167,8 @@ Before jumping into the kernel, the following conditions must be met: All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError, IRQ and FIQ). - The CPU must be in either EL2 (RECOMMENDED in order to have access to - the virtualisation extensions) or non-secure EL1. + The CPU must be in non-secure state, either in EL2 (RECOMMENDED in order + to have access to the virtualisation extensions), or in EL1. - Caches, MMUs diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index b72ff17d600a..a8f30963e550 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -259,6 +259,11 @@ HWCAP2_RPRES Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001. +HWCAP2_MTE3 + + Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described + by Documentation/arm64/memory-tagging-extension.rst. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/memory-tagging-extension.rst b/Documentation/arm64/memory-tagging-extension.rst index 7b99c8f428eb..dd27f78d7608 100644 --- a/Documentation/arm64/memory-tagging-extension.rst +++ b/Documentation/arm64/memory-tagging-extension.rst @@ -76,6 +76,9 @@ configurable behaviours: with ``.si_code = SEGV_MTEAERR`` and ``.si_addr = 0`` (the faulting address is unknown). +- *Asymmetric* - Reads are handled as for synchronous mode while writes + are handled as for asynchronous mode. + The user can select the above modes, per thread, using the ``prctl(PR_SET_TAGGED_ADDR_CTRL, flags, 0, 0, 0)`` system call where ``flags`` contains any number of the following values in the ``PR_MTE_TCF_MASK`` @@ -91,8 +94,9 @@ mode is specified, the program will run in that mode. If multiple modes are specified, the mode is selected as described in the "Per-CPU preferred tag checking modes" section below. -The current tag check fault mode can be read using the -``prctl(PR_GET_TAGGED_ADDR_CTRL, 0, 0, 0, 0)`` system call. +The current tag check fault configuration can be read using the +``prctl(PR_GET_TAGGED_ADDR_CTRL, 0, 0, 0, 0)`` system call. If +multiple modes were requested then all will be reported. Tag checking can also be disabled for a user thread by setting the ``PSTATE.TCO`` bit with ``MSR TCO, #1``. @@ -139,18 +143,25 @@ tag checking mode as the CPU's preferred tag checking mode. The preferred tag checking mode for each CPU is controlled by ``/sys/devices/system/cpu/cpu<N>/mte_tcf_preferred``, to which a -privileged user may write the value ``async`` or ``sync``. The default -preferred mode for each CPU is ``async``. +privileged user may write the value ``async``, ``sync`` or ``asymm``. The +default preferred mode for each CPU is ``async``. To allow a program to potentially run in the CPU's preferred tag checking mode, the user program may set multiple tag check fault mode bits in the ``flags`` argument to the ``prctl(PR_SET_TAGGED_ADDR_CTRL, -flags, 0, 0, 0)`` system call. If the CPU's preferred tag checking -mode is in the task's set of provided tag checking modes (this will -always be the case at present because the kernel only supports two -tag checking modes, but future kernels may support more modes), that -mode will be selected. Otherwise, one of the modes in the task's mode -set will be selected in a currently unspecified manner. +flags, 0, 0, 0)`` system call. If both synchronous and asynchronous +modes are requested then asymmetric mode may also be selected by the +kernel. If the CPU's preferred tag checking mode is in the task's set +of provided tag checking modes, that mode will be selected. Otherwise, +one of the modes in the task's mode will be selected by the kernel +from the task's mode set using the preference order: + + 1. Asynchronous + 2. Asymmetric + 3. Synchronous + +Note that there is no way for userspace to request multiple modes and +also disable asymmetric mode. Initial process state --------------------- @@ -213,6 +224,29 @@ address ABI control and MTE configuration of a process as per the Documentation/arm64/tagged-address-abi.rst and above. The corresponding ``regset`` is 1 element of 8 bytes (``sizeof(long))``). +Core dump support +----------------- + +The allocation tags for user memory mapped with ``PROT_MTE`` are dumped +in the core file as additional ``PT_ARM_MEMTAG_MTE`` segments. The +program header for such segment is defined as: + +:``p_type``: ``PT_ARM_MEMTAG_MTE`` +:``p_flags``: 0 +:``p_offset``: segment file offset +:``p_vaddr``: segment virtual address, same as the corresponding + ``PT_LOAD`` segment +:``p_paddr``: 0 +:``p_filesz``: segment size in file, calculated as ``p_mem_sz / 32`` + (two 4-bit tags cover 32 bytes of memory) +:``p_memsz``: segment size in memory, same as the corresponding + ``PT_LOAD`` segment +:``p_align``: 0 + +The tags are stored in the core file at ``p_offset`` as two 4-bit tags +in a byte. With the tag granule of 16 bytes, a 4K page requires 128 +bytes in the core file. + Example of correct usage ======================== diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 5342e895fb60..466cb9e89047 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -52,6 +52,12 @@ stable kernels. | Allwinner | A64/R18 | UNKNOWN1 | SUN50I_ERRATUM_UNKNOWN1 | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2064142 | ARM64_ERRATUM_2064142 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2038923 | ARM64_ERRATUM_2038923 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #1902691 | ARM64_ERRATUM_1902691 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | @@ -92,12 +98,20 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A77 | #1508412 | ARM64_ERRATUM_1508412 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2051678 | ARM64_ERRATUM_2051678 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2077057 | ARM64_ERRATUM_2077057 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2119858 | ARM64_ERRATUM_2119858 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2054223 | ARM64_ERRATUM_2054223 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2224489 | ARM64_ERRATUM_2224489 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-X2 | #2119858 | ARM64_ERRATUM_2119858 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-X2 | #2224489 | ARM64_ERRATUM_2224489 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1349291 | N/A | @@ -122,7 +136,7 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 | +----------------+-----------------+-----------------+-----------------------------+ -| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | +| Cavium | ThunderX GICv3 | #23154,38545 | CAVIUM_ERRATUM_23154 | +----------------+-----------------+-----------------+-----------------------------+ | Cavium | ThunderX GICv3 | #38539 | N/A | +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/asm-annotations.rst b/Documentation/asm-annotations.rst index f4bf0f6395fb..a64f2ca469d4 100644 --- a/Documentation/asm-annotations.rst +++ b/Documentation/asm-annotations.rst @@ -130,14 +130,13 @@ denoting a range of code via ``SYM_*_START/END`` annotations. In fact, this kind of annotation corresponds to the now deprecated ``ENTRY`` and ``ENDPROC`` macros. -* ``SYM_FUNC_START_ALIAS`` and ``SYM_FUNC_START_LOCAL_ALIAS`` serve for those - who decided to have two or more names for one function. The typical use is:: +* ``SYM_FUNC_ALIAS``, ``SYM_FUNC_ALIAS_LOCAL``, and ``SYM_FUNC_ALIAS_WEAK`` can + be used to define multiple names for a function. The typical use is:: - SYM_FUNC_START_ALIAS(__memset) - SYM_FUNC_START(memset) + SYM_FUNC_START(__memset) ... asm insns ... - SYM_FUNC_END(memset) - SYM_FUNC_END_ALIAS(__memset) + SYN_FUNC_END(__memset) + SYM_FUNC_ALIAS(memset, __memset) In this example, one can call ``__memset`` or ``memset`` with the same result, except the debug information for the instructions is generated to diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst deleted file mode 100644 index 2098477851a4..000000000000 --- a/Documentation/block/biodoc.rst +++ /dev/null @@ -1,1164 +0,0 @@ -===================================================== -Notes on the Generic Block Layer Rewrite in Linux 2.5 -===================================================== - -.. note:: - - It seems that there are lot of outdated stuff here. This seems - to be written somewhat as a task list. Yet, eventually, something - here might still be useful. - -Notes Written on Jan 15, 2002: - - - Jens Axboe <jens.axboe@oracle.com> - - Suparna Bhattacharya <suparna@in.ibm.com> - -Last Updated May 2, 2002 - -September 2003: Updated I/O Scheduler portions - - Nick Piggin <npiggin@kernel.dk> - -Introduction -============ - -These are some notes describing some aspects of the 2.5 block layer in the -context of the bio rewrite. The idea is to bring out some of the key -changes and a glimpse of the rationale behind those changes. - -Please mail corrections & suggestions to suparna@in.ibm.com. - -Credits -======= - -2.5 bio rewrite: - - Jens Axboe <jens.axboe@oracle.com> - -Many aspects of the generic block layer redesign were driven by and evolved -over discussions, prior patches and the collective experience of several -people. See sections 8 and 9 for a list of some related references. - -The following people helped with review comments and inputs for this -document: - - - Christoph Hellwig <hch@infradead.org> - - Arjan van de Ven <arjanv@redhat.com> - - Randy Dunlap <rdunlap@xenotime.net> - - Andre Hedrick <andre@linux-ide.org> - -The following people helped with fixes/contributions to the bio patches -while it was still work-in-progress: - - - David S. Miller <davem@redhat.com> - - -.. Description of Contents: - - 1. Scope for tuning of logic to various needs - 1.1 Tuning based on device or low level driver capabilities - - Per-queue parameters - - Highmem I/O support - - I/O scheduler modularization - 1.2 Tuning based on high level requirements/capabilities - 1.2.1 Request Priority/Latency - 1.3 Direct access/bypass to lower layers for diagnostics and special - device operations - 1.3.1 Pre-built commands - 2. New flexible and generic but minimalist i/o structure or descriptor - (instead of using buffer heads at the i/o layer) - 2.1 Requirements/Goals addressed - 2.2 The bio struct in detail (multi-page io unit) - 2.3 Changes in the request structure - 3. Using bios - 3.1 Setup/teardown (allocation, splitting) - 3.2 Generic bio helper routines - 3.2.1 Traversing segments and completion units in a request - 3.2.2 Setting up DMA scatterlists - 3.2.3 I/O completion - 3.2.4 Implications for drivers that do not interpret bios (don't handle - multiple segments) - 3.3 I/O submission - 4. The I/O scheduler - 5. Scalability related changes - 5.1 Granular locking: Removal of io_request_lock - 5.2 Prepare for transition to 64 bit sector_t - 6. Other Changes/Implications - 6.1 Partition re-mapping handled by the generic block layer - 7. A few tips on migration of older drivers - 8. A list of prior/related/impacted patches/ideas - 9. Other References/Discussion Threads - - -Bio Notes -========= - -Let us discuss the changes in the context of how some overall goals for the -block layer are addressed. - -1. Scope for tuning the generic logic to satisfy various requirements -===================================================================== - -The block layer design supports adaptable abstractions to handle common -processing with the ability to tune the logic to an appropriate extent -depending on the nature of the device and the requirements of the caller. -One of the objectives of the rewrite was to increase the degree of tunability -and to enable higher level code to utilize underlying device/driver -capabilities to the maximum extent for better i/o performance. This is -important especially in the light of ever improving hardware capabilities -and application/middleware software designed to take advantage of these -capabilities. - -1.1 Tuning based on low level device / driver capabilities ----------------------------------------------------------- - -Sophisticated devices with large built-in caches, intelligent i/o scheduling -optimizations, high memory DMA support, etc may find some of the -generic processing an overhead, while for less capable devices the -generic functionality is essential for performance or correctness reasons. -Knowledge of some of the capabilities or parameters of the device should be -used at the generic block layer to take the right decisions on -behalf of the driver. - -How is this achieved ? - -Tuning at a per-queue level: - -i. Per-queue limits/values exported to the generic layer by the driver - -Various parameters that the generic i/o scheduler logic uses are set at -a per-queue level (e.g maximum request size, maximum number of segments in -a scatter-gather list, logical block size) - -Some parameters that were earlier available as global arrays indexed by -major/minor are now directly associated with the queue. Some of these may -move into the block device structure in the future. Some characteristics -have been incorporated into a queue flags field rather than separate fields -in themselves. There are blk_queue_xxx functions to set the parameters, -rather than update the fields directly - -Some new queue property settings: - - blk_queue_bounce_limit(q, u64 dma_address) - Enable I/O to highmem pages, dma_address being the - limit. No highmem default. - - blk_queue_max_sectors(q, max_sectors) - Sets two variables that limit the size of the request. - - - The request queue's max_sectors, which is a soft size in - units of 512 byte sectors, and could be dynamically varied - by the core kernel. - - - The request queue's max_hw_sectors, which is a hard limit - and reflects the maximum size request a driver can handle - in units of 512 byte sectors. - - The default for both max_sectors and max_hw_sectors is - 255. The upper limit of max_sectors is 1024. - - blk_queue_max_phys_segments(q, max_segments) - Maximum physical segments you can handle in a request. 128 - default (driver limit). (See 3.2.2) - - blk_queue_max_hw_segments(q, max_segments) - Maximum dma segments the hardware can handle in a request. 128 - default (host adapter limit, after dma remapping). - (See 3.2.2) - - blk_queue_max_segment_size(q, max_seg_size) - Maximum size of a clustered segment, 64kB default. - - blk_queue_logical_block_size(q, logical_block_size) - Lowest possible sector size that the hardware can operate - on, 512 bytes default. - -New queue flags: - - - QUEUE_FLAG_CLUSTER (see 3.2.2) - - QUEUE_FLAG_QUEUED (see 3.2.4) - - -ii. High-mem i/o capabilities are now considered the default - -The generic bounce buffer logic, present in 2.4, where the block layer would -by default copyin/out i/o requests on high-memory buffers to low-memory buffers -assuming that the driver wouldn't be able to handle it directly, has been -changed in 2.5. The bounce logic is now applied only for memory ranges -for which the device cannot handle i/o. A driver can specify this by -setting the queue bounce limit for the request queue for the device -(blk_queue_bounce_limit()). This avoids the inefficiencies of the copyin/out -where a device is capable of handling high memory i/o. - -In order to enable high-memory i/o where the device is capable of supporting -it, the pci dma mapping routines and associated data structures have now been -modified to accomplish a direct page -> bus translation, without requiring -a virtual address mapping (unlike the earlier scheme of virtual address --> bus translation). So this works uniformly for high-memory pages (which -do not have a corresponding kernel virtual address space mapping) and -low-memory pages. - -Note: Please refer to Documentation/core-api/dma-api-howto.rst for a discussion -on PCI high mem DMA aspects and mapping of scatter gather lists, and support -for 64 bit PCI. - -Special handling is required only for cases where i/o needs to happen on -pages at physical memory addresses beyond what the device can support. In these -cases, a bounce bio representing a buffer from the supported memory range -is used for performing the i/o with copyin/copyout as needed depending on -the type of the operation. For example, in case of a read operation, the -data read has to be copied to the original buffer on i/o completion, so a -callback routine is set up to do this, while for write, the data is copied -from the original buffer to the bounce buffer prior to issuing the -operation. Since an original buffer may be in a high memory area that's not -mapped in kernel virtual addr, a kmap operation may be required for -performing the copy, and special care may be needed in the completion path -as it may not be in irq context. Special care is also required (by way of -GFP flags) when allocating bounce buffers, to avoid certain highmem -deadlock possibilities. - -It is also possible that a bounce buffer may be allocated from high-memory -area that's not mapped in kernel virtual addr, but within the range that the -device can use directly; so the bounce page may need to be kmapped during -copy operations. [Note: This does not hold in the current implementation, -though] - -There are some situations when pages from high memory may need to -be kmapped, even if bounce buffers are not necessary. For example a device -may need to abort DMA operations and revert to PIO for the transfer, in -which case a virtual mapping of the page is required. For SCSI it is also -done in some scenarios where the low level driver cannot be trusted to -handle a single sg entry correctly. The driver is expected to perform the -kmaps as needed on such occasions as appropriate. A driver could also use -the blk_queue_bounce() routine on its own to bounce highmem i/o to low -memory for specific requests if so desired. - -iii. The i/o scheduler algorithm itself can be replaced/set as appropriate - -As in 2.4, it is possible to plugin a brand new i/o scheduler for a particular -queue or pick from (copy) existing generic schedulers and replace/override -certain portions of it. The 2.5 rewrite provides improved modularization -of the i/o scheduler. There are more pluggable callbacks, e.g for init, -add request, extract request, which makes it possible to abstract specific -i/o scheduling algorithm aspects and details outside of the generic loop. -It also makes it possible to completely hide the implementation details of -the i/o scheduler from block drivers. - -I/O scheduler wrappers are to be used instead of accessing the queue directly. -See section 4. The I/O scheduler for details. - -1.2 Tuning Based on High level code capabilities ------------------------------------------------- - -i. Application capabilities for raw i/o - -This comes from some of the high-performance database/middleware -requirements where an application prefers to make its own i/o scheduling -decisions based on an understanding of the access patterns and i/o -characteristics - -ii. High performance filesystems or other higher level kernel code's -capabilities - -Kernel components like filesystems could also take their own i/o scheduling -decisions for optimizing performance. Journalling filesystems may need -some control over i/o ordering. - -What kind of support exists at the generic block layer for this ? - -The flags and rw fields in the bio structure can be used for some tuning -from above e.g indicating that an i/o is just a readahead request, or priority -settings (currently unused). As far as user applications are concerned they -would need an additional mechanism either via open flags or ioctls, or some -other upper level mechanism to communicate such settings to block. - -1.2.1 Request Priority/Latency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Todo/Under discussion:: - - Arjan's proposed request priority scheme allows higher levels some broad - control (high/med/low) over the priority of an i/o request vs other pending - requests in the queue. For example it allows reads for bringing in an - executable page on demand to be given a higher priority over pending write - requests which haven't aged too much on the queue. Potentially this priority - could even be exposed to applications in some manner, providing higher level - tunability. Time based aging avoids starvation of lower priority - requests. Some bits in the bi_opf flags field in the bio structure are - intended to be used for this priority information. - - -1.3 Direct Access to Low level Device/Driver Capabilities (Bypass mode) ------------------------------------------------------------------------ - -(e.g Diagnostics, Systems Management) - -There are situations where high-level code needs to have direct access to -the low level device capabilities or requires the ability to issue commands -to the device bypassing some of the intermediate i/o layers. -These could, for example, be special control commands issued through ioctl -interfaces, or could be raw read/write commands that stress the drive's -capabilities for certain kinds of fitness tests. Having direct interfaces at -multiple levels without having to pass through upper layers makes -it possible to perform bottom up validation of the i/o path, layer by -layer, starting from the media. - -The normal i/o submission interfaces, e.g submit_bio, could be bypassed -for specially crafted requests which such ioctl or diagnostics -interfaces would typically use, and the elevator add_request routine -can instead be used to directly insert such requests in the queue or preferably -the blk_do_rq routine can be used to place the request on the queue and -wait for completion. Alternatively, sometimes the caller might just -invoke a lower level driver specific interface with the request as a -parameter. - -If the request is a means for passing on special information associated with -the command, then such information is associated with the request->special -field (rather than misuse the request->buffer field which is meant for the -request data buffer's virtual mapping). - -For passing request data, the caller must build up a bio descriptor -representing the concerned memory buffer if the underlying driver interprets -bio segments or uses the block layer end*request* functions for i/o -completion. Alternatively one could directly use the request->buffer field to -specify the virtual address of the buffer, if the driver expects buffer -addresses passed in this way and ignores bio entries for the request type -involved. In the latter case, the driver would modify and manage the -request->buffer, request->sector and request->nr_sectors or -request->current_nr_sectors fields itself rather than using the block layer -end_request or end_that_request_first completion interfaces. -(See 2.3 or Documentation/block/request.rst for a brief explanation of -the request structure fields) - -:: - - [TBD: end_that_request_last should be usable even in this case; - Perhaps an end_that_direct_request_first routine could be implemented to make - handling direct requests easier for such drivers; Also for drivers that - expect bios, a helper function could be provided for setting up a bio - corresponding to a data buffer] - - <JENS: I dont understand the above, why is end_that_request_first() not - usable? Or _last for that matter. I must be missing something> - - <SUP: What I meant here was that if the request doesn't have a bio, then - end_that_request_first doesn't modify nr_sectors or current_nr_sectors, - and hence can't be used for advancing request state settings on the - completion of partial transfers. The driver has to modify these fields - directly by hand. - This is because end_that_request_first only iterates over the bio list, - and always returns 0 if there are none associated with the request. - _last works OK in this case, and is not a problem, as I mentioned earlier - > - -1.3.1 Pre-built Commands -^^^^^^^^^^^^^^^^^^^^^^^^ - -A request can be created with a pre-built custom command to be sent directly -to the device. The cmd block in the request structure has room for filling -in the command bytes. (i.e rq->cmd is now 16 bytes in size, and meant for -command pre-building, and the type of the request is now indicated -through rq->flags instead of via rq->cmd) - -The request structure flags can be set up to indicate the type of request -in such cases (REQ_PC: direct packet command passed to driver, REQ_BLOCK_PC: -packet command issued via blk_do_rq, REQ_SPECIAL: special request). - -It can help to pre-build device commands for requests in advance. -Drivers can now specify a request prepare function (q->prep_rq_fn) that the -block layer would invoke to pre-build device commands for a given request, -or perform other preparatory processing for the request. This is routine is -called by elv_next_request(), i.e. typically just before servicing a request. -(The prepare function would not be called for requests that have RQF_DONTPREP -enabled) - -Aside: - Pre-building could possibly even be done early, i.e before placing the - request on the queue, rather than construct the command on the fly in the - driver while servicing the request queue when it may affect latencies in - interrupt context or responsiveness in general. One way to add early - pre-building would be to do it whenever we fail to merge on a request. - Now REQ_NOMERGE is set in the request flags to skip this one in the future, - which means that it will not change before we feed it to the device. So - the pre-builder hook can be invoked there. - - -2. Flexible and generic but minimalist i/o structure/descriptor -=============================================================== - -2.1 Reason for a new structure and requirements addressed ---------------------------------------------------------- - -Prior to 2.5, buffer heads were used as the unit of i/o at the generic block -layer, and the low level request structure was associated with a chain of -buffer heads for a contiguous i/o request. This led to certain inefficiencies -when it came to large i/o requests and readv/writev style operations, as it -forced such requests to be broken up into small chunks before being passed -on to the generic block layer, only to be merged by the i/o scheduler -when the underlying device was capable of handling the i/o in one shot. -Also, using the buffer head as an i/o structure for i/os that didn't originate -from the buffer cache unnecessarily added to the weight of the descriptors -which were generated for each such chunk. - -The following were some of the goals and expectations considered in the -redesign of the block i/o data structure in 2.5. - -1. Should be appropriate as a descriptor for both raw and buffered i/o - - avoid cache related fields which are irrelevant in the direct/page i/o path, - or filesystem block size alignment restrictions which may not be relevant - for raw i/o. -2. Ability to represent high-memory buffers (which do not have a virtual - address mapping in kernel address space). -3. Ability to represent large i/os w/o unnecessarily breaking them up (i.e - greater than PAGE_SIZE chunks in one shot) -4. At the same time, ability to retain independent identity of i/os from - different sources or i/o units requiring individual completion (e.g. for - latency reasons) -5. Ability to represent an i/o involving multiple physical memory segments - (including non-page aligned page fragments, as specified via readv/writev) - without unnecessarily breaking it up, if the underlying device is capable of - handling it. -6. Preferably should be based on a memory descriptor structure that can be - passed around different types of subsystems or layers, maybe even - networking, without duplication or extra copies of data/descriptor fields - themselves in the process -7. Ability to handle the possibility of splits/merges as the structure passes - through layered drivers (lvm, md, evms), with minimal overhead. - -The solution was to define a new structure (bio) for the block layer, -instead of using the buffer head structure (bh) directly, the idea being -avoidance of some associated baggage and limitations. The bio structure -is uniformly used for all i/o at the block layer ; it forms a part of the -bh structure for buffered i/o, and in the case of raw/direct i/o kiobufs are -mapped to bio structures. - -2.2 The bio struct ------------------- - -The bio structure uses a vector representation pointing to an array of tuples -of <page, offset, len> to describe the i/o buffer, and has various other -fields describing i/o parameters and state that needs to be maintained for -performing the i/o. - -Notice that this representation means that a bio has no virtual address -mapping at all (unlike buffer heads). - -:: - - struct bio_vec { - struct page *bv_page; - unsigned short bv_len; - unsigned short bv_offset; - }; - - /* - * main unit of I/O for the block layer and lower layers (ie drivers) - */ - struct bio { - struct bio *bi_next; /* request queue link */ - struct block_device *bi_bdev; /* target device */ - unsigned long bi_flags; /* status, command, etc */ - unsigned long bi_opf; /* low bits: r/w, high: priority */ - - unsigned int bi_vcnt; /* how may bio_vec's */ - struct bvec_iter bi_iter; /* current index into bio_vec array */ - - unsigned int bi_size; /* total size in bytes */ - unsigned short bi_hw_segments; /* segments after DMA remapping */ - unsigned int bi_max; /* max bio_vecs we can hold - used as index into pool */ - struct bio_vec *bi_io_vec; /* the actual vec list */ - bio_end_io_t *bi_end_io; /* bi_end_io (bio) */ - atomic_t bi_cnt; /* pin count: free when it hits zero */ - void *bi_private; - }; - -With this multipage bio design: - -- Large i/os can be sent down in one go using a bio_vec list consisting - of an array of <page, offset, len> fragments (similar to the way fragments - are represented in the zero-copy network code) -- Splitting of an i/o request across multiple devices (as in the case of - lvm or raid) is achieved by cloning the bio (where the clone points to - the same bi_io_vec array, but with the index and size accordingly modified) -- A linked list of bios is used as before for unrelated merges [#]_ - this - avoids reallocs and makes independent completions easier to handle. -- Code that traverses the req list can find all the segments of a bio - by using rq_for_each_segment. This handles the fact that a request - has multiple bios, each of which can have multiple segments. -- Drivers which can't process a large bio in one shot can use the bi_iter - field to keep track of the next bio_vec entry to process. - (e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE) - [TBD: Should preferably also have a bi_voffset and bi_vlen to avoid modifying - bi_offset an len fields] - -.. [#] - - unrelated merges -- a request ends up containing two or more bios that - didn't originate from the same place. - -bi_end_io() i/o callback gets called on i/o completion of the entire bio. - -At a lower level, drivers build a scatter gather list from the merged bios. -The scatter gather list is in the form of an array of <page, offset, len> -entries with their corresponding dma address mappings filled in at the -appropriate time. As an optimization, contiguous physical pages can be -covered by a single entry where <page> refers to the first page and <len> -covers the range of pages (up to 16 contiguous pages could be covered this -way). There is a helper routine (blk_rq_map_sg) which drivers can use to build -the sg list. - -Note: Right now the only user of bios with more than one page is ll_rw_kio, -which in turn means that only raw I/O uses it (direct i/o may not work -right now). The intent however is to enable clustering of pages etc to -become possible. The pagebuf abstraction layer from SGI also uses multi-page -bios, but that is currently not included in the stock development kernels. -The same is true of Andrew Morton's work-in-progress multipage bio writeout -and readahead patches. - -2.3 Changes in the Request Structure ------------------------------------- - -The request structure is the structure that gets passed down to low level -drivers. The block layer make_request function builds up a request structure, -places it on the queue and invokes the drivers request_fn. The driver makes -use of block layer helper routine elv_next_request to pull the next request -off the queue. Control or diagnostic functions might bypass block and directly -invoke underlying driver entry points passing in a specially constructed -request structure. - -Only some relevant fields (mainly those which changed or may be referred -to in some of the discussion here) are listed below, not necessarily in -the order in which they occur in the structure (see include/linux/blkdev.h) -Refer to Documentation/block/request.rst for details about all the request -structure fields and a quick reference about the layers which are -supposed to use or modify those fields:: - - struct request { - struct list_head queuelist; /* Not meant to be directly accessed by - the driver. - Used by q->elv_next_request_fn - rq->queue is gone - */ - . - . - unsigned char cmd[16]; /* prebuilt command data block */ - unsigned long flags; /* also includes earlier rq->cmd settings */ - . - . - sector_t sector; /* this field is now of type sector_t instead of int - preparation for 64 bit sectors */ - . - . - - /* Number of scatter-gather DMA addr+len pairs after - * physical address coalescing is performed. - */ - unsigned short nr_phys_segments; - - /* Number of scatter-gather addr+len pairs after - * physical and DMA remapping hardware coalescing is performed. - * This is the number of scatter-gather entries the driver - * will actually have to deal with after DMA mapping is done. - */ - unsigned short nr_hw_segments; - - /* Various sector counts */ - unsigned long nr_sectors; /* no. of sectors left: driver modifiable */ - unsigned long hard_nr_sectors; /* block internal copy of above */ - unsigned int current_nr_sectors; /* no. of sectors left in the - current segment:driver modifiable */ - unsigned long hard_cur_sectors; /* block internal copy of the above */ - . - . - int tag; /* command tag associated with request */ - void *special; /* same as before */ - char *buffer; /* valid only for low memory buffers up to - current_nr_sectors */ - . - . - struct bio *bio, *biotail; /* bio list instead of bh */ - struct request_list *rl; - } - -See the req_ops and req_flag_bits definitions for an explanation of the various -flags available. Some bits are used by the block layer or i/o scheduler. - -The behaviour of the various sector counts are almost the same as before, -except that since we have multi-segment bios, current_nr_sectors refers -to the numbers of sectors in the current segment being processed which could -be one of the many segments in the current bio (i.e i/o completion unit). -The nr_sectors value refers to the total number of sectors in the whole -request that remain to be transferred (no change). The purpose of the -hard_xxx values is for block to remember these counts every time it hands -over the request to the driver. These values are updated by block on -end_that_request_first, i.e. every time the driver completes a part of the -transfer and invokes block end*request helpers to mark this. The -driver should not modify these values. The block layer sets up the -nr_sectors and current_nr_sectors fields (based on the corresponding -hard_xxx values and the number of bytes transferred) and updates it on -every transfer that invokes end_that_request_first. It does the same for the -buffer, bio, bio->bi_iter fields too. - -The buffer field is just a virtual address mapping of the current segment -of the i/o buffer in cases where the buffer resides in low-memory. For high -memory i/o, this field is not valid and must not be used by drivers. - -Code that sets up its own request structures and passes them down to -a driver needs to be careful about interoperation with the block layer helper -functions which the driver uses. (Section 1.3) - -3. Using bios -============= - -3.1 Setup/Teardown ------------------- - -There are routines for managing the allocation, and reference counting, and -freeing of bios (bio_alloc, bio_get, bio_put). - -This makes use of Ingo Molnar's mempool implementation, which enables -subsystems like bio to maintain their own reserve memory pools for guaranteed -deadlock-free allocations during extreme VM load. For example, the VM -subsystem makes use of the block layer to writeout dirty pages in order to be -able to free up memory space, a case which needs careful handling. The -allocation logic draws from the preallocated emergency reserve in situations -where it cannot allocate through normal means. If the pool is empty and it -can wait, then it would trigger action that would help free up memory or -replenish the pool (without deadlocking) and wait for availability in the pool. -If it is in IRQ context, and hence not in a position to do this, allocation -could fail if the pool is empty. In general mempool always first tries to -perform allocation without having to wait, even if it means digging into the -pool as long it is not less that 50% full. - -On a free, memory is released to the pool or directly freed depending on -the current availability in the pool. The mempool interface lets the -subsystem specify the routines to be used for normal alloc and free. In the -case of bio, these routines make use of the standard slab allocator. - -The caller of bio_alloc is expected to taken certain steps to avoid -deadlocks, e.g. avoid trying to allocate more memory from the pool while -already holding memory obtained from the pool. - -:: - - [TBD: This is a potential issue, though a rare possibility - in the bounce bio allocation that happens in the current code, since - it ends up allocating a second bio from the same pool while - holding the original bio ] - -Memory allocated from the pool should be released back within a limited -amount of time (in the case of bio, that would be after the i/o is completed). -This ensures that if part of the pool has been used up, some work (in this -case i/o) must already be in progress and memory would be available when it -is over. If allocating from multiple pools in the same code path, the order -or hierarchy of allocation needs to be consistent, just the way one deals -with multiple locks. - -The bio_alloc routine also needs to allocate the bio_vec_list (bvec_alloc()) -for a non-clone bio. There are the 6 pools setup for different size biovecs, -so bio_alloc(gfp_mask, nr_iovecs) will allocate a vec_list of the -given size from these slabs. - -The bio_get() routine may be used to hold an extra reference on a bio prior -to i/o submission, if the bio fields are likely to be accessed after the -i/o is issued (since the bio may otherwise get freed in case i/o completion -happens in the meantime). - -The bio_clone_fast() routine may be used to duplicate a bio, where the clone -shares the bio_vec_list with the original bio (i.e. both point to the -same bio_vec_list). This would typically be used for splitting i/o requests -in lvm or md. - -3.2 Generic bio helper Routines -------------------------------- - -3.2.1 Traversing segments and completion units in a request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The macro rq_for_each_segment() should be used for traversing the bios -in the request list (drivers should avoid directly trying to do it -themselves). Using these helpers should also make it easier to cope -with block changes in the future. - -:: - - struct req_iterator iter; - rq_for_each_segment(bio_vec, rq, iter) - /* bio_vec is now current segment */ - -I/O completion callbacks are per-bio rather than per-segment, so drivers -that traverse bio chains on completion need to keep that in mind. Drivers -which don't make a distinction between segments and completion units would -need to be reorganized to support multi-segment bios. - -3.2.2 Setting up DMA scatterlists -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The blk_rq_map_sg() helper routine would be used for setting up scatter -gather lists from a request, so a driver need not do it on its own. - - nr_segments = blk_rq_map_sg(q, rq, scatterlist); - -The helper routine provides a level of abstraction which makes it easier -to modify the internals of request to scatterlist conversion down the line -without breaking drivers. The blk_rq_map_sg routine takes care of several -things like collapsing physically contiguous segments (if QUEUE_FLAG_CLUSTER -is set) and correct segment accounting to avoid exceeding the limits which -the i/o hardware can handle, based on various queue properties. - -- Prevents a clustered segment from crossing a 4GB mem boundary -- Avoids building segments that would exceed the number of physical - memory segments that the driver can handle (phys_segments) and the - number that the underlying hardware can handle at once, accounting for - DMA remapping (hw_segments) (i.e. IOMMU aware limits). - -Routines which the low level driver can use to set up the segment limits: - -blk_queue_max_hw_segments() : Sets an upper limit of the maximum number of -hw data segments in a request (i.e. the maximum number of address/length -pairs the host adapter can actually hand to the device at once) - -blk_queue_max_phys_segments() : Sets an upper limit on the maximum number -of physical data segments in a request (i.e. the largest sized scatter list -a driver could handle) - -3.2.3 I/O completion -^^^^^^^^^^^^^^^^^^^^ - -The existing generic block layer helper routines end_request, -end_that_request_first and end_that_request_last can be used for i/o -completion (and setting things up so the rest of the i/o or the next -request can be kicked of) as before. With the introduction of multi-page -bio support, end_that_request_first requires an additional argument indicating -the number of sectors completed. - -3.2.4 Implications for drivers that do not interpret bios -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -(don't handle multiple segments) - -Drivers that do not interpret bios e.g those which do not handle multiple -segments and do not support i/o into high memory addresses (require bounce -buffers) and expect only virtually mapped buffers, can access the rq->buffer -field. As before the driver should use current_nr_sectors to determine the -size of remaining data in the current segment (that is the maximum it can -transfer in one go unless it interprets segments), and rely on the block layer -end_request, or end_that_request_first/last to take care of all accounting -and transparent mapping of the next bio segment when a segment boundary -is crossed on completion of a transfer. (The end*request* functions should -be used if only if the request has come down from block/bio path, not for -direct access requests which only specify rq->buffer without a valid rq->bio) - -3.3 I/O Submission ------------------- - -The routine submit_bio() is used to submit a single io. Higher level i/o -routines make use of this: - -(a) Buffered i/o: - -The routine submit_bh() invokes submit_bio() on a bio corresponding to the -bh, allocating the bio if required. ll_rw_block() uses submit_bh() as before. - -(b) Kiobuf i/o (for raw/direct i/o): - -The ll_rw_kio() routine breaks up the kiobuf into page sized chunks and -maps the array to one or more multi-page bios, issuing submit_bio() to -perform the i/o on each of these. - -The embedded bh array in the kiobuf structure has been removed and no -preallocation of bios is done for kiobufs. [The intent is to remove the -blocks array as well, but it's currently in there to kludge around direct i/o.] -Thus kiobuf allocation has switched back to using kmalloc rather than vmalloc. - -Todo/Observation: - - A single kiobuf structure is assumed to correspond to a contiguous range - of data, so brw_kiovec() invokes ll_rw_kio for each kiobuf in a kiovec. - So right now it wouldn't work for direct i/o on non-contiguous blocks. - This is to be resolved. The eventual direction is to replace kiobuf - by kvec's. - - Badari Pulavarty has a patch to implement direct i/o correctly using - bio and kvec. - - -(c) Page i/o: - -Todo/Under discussion: - - Andrew Morton's multi-page bio patches attempt to issue multi-page - writeouts (and reads) from the page cache, by directly building up - large bios for submission completely bypassing the usage of buffer - heads. This work is still in progress. - - Christoph Hellwig had some code that uses bios for page-io (rather than - bh). This isn't included in bio as yet. Christoph was also working on a - design for representing virtual/real extents as an entity and modifying - some of the address space ops interfaces to utilize this abstraction rather - than buffer_heads. (This is somewhat along the lines of the SGI XFS pagebuf - abstraction, but intended to be as lightweight as possible). - -(d) Direct access i/o: - -Direct access requests that do not contain bios would be submitted differently -as discussed earlier in section 1.3. - -Aside: - - Kvec i/o: - - Ben LaHaise's aio code uses a slightly different structure instead - of kiobufs, called a kvec_cb. This contains an array of <page, offset, len> - tuples (very much like the networking code), together with a callback function - and data pointer. This is embedded into a brw_cb structure when passed - to brw_kvec_async(). - - Now it should be possible to directly map these kvecs to a bio. Just as while - cloning, in this case rather than PRE_BUILT bio_vecs, we set the bi_io_vec - array pointer to point to the veclet array in kvecs. - - TBD: In order for this to work, some changes are needed in the way multi-page - bios are handled today. The values of the tuples in such a vector passed in - from higher level code should not be modified by the block layer in the course - of its request processing, since that would make it hard for the higher layer - to continue to use the vector descriptor (kvec) after i/o completes. Instead, - all such transient state should either be maintained in the request structure, - and passed on in some way to the endio completion routine. - - -4. The I/O scheduler -==================== - -I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch -queue and specific I/O schedulers. Unless stated otherwise, elevator is used -to refer to both parts and I/O scheduler to specific I/O schedulers. - -Block layer implements generic dispatch queue in `block/*.c`. -The generic dispatch queue is responsible for requeueing, handling non-fs -requests and all other subtleties. - -Specific I/O schedulers are responsible for ordering normal filesystem -requests. They can also choose to delay certain requests to improve -throughput or whatever purpose. As the plural form indicates, there are -multiple I/O schedulers. They can be built as modules but at least one should -be built inside the kernel. Each queue can choose different one and can also -change to another one dynamically. - -A block layer call to the i/o scheduler follows the convention elv_xxx(). This -calls elevator_xxx_fn in the elevator switch (block/elevator.c). Oh, xxx -and xxx might not match exactly, but use your imagination. If an elevator -doesn't implement a function, the switch does nothing or some minimal house -keeping work. - -4.1. I/O scheduler API ----------------------- - -The functions an elevator may implement are: (* are mandatory) - -=============================== ================================================ -elevator_merge_fn called to query requests for merge with a bio - -elevator_merge_req_fn called when two requests get merged. the one - which gets merged into the other one will be - never seen by I/O scheduler again. IOW, after - being merged, the request is gone. - -elevator_merged_fn called when a request in the scheduler has been - involved in a merge. It is used in the deadline - scheduler for example, to reposition the request - if its sorting order has changed. - -elevator_allow_merge_fn called whenever the block layer determines - that a bio can be merged into an existing - request safely. The io scheduler may still - want to stop a merge at this point if it - results in some sort of conflict internally, - this hook allows it to do that. Note however - that two *requests* can still be merged at later - time. Currently the io scheduler has no way to - prevent that. It can only learn about the fact - from elevator_merge_req_fn callback. - -elevator_dispatch_fn* fills the dispatch queue with ready requests. - I/O schedulers are free to postpone requests by - not filling the dispatch queue unless @force - is non-zero. Once dispatched, I/O schedulers - are not allowed to manipulate the requests - - they belong to generic dispatch queue. - -elevator_add_req_fn* called to add a new request into the scheduler - -elevator_former_req_fn -elevator_latter_req_fn These return the request before or after the - one specified in disk sort order. Used by the - block layer to find merge possibilities. - -elevator_completed_req_fn called when a request is completed. - -elevator_set_req_fn -elevator_put_req_fn Must be used to allocate and free any elevator - specific storage for a request. - -elevator_activate_req_fn Called when device driver first sees a request. - I/O schedulers can use this callback to - determine when actual execution of a request - starts. -elevator_deactivate_req_fn Called when device driver decides to delay - a request by requeueing it. - -elevator_init_fn* -elevator_exit_fn Allocate and free any elevator specific storage - for a queue. -=============================== ================================================ - -4.2 Request flows seen by I/O schedulers ----------------------------------------- - -All requests seen by I/O schedulers strictly follow one of the following three -flows. - - set_req_fn -> - - i. add_req_fn -> (merged_fn ->)* -> dispatch_fn -> activate_req_fn -> - (deactivate_req_fn -> activate_req_fn ->)* -> completed_req_fn - ii. add_req_fn -> (merged_fn ->)* -> merge_req_fn - iii. [none] - - -> put_req_fn - -4.3 I/O scheduler implementation --------------------------------- - -The generic i/o scheduler algorithm attempts to sort/merge/batch requests for -optimal disk scan and request servicing performance (based on generic -principles and device capabilities), optimized for: - -i. improved throughput -ii. improved latency -iii. better utilization of h/w & CPU time - -Characteristics: - -i. Binary tree -AS and deadline i/o schedulers use red black binary trees for disk position -sorting and searching, and a fifo linked list for time-based searching. This -gives good scalability and good availability of information. Requests are -almost always dispatched in disk sort order, so a cache is kept of the next -request in sort order to prevent binary tree lookups. - -This arrangement is not a generic block layer characteristic however, so -elevators may implement queues as they please. - -ii. Merge hash -AS and deadline use a hash table indexed by the last sector of a request. This -enables merging code to quickly look up "back merge" candidates, even when -multiple I/O streams are being performed at once on one disk. - -"Front merges", a new request being merged at the front of an existing request, -are far less common than "back merges" due to the nature of most I/O patterns. -Front merges are handled by the binary trees in AS and deadline schedulers. - -iii. Plugging the queue to batch requests in anticipation of opportunities for - merge/sort optimizations - -Plugging is an approach that the current i/o scheduling algorithm resorts to so -that it collects up enough requests in the queue to be able to take -advantage of the sorting/merging logic in the elevator. If the -queue is empty when a request comes in, then it plugs the request queue -(sort of like plugging the bath tub of a vessel to get fluid to build up) -till it fills up with a few more requests, before starting to service -the requests. This provides an opportunity to merge/sort the requests before -passing them down to the device. There are various conditions when the queue is -unplugged (to open up the flow again), either through a scheduled task or -could be on demand. For example wait_on_buffer sets the unplugging going -through sync_buffer() running blk_run_address_space(mapping). Or the caller -can do it explicity through blk_unplug(bdev). So in the read case, -the queue gets explicitly unplugged as part of waiting for completion on that -buffer. - -Aside: - This is kind of controversial territory, as it's not clear if plugging is - always the right thing to do. Devices typically have their own queues, - and allowing a big queue to build up in software, while letting the device be - idle for a while may not always make sense. The trick is to handle the fine - balance between when to plug and when to open up. Also now that we have - multi-page bios being queued in one shot, we may not need to wait to merge - a big request from the broken up pieces coming by. - -4.4 I/O contexts ----------------- - -I/O contexts provide a dynamically allocated per process data area. They may -be used in I/O schedulers, and in the block layer (could be used for IO statis, -priorities for example). See `*io_context` in block/ll_rw_blk.c, and as-iosched.c -for an example of usage in an i/o scheduler. - - -5. Scalability related changes -============================== - -5.1 Granular Locking: io_request_lock replaced by a per-queue lock ------------------------------------------------------------------- - -The global io_request_lock has been removed as of 2.5, to avoid -the scalability bottleneck it was causing, and has been replaced by more -granular locking. The request queue structure has a pointer to the -lock to be used for that queue. As a result, locking can now be -per-queue, with a provision for sharing a lock across queues if -necessary (e.g the scsi layer sets the queue lock pointers to the -corresponding adapter lock, which results in a per host locking -granularity). The locking semantics are the same, i.e. locking is -still imposed by the block layer, grabbing the lock before -request_fn execution which it means that lots of older drivers -should still be SMP safe. Drivers are free to drop the queue -lock themselves, if required. Drivers that explicitly used the -io_request_lock for serialization need to be modified accordingly. -Usually it's as easy as adding a global lock:: - - static DEFINE_SPINLOCK(my_driver_lock); - -and passing the address to that lock to blk_init_queue(). - -5.2 64 bit sector numbers (sector_t prepares for 64 bit support) ----------------------------------------------------------------- - -The sector number used in the bio structure has been changed to sector_t, -which could be defined as 64 bit in preparation for 64 bit sector support. - -6. Other Changes/Implications -============================= - -6.1 Partition re-mapping handled by the generic block layer ------------------------------------------------------------ - -In 2.5 some of the gendisk/partition related code has been reorganized. -Now the generic block layer performs partition-remapping early and thus -provides drivers with a sector number relative to whole device, rather than -having to take partition number into account in order to arrive at the true -sector number. The routine blk_partition_remap() is invoked by -submit_bio_noacct even before invoking the queue specific ->submit_bio, -so the i/o scheduler also gets to operate on whole disk sector numbers. This -should typically not require changes to block drivers, it just never gets -to invoke its own partition sector offset calculations since all bios -sent are offset from the beginning of the device. - - -7. A Few Tips on Migration of older drivers -=========================================== - -Old-style drivers that just use CURRENT and ignores clustered requests, -may not need much change. The generic layer will automatically handle -clustered requests, multi-page bios, etc for the driver. - -For a low performance driver or hardware that is PIO driven or just doesn't -support scatter-gather changes should be minimal too. - -The following are some points to keep in mind when converting old drivers -to bio. - -Drivers should use elv_next_request to pick up requests and are no longer -supposed to handle looping directly over the request list. -(struct request->queue has been removed) - -Now end_that_request_first takes an additional number_of_sectors argument. -It used to handle always just the first buffer_head in a request, now -it will loop and handle as many sectors (on a bio-segment granularity) -as specified. - -Now bh->b_end_io is replaced by bio->bi_end_io, but most of the time the -right thing to use is bio_endio(bio) instead. - -If the driver is dropping the io_request_lock from its request_fn strategy, -then it just needs to replace that with q->queue_lock instead. - -As described in Sec 1.1, drivers can set max sector size, max segment size -etc per queue now. Drivers that used to define their own merge functions i -to handle things like this can now just use the blk_queue_* functions at -blk_init_queue time. - -Drivers no longer have to map a {partition, sector offset} into the -correct absolute location anymore, this is done by the block layer, so -where a driver received a request ala this before:: - - rq->rq_dev = mk_kdev(3, 5); /* /dev/hda5 */ - rq->sector = 0; /* first sector on hda5 */ - -it will now see:: - - rq->rq_dev = mk_kdev(3, 0); /* /dev/hda */ - rq->sector = 123128; /* offset from start of disk */ - -As mentioned, there is no virtual mapping of a bio. For DMA, this is -not a problem as the driver probably never will need a virtual mapping. -Instead it needs a bus mapping (dma_map_page for a single segment or -use dma_map_sg for scatter gather) to be able to ship it to the driver. For -PIO drivers (or drivers that need to revert to PIO transfer once in a -while (IDE for example)), where the CPU is doing the actual data -transfer a virtual mapping is needed. If the driver supports highmem I/O, -(Sec 1.1, (ii) ) it needs to use kmap_atomic or similar to temporarily map -a bio into the virtual address space. - - -8. Prior/Related/Impacted patches -================================= - -8.1. Earlier kiobuf patches (sct/axboe/chait/hch/mkp) ------------------------------------------------------ - -- orig kiobuf & raw i/o patches (now in 2.4 tree) -- direct kiobuf based i/o to devices (no intermediate bh's) -- page i/o using kiobuf -- kiobuf splitting for lvm (mkp) -- elevator support for kiobuf request merging (axboe) - -8.2. Zero-copy networking (Dave Miller) ---------------------------------------- - -8.3. SGI XFS - pagebuf patches - use of kiobufs ------------------------------------------------ -8.4. Multi-page pioent patch for bio (Christoph Hellwig) --------------------------------------------------------- -8.5. Direct i/o implementation (Andrea Arcangeli) since 2.4.10-pre11 --------------------------------------------------------------------- -8.6. Async i/o implementation patch (Ben LaHaise) -------------------------------------------------- -8.7. EVMS layering design (IBM EVMS team) ------------------------------------------ -8.8. Larger page cache size patch (Ben LaHaise) and Large page size (Daniel Phillips) -------------------------------------------------------------------------------------- - - => larger contiguous physical memory buffers - -8.9. VM reservations patch (Ben LaHaise) ----------------------------------------- -8.10. Write clustering patches ? (Marcelo/Quintela/Riel ?) ----------------------------------------------------------- -8.11. Block device in page cache patch (Andrea Archangeli) - now in 2.4.10+ ---------------------------------------------------------------------------- -8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar, Badari) -------------------------------------------------------------------------------- -8.13 Priority based i/o scheduler - prepatches (Arjan van de Ven) ------------------------------------------------------------------- -8.14 IDE Taskfile i/o patch (Andre Hedrick) --------------------------------------------- -8.15 Multi-page writeout and readahead patches (Andrew Morton) ---------------------------------------------------------------- -8.16 Direct i/o patches for 2.5 using kvec and bio (Badari Pulavarthy) ------------------------------------------------------------------------ - -9. Other References -=================== - -9.1 The Splice I/O Model ------------------------- - -Larry McVoy (and subsequent discussions on lkml, and Linus' comments - Jan 2001 - -9.2 Discussions about kiobuf and bh design ------------------------------------------- - -On lkml between sct, linus, alan et al - Feb-March 2001 (many of the -initial thoughts that led to bio were brought up in this discussion thread) - -9.3 Discussions on mempool on lkml - Dec 2001. ----------------------------------------------- diff --git a/Documentation/block/capability.rst b/Documentation/block/capability.rst index 160a5148b915..2ae7f064736a 100644 --- a/Documentation/block/capability.rst +++ b/Documentation/block/capability.rst @@ -7,4 +7,4 @@ This file documents the sysfs file ``block/<disk>/capability``. ``capability`` is a bitfield, printed in hexadecimal, indicating which capabilities a specific block device supports: -.. kernel-doc:: include/linux/genhd.h +.. kernel-doc:: include/linux/blkdev.h diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 86dcf7159f99..68f115f2b1c6 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -8,7 +8,6 @@ Block :maxdepth: 1 bfq-iosched - biodoc biovecs blk-mq capability @@ -20,7 +19,6 @@ Block kyber-iosched null_blk pr - queue-sysfs request stat switching-sched diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst deleted file mode 100644 index 3f569d532485..000000000000 --- a/Documentation/block/queue-sysfs.rst +++ /dev/null @@ -1,321 +0,0 @@ -================= -Queue sysfs files -================= - -This text file will detail the queue files that are located in the sysfs tree -for each block device. Note that stacked devices typically do not export -any settings, since their queue merely functions as a remapping target. -These files are the ones found in the /sys/block/xxx/queue/ directory. - -Files denoted with a RO postfix are readonly and the RW postfix means -read-write. - -add_random (RW) ---------------- -This file allows to turn off the disk entropy contribution. Default -value of this file is '1'(on). - -chunk_sectors (RO) ------------------- -This has different meaning depending on the type of the block device. -For a RAID device (dm-raid), chunk_sectors indicates the size in 512B sectors -of the RAID volume stripe segment. For a zoned block device, either host-aware -or host-managed, chunk_sectors indicates the size in 512B sectors of the zones -of the device, with the eventual exception of the last zone of the device which -may be smaller. - -dax (RO) --------- -This file indicates whether the device supports Direct Access (DAX), -used by CPU-addressable storage to bypass the pagecache. It shows '1' -if true, '0' if not. - -discard_granularity (RO) ------------------------- -This shows the size of internal allocation of the device in bytes, if -reported by the device. A value of '0' means device does not support -the discard functionality. - -discard_max_hw_bytes (RO) -------------------------- -Devices that support discard functionality may have internal limits on -the number of bytes that can be trimmed or unmapped in a single operation. -The `discard_max_hw_bytes` parameter is set by the device driver to the -maximum number of bytes that can be discarded in a single operation. -Discard requests issued to the device must not exceed this limit. -A `discard_max_hw_bytes` value of 0 means that the device does not support -discard functionality. - -discard_max_bytes (RW) ----------------------- -While discard_max_hw_bytes is the hardware limit for the device, this -setting is the software limit. Some devices exhibit large latencies when -large discards are issued, setting this value lower will make Linux issue -smaller discards and potentially help reduce latencies induced by large -discard operations. - -discard_zeroes_data (RO) ------------------------- -Obsolete. Always zero. - -fua (RO) --------- -Whether or not the block driver supports the FUA flag for write requests. -FUA stands for Force Unit Access. If the FUA flag is set that means that -write requests must bypass the volatile cache of the storage device. - -hw_sector_size (RO) -------------------- -This is the hardware sector size of the device, in bytes. - -io_poll (RW) ------------- -When read, this file shows whether polling is enabled (1) or disabled -(0). Writing '0' to this file will disable polling for this device. -Writing any non-zero value will enable this feature. - -io_poll_delay (RW) ------------------- -If polling is enabled, this controls what kind of polling will be -performed. It defaults to -1, which is classic polling. In this mode, -the CPU will repeatedly ask for completions without giving up any time. -If set to 0, a hybrid polling mode is used, where the kernel will attempt -to make an educated guess at when the IO will complete. Based on this -guess, the kernel will put the process issuing IO to sleep for an amount -of time, before entering a classic poll loop. This mode might be a -little slower than pure classic polling, but it will be more efficient. -If set to a value larger than 0, the kernel will put the process issuing -IO to sleep for this amount of microseconds before entering classic -polling. - -io_timeout (RW) ---------------- -io_timeout is the request timeout in milliseconds. If a request does not -complete in this time then the block driver timeout handler is invoked. -That timeout handler can decide to retry the request, to fail it or to start -a device recovery strategy. - -iostats (RW) -------------- -This file is used to control (on/off) the iostats accounting of the -disk. - -logical_block_size (RO) ------------------------ -This is the logical block size of the device, in bytes. - -max_discard_segments (RO) -------------------------- -The maximum number of DMA scatter/gather entries in a discard request. - -max_hw_sectors_kb (RO) ----------------------- -This is the maximum number of kilobytes supported in a single data transfer. - -max_integrity_segments (RO) ---------------------------- -Maximum number of elements in a DMA scatter/gather list with integrity -data that will be submitted by the block layer core to the associated -block driver. - -max_active_zones (RO) ---------------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), the sum of zones belonging to any of the zone states: -EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value. -If this value is 0, there is no limit. - -If the host attempts to exceed this limit, the driver should report this error -with BLK_STS_ZONE_ACTIVE_RESOURCE, which user space may see as the EOVERFLOW -errno. - -max_open_zones (RO) -------------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), the sum of zones belonging to any of the zone states: -EXPLICIT OPEN or IMPLICIT OPEN, is limited by this value. -If this value is 0, there is no limit. - -If the host attempts to exceed this limit, the driver should report this error -with BLK_STS_ZONE_OPEN_RESOURCE, which user space may see as the ETOOMANYREFS -errno. - -max_sectors_kb (RW) -------------------- -This is the maximum number of kilobytes that the block layer will allow -for a filesystem request. Must be smaller than or equal to the maximum -size allowed by the hardware. - -max_segments (RO) ------------------ -Maximum number of elements in a DMA scatter/gather list that is submitted -to the associated block driver. - -max_segment_size (RO) ---------------------- -Maximum size in bytes of a single element in a DMA scatter/gather list. - -minimum_io_size (RO) --------------------- -This is the smallest preferred IO size reported by the device. - -nomerges (RW) -------------- -This enables the user to disable the lookup logic involved with IO -merging requests in the block layer. By default (0) all merges are -enabled. When set to 1 only simple one-hit merges will be tried. When -set to 2 no merge algorithms will be tried (including one-hit or more -complex tree/hash lookups). - -nr_requests (RW) ----------------- -This controls how many requests may be allocated in the block layer for -read or write requests. Note that the total allocated number may be twice -this amount, since it applies only to reads or writes (not the accumulated -sum). - -To avoid priority inversion through request starvation, a request -queue maintains a separate request pool per each cgroup when -CONFIG_BLK_CGROUP is enabled, and this parameter applies to each such -per-block-cgroup request pool. IOW, if there are N block cgroups, -each request queue may have up to N request pools, each independently -regulated by nr_requests. - -nr_zones (RO) -------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), this indicates the total number of zones of the device. -This is always 0 for regular block devices. - -optimal_io_size (RO) --------------------- -This is the optimal IO size reported by the device. - -physical_block_size (RO) ------------------------- -This is the physical block size of device, in bytes. - -read_ahead_kb (RW) ------------------- -Maximum number of kilobytes to read-ahead for filesystems on this block -device. - -rotational (RW) ---------------- -This file is used to stat if the device is of rotational type or -non-rotational type. - -rq_affinity (RW) ----------------- -If this option is '1', the block layer will migrate request completions to the -cpu "group" that originally submitted the request. For some workloads this -provides a significant reduction in CPU cycles due to caching effects. - -For storage configurations that need to maximize distribution of completion -processing setting this option to '2' forces the completion to run on the -requesting cpu (bypassing the "group" aggregation logic). - -scheduler (RW) --------------- -When read, this file will display the current and available IO schedulers -for this block device. The currently active IO scheduler will be enclosed -in [] brackets. Writing an IO scheduler name to this file will switch -control of this block device to that new IO scheduler. Note that writing -an IO scheduler name to this file will attempt to load that IO scheduler -module, if it isn't already present in the system. - -write_cache (RW) ----------------- -When read, this file will display whether the device has write back -caching enabled or not. It will return "write back" for the former -case, and "write through" for the latter. Writing to this file can -change the kernels view of the device, but it doesn't alter the -device state. This means that it might not be safe to toggle the -setting from "write back" to "write through", since that will also -eliminate cache flushes issued by the kernel. - -write_same_max_bytes (RO) -------------------------- -This is the number of bytes the device can write in a single write-same -command. A value of '0' means write-same is not supported by this -device. - -wbt_lat_usec (RW) ------------------ -If the device is registered for writeback throttling, then this file shows -the target minimum read latency. If this latency is exceeded in a given -window of time (see wb_window_usec), then the writeback throttling will start -scaling back writes. Writing a value of '0' to this file disables the -feature. Writing a value of '-1' to this file resets the value to the -default setting. - -throttle_sample_time (RW) -------------------------- -This is the time window that blk-throttle samples data, in millisecond. -blk-throttle makes decision based on the samplings. Lower time means cgroups -have more smooth throughput, but higher CPU overhead. This exists only when -CONFIG_BLK_DEV_THROTTLING_LOW is enabled. - -write_zeroes_max_bytes (RO) ---------------------------- -For block drivers that support REQ_OP_WRITE_ZEROES, the maximum number of -bytes that can be zeroed at once. The value 0 means that REQ_OP_WRITE_ZEROES -is not supported. - -zone_append_max_bytes (RO) --------------------------- -This is the maximum number of bytes that can be written to a sequential -zone of a zoned block device using a zone append write operation -(REQ_OP_ZONE_APPEND). This value is always 0 for regular block devices. - -zoned (RO) ----------- -This indicates if the device is a zoned block device and the zone model of the -device if it is indeed zoned. The possible values indicated by zoned are -"none" for regular block devices and "host-aware" or "host-managed" for zoned -block devices. The characteristics of host-aware and host-managed zoned block -devices are described in the ZBC (Zoned Block Commands) and ZAC -(Zoned Device ATA Command Set) standards. These standards also define the -"drive-managed" zone model. However, since drive-managed zoned block devices -do not support zone commands, they will be treated as regular block devices -and zoned will report "none". - -zone_write_granularity (RO) ---------------------------- -This indicates the alignment constraint, in bytes, for write operations in -sequential zones of zoned block devices (devices with a zoned attributed -that reports "host-managed" or "host-aware"). This value is always 0 for -regular block devices. - -independent_access_ranges (RO) ------------------------------- - -The presence of this sub-directory of the /sys/block/xxx/queue/ directory -indicates that the device is capable of executing requests targeting -different sector ranges in parallel. For instance, single LUN multi-actuator -hard-disks will have an independent_access_ranges directory if the device -correctly advertizes the sector ranges of its actuators. - -The independent_access_ranges directory contains one directory per access -range, with each range described using the sector (RO) attribute file to -indicate the first sector of the range and the nr_sectors (RO) attribute file -to indicate the total number of sectors in the range starting from the first -sector of the range. For example, a dual-actuator hard-disk will have the -following independent_access_ranges entries.:: - - $ tree /sys/block/<device>/queue/independent_access_ranges/ - /sys/block/<device>/queue/independent_access_ranges/ - |-- 0 - | |-- nr_sectors - | `-- sector - `-- 1 - |-- nr_sectors - `-- sector - -The sector and nr_sectors attributes use 512B sector unit, regardless of -the actual block size of the device. Independent access ranges do not -overlap and include all sectors within the device capacity. The access -ranges are numbered in increasing order of the range start sector, -that is, the sector attribute of range 0 always has the value 0. - -Jens Axboe <jens.axboe@oracle.com>, February 2009 diff --git a/Documentation/cdrom/packet-writing.rst b/Documentation/cdrom/packet-writing.rst index c5c957195a5a..43db58c50d29 100644 --- a/Documentation/cdrom/packet-writing.rst +++ b/Documentation/cdrom/packet-writing.rst @@ -11,7 +11,7 @@ Getting started quick - Compile and install kernel and modules, reboot. - You need the udftools package (pktsetup, mkudffs, cdrwtool). - Download from http://sourceforge.net/projects/linux-udf/ + Download from https://github.com/pali/udftools - Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute as appropriate):: @@ -102,7 +102,7 @@ Using the pktcdvd sysfs interface Since Linux 2.6.20, the pktcdvd module has a sysfs interface and can be controlled by it. For example the "pktcdvd" tool uses -this interface. (see http://tom.ist-im-web.de/download/pktcdvd ) +this interface. (see http://tom.ist-im-web.de/linux/software/pktcdvd ) "pktcdvd" works similar to "pktsetup", e.g.:: diff --git a/Documentation/conf.py b/Documentation/conf.py index 76e5eb5cb62b..072ee31a301d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -208,16 +208,86 @@ highlight_language = 'none' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# The Read the Docs theme is available from -# - https://github.com/snide/sphinx_rtd_theme -# - https://pypi.python.org/pypi/sphinx_rtd_theme -# - python-sphinx-rtd-theme package (on Debian) -try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -except ImportError: - sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n') +# Default theme +html_theme = 'sphinx_rtd_theme' +html_css_files = [] + +if "DOCS_THEME" in os.environ: + html_theme = os.environ["DOCS_THEME"] + +if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': + # Read the Docs theme + try: + import sphinx_rtd_theme + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + # Add any paths that contain custom static files (such as style sheets) here, + # relative to this directory. They are copied after the builtin static files, + # so a file named "default.css" will overwrite the builtin "default.css". + html_css_files = [ + 'theme_overrides.css', + ] + + # Read the Docs dark mode override theme + if html_theme == 'sphinx_rtd_dark_mode': + try: + import sphinx_rtd_dark_mode + extensions.append('sphinx_rtd_dark_mode') + except ImportError: + html_theme == 'sphinx_rtd_theme' + + if html_theme == 'sphinx_rtd_theme': + # Add color-specific RTD normal mode + html_css_files.append('theme_rtd_colors.css') + + except ImportError: + html_theme = 'classic' + +if "DOCS_CSS" in os.environ: + css = os.environ["DOCS_CSS"].split(" ") + + for l in css: + html_css_files.append(l) + +if major <= 1 and minor < 8: + html_context = { + 'css_files': [], + } + + for l in html_css_files: + html_context['css_files'].append('_static/' + l) + +if html_theme == 'classic': + html_theme_options = { + 'rightsidebar': False, + 'stickysidebar': True, + 'collapsiblesidebar': True, + 'externalrefs': False, + + 'footerbgcolor': "white", + 'footertextcolor': "white", + 'sidebarbgcolor': "white", + 'sidebarbtncolor': "black", + 'sidebartextcolor': "black", + 'sidebarlinkcolor': "#686bff", + 'relbarbgcolor': "#133f52", + 'relbartextcolor': "white", + 'relbarlinkcolor': "white", + 'bgcolor': "white", + 'textcolor': "black", + 'headbgcolor': "#f2f2f2", + 'headtextcolor': "#20435c", + 'headlinkcolor': "#c60f0f", + 'linkcolor': "#355f7c", + 'visitedlinkcolor': "#355f7c", + 'codebgcolor': "#3f3f3f", + 'codetextcolor': "white", + + 'bodyfont': "serif", + 'headfont': "sans-serif", + } + +sys.stderr.write("Using %s theme\n" % html_theme) # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -246,20 +316,8 @@ except ImportError: # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". - html_static_path = ['sphinx-static'] -html_css_files = [ - 'theme_overrides.css', -] - -if major <= 1 and minor < 8: - html_context = { - 'css_files': [ - '_static/theme_overrides.css', - ], - } - # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. @@ -351,135 +409,25 @@ latex_elements = { # Additional stuff for the LaTeX preamble. 'preamble': ''' - % Prevent column squeezing of tabulary. - \\setlength{\\tymin}{20em} % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} \\setsansfont{DejaVu Sans} \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - % Adjust \\headheight for fancyhdr - \\addtolength{\\headheight}{1.6pt} - \\addtolength{\\topmargin}{-1.6pt} - ''', + ''', } -# Translations have Asian (CJK) characters which are only displayed if -# xeCJK is used - -latex_elements['preamble'] += ''' - \\IfFontExistsTF{Noto Sans CJK SC}{ - % This is needed for translations - \\usepackage{xeCJK} - \\IfFontExistsTF{Noto Serif CJK SC}{ - \\setCJKmainfont{Noto Serif CJK SC}[AutoFakeSlant] - }{ - \\setCJKmainfont{Noto Sans CJK SC}[AutoFakeSlant] - } - \\setCJKsansfont{Noto Sans CJK SC}[AutoFakeSlant] - \\setCJKmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant] - % CJK Language-specific font choices - \\IfFontExistsTF{Noto Serif CJK SC}{ - \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}[AutoFakeSlant] - \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant] - }{ - \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}[AutoFakeSlant] - \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}[AutoFakeSlant] - } - \\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant] - \\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant] - \\IfFontExistsTF{Noto Serif CJK TC}{ - \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}[AutoFakeSlant] - \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}[AutoFakeSlant] - }{ - \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}[AutoFakeSlant] - \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}[AutoFakeSlant] - } - \\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}[AutoFakeSlant] - \\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant] - \\IfFontExistsTF{Noto Serif CJK KR}{ - \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}[AutoFakeSlant] - \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant] - }{ - \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}[AutoFakeSlant] - \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}[AutoFakeSlant] - } - \\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant] - \\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant] - \\IfFontExistsTF{Noto Serif CJK JP}{ - \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}[AutoFakeSlant] - \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant] - }{ - \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}[AutoFakeSlant] - \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}[AutoFakeSlant] - } - \\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant] - \\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant] - % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support) - \\providecommand{\\onehalfspacing}{} - \\providecommand{\\singlespacing}{} - % Define custom macros to on/off CJK - \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing} - \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing} - \\newcommand{\\kerneldocBeginSC}{% - \\begingroup% - \\scmain% - } - \\newcommand{\\kerneldocEndSC}{\\endgroup} - \\newcommand{\\kerneldocBeginTC}{% - \\begingroup% - \\tcmain% - \\renewcommand{\\CJKrmdefault}{TCserif}% - \\renewcommand{\\CJKsfdefault}{TCsans}% - \\renewcommand{\\CJKttdefault}{TCmono}% - } - \\newcommand{\\kerneldocEndTC}{\\endgroup} - \\newcommand{\\kerneldocBeginKR}{% - \\begingroup% - \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}% - \\xeCJKDeclareCharClass{HalfRight}{`â€,`’}% - \\krmain% - \\renewcommand{\\CJKrmdefault}{KRserif}% - \\renewcommand{\\CJKsfdefault}{KRsans}% - \\renewcommand{\\CJKttdefault}{KRmono}% - \\xeCJKsetup{CJKspace = true} % For inter-phrase space - } - \\newcommand{\\kerneldocEndKR}{\\endgroup} - \\newcommand{\\kerneldocBeginJP}{% - \\begingroup% - \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}% - \\xeCJKDeclareCharClass{HalfRight}{`â€,`’}% - \\jpmain% - \\renewcommand{\\CJKrmdefault}{JPserif}% - \\renewcommand{\\CJKsfdefault}{JPsans}% - \\renewcommand{\\CJKttdefault}{JPmono}% - } - \\newcommand{\\kerneldocEndJP}{\\endgroup} - % Single spacing in literal blocks - \\fvset{baselinestretch=1} - % To customize \\sphinxtableofcontents - \\usepackage{etoolbox} - % Inactivate CJK after tableofcontents - \\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{} - }{ % No CJK font found - % Custom macros to on/off CJK (Dummy) - \\newcommand{\\kerneldocCJKon}{} - \\newcommand{\\kerneldocCJKoff}{} - \\newcommand{\\kerneldocBeginSC}{} - \\newcommand{\\kerneldocEndSC}{} - \\newcommand{\\kerneldocBeginTC}{} - \\newcommand{\\kerneldocEndTC}{} - \\newcommand{\\kerneldocBeginKR}{} - \\newcommand{\\kerneldocEndKR}{} - \\newcommand{\\kerneldocBeginJP}{} - \\newcommand{\\kerneldocEndJP}{} - } -''' - # Fix reference escape troubles with Sphinx 1.4.x if major == 1: latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n' + +# Load kerneldoc specific LaTeX settings +latex_elements['preamble'] += ''' + % Load kerneldoc specific LaTeX settings + \\input{kerneldoc-preamble.sty} +''' + # With Sphinx 1.6, it is possible to change the Bg color directly # by using: # \definecolor{sphinxnoteBgColor}{RGB}{204,255,255} @@ -541,6 +489,11 @@ for fn in os.listdir('.'): # If false, no module index is generated. #latex_domain_indices = True +# Additional LaTeX stuff to be copied to build directory +latex_additional_files = [ + 'sphinx/kerneldoc-preamble.sty', +] + # -- Options for manual page output --------------------------------------- diff --git a/Documentation/core-api/entry.rst b/Documentation/core-api/entry.rst new file mode 100644 index 000000000000..e12f22ab33c7 --- /dev/null +++ b/Documentation/core-api/entry.rst @@ -0,0 +1,279 @@ +Entry/exit handling for exceptions, interrupts, syscalls and KVM +================================================================ + +All transitions between execution domains require state updates which are +subject to strict ordering constraints. State updates are required for the +following: + + * Lockdep + * RCU / Context tracking + * Preemption counter + * Tracing + * Time accounting + +The update order depends on the transition type and is explained below in +the transition type sections: `Syscalls`_, `KVM`_, `Interrupts and regular +exceptions`_, `NMI and NMI-like exceptions`_. + +Non-instrumentable code - noinstr +--------------------------------- + +Most instrumentation facilities depend on RCU, so intrumentation is prohibited +for entry code before RCU starts watching and exit code after RCU stops +watching. In addition, many architectures must save and restore register state, +which means that (for example) a breakpoint in the breakpoint entry code would +overwrite the debug registers of the initial breakpoint. + +Such code must be marked with the 'noinstr' attribute, placing that code into a +special section inaccessible to instrumentation and debug facilities. Some +functions are partially instrumentable, which is handled by marking them +noinstr and using instrumentation_begin() and instrumentation_end() to flag the +instrumentable ranges of code: + +.. code-block:: c + + noinstr void entry(void) + { + handle_entry(); // <-- must be 'noinstr' or '__always_inline' + ... + + instrumentation_begin(); + handle_context(); // <-- instrumentable code + instrumentation_end(); + + ... + handle_exit(); // <-- must be 'noinstr' or '__always_inline' + } + +This allows verification of the 'noinstr' restrictions via objtool on +supported architectures. + +Invoking non-instrumentable functions from instrumentable context has no +restrictions and is useful to protect e.g. state switching which would +cause malfunction if instrumented. + +All non-instrumentable entry/exit code sections before and after the RCU +state transitions must run with interrupts disabled. + +Syscalls +-------- + +Syscall-entry code starts in assembly code and calls out into low-level C code +after establishing low-level architecture-specific state and stack frames. This +low-level C code must not be instrumented. A typical syscall handling function +invoked from low-level assembly code looks like this: + +.. code-block:: c + + noinstr void syscall(struct pt_regs *regs, int nr) + { + arch_syscall_enter(regs); + nr = syscall_enter_from_user_mode(regs, nr); + + instrumentation_begin(); + if (!invoke_syscall(regs, nr) && nr != -1) + result_reg(regs) = __sys_ni_syscall(regs); + instrumentation_end(); + + syscall_exit_to_user_mode(regs); + } + +syscall_enter_from_user_mode() first invokes enter_from_user_mode() which +establishes state in the following order: + + * Lockdep + * RCU / Context tracking + * Tracing + +and then invokes the various entry work functions like ptrace, seccomp, audit, +syscall tracing, etc. After all that is done, the instrumentable invoke_syscall +function can be invoked. The instrumentable code section then ends, after which +syscall_exit_to_user_mode() is invoked. + +syscall_exit_to_user_mode() handles all work which needs to be done before +returning to user space like tracing, audit, signals, task work etc. After +that it invokes exit_to_user_mode() which again handles the state +transition in the reverse order: + + * Tracing + * RCU / Context tracking + * Lockdep + +syscall_enter_from_user_mode() and syscall_exit_to_user_mode() are also +available as fine grained subfunctions in cases where the architecture code +has to do extra work between the various steps. In such cases it has to +ensure that enter_from_user_mode() is called first on entry and +exit_to_user_mode() is called last on exit. + +Do not nest syscalls. Nested systcalls will cause RCU and/or context tracking +to print a warning. + +KVM +--- + +Entering or exiting guest mode is very similar to syscalls. From the host +kernel point of view the CPU goes off into user space when entering the +guest and returns to the kernel on exit. + +kvm_guest_enter_irqoff() is a KVM-specific variant of exit_to_user_mode() +and kvm_guest_exit_irqoff() is the KVM variant of enter_from_user_mode(). +The state operations have the same ordering. + +Task work handling is done separately for guest at the boundary of the +vcpu_run() loop via xfer_to_guest_mode_handle_work() which is a subset of +the work handled on return to user space. + +Do not nest KVM entry/exit transitions because doing so is nonsensical. + +Interrupts and regular exceptions +--------------------------------- + +Interrupts entry and exit handling is slightly more complex than syscalls +and KVM transitions. + +If an interrupt is raised while the CPU executes in user space, the entry +and exit handling is exactly the same as for syscalls. + +If the interrupt is raised while the CPU executes in kernel space the entry and +exit handling is slightly different. RCU state is only updated when the +interrupt is raised in the context of the CPU's idle task. Otherwise, RCU will +already be watching. Lockdep and tracing have to be updated unconditionally. + +irqentry_enter() and irqentry_exit() provide the implementation for this. + +The architecture-specific part looks similar to syscall handling: + +.. code-block:: c + + noinstr void interrupt(struct pt_regs *regs, int nr) + { + arch_interrupt_enter(regs); + state = irqentry_enter(regs); + + instrumentation_begin(); + + irq_enter_rcu(); + invoke_irq_handler(regs, nr); + irq_exit_rcu(); + + instrumentation_end(); + + irqentry_exit(regs, state); + } + +Note that the invocation of the actual interrupt handler is within a +irq_enter_rcu() and irq_exit_rcu() pair. + +irq_enter_rcu() updates the preemption count which makes in_hardirq() +return true, handles NOHZ tick state and interrupt time accounting. This +means that up to the point where irq_enter_rcu() is invoked in_hardirq() +returns false. + +irq_exit_rcu() handles interrupt time accounting, undoes the preemption +count update and eventually handles soft interrupts and NOHZ tick state. + +In theory, the preemption count could be updated in irqentry_enter(). In +practice, deferring this update to irq_enter_rcu() allows the preemption-count +code to be traced, while also maintaining symmetry with irq_exit_rcu() and +irqentry_exit(), which are described in the next paragraph. The only downside +is that the early entry code up to irq_enter_rcu() must be aware that the +preemption count has not yet been updated with the HARDIRQ_OFFSET state. + +Note that irq_exit_rcu() must remove HARDIRQ_OFFSET from the preemption count +before it handles soft interrupts, whose handlers must run in BH context rather +than irq-disabled context. In addition, irqentry_exit() might schedule, which +also requires that HARDIRQ_OFFSET has been removed from the preemption count. + +Even though interrupt handlers are expected to run with local interrupts +disabled, interrupt nesting is common from an entry/exit perspective. For +example, softirq handling happens within an irqentry_{enter,exit}() block with +local interrupts enabled. Also, although uncommon, nothing prevents an +interrupt handler from re-enabling interrupts. + +Interrupt entry/exit code doesn't strictly need to handle reentrancy, since it +runs with local interrupts disabled. But NMIs can happen anytime, and a lot of +the entry code is shared between the two. + +NMI and NMI-like exceptions +--------------------------- + +NMIs and NMI-like exceptions (machine checks, double faults, debug +interrupts, etc.) can hit any context and must be extra careful with +the state. + +State changes for debug exceptions and machine-check exceptions depend on +whether these exceptions happened in user-space (breakpoints or watchpoints) or +in kernel mode (code patching). From user-space, they are treated like +interrupts, while from kernel mode they are treated like NMIs. + +NMIs and other NMI-like exceptions handle state transitions without +distinguishing between user-mode and kernel-mode origin. + +The state update on entry is handled in irqentry_nmi_enter() which updates +state in the following order: + + * Preemption counter + * Lockdep + * RCU / Context tracking + * Tracing + +The exit counterpart irqentry_nmi_exit() does the reverse operation in the +reverse order. + +Note that the update of the preemption counter has to be the first +operation on enter and the last operation on exit. The reason is that both +lockdep and RCU rely on in_nmi() returning true in this case. The +preemption count modification in the NMI entry/exit case must not be +traced. + +Architecture-specific code looks like this: + +.. code-block:: c + + noinstr void nmi(struct pt_regs *regs) + { + arch_nmi_enter(regs); + state = irqentry_nmi_enter(regs); + + instrumentation_begin(); + nmi_handler(regs); + instrumentation_end(); + + irqentry_nmi_exit(regs); + } + +and for e.g. a debug exception it can look like this: + +.. code-block:: c + + noinstr void debug(struct pt_regs *regs) + { + arch_nmi_enter(regs); + + debug_regs = save_debug_regs(); + + if (user_mode(regs)) { + state = irqentry_enter(regs); + + instrumentation_begin(); + user_mode_debug_handler(regs, debug_regs); + instrumentation_end(); + + irqentry_exit(regs, state); + } else { + state = irqentry_nmi_enter(regs); + + instrumentation_begin(); + kernel_mode_debug_handler(regs, debug_regs); + instrumentation_end(); + + irqentry_nmi_exit(regs, state); + } + } + +There is no combined irqentry_nmi_if_kernel() function available as the +above cannot be handled in an exception-agnostic way. + +NMIs can happen in any context. For example, an NMI-like exception triggered +while handling an NMI. So NMI entry code has to be reentrant and state updates +need to handle nesting. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 5de2c7a4b1b3..972d46a5ddf6 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -44,6 +44,14 @@ Library functionality that is used throughout the kernel. timekeeping errseq +Low level entry and exit +======================== + +.. toctree:: + :maxdepth: 1 + + entry + Concurrency primitives ====================== diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 2e7186805148..d6b3f94b9f1f 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -279,6 +279,7 @@ Accounting Framework Block Devices ============= +.. kernel-doc:: include/linux/bio.h .. kernel-doc:: block/blk-core.c :export: @@ -294,9 +295,6 @@ Block Devices .. kernel-doc:: block/blk-settings.c :export: -.. kernel-doc:: block/blk-exec.c - :export: - .. kernel-doc:: block/blk-flush.c :export: diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst index 2739f8b72575..7310247310a0 100644 --- a/Documentation/core-api/kobject.rst +++ b/Documentation/core-api/kobject.rst @@ -118,7 +118,7 @@ Initialization of kobjects Code which creates a kobject must, of course, initialize that object. Some of the internal fields are setup with a (mandatory) call to kobject_init():: - void kobject_init(struct kobject *kobj, struct kobj_type *ktype); + void kobject_init(struct kobject *kobj, const struct kobj_type *ktype); The ktype is required for a kobject to be created properly, as every kobject must have an associated kobj_type. After calling kobject_init(), to @@ -156,7 +156,7 @@ kobject_name():: There is a helper function to both initialize and add the kobject to the kernel at the same time, called surprisingly enough kobject_init_and_add():: - int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype, + int kobject_init_and_add(struct kobject *kobj, const struct kobj_type *ktype, struct kobject *parent, const char *fmt, ...); The arguments are the same as the individual kobject_init() and @@ -299,7 +299,6 @@ kobj_type:: struct kobj_type { void (*release)(struct kobject *kobj); const struct sysfs_ops *sysfs_ops; - struct attribute **default_attrs; const struct attribute_group **default_groups; const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj); const void *(*namespace)(struct kobject *kobj); @@ -313,10 +312,10 @@ call kobject_init() or kobject_init_and_add(). The release field in struct kobj_type is, of course, a pointer to the release() method for this type of kobject. The other two fields (sysfs_ops -and default_attrs) control how objects of this type are represented in +and default_groups) control how objects of this type are represented in sysfs; they are beyond the scope of this document. -The default_attrs pointer is a list of default attributes that will be +The default_groups pointer is a list of default attributes that will be automatically created for any kobject that is registered with this ktype. @@ -373,10 +372,9 @@ If a kset wishes to control the uevent operations of the kobjects associated with it, it can use the struct kset_uevent_ops to handle it:: struct kset_uevent_ops { - int (* const filter)(struct kset *kset, struct kobject *kobj); - const char *(* const name)(struct kset *kset, struct kobject *kobj); - int (* const uevent)(struct kset *kset, struct kobject *kobj, - struct kobj_uevent_env *env); + int (* const filter)(struct kobject *kobj); + const char *(* const name)(struct kobject *kobj); + int (* const uevent)(struct kobject *kobj, struct kobj_uevent_env *env); }; diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 395835f9289f..f5b2f92822c8 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -58,15 +58,30 @@ Virtually Contiguous Mappings File Mapping and Page Cache =========================== -.. kernel-doc:: mm/readahead.c - :export: +Filemap +------- .. kernel-doc:: mm/filemap.c :export: +Readahead +--------- + +.. kernel-doc:: mm/readahead.c + :doc: Readahead Overview + +.. kernel-doc:: mm/readahead.c + :export: + +Writeback +--------- + .. kernel-doc:: mm/page-writeback.c :export: +Truncate +-------- + .. kernel-doc:: mm/truncate.c :export: diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index fcf605be43d0..b18416f4500f 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -55,18 +55,18 @@ flags the caller provides. The caller is required to pass in a non-null struct pages* array, and the function then pins pages by incrementing each by a special value: GUP_PIN_COUNTING_BIAS. -For huge pages (and in fact, any compound page of more than 2 pages), the -GUP_PIN_COUNTING_BIAS scheme is not used. Instead, an exact form of pin counting -is achieved, by using the 3rd struct page in the compound page. A new struct -page field, hpage_pinned_refcount, has been added in order to support this. +For compound pages, the GUP_PIN_COUNTING_BIAS scheme is not used. Instead, +an exact form of pin counting is achieved, by using the 2nd struct page +in the compound page. A new struct page field, compound_pincount, has +been added in order to support this. This approach for compound pages avoids the counting upper limit problems that are discussed below. Those limitations would have been aggravated severely by huge pages, because each tail page adds a refcount to the head page. And in -fact, testing revealed that, without a separate hpage_pinned_refcount field, +fact, testing revealed that, without a separate compound_pincount field, page overflows were seen in some huge page stress tests. -This also means that huge pages and compound pages (of order > 1) do not suffer +This also means that huge pages and compound pages do not suffer from the false positives problem that is mentioned below.:: Function @@ -264,9 +264,9 @@ place.) Other diagnostics ================= -dump_page() has been enhanced slightly, to handle these new counting fields, and -to better report on compound pages in general. Specifically, for compound pages -with order > 1, the exact (hpage_pinned_refcount) pincount is reported. +dump_page() has been enhanced slightly, to handle these new counting +fields, and to better report on compound pages in general. Specifically, +for compound pages, the exact (compound_pincount) pincount is reported. References ========== diff --git a/Documentation/cpu-freq/cpu-drivers.rst b/Documentation/cpu-freq/cpu-drivers.rst index 3b32336a7803..d84ededb66f9 100644 --- a/Documentation/cpu-freq/cpu-drivers.rst +++ b/Documentation/cpu-freq/cpu-drivers.rst @@ -75,6 +75,9 @@ And optionally .resume - A pointer to a per-policy resume function which is called with interrupts disabled and _before_ the governor is started again. + .ready - A pointer to a per-policy ready function which is called after + the policy is fully initialized. + .attr - A pointer to a NULL-terminated list of "struct freq_attr" which allow to export values to sysfs. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 010a2af1e7d9..4621eac290f4 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst kgdb kselftest kunit/index + ktap .. only:: subproject and html diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 7db43c7c09b8..3ae866dcc924 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -204,17 +204,17 @@ Ultimately this allows to determine the possible executions of concurrent code, and if that code is free from data races. KCSAN is aware of *marked atomic operations* (``READ_ONCE``, ``WRITE_ONCE``, -``atomic_*``, etc.), but is oblivious of any ordering guarantees and simply -assumes that memory barriers are placed correctly. In other words, KCSAN -assumes that as long as a plain access is not observed to race with another -conflicting access, memory operations are correctly ordered. - -This means that KCSAN will not report *potential* data races due to missing -memory ordering. Developers should therefore carefully consider the required -memory ordering requirements that remain unchecked. If, however, missing -memory ordering (that is observable with a particular compiler and -architecture) leads to an observable data race (e.g. entering a critical -section erroneously), KCSAN would report the resulting data race. +``atomic_*``, etc.), and a subset of ordering guarantees implied by memory +barriers. With ``CONFIG_KCSAN_WEAK_MEMORY=y``, KCSAN models load or store +buffering, and can detect missing ``smp_mb()``, ``smp_wmb()``, ``smp_rmb()``, +``smp_store_release()``, and all ``atomic_*`` operations with equivalent +implied barriers. + +Note, KCSAN will not report all data races due to missing memory ordering, +specifically where a memory barrier would be required to prohibit subsequent +memory operation from reordering before the barrier. Developers should +therefore carefully consider the required memory ordering requirements that +remain unchecked. Race Detection Beyond Data Races -------------------------------- @@ -268,6 +268,56 @@ marked operations, if all accesses to a variable that is accessed concurrently are properly marked, KCSAN will never trigger a watchpoint and therefore never report the accesses. +Modeling Weak Memory +~~~~~~~~~~~~~~~~~~~~ + +KCSAN's approach to detecting data races due to missing memory barriers is +based on modeling access reordering (with ``CONFIG_KCSAN_WEAK_MEMORY=y``). +Each plain memory access for which a watchpoint is set up, is also selected for +simulated reordering within the scope of its function (at most 1 in-flight +access). + +Once an access has been selected for reordering, it is checked along every +other access until the end of the function scope. If an appropriate memory +barrier is encountered, the access will no longer be considered for simulated +reordering. + +When the result of a memory operation should be ordered by a barrier, KCSAN can +then detect data races where the conflict only occurs as a result of a missing +barrier. Consider the example:: + + int x, flag; + void T1(void) + { + x = 1; // data race! + WRITE_ONCE(flag, 1); // correct: smp_store_release(&flag, 1) + } + void T2(void) + { + while (!READ_ONCE(flag)); // correct: smp_load_acquire(&flag) + ... = x; // data race! + } + +When weak memory modeling is enabled, KCSAN can consider ``x`` in ``T1`` for +simulated reordering. After the write of ``flag``, ``x`` is again checked for +concurrent accesses: because ``T2`` is able to proceed after the write of +``flag``, a data race is detected. With the correct barriers in place, ``x`` +would not be considered for reordering after the proper release of ``flag``, +and no data race would be detected. + +Deliberate trade-offs in complexity but also practical limitations mean only a +subset of data races due to missing memory barriers can be detected. With +currently available compiler support, the implementation is limited to modeling +the effects of "buffering" (delaying accesses), since the runtime cannot +"prefetch" accesses. Also recall that watchpoints are only set up for plain +accesses, and the only access type for which KCSAN simulates reordering. This +means reordering of marked accesses is not modeled. + +A consequence of the above is that acquire operations do not require barrier +instrumentation (no prefetching). Furthermore, marked accesses introducing +address or control dependencies do not require special handling (the marked +access cannot be reordered, later dependent accesses cannot be prefetched). + Key Properties ~~~~~~~~~~~~~~ @@ -290,8 +340,8 @@ Key Properties 4. **Detects Racy Writes from Devices:** Due to checking data values upon setting up watchpoints, racy writes from devices can also be detected. -5. **Memory Ordering:** KCSAN is *not* explicitly aware of the LKMM's ordering - rules; this may result in missed data races (false negatives). +5. **Memory Ordering:** KCSAN is aware of only a subset of LKMM ordering rules; + this may result in missed data races (false negatives). 6. **Analysis Accuracy:** For observed executions, due to using a sampling strategy, the analysis is *unsound* (false negatives possible), but aims to diff --git a/Documentation/dev-tools/kfence.rst b/Documentation/dev-tools/kfence.rst index ac6b89d1a8c3..936f6aaa75c8 100644 --- a/Documentation/dev-tools/kfence.rst +++ b/Documentation/dev-tools/kfence.rst @@ -41,6 +41,18 @@ guarded by KFENCE. The default is configurable via the Kconfig option ``CONFIG_KFENCE_SAMPLE_INTERVAL``. Setting ``kfence.sample_interval=0`` disables KFENCE. +The sample interval controls a timer that sets up KFENCE allocations. By +default, to keep the real sample interval predictable, the normal timer also +causes CPU wake-ups when the system is completely idle. This may be undesirable +on power-constrained systems. The boot parameter ``kfence.deferrable=1`` +instead switches to a "deferrable" timer which does not force CPU wake-ups on +idle systems, at the risk of unpredictable sample intervals. The default is +configurable via the Kconfig option ``CONFIG_KFENCE_DEFERRABLE``. + +.. warning:: + The KUnit test suite is very likely to fail when using a deferrable timer + since it currently causes very unpredictable sample intervals. + The KFENCE memory pool is of fixed size, and if the pool is exhausted, no further KFENCE allocations occur. With ``CONFIG_KFENCE_NUM_OBJECTS`` (default 255), the number of available guarded objects can be controlled. Each object diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 43456244651a..f83ba2601e55 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -402,7 +402,7 @@ This is a quick example of how to use kdb. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -461,7 +461,7 @@ This is a quick example of how to use kdb with a keyboard. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -557,7 +557,7 @@ Connecting with gdb to a serial port Example (using a directly connected port):: % gdb ./vmlinux - (gdb) set remotebaud 115200 + (gdb) set serial baud 115200 (gdb) target remote /dev/ttyS0 diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index dcefee707ccd..a833ecf12fbc 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -7,6 +7,14 @@ directory. These are intended to be small tests to exercise individual code paths in the kernel. Tests are intended to be run after building, installing and booting a kernel. +Kselftest from mainline can be run on older stable kernels. Running tests +from mainline offers the best coverage. Several test rings run mainline +kselftest suite on stable releases. The reason is that when a new test +gets added to test existing code to regression test a bug, we should be +able to run that test on an older kernel. Hence, it is important to keep +code that can still test an older kernel and make sure it skips the test +gracefully on newer releases. + You can find additional information on Kselftest framework, how to write new tests using the framework on Kselftest wiki: diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst new file mode 100644 index 000000000000..5ee735c6687f --- /dev/null +++ b/Documentation/dev-tools/ktap.rst @@ -0,0 +1,313 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================== +The Kernel Test Anything Protocol (KTAP), version 1 +=================================================== + +TAP, or the Test Anything Protocol is a format for specifying test results used +by a number of projects. It's website and specification are found at this `link +<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test +results. However, Kernel testing frameworks have special needs for test results +which don't align with the original TAP specification. Thus, a "Kernel TAP" +(KTAP) format is specified to extend and alter TAP to support these use-cases. +This specification describes the generally accepted format of KTAP as it is +currently used in the kernel. + +KTAP test results describe a series of tests (which may be nested: i.e., test +can have subtests), each of which can contain both diagnostic data -- e.g., log +lines -- and a final result. The test structure and results are +machine-readable, whereas the diagnostic data is unstructured and is there to +aid human debugging. + +KTAP output is built from four different types of lines: +- Version lines +- Plan lines +- Test case result lines +- Diagnostic lines + +In general, valid KTAP output should also form valid TAP output, but some +information, in particular nested test results, may be lost. Also note that +there is a stagnant draft specification for TAP14, KTAP diverges from this in +a couple of places (notably the "Subtest" header), which are described where +relevant later in this document. + +Version lines +------------- + +All KTAP-formatted results begin with a "version line" which specifies which +version of the (K)TAP standard the result is compliant with. + +For example: +- "KTAP version 1" +- "TAP version 13" +- "TAP version 14" + +Note that, in KTAP, subtests also begin with a version line, which denotes the +start of the nested test results. This differs from TAP14, which uses a +separate "Subtest" line. + +While, going forward, "KTAP version 1" should be used by compliant tests, it +is expected that most parsers and other tooling will accept the other versions +listed here for compatibility with existing tests and frameworks. + +Plan lines +---------- + +A test plan provides the number of tests (or subtests) in the KTAP output. + +Plan lines must follow the format of "1..N" where N is the number of tests or subtests. +Plan lines follow version lines to indicate the number of nested tests. + +While there are cases where the number of tests is not known in advance -- in +which case the test plan may be omitted -- it is strongly recommended one is +present where possible. + +Test case result lines +---------------------- + +Test case result lines indicate the final status of a test. +They are required and must have the format: + +.. code-block:: none + + <result> <number> [<description>][ # [<directive>] [<diagnostic data>]] + +The result can be either "ok", which indicates the test case passed, +or "not ok", which indicates that the test case failed. + +<number> represents the number of the test being performed. The first test must +have the number 1 and the number then must increase by 1 for each additional +subtest within the same test at the same nesting level. + +The description is a description of the test, generally the name of +the test, and can be any string of words (can't include #). The +description is optional, but recommended. + +The directive and any diagnostic data is optional. If either are present, they +must follow a hash sign, "#". + +A directive is a keyword that indicates a different outcome for a test other +than passed and failed. The directive is optional, and consists of a single +keyword preceding the diagnostic data. In the event that a parser encounters +a directive it doesn't support, it should fall back to the "ok" / "not ok" +result. + +Currently accepted directives are: + +- "SKIP", which indicates a test was skipped (note the result of the test case + result line can be either "ok" or "not ok" if the SKIP directive is used) +- "TODO", which indicates that a test is not expected to pass at the moment, + e.g. because the feature it is testing is known to be broken. While this + directive is inherited from TAP, its use in the kernel is discouraged. +- "XFAIL", which indicates that a test is expected to fail. This is similar + to "TODO", above, and is used by some kselftest tests. +- “TIMEOUTâ€, which indicates a test has timed out (note the result of the test + case result line should be “not ok†if the TIMEOUT directive is used) +- “ERRORâ€, which indicates that the execution of a test has failed due to a + specific error that is included in the diagnostic data. (note the result of + the test case result line should be “not ok†if the ERROR directive is used) + +The diagnostic data is a plain-text field which contains any additional details +about why this result was produced. This is typically an error message for ERROR +or failed tests, or a description of missing dependencies for a SKIP result. + +The diagnostic data field is optional, and results which have neither a +directive nor any diagnostic data do not need to include the "#" field +separator. + +Example result lines include: + +.. code-block:: none + + ok 1 test_case_name + +The test "test_case_name" passed. + +.. code-block:: none + + not ok 1 test_case_name + +The test "test_case_name" failed. + +.. code-block:: none + + ok 1 test # SKIP necessary dependency unavailable + +The test "test" was SKIPPED with the diagnostic message "necessary dependency +unavailable". + +.. code-block:: none + + not ok 1 test # TIMEOUT 30 seconds + +The test "test" timed out, with diagnostic data "30 seconds". + +.. code-block:: none + + ok 5 check return code # rcode=0 + +The test "check return code" passed, with additional diagnostic data “rcode=0†+ + +Diagnostic lines +---------------- + +If tests wish to output any further information, they should do so using +"diagnostic lines". Diagnostic lines are optional, freeform text, and are +often used to describe what is being tested and any intermediate results in +more detail than the final result and diagnostic data line provides. + +Diagnostic lines are formatted as "# <diagnostic_description>", where the +description can be any string. Diagnostic lines can be anywhere in the test +output. As a rule, diagnostic lines regarding a test are directly before the +test result line for that test. + +Note that most tools will treat unknown lines (see below) as diagnostic lines, +even if they do not start with a "#": this is to capture any other useful +kernel output which may help debug the test. It is nevertheless recommended +that tests always prefix any diagnostic output they have with a "#" character. + +Unknown lines +------------- + +There may be lines within KTAP output that do not follow the format of one of +the four formats for lines described above. This is allowed, however, they will +not influence the status of the tests. + +This is an important difference from TAP. Kernel tests may print messages +to the system console or a log file. Both of these destinations may contain +messages either from unrelated kernel or userspace activity, or kernel +messages from non-test code that is invoked by the test. The kernel code +invoked by the test likely is not aware that a test is in progress and +thus can not print the message as a diagnostic message. + +Nested tests +------------ + +In KTAP, tests can be nested. This is done by having a test include within its +output an entire set of KTAP-formatted results. This can be used to categorize +and group related tests, or to split out different results from the same test. + +The "parent" test's result should consist of all of its subtests' results, +starting with another KTAP version line and test plan, and end with the overall +result. If one of the subtests fail, for example, the parent test should also +fail. + +Additionally, all lines in a subtest should be indented. One level of +indentation is two spaces: " ". The indentation should begin at the version +line and should end before the parent test's result line. + +"Unknown lines" are not considered to be lines in a subtest and thus are +allowed to be either indented or not indented. + +An example of a test with two nested subtests: + +.. code-block:: none + + KTAP version 1 + 1..1 + KTAP version 1 + 1..2 + ok 1 test_1 + not ok 2 test_2 + # example failed + not ok 1 example + +An example format with multiple levels of nested testing: + +.. code-block:: none + + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + not ok 1 test_1 + ok 2 test_2 + not ok 1 test_3 + ok 2 test_4 # SKIP + not ok 1 example_test_1 + ok 2 example_test_2 + + +Major differences between TAP and KTAP +-------------------------------------- + +================================================== ========= =============== +Feature TAP KTAP +================================================== ========= =============== +yaml and json in diagnosic message ok not recommended +TODO directive ok not recognized +allows an arbitrary number of tests to be nested no yes +"Unknown lines" are in category of "Anything else" yes no +"Unknown lines" are incorrect allowed +================================================== ========= =============== + +The TAP14 specification does permit nested tests, but instead of using another +nested version line, uses a line of the form +"Subtest: <name>" where <name> is the name of the parent test. + +Example KTAP output +-------------------- +.. code-block:: none + + KTAP version 1 + 1..1 + KTAP version 1 + 1..3 + KTAP version 1 + 1..1 + # test_1: initializing test_1 + ok 1 test_1 + ok 1 example_test_1 + KTAP version 1 + 1..2 + ok 1 test_1 # SKIP test_1 skipped + ok 2 test_2 + ok 2 example_test_2 + KTAP version 1 + 1..3 + ok 1 test_1 + # test_2: FAIL + not ok 2 test_2 + ok 3 test_3 # SKIP test_3 skipped + not ok 3 example_test_3 + not ok 1 main_test + +This output defines the following hierarchy: + +A single test called "main_test", which fails, and has three subtests: +- "example_test_1", which passes, and has one subtest: + + - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1" + +- "example_test_2", which passes, and has two subtests: + + - "test_1", which is skipped, with the explanation "test_1 skipped" + - "test_2", which passes + +- "example_test_3", which fails, and has three subtests + + - "test_1", which passes + - "test_2", which outputs the diagnostic line "test_2: FAIL", and fails. + - "test_3", which is skipped with the explanation "test_3 skipped" + +Note that the individual subtests with the same names do not conflict, as they +are found in different parent tests. This output also exhibits some sensible +rules for "bubbling up" test results: a test fails if any of its subtests fail. +Skipped tests do not affect the result of the parent test (though it often +makes sense for a test to be marked skipped if _all_ of its subtests have been +skipped). + +See also: +--------- + +- The TAP specification: + https://testanything.org/tap-version-13-specification.html +- The (stagnant) TAP version 14 specification: + https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md +- The kselftest documentation: + Documentation/dev-tools/kselftest.rst +- The KUnit documentation: + Documentation/dev-tools/kunit/index.rst diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst new file mode 100644 index 000000000000..aa2cea821e25 --- /dev/null +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -0,0 +1,204 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +KUnit Architecture +================== + +The KUnit architecture can be divided into two parts: + +- Kernel testing library +- kunit_tool (Command line test harness) + +In-Kernel Testing Framework +=========================== + +The kernel testing library supports KUnit tests written in C using +KUnit. KUnit tests are kernel code. KUnit does several things: + +- Organizes tests +- Reports test results +- Provides test utilities + +Test Cases +---------- + +The fundamental unit in KUnit is the test case. The KUnit test cases are +grouped into KUnit suites. A KUnit test case is a function with type +signature ``void (*)(struct kunit *test)``. +These test case functions are wrapped in a struct called +``struct kunit_case``. For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: kunit_case + +.. note: + ``generate_params`` is optional for non-parameterized tests. + +Each KUnit test case gets a ``struct kunit`` context +object passed to it that tracks a running test. The KUnit assertion +macros and other KUnit utilities use the ``struct kunit`` context +object. As an exception, there are two fields: + +- ``->priv``: The setup functions can use it to store arbitrary test + user data. + +- ``->param_value``: It contains the parameter value which can be + retrieved in the parameterized tests. + +Test Suites +----------- + +A KUnit suite includes a collection of test cases. The KUnit suites +are represented by the ``struct kunit_suite``. For example: + +.. code-block:: c + + static struct kunit_case example_test_cases[] = { + KUNIT_CASE(example_test_foo), + KUNIT_CASE(example_test_bar), + KUNIT_CASE(example_test_baz), + {} + }; + + static struct kunit_suite example_test_suite = { + .name = "example", + .init = example_test_init, + .exit = example_test_exit, + .test_cases = example_test_cases, + }; + kunit_test_suite(example_test_suite); + +In the above example, the test suite ``example_test_suite``, runs the +test cases ``example_test_foo``, ``example_test_bar``, and +``example_test_baz``. Before running the test, the ``example_test_init`` +is called and after running the test, ``example_test_exit`` is called. +The ``kunit_test_suite(example_test_suite)`` registers the test suite +with the KUnit test framework. + +Executor +-------- + +The KUnit executor can list and run built-in KUnit tests on boot. +The Test suites are stored in a linker section +called ``.kunit_test_suites``. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945. +The linker section consists of an array of pointers to +``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` +macro. To run all tests compiled into the kernel, the KUnit executor +iterates over the linker section array. + +.. kernel-figure:: kunit_suitememorydiagram.svg + :alt: KUnit Suite Memory + + KUnit Suite Memory Diagram + +On the kernel boot, the KUnit executor uses the start and end addresses +of this section to iterate over and run all tests. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c + +When built as a module, the ``kunit_test_suites()`` macro defines a +``module_init()`` function, which runs all the tests in the compilation +unit instead of utilizing the executor. + +In KUnit tests, some error classes do not affect other tests +or parts of the kernel, each KUnit case executes in a separate thread +context. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58 + +Assertion Macros +---------------- + +KUnit tests verify state using expectations/assertions. +All expectations/assertions are formatted as: +``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])`` + +- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an + expectation. + + - For an expectation, if the check fails, marks the test as failed + and logs the failure. + + - An assertion, on failure, causes the test case to terminate + immediately. + + - Assertions call function: + ``void __noreturn kunit_abort(struct kunit *)``. + + - ``kunit_abort`` calls function: + ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. + + - ``kunit_try_catch_throw`` calls function: + ``void complete_and_exit(struct completion *, long) __noreturn;`` + and terminates the special thread context. + +- ``<op>`` denotes a check with options: ``TRUE`` (supplied property + has the boolean value “trueâ€), ``EQ`` (two supplied properties are + equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not + contain an “err†value). + +- ``[_MSG]`` prints a custom message on failure. + +Test Result Reporting +--------------------- +KUnit prints test results in KTAP format. KTAP is based on TAP14, see: +https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md. +KTAP (yet to be standardized format) works with KUnit and Kselftest. +The KUnit executor prints KTAP results to dmesg, and debugfs +(if configured). + +Parameterized Tests +------------------- + +Each KUnit parameterized test is associated with a collection of +parameters. The test is invoked multiple times, once for each parameter +value and the parameter is stored in the ``param_value`` field. +The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a +generator function. +The generator function is passed the previous parameter and returns the next +parameter. It also provides a macro to generate common-case generators based on +arrays. + +For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: KUNIT_ARRAY_PARAM + + +kunit_tool (Command Line Test Harness) +====================================== + +kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)`` +that can be used to configure, build, exec, parse and run (runs other +commands in order) test results. You can either run KUnit tests using +kunit_tool or can include KUnit in kernel and parse manually. + +- ``configure`` command generates the kernel ``.config`` from a + ``.kunitconfig`` file (and any architecture-specific options). + For some architectures, additional config options are specified in the + ``qemu_config`` Python script + (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``). + It parses both the existing ``.config`` and the ``.kunitconfig`` files + and ensures that ``.config`` is a superset of ``.kunitconfig``. + If this is not the case, it will combine the two and run + ``make olddefconfig`` to regenerate the ``.config`` file. It then + verifies that ``.config`` is now a superset. This checks if all + Kconfig dependencies are correctly specified in ``.kunitconfig``. + ``kunit_config.py`` includes the parsing Kconfigs code. The code which + runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can + invoke this command via: ``./tools/testing/kunit/kunit.py config`` and + generate a ``.config`` file. +- ``build`` runs ``make`` on the kernel tree with required options + (depends on the architecture and some options, for example: build_dir) + and reports any errors. + To build a KUnit kernel from the current ``.config``, you can use the + ``build`` argument: ``./tools/testing/kunit/kunit.py build``. +- ``exec`` command executes kernel results either directly (using + User-mode Linux configuration), or via an emulator such + as QEMU. It reads results from the log via standard + output (stdout), and passes them to ``parse`` to be parsed. + If you already have built a kernel with built-in KUnit tests, + you can run the kernel and display the test results with the ``exec`` + argument: ``./tools/testing/kunit/kunit.py exec``. +- ``parse`` extracts the KTAP output from a kernel log, parses + the test results, and prints a summary. For failed tests, any + diagnostic output will be included. diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 5c6555d020f3..172e239791a8 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -4,56 +4,55 @@ Frequently Asked Questions ========================== -How is this different from Autotest, kselftest, etc? -==================================================== +How is this different from Autotest, kselftest, and so on? +========================================================== KUnit is a unit testing framework. Autotest, kselftest (and some others) are not. A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is supposed to -test a single unit of code in isolation, hence the name. A unit test should be -the finest granularity of testing and as such should allow all possible code -paths to be tested in the code under test; this is only possible if the code -under test is very small and does not have any external dependencies outside of +test a single unit of code in isolation and hence the name *unit test*. A unit +test should be the finest granularity of testing and should allow all possible +code paths to be tested in the code under test. This is only possible if the +code under test is small and does not have any external dependencies outside of the test's control like hardware. There are no testing frameworks currently available for the kernel that do not -require installing the kernel on a test machine or in a VM and all require -tests to be written in userspace and run on the kernel under test; this is true -for Autotest, kselftest, and some others, disqualifying any of them from being -considered unit testing frameworks. +require installing the kernel on a test machine or in a virtual machine. All +testing frameworks require tests to be written in userspace and run on the +kernel under test. This is true for Autotest, kselftest, and some others, +disqualifying any of them from being considered unit testing frameworks. Does KUnit support running on architectures other than UML? =========================================================== -Yes, well, mostly. +Yes, mostly. -For the most part, the KUnit core framework (what you use to write the tests) -can compile to any architecture; it compiles like just another part of the +For the most part, the KUnit core framework (what we use to write the tests) +can compile to any architecture. It compiles like just another part of the kernel and runs when the kernel boots, or when built as a module, when the -module is loaded. However, there is some infrastructure, -like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support -other architectures. +module is loaded. However, there is infrastructure, like the KUnit Wrapper +(``tools/testing/kunit/kunit.py``) that does not support other architectures. -In short, this means that, yes, you can run KUnit on other architectures, but -it might require more work than using KUnit on UML. +In short, yes, you can run KUnit on other architectures, but it might require +more work than using KUnit on UML. For more information, see :ref:`kunit-on-non-uml`. -What is the difference between a unit test and these other kinds of tests? -========================================================================== +What is the difference between a unit test and other kinds of tests? +==================================================================== Most existing tests for the Linux kernel would be categorized as an integration test, or an end-to-end test. -- A unit test is supposed to test a single unit of code in isolation, hence the - name. A unit test should be the finest granularity of testing and as such - should allow all possible code paths to be tested in the code under test; this - is only possible if the code under test is very small and does not have any - external dependencies outside of the test's control like hardware. +- A unit test is supposed to test a single unit of code in isolation. A unit + test should be the finest granularity of testing and, as such, allows all + possible code paths to be tested in the code under test. This is only possible + if the code under test is small and does not have any external dependencies + outside of the test's control like hardware. - An integration test tests the interaction between a minimal set of components, usually just two or three. For example, someone might write an integration test to test the interaction between a driver and a piece of hardware, or to test the interaction between the userspace libraries the kernel provides and - the kernel itself; however, one of these tests would probably not test the + the kernel itself. However, one of these tests would probably not test the entire kernel along with hardware interactions and interactions with the userspace. - An end-to-end test usually tests the entire system from the perspective of the @@ -62,26 +61,26 @@ test, or an end-to-end test. hardware with a production userspace and then trying to exercise some behavior that depends on interactions between the hardware, the kernel, and userspace. -KUnit isn't working, what should I do? -====================================== +KUnit is not working, what should I do? +======================================= Unfortunately, there are a number of things which can break, but here are some things to try. -1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` +1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` parameter. This might show details or error messages hidden by the kunit_tool parser. 2. Instead of running ``kunit.py run``, try running ``kunit.py config``, ``kunit.py build``, and ``kunit.py exec`` independently. This can help track down where an issue is occurring. (If you think the parser is at fault, you - can run it manually against stdin or a file with ``kunit.py parse``.) -3. Running the UML kernel directly can often reveal issues or error messages - kunit_tool ignores. This should be as simple as running ``./vmlinux`` after - building the UML kernel (e.g., by using ``kunit.py build``). Note that UML - has some unusual requirements (such as the host having a tmpfs filesystem - mounted), and has had issues in the past when built statically and the host - has KASLR enabled. (On older host kernels, you may need to run ``setarch - `uname -m` -R ./vmlinux`` to disable KASLR.) + can run it manually against ``stdin`` or a file with ``kunit.py parse``.) +3. Running the UML kernel directly can often reveal issues or error messages, + ``kunit_tool`` ignores. This should be as simple as running ``./vmlinux`` + after building the UML kernel (for example, by using ``kunit.py build``). + Note that UML has some unusual requirements (such as the host having a tmpfs + filesystem mounted), and has had issues in the past when built statically and + the host has KASLR enabled. (On older host kernels, you may need to run + ``setarch `uname -m` -R ./vmlinux`` to disable KASLR.) 4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config around, so you can see what config was used after running ``kunit.py run``. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index 7af7dec83646..595205348d2d 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -1,13 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0 -========================================= -KUnit - Unit Testing for the Linux Kernel -========================================= +================================= +KUnit - Linux Kernel Unit Testing +================================= .. toctree:: :maxdepth: 2 + :caption: Contents: start + architecture + run_wrapper + run_manual usage kunit-tool api/index @@ -16,82 +20,94 @@ KUnit - Unit Testing for the Linux Kernel tips running_tips -What is KUnit? -============== - -KUnit is a lightweight unit testing framework for the Linux kernel. - -KUnit is heavily inspired by JUnit, Python's unittest.mock, and -Googletest/Googlemock for C++. KUnit provides facilities for defining unit test -cases, grouping related test cases into test suites, providing common -infrastructure for running tests, and much more. - -KUnit consists of a kernel component, which provides a set of macros for easily -writing unit tests. Tests written against KUnit will run on kernel boot if -built-in, or when loaded if built as a module. These tests write out results to -the kernel log in `TAP <https://testanything.org/>`_ format. - -To make running these tests (and reading the results) easier, KUnit offers -:doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux -<http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test -results. This provides a quick way of running KUnit tests during development, -without requiring a virtual machine or separate hardware. - -Get started now: Documentation/dev-tools/kunit/start.rst - -Why KUnit? -========== - -A unit test is supposed to test a single unit of code in isolation, hence the -name. A unit test should be the finest granularity of testing and as such should -allow all possible code paths to be tested in the code under test; this is only -possible if the code under test is very small and does not have any external -dependencies outside of the test's control like hardware. - -KUnit provides a common framework for unit tests within the kernel. - -KUnit tests can be run on most architectures, and most tests are architecture -independent. All built-in KUnit tests run on kernel startup. Alternatively, -KUnit and KUnit tests can be built as modules and tests will run when the test -module is loaded. - -.. note:: - - KUnit can also run tests without needing a virtual machine or actual - hardware under User Mode Linux. User Mode Linux is a Linux architecture, - like ARM or x86, which compiles the kernel as a Linux executable. KUnit - can be used with UML either by building with ``ARCH=um`` (like any other - architecture), or by using :doc:`kunit_tool <kunit-tool>`. - -KUnit is fast. Excluding build time, from invocation to completion KUnit can run -several dozen tests in only 10 to 20 seconds; this might not sound like a big -deal to some people, but having such fast and easy to run tests fundamentally -changes the way you go about testing and even writing code in the first place. -Linus himself said in his `git talk at Google -<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_: - - "... a lot of people seem to think that performance is about doing the - same thing, just doing it faster, and that is not true. That is not what - performance is all about. If you can do something really fast, really - well, people will start using it differently." - -In this context Linus was talking about branching and merging, -but this point also applies to testing. If your tests are slow, unreliable, are -difficult to write, and require a special setup or special hardware to run, -then you wait a lot longer to write tests, and you wait a lot longer to run -tests; this means that tests are likely to break, unlikely to test a lot of -things, and are unlikely to be rerun once they pass. If your tests are really -fast, you run them all the time, every time you make a change, and every time -someone sends you some code. Why trust that someone ran all their tests -correctly on every change when you can just run them yourself in less time than -it takes to read their test log? +This section details the kernel unit testing framework. + +Introduction +============ + +KUnit (Kernel unit testing framework) provides a common framework for +unit tests within the Linux kernel. Using KUnit, you can define groups +of test cases called test suites. The tests either run on kernel boot +if built-in, or load as a module. KUnit automatically flags and reports +failed test cases in the kernel log. The test results appear in `TAP +(Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by +JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing +framework). + +KUnit tests are part of the kernel, written in the C (programming) +language, and test parts of the Kernel implementation (example: a C +language function). Excluding build time, from invocation to +completion, KUnit can run around 100 tests in less than 10 seconds. +KUnit can test any kernel component, for example: file system, system +calls, memory management, device drivers and so on. + +KUnit follows the white-box testing approach. The test has access to +internal system functionality. KUnit runs in kernel space and is not +restricted to things exposed to user-space. + +In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``) +that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode +Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and +displays them in a user friendly manner. + +Features +-------- + +- Provides a framework for writing unit tests. +- Runs tests on any kernel architecture. +- Runs a test in milliseconds. + +Prerequisites +------------- + +- Any Linux kernel compatible hardware. +- For Kernel under test, Linux kernel version 5.5 or greater. + +Unit Testing +============ + +A unit test tests a single unit of code in isolation. A unit test is the finest +granularity of testing and allows all possible code paths to be tested in the +code under test. This is possible if the code under test is small and does not +have any external dependencies outside of the test's control like hardware. + + +Write Unit Tests +---------------- + +To write good unit tests, there is a simple but powerful pattern: +Arrange-Act-Assert. This is a great way to structure test cases and +defines an order of operations. + +- Arrange inputs and targets: At the start of the test, arrange the data + that allows a function to work. Example: initialize a statement or + object. +- Act on the target behavior: Call your function/code under test. +- Assert expected outcome: Verify that the result (or resulting state) is as + expected. + +Unit Testing Advantages +----------------------- + +- Increases testing speed and development in the long run. +- Detects bugs at initial stage and therefore decreases bug fix cost + compared to acceptance testing. +- Improves code quality. +- Encourages writing testable code. How do I use it? ================ -* Documentation/dev-tools/kunit/start.rst - for new users of KUnit -* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices -* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features -* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing -* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script -* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit +* Documentation/dev-tools/kunit/start.rst - for KUnit new users. +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg new file mode 100644 index 000000000000..cf8fddc27500 --- /dev/null +++ b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg width="796.93" height="555.73" version="1.1" viewBox="0 0 796.93 555.73" xmlns="http://www.w3.org/2000/svg"> + <g transform="translate(-13.724 -17.943)"> + <g fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"> + <rect x="323.56" y="18.443" width="115.75" height="41.331"/> + <rect x="323.56" y="463.09" width="115.75" height="41.331"/> + <rect x="323.56" y="531.84" width="115.75" height="41.331"/> + <rect x="323.56" y="88.931" width="115.75" height="74.231"/> + </g> + <g> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -258.6)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -217.27)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -175.94)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -134.61)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -41.331)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(3.4459e-5 -.71088)"> + <rect x="502.19" y="143.16" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="512.02319" y="168.02026" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="512.02319" y="168.02026" font-family="monospace">_kunit_suites_start</tspan></text> + </g> + <g transform="translate(3.0518e-5 -3.1753)"> + <rect x="502.19" y="445.69" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="521.61694" y="470.54846" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="521.61694" y="470.54846" font-family="monospace">_kunit_suites_end</tspan></text> + </g> + <rect x="14.224" y="277.78" width="134.47" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="32.062176" y="304.41287" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="32.062176" y="304.41287" font-family="monospace">.init.data</tspan></text> + <g transform="translate(217.98 145.12)" stroke="#1a1a1a"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + <g transform="translate(217.98 -298.66)" stroke="#1a1a1a"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + <g stroke="#1a1a1a"> + <rect x="323.56" y="328.49" width="115.75" height="51.549" fill="#b9dbc6"/> + <g transform="translate(217.98 -18.75)"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + </g> + <g transform="scale(1.0933 .9147)" stroke-width="32.937" aria-label="{"> + <path d="m275.49 545.57c-35.836-8.432-47.43-24.769-47.957-64.821v-88.536c-0.527-44.795-10.54-57.97-49.538-67.456 38.998-10.013 49.011-23.715 49.538-67.983v-88.536c0.527-40.052 12.121-56.389 47.957-64.821v-5.797c-65.348 0-85.901 17.391-86.955 73.253v93.806c-0.527 36.89-10.013 50.065-44.795 59.551 34.782 10.013 44.268 23.188 44.795 60.078v93.279c1.581 56.389 21.607 73.78 86.955 73.78z"/> + </g> + <g transform="scale(1.1071 .90325)" stroke-width="14.44" aria-label="{"> + <path d="m461.46 443.55c-15.711-3.6967-20.794-10.859-21.025-28.418v-38.815c-0.23104-19.639-4.6209-25.415-21.718-29.574 17.097-4.3898 21.487-10.397 21.718-29.805v-38.815c0.23105-17.559 5.314-24.722 21.025-28.418v-2.5415c-28.649 0-37.66 7.6244-38.122 32.115v41.126c-0.23105 16.173-4.3898 21.949-19.639 26.108 15.249 4.3898 19.408 10.166 19.639 26.339v40.895c0.69313 24.722 9.4728 32.346 38.122 32.346z"/> + </g> + <path d="m449.55 161.84v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/> + <g fill-rule="evenodd"> + <path d="m443.78 163.09 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/> + <path d="m453.1 156.94-10.648 6.1543 0.99804 0.57812 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/> + </g> + <path d="m449.55 461.91v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/> + <g fill-rule="evenodd"> + <path d="m443.78 463.16 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/> + <path d="m453.1 457-10.648 6.1562 0.99804 0.57617 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/> + </g> + <rect x="515.64" y="223.9" width="294.52" height="178.49" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="523.33319" y="262.52542" font-family="monospace" font-size="14.667px" style="line-height:1.25" xml:space="preserve"><tspan x="523.33319" y="262.52542"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_suite {</tspan><tspan x="523.33319" y="280.8588"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold"> const char</tspan> name[<tspan fill="#ff00ff" font-size="14.667px">256</tspan>];</tspan><tspan x="523.33319" y="299.19217"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">int</tspan> (*init)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="317.52554"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">void</tspan> (*exit)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="335.85892"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_case *test_cases;</tspan><tspan x="523.33319" y="354.19229"> ...</tspan><tspan x="523.33319" y="372.52567">};</tspan></text> + </g> +</svg> diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst new file mode 100644 index 000000000000..e7b46421f247 --- /dev/null +++ b/Documentation/dev-tools/kunit/run_manual.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Run Tests without kunit_tool +============================ + +If we do not want to use kunit_tool (For example: we want to integrate +with other systems, or run tests on real hardware), we can +include KUnit in any kernel, read out results, and parse manually. + +.. note:: KUnit is not designed for use in a production system. It is + possible that tests may reduce the stability or security of + the system. + +Configure the Kernel +==================== + +KUnit tests can run without kunit_tool. This can be useful, if: + +- We have an existing kernel configuration to test. +- Need to run on real hardware (or using an emulator/VM kunit_tool + does not support). +- Wish to integrate with some existing testing systems. + +KUnit is configured with the ``CONFIG_KUNIT`` option, and individual +tests can also be built by enabling their config options in our +``.config``. KUnit tests usually (but don't always) have config options +ending in ``_KUNIT_TEST``. Most tests can either be built as a module, +or be built into the kernel. + +.. note :: + + We can enable the ``KUNIT_ALL_TESTS`` config option to + automatically enable all tests with satisfied dependencies. This is + a good way of quickly testing everything applicable to the current + config. + +Once we have built our kernel (and/or modules), it is simple to run +the tests. If the tests are built-in, they will run automatically on the +kernel boot. The results will be written to the kernel log (``dmesg``) +in TAP format. + +If the tests are built as modules, they will run when the module is +loaded. + +.. code-block :: bash + + # modprobe example-test + +The results will appear in TAP format in ``dmesg``. + +.. note :: + + If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will + be accessible from the ``debugfs`` filesystem (if mounted). + They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in + TAP format. diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst new file mode 100644 index 000000000000..653985ce9cae --- /dev/null +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -0,0 +1,247 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Run Tests with kunit_tool +========================= + +We can either run KUnit tests using kunit_tool or can run tests +manually, and then use kunit_tool to parse the results. To run tests +manually, see: Documentation/dev-tools/kunit/run_manual.rst. +As long as we can build the kernel, we can run KUnit. + +kunit_tool is a Python script which configures and builds a kernel, runs +tests, and formats the test results. + +Run command: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run + +We should see the following: + +.. code-block:: + + Generating .config... + Building KUnit kernel... + Starting KUnit kernel... + +We may want to use the following options: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all + +- ``--timeout`` sets a maximum amount of time for tests to run. +- ``--jobs`` sets the number of threads to build the kernel. + +kunit_tool will generate a ``.kunitconfig`` with a default +configuration, if no other ``.kunitconfig`` file exists +(in the build directory). In addition, it verifies that the +generated ``.config`` file contains the ``CONFIG`` options in the +``.kunitconfig``. +It is also possible to pass a separate ``.kunitconfig`` fragment to +kunit_tool. This is useful if we have several different groups of +tests we want to run independently, or if we want to use pre-defined +test configs for certain subsystems. + +To use a different ``.kunitconfig`` file (such as one +provided to test a particular subsystem), pass it as an option: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig + +To view kunit_tool flags (optional command-line arguments), run: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --help + +Create a ``.kunitconfig`` File +=============================== + +If we want to run a specific set of tests (rather than those listed +in the KUnit ``defconfig``), we can provide Kconfig options in the +``.kunitconfig`` file. For default .kunitconfig, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config. +A ``.kunitconfig`` is a ``minconfig`` (a .config +generated by running ``make savedefconfig``), used for running a +specific set of tests. This file contains the regular Kernel configs +with specific test targets. The ``.kunitconfig`` also +contains any other config options required by the tests (For example: +dependencies for features under tests, configs that enable/disable +certain code blocks, arch configs and so on). + +To create a ``.kunitconfig``, using the KUnit ``defconfig``: + +.. code-block:: + + cd $PATH_TO_LINUX_REPO + cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig + +We can then add any other Kconfig options. For example: + +.. code-block:: + + CONFIG_LIST_KUNIT_TEST=y + +kunit_tool ensures that all config options in ``.kunitconfig`` are +set in the kernel ``.config`` before running the tests. It warns if we +have not included the options dependencies. + +.. note:: Removing something from the ``.kunitconfig`` will + not rebuild the ``.config file``. The configuration is only + updated if the ``.kunitconfig`` is not a subset of ``.config``. + This means that we can use other tools + (For example: ``make menuconfig``) to adjust other config options. + The build dir needs to be set for ``make menuconfig`` to + work, therefore by default use ``make O=.kunit menuconfig``. + +Configure, Build, and Run Tests +=============================== + +If we want to make manual changes to the KUnit build process, we +can run part of the KUnit build process independently. +When running kunit_tool, from a ``.kunitconfig``, we can generate a +``.config`` by using the ``config`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py config + +To build a KUnit kernel from the current ``.config``, we can use the +``build`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py build + +If we already have built UML kernel with built-in KUnit tests, we +can run the kernel, and display the test results with the ``exec`` +argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py exec + +The ``run`` command discussed in section: **Run Tests with kunit_tool**, +is equivalent to running the above three commands in sequence. + +Parse Test Results +================== + +KUnit tests output displays results in TAP (Test Anything Protocol) +format. When running tests, kunit_tool parses this output and prints +a summary. To see the raw test results in TAP format, we can pass the +``--raw_output`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --raw_output + +If we have KUnit results in the raw TAP format, we can parse them and +print the human-readable summary with the ``parse`` command for +kunit_tool. This accepts a filename for an argument, or will read from +standard input. + +.. code-block:: bash + + # Reading from a file + ./tools/testing/kunit/kunit.py parse /var/log/dmesg + # Reading from stdin + dmesg | ./tools/testing/kunit/kunit.py parse + +Run Selected Test Suites +======================== + +By passing a bash style glob filter to the ``exec`` or ``run`` +commands, we can run a subset of the tests built into a kernel . For +example: if we only want to run KUnit resource tests, use: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run 'kunit-resource*' + +This uses the standard glob format with wildcard characters. + +Run Tests on qemu +================= + +kunit_tool supports running tests on qemu as well as +via UML. To run tests on qemu, by default it requires two flags: + +- ``--arch``: Selects a configs collection (Kconfig, qemu config options + and so on), that allow KUnit tests to be run on the specified + architecture in a minimal way. The architecture argument is same as + the option name passed to the ``ARCH`` variable used by Kbuild. + Not all architectures currently support this flag, but we can use + ``--qemu_config`` to handle it. If ``um`` is passed (or this flag + is ignored), the tests will run via UML. Non-UML architectures, + for example: i386, x86_64, arm and so on; run on qemu. + +- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the + same argument as passed to the ``CROSS_COMPILE`` variable used by + Kbuild. As a reminder, this will be the prefix for the toolchain + binaries such as GCC. For example: + + - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on + our system. + + - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` + if we have downloaded the microblaze toolchain from the 0-day + website to a directory in our home directory called toolchains. + +If we want to run KUnit tests on an architecture not supported by +the ``--arch`` flag, or want to run KUnit tests on qemu using a +non-default configuration; then we can write our own``QemuConfig``. +These ``QemuConfigs`` are written in Python. They have an import line +``from..qemu_config import QemuArchParams`` at the top of the file. +The file must contain a variable called ``QEMU_ARCH`` that has an +instance of ``QemuArchParams`` assigned to it. See example in: +``tools/testing/kunit/qemu_configs/x86_64.py``. + +Once we have a ``QemuConfig``, we can pass it into kunit_tool, +using the ``--qemu_config`` flag. When used, this flag replaces the +``--arch`` flag. For example: using +``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear +as + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run \ + --timeout=60 \ + --jobs=12 \ + --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py + +To run existing KUnit tests on non-UML architectures, see: +Documentation/dev-tools/kunit/non_uml.rst. + +Command-Line Arguments +====================== + +kunit_tool has a number of other command-line arguments which can +be useful for our test environment. Below the most commonly used +command line arguments: + +- ``--help``: Lists all available options. To list common options, + place ``--help`` before the command. To list options specific to that + command, place ``--help`` after the command. + + .. note:: Different commands (``config``, ``build``, ``run``, etc) + have different supported options. +- ``--build_dir``: Specifies kunit_tool build directory. It includes + the ``.kunitconfig``, ``.config`` files and compiled kernel. + +- ``--make_options``: Specifies additional options to pass to make, when + compiling a kernel (using ``build`` or ``run`` commands). For example: + to enable compiler warnings, we can pass ``--make_options W=1``. + +- ``--alltests``: Builds a UML kernel with all config options enabled + using ``make allyesconfig``. This allows us to run as many tests as + possible. + + .. note:: It is slow and prone to breakage as new options are + added or modified. Instead, enable all tests + which have satisfied dependencies by adding + ``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``. diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index 0a5e65540974..ad168d16968f 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -4,132 +4,137 @@ Getting Started =============== -Installing dependencies +Installing Dependencies ======================= -KUnit has the same dependencies as the Linux kernel. As long as you can build -the kernel, you can run KUnit. +KUnit has the same dependencies as the Linux kernel. As long as you can +build the kernel, you can run KUnit. -Running tests with the KUnit Wrapper -==================================== -Included with KUnit is a simple Python wrapper which runs tests under User Mode -Linux, and formats the test results. - -The wrapper can be run with: +Running tests with kunit_tool +============================= +kunit_tool is a Python script, which configures and builds a kernel, runs +tests, and formats the test results. From the kernel repository, you +can run kunit_tool: .. code-block:: bash ./tools/testing/kunit/kunit.py run -For more information on this wrapper (also called kunit_tool) check out the -Documentation/dev-tools/kunit/kunit-tool.rst page. +For more information on this wrapper, see: +Documentation/dev-tools/kunit/run_wrapper.rst. + +Creating a ``.kunitconfig`` +--------------------------- + +By default, kunit_tool runs a selection of tests. However, you can specify which +unit tests to run by creating a ``.kunitconfig`` file with kernel config options +that enable only a specific set of tests and their dependencies. +The ``.kunitconfig`` file contains a list of kconfig options which are required +to run the desired targets. The ``.kunitconfig`` also contains any other test +specific config options, such as test dependencies. For example: the +``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on +``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS`` +or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has: -Creating a .kunitconfig ------------------------ -If you want to run a specific set of tests (rather than those listed in the -KUnit defconfig), you can provide Kconfig options in the ``.kunitconfig`` file. -This file essentially contains the regular Kernel config, with the specific -test targets as well. The ``.kunitconfig`` should also contain any other config -options required by the tests. +.. code-block:: none + + CONFIG_KUNIT=y + CONFIG_MSDOS_FS=y + CONFIG_FAT_KUNIT_TEST=y -A good starting point for a ``.kunitconfig`` is the KUnit defconfig: +1. A good starting point for the ``.kunitconfig``, is the KUnit default + config. Run the command: .. code-block:: bash cd $PATH_TO_LINUX_REPO cp tools/testing/kunit/configs/default.config .kunitconfig -You can then add any other Kconfig options you wish, e.g.: +.. note :: + You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as + it will enable a number of additional tests that you may not want. + +2. You can then add any other Kconfig options, for example: .. code-block:: none CONFIG_LIST_KUNIT_TEST=y -:doc:`kunit_tool <kunit-tool>` will ensure that all config options set in -``.kunitconfig`` are set in the kernel ``.config`` before running the tests. -It'll warn you if you haven't included the dependencies of the options you're -using. +Before running the tests, kunit_tool ensures that all config options +set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn +you if you have not included dependencies for the options used. -.. note:: +.. note :: If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the ``.config`` file. But you can edit the ``.config`` file directly or with tools like ``make menuconfig O=.kunit``. As long as its a superset of ``.kunitconfig``, kunit.py won't overwrite your changes. - -Running the tests (KUnit Wrapper) ---------------------------------- - -To make sure that everything is set up correctly, simply invoke the Python -wrapper from your kernel repo: +Running Tests (KUnit Wrapper) +----------------------------- +1. To make sure that everything is set up correctly, invoke the Python + wrapper from your kernel repository: .. code-block:: bash ./tools/testing/kunit/kunit.py run -.. note:: - You may want to run ``make mrproper`` first. - If everything worked correctly, you should see the following: -.. code-block:: bash +.. code-block:: Generating .config ... Building KUnit Kernel ... Starting KUnit Kernel ... -followed by a list of tests that are run. All of them should be passing. +The tests will pass or fail. -.. note:: - Because it is building a lot of sources for the first time, the - ``Building KUnit kernel`` step may take a while. +.. note :: + Because it is building a lot of sources for the first time, the + ``Building KUnit kernel`` may take a while. -Running tests without the KUnit Wrapper +Running Tests without the KUnit Wrapper ======================================= - -If you'd rather not use the KUnit Wrapper (if, for example, you need to -integrate with other systems, or use an architecture other than UML), KUnit can -be included in any kernel, and the results read out and parsed manually. - -.. note:: - KUnit is not designed for use in a production system, and it's possible that - tests may reduce the stability or security of the system. - - - -Configuring the kernel +If you do not want to use the KUnit Wrapper (for example: you want code +under test to integrate with other systems, or use a different/ +unsupported architecture or configuration), KUnit can be included in +any kernel, and the results are read out and parsed manually. + +.. note :: + ``CONFIG_KUNIT`` should not be enabled in a production environment. + Enabling KUnit disables Kernel Address-Space Layout Randomization + (KASLR), and tests may affect the state of the kernel in ways not + suitable for production. + +Configuring the Kernel ---------------------- +To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig +option (under Kernel Hacking/Kernel Testing and Coverage in +``menuconfig``). From there, you can enable any KUnit tests. They +usually have config options ending in ``_KUNIT_TEST``. -In order to enable KUnit itself, you simply need to enable the ``CONFIG_KUNIT`` -Kconfig option (it's under Kernel Hacking/Kernel Testing and Coverage in -menuconfig). From there, you can enable any KUnit tests you want: they usually -have config options ending in ``_KUNIT_TEST``. - -KUnit and KUnit tests can be compiled as modules: in this case the tests in a -module will be run when the module is loaded. +KUnit and KUnit tests can be compiled as modules. The tests in a module +will run when the module is loaded. - -Running the tests (w/o KUnit Wrapper) +Running Tests (without KUnit Wrapper) ------------------------------------- +Build and run your kernel. In the kernel log, the test output is printed +out in the TAP format. This will only happen by default if KUnit/tests +are built-in. Otherwise the module will need to be loaded. -Build and run your kernel as usual. Test output will be written to the kernel -log in `TAP <https://testanything.org/>`_ format. - -.. note:: - It's possible that there will be other lines and/or data interspersed in the - TAP output. - +.. note :: + Some lines and/or data may get interspersed in the TAP output. -Writing your first test +Writing Your First Test ======================= +In your kernel repository, let's add some code that we can test. -In your kernel repo let's add some code that we can test. Create a file -``drivers/misc/example.h`` with the contents: +1. Create a file ``drivers/misc/example.h``, which includes: .. code-block:: c int misc_example_add(int left, int right); -create a file ``drivers/misc/example.c``: +2. Create a file ``drivers/misc/example.c``, which includes: .. code-block:: c @@ -142,21 +147,22 @@ create a file ``drivers/misc/example.c``: return left + right; } -Now add the following lines to ``drivers/misc/Kconfig``: +3. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig config MISC_EXAMPLE bool "My example" -and the following lines to ``drivers/misc/Makefile``: +4. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE) += example.o -Now we are ready to write the test. The test will be in -``drivers/misc/example-test.c``: +Now we are ready to write the test cases. + +1. Add the below test case in ``drivers/misc/example_test.c``: .. code-block:: c @@ -191,7 +197,7 @@ Now we are ready to write the test. The test will be in }; kunit_test_suite(misc_example_test_suite); -Now add the following to ``drivers/misc/Kconfig``: +2. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig @@ -200,20 +206,20 @@ Now add the following to ``drivers/misc/Kconfig``: depends on MISC_EXAMPLE && KUNIT=y default KUNIT_ALL_TESTS -and the following to ``drivers/misc/Makefile``: +3. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make - obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o + obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o -Now add it to your ``.kunitconfig``: +4. Add the following lines to ``.kunitconfig``: .. code-block:: none CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y -Now you can run the test: +5. Run the test: .. code-block:: bash @@ -227,16 +233,23 @@ You should see the following failure: [16:08:57] [PASSED] misc-example:misc_example_add_test_basic [16:08:57] [FAILED] misc-example:misc_example_test_failure [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 - [16:08:57] This test never passes. + [16:08:57] This test never passes. ... -Congrats! You just wrote your first KUnit test! +Congrats! You just wrote your first KUnit test. Next Steps ========== -* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on - writing idiomatic KUnit tests. -* Check out the :doc:`running_tips` page for tips on - how to make running KUnit tests easier. -* Optional: see the :doc:`usage` page for a more - in-depth explanation of KUnit. + +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index 8dbcdc552606..b6d0d7359f00 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -4,37 +4,36 @@ Test Style and Nomenclature =========================== -To make finding, writing, and using KUnit tests as simple as possible, it's +To make finding, writing, and using KUnit tests as simple as possible, it is strongly encouraged that they are named and written according to the guidelines -below. While it's possible to write KUnit tests which do not follow these rules, +below. While it is possible to write KUnit tests which do not follow these rules, they may break some tooling, may conflict with other tests, and may not be run automatically by testing systems. -It's recommended that you only deviate from these guidelines when: +It is recommended that you only deviate from these guidelines when: -1. Porting tests to KUnit which are already known with an existing name, or -2. Writing tests which would cause serious problems if automatically run (e.g., - non-deterministically producing false positives or negatives, or taking an - extremely long time to run). +1. Porting tests to KUnit which are already known with an existing name. +2. Writing tests which would cause serious problems if automatically run. For + example, non-deterministically producing false positives or negatives, or + taking a long time to run. Subsystems, Suites, and Tests ============================= -In order to make tests as easy to find as possible, they're grouped into suites -and subsystems. A test suite is a group of tests which test a related area of -the kernel, and a subsystem is a set of test suites which test different parts -of the same kernel subsystem or driver. +To make tests easy to find, they are grouped into suites and subsystems. A test +suite is a group of tests which test a related area of the kernel. A subsystem +is a set of test suites which test different parts of a kernel subsystem +or a driver. Subsystems ---------- Every test suite must belong to a subsystem. A subsystem is a collection of one or more KUnit test suites which test the same driver or part of the kernel. A -rule of thumb is that a test subsystem should match a single kernel module. If -the code being tested can't be compiled as a module, in many cases the subsystem -should correspond to a directory in the source tree or an entry in the -MAINTAINERS file. If unsure, follow the conventions set by tests in similar -areas. +test subsystem should match a single kernel module. If the code being tested +cannot be compiled as a module, in many cases the subsystem should correspond to +a directory in the source tree or an entry in the ``MAINTAINERS`` file. If +unsure, follow the conventions set by tests in similar areas. Test subsystems should be named after the code being tested, either after the module (wherever possible), or after the directory or files being tested. Test @@ -42,9 +41,8 @@ subsystems should be named to avoid ambiguity where necessary. If a test subsystem name has multiple components, they should be separated by underscores. *Do not* include "test" or "kunit" directly in the subsystem name -unless you are actually testing other tests or the kunit framework itself. - -Example subsystems could be: +unless we are actually testing other tests or the kunit framework itself. For +example, subsystems could be called: ``ext4`` Matches the module and filesystem name. @@ -56,48 +54,46 @@ Example subsystems could be: Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name. -Avoid names like these: +Avoid names as shown in examples below: ``linear-ranges`` Names should use underscores, not dashes, to separate words. Prefer ``linear_ranges``. ``qos-kunit-test`` - As well as using underscores, this name should not have "kunit-test" as a - suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a - better name. + This name should use underscores, and not have "kunit-test" as a + suffix. ``qos`` is also ambiguous as a subsystem name, because several parts + of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name. ``pc_parallel_port`` The corresponding module name is ``parport_pc``, so this subsystem should also be named ``parport_pc``. .. note:: - The KUnit API and tools do not explicitly know about subsystems. They're - simply a way of categorising test suites and naming modules which - provides a simple, consistent way for humans to find and run tests. This - may change in the future, though. + The KUnit API and tools do not explicitly know about subsystems. They are + a way of categorizing test suites and naming modules which provides a + simple, consistent way for humans to find and run tests. This may change + in the future. Suites ------ KUnit tests are grouped into test suites, which cover a specific area of -functionality being tested. Test suites can have shared initialisation and -shutdown code which is run for all tests in the suite. -Not all subsystems will need to be split into multiple test suites (e.g. simple drivers). +functionality being tested. Test suites can have shared initialization and +shutdown code which is run for all tests in the suite. Not all subsystems need +to be split into multiple test suites (for example, simple drivers). Test suites are named after the subsystem they are part of. If a subsystem contains several suites, the specific area under test should be appended to the subsystem name, separated by an underscore. In the event that there are multiple types of test using KUnit within a -subsystem (e.g., both unit tests and integration tests), they should be put into -separate suites, with the type of test as the last element in the suite name. -Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or -similar in the suite name. +subsystem (for example, both unit tests and integration tests), they should be +put into separate suites, with the type of test as the last element in the suite +name. Unless these tests are actually present, avoid using ``_test``, ``_unittest`` +or similar in the suite name. The full test suite name (including the subsystem name) should be specified as the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the -module name (see below). - -Example test suites could include: +module name. For example, test suites could include: ``ext4_inode`` Part of the ``ext4`` subsystem, testing the ``inode`` area. @@ -109,26 +105,27 @@ Example test suites could include: The ``kasan`` subsystem has only one suite, so the suite name is the same as the subsystem name. -Avoid names like: +Avoid names, for example: ``ext4_ext4_inode`` - There's no reason to state the subsystem twice. + There is no reason to state the subsystem twice. ``property_entry`` The suite name is ambiguous without the subsystem name. ``kasan_integration_test`` Because there is only one suite in the ``kasan`` subsystem, the suite should - just be called ``kasan``. There's no need to redundantly add - ``integration_test``. Should a separate test suite with, for example, unit - tests be added, then that suite could be named ``kasan_unittest`` or similar. + just be called as ``kasan``. Do not redundantly add + ``integration_test``. It should be a separate test suite. For example, if the + unit tests are added, then that suite could be named as ``kasan_unittest`` or + similar. Test Cases ---------- Individual tests consist of a single function which tests a constrained -codepath, property, or function. In the test output, individual tests' results -will show up as subtests of the suite's results. +codepath, property, or function. In the test output, an individual test's +results will show up as subtests of the suite's results. -Tests should be named after what they're testing. This is often the name of the +Tests should be named after what they are testing. This is often the name of the function being tested, with a description of the input or codepath being tested. As tests are C functions, they should be named and written in accordance with the kernel coding style. @@ -136,7 +133,7 @@ the kernel coding style. .. note:: As tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative - naming. It's a good idea to make your test functions `static` to avoid + naming. It is a good idea to make your test functions `static` to avoid polluting the global namespace. Example test names include: @@ -162,16 +159,16 @@ This Kconfig entry must: * be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test suite. * be listed either alongside the config entries for the driver/subsystem being - tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage] -* depend on ``CONFIG_KUNIT`` + tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage] +* depend on ``CONFIG_KUNIT``. * be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled. * have a default value of ``CONFIG_KUNIT_ALL_TESTS``. -* have a brief description of KUnit in the help text +* have a brief description of KUnit in the help text. -Unless there's a specific reason not to (e.g. the test is unable to be built as -a module), Kconfig entries for tests should be tristate. +If we are not able to meet above conditions (for example, the test is unable to +be built as a module), Kconfig entries for tests should be tristate. -An example Kconfig entry: +For example, a Kconfig entry might look like: .. code-block:: none @@ -182,8 +179,8 @@ An example Kconfig entry: help This builds unit tests for foo. - For more information on KUnit and unit tests in general, please refer - to the KUnit documentation in Documentation/dev-tools/kunit/. + For more information on KUnit and unit tests in general, + please refer to the KUnit documentation in Documentation/dev-tools/kunit/. If unsure, say N. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 63f1bb89ebf5..1c83e7d60a8a 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -1,57 +1,13 @@ .. SPDX-License-Identifier: GPL-2.0 -=========== -Using KUnit -=========== - -The purpose of this document is to describe what KUnit is, how it works, how it -is intended to be used, and all the concepts and terminology that are needed to -understand it. This guide assumes a working knowledge of the Linux kernel and -some basic knowledge of testing. - -For a high level introduction to KUnit, including setting up KUnit for your -project, see Documentation/dev-tools/kunit/start.rst. - -Organization of this document -============================= - -This document is organized into two main sections: Testing and Common Patterns. -The first covers what unit tests are and how to use KUnit to write them. The -second covers common testing patterns, e.g. how to isolate code and make it -possible to unit test code that was otherwise un-unit-testable. - -Testing -======= - -What is KUnit? --------------- - -"K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing -Framework." KUnit is intended first and foremost for writing unit tests; it is -general enough that it can be used to write integration tests; however, this is -a secondary goal. KUnit has no ambition of being the only testing framework for -the kernel; for example, it does not intend to be an end-to-end testing -framework. - -What is Unit Testing? ---------------------- - -A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is a test that -tests code at the smallest possible scope, a *unit* of code. In the C -programming language that's a function. - -Unit tests should be written for all the publicly exposed functions in a -compilation unit; so that is all the functions that are exported in either a -*class* (defined below) or all functions which are **not** static. - Writing Tests -------------- +============= Test Cases -~~~~~~~~~~ +---------- The fundamental unit in KUnit is the test case. A test case is a function with -the signature ``void (*)(struct kunit *test)``. It calls a function to be tested +the signature ``void (*)(struct kunit *test)``. It calls the function under test and then sets *expectations* for what should happen. For example: .. code-block:: c @@ -65,18 +21,19 @@ and then sets *expectations* for what should happen. For example: KUNIT_FAIL(test, "This test never passes."); } -In the above example ``example_test_success`` always passes because it does -nothing; no expectations are set, so all expectations pass. On the other hand -``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is -a special expectation that logs a message and causes the test case to fail. +In the above example, ``example_test_success`` always passes because it does +nothing; no expectations are set, and therefore all expectations pass. On the +other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, +which is a special expectation that logs a message and causes the test case to +fail. Expectations ~~~~~~~~~~~~ -An *expectation* is a way to specify that you expect a piece of code to do -something in a test. An expectation is called like a function. A test is made -by setting expectations about the behavior of a piece of code under test; when -one or more of the expectations fail, the test case fails and information about -the failure is logged. For example: +An *expectation* specifies that we expect a piece of code to do something in a +test. An expectation is called like a function. A test is made by setting +expectations about the behavior of a piece of code under test. When one or more +expectations fail, the test case fails and information about the failure is +logged. For example: .. code-block:: c @@ -86,29 +43,28 @@ the failure is logged. For example: KUNIT_EXPECT_EQ(test, 2, add(1, 1)); } -In the above example ``add_test_basic`` makes a number of assertions about the -behavior of a function called ``add``; the first parameter is always of type -``struct kunit *``, which contains information about the current test context; -the second parameter, in this case, is what the value is expected to be; the +In the above example, ``add_test_basic`` makes a number of assertions about the +behavior of a function called ``add``. The first parameter is always of type +``struct kunit *``, which contains information about the current test context. +The second parameter, in this case, is what the value is expected to be. The last value is what the value actually is. If ``add`` passes all of these expectations, the test case, ``add_test_basic`` will pass; if any one of these expectations fails, the test case will fail. -It is important to understand that a test case *fails* when any expectation is -violated; however, the test will continue running, potentially trying other -expectations until the test case ends or is otherwise terminated. This is as -opposed to *assertions* which are discussed later. +A test case *fails* when any expectation is violated; however, the test will +continue to run, and try other expectations until the test case ends or is +otherwise terminated. This is as opposed to *assertions* which are discussed +later. -To learn about more expectations supported by KUnit, see -Documentation/dev-tools/kunit/api/test.rst. +To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst. .. note:: - A single test case should be pretty short, pretty easy to understand, - focused on a single behavior. + A single test case should be short, easy to understand, and focused on a + single behavior. -For example, if we wanted to properly test the add function above, we would -create additional tests cases which would each test a different property that an -add function should have like this: +For example, if we want to rigorously test the ``add`` function above, create +additional tests cases which would test each property that an ``add`` function +should have as shown below: .. code-block:: c @@ -134,56 +90,43 @@ add function should have like this: KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1)); } -Notice how it is immediately obvious what all the properties that we are testing -for are. - Assertions ~~~~~~~~~~ -KUnit also has the concept of an *assertion*. An assertion is just like an -expectation except the assertion immediately terminates the test case if it is -not satisfied. - -For example: +An assertion is like an expectation, except that the assertion immediately +terminates the test case if the condition is not satisfied. For example: .. code-block:: c - static void mock_test_do_expect_default_return(struct kunit *test) + static void test_sort(struct kunit *test) { - struct mock_test_context *ctx = test->priv; - struct mock *mock = ctx->mock; - int param0 = 5, param1 = -5; - const char *two_param_types[] = {"int", "int"}; - const void *two_params[] = {¶m0, ¶m1}; - const void *ret; - - ret = mock->do_expect(mock, - "test_printk", test_printk, - two_param_types, two_params, - ARRAY_SIZE(two_params)); - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ret); - KUNIT_EXPECT_EQ(test, -4, *((int *) ret)); + int *a, i, r = 1; + a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a); + for (i = 0; i < TEST_LEN; i++) { + r = (r * 725861) % 6599; + a[i] = r; + } + sort(a, TEST_LEN, sizeof(*a), cmpint, NULL); + for (i = 0; i < TEST_LEN-1; i++) + KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return a pointer to a value, so -if the pointer returned by the method is null or an errno, we don't want to -bother continuing the test since the following expectation could crash the test -case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if -the appropriate conditions have not been satisfied to complete the test. +In this example, the method under test should return pointer to a value. If the +pointer returns null or an errno, we want to stop the test since the following +expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us +to bail out of the test case if the appropriate conditions are not satisfied to +complete the test. Test Suites ~~~~~~~~~~~ -Now obviously one unit test isn't very helpful; the power comes from having -many test cases covering all of a unit's behaviors. Consequently it is common -to have many *similar* tests; in order to reduce duplication in these closely -related tests most unit testing frameworks - including KUnit - provide the -concept of a *test suite*. A *test suite* is just a collection of test cases -for a unit of code with a set up function that gets invoked before every test -case and then a tear down function that gets invoked after every test case -completes. - -Example: +We need many test cases covering all the unit's behaviors. It is common to have +many similar tests. In order to reduce duplication in these closely related +tests, most unit testing frameworks (including KUnit) provide the concept of a +*test suite*. A test suite is a collection of test cases for a unit of code +with a setup function that gets invoked before every test case and then a tear +down function that gets invoked after every test case completes. For example: .. code-block:: c @@ -202,23 +145,48 @@ Example: }; kunit_test_suite(example_test_suite); -In the above example the test suite, ``example_test_suite``, would run the test -cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``; -each would have ``example_test_init`` called immediately before it and would -have ``example_test_exit`` called immediately after it. +In the above example, the test suite ``example_test_suite`` would run the test +cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``. Each +would have ``example_test_init`` called immediately before it and +``example_test_exit`` called immediately after it. ``kunit_test_suite(example_test_suite)`` registers the test suite with the KUnit test framework. .. note:: - A test case will only be run if it is associated with a test suite. + A test case will only run if it is associated with a test suite. + +``kunit_test_suite(...)`` is a macro which tells the linker to put the +specified test suite in a special linker section so that it can be run by KUnit +either after ``late_init``, or when the test module is loaded (if the test was +built as a module). + +For more information, see Documentation/dev-tools/kunit/api/test.rst. + +Writing Tests For Other Architectures +------------------------------------- + +It is better to write tests that run on UML to tests that only run under a +particular architecture. It is better to write tests that run under QEMU or +another easy to obtain (and monetarily free) software environment to a specific +piece of hardware. -``kunit_test_suite(...)`` is a macro which tells the linker to put the specified -test suite in a special linker section so that it can be run by KUnit either -after late_init, or when the test module is loaded (depending on whether the -test was built in or not). +Nevertheless, there are still valid reasons to write a test that is architecture +or hardware specific. For example, we might want to test code that really +belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does +not depend on physical hardware. Some of our test cases may not need hardware, +only few tests actually require the hardware to test it. When hardware is not +available, instead of disabling tests, we can skip them. -For more information on these types of things see the -Documentation/dev-tools/kunit/api/test.rst. +Now that we have narrowed down exactly what bits are hardware specific, the +actual procedure for writing and running the tests is same as writing normal +KUnit tests. + +.. important:: + We may have to reset hardware state. If this is not possible, we may only + be able to run one test case per invocation. + +.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- + dependent KUnit test. Common Patterns =============== @@ -226,43 +194,39 @@ Common Patterns Isolating Behavior ------------------ -The most important aspect of unit testing that other forms of testing do not -provide is the ability to limit the amount of code under test to a single unit. -In practice, this is only possible by being able to control what code gets run -when the unit under test calls a function and this is usually accomplished -through some sort of indirection where a function is exposed as part of an API -such that the definition of that function can be changed without affecting the -rest of the code base. In the kernel this primarily comes from two constructs, -classes, structs that contain function pointers that are provided by the -implementer, and architecture-specific functions which have definitions selected -at compile time. +Unit testing limits the amount of code under test to a single unit. It controls +what code gets run when the unit under test calls a function. Where a function +is exposed as part of an API such that the definition of that function can be +changed without affecting the rest of the code base. In the kernel, this comes +from two constructs: classes, which are structs that contain function pointers +provided by the implementer, and architecture-specific functions, which have +definitions selected at compile time. Classes ~~~~~~~ Classes are not a construct that is built into the C programming language; -however, it is an easily derived concept. Accordingly, pretty much every project -that does not use a standardized object oriented library (like GNOME's GObject) -has their own slightly different way of doing object oriented programming; the -Linux kernel is no exception. +however, it is an easily derived concept. Accordingly, in most cases, every +project that does not use a standardized object oriented library (like GNOME's +GObject) has their own slightly different way of doing object oriented +programming; the Linux kernel is no exception. The central concept in kernel object oriented programming is the class. In the kernel, a *class* is a struct that contains function pointers. This creates a contract between *implementers* and *users* since it forces them to use the -same function signature without having to call the function directly. In order -for it to truly be a class, the function pointers must specify that a pointer -to the class, known as a *class handle*, be one of the parameters; this makes -it possible for the member functions (also known as *methods*) to have access -to member variables (more commonly known as *fields*) allowing the same -implementation to have multiple *instances*. - -Typically a class can be *overridden* by *child classes* by embedding the -*parent class* in the child class. Then when a method provided by the child -class is called, the child implementation knows that the pointer passed to it is -of a parent contained within the child; because of this, the child can compute -the pointer to itself because the pointer to the parent is always a fixed offset -from the pointer to the child; this offset is the offset of the parent contained -in the child struct. For example: +same function signature without having to call the function directly. To be a +class, the function pointers must specify that a pointer to the class, known as +a *class handle*, be one of the parameters. Thus the member functions (also +known as *methods*) have access to member variables (also known as *fields*) +allowing the same implementation to have multiple *instances*. + +A class can be *overridden* by *child classes* by embedding the *parent class* +in the child class. Then when the child class *method* is called, the child +implementation knows that the pointer passed to it is of a parent contained +within the child. Thus, the child can compute the pointer to itself because the +pointer to the parent is always a fixed offset from the pointer to the child. +This offset is the offset of the parent contained in the child struct. For +example: .. code-block:: c @@ -278,7 +242,7 @@ in the child struct. For example: int rectangle_area(struct shape *this) { - struct rectangle *self = container_of(this, struct shape, parent); + struct rectangle *self = container_of(this, struct rectangle, parent); return self->length * self->width; }; @@ -290,8 +254,8 @@ in the child struct. For example: self->width = width; } -In this example (as in most kernel code) the operation of computing the pointer -to the child from the pointer to the parent is done by ``container_of``. +In this example, computing the pointer to the child from the pointer to the +parent is done by ``container_of``. Faking Classes ~~~~~~~~~~~~~~ @@ -300,14 +264,11 @@ In order to unit test a piece of code that calls a method in a class, the behavior of the method must be controllable, otherwise the test ceases to be a unit test and becomes an integration test. -A fake just provides an implementation of a piece of code that is different than -what runs in a production instance, but behaves identically from the standpoint -of the callers; this is usually done to replace a dependency that is hard to -deal with, or is slow. - -A good example for this might be implementing a fake EEPROM that just stores the -"contents" in an internal buffer. For example, let's assume we have a class that -represents an EEPROM: +A fake class implements a piece of code that is different than what runs in a +production instance, but behaves identical from the standpoint of the callers. +This is done to replace a dependency that is hard to deal with, or is slow. For +example, implementing a fake EEPROM that stores the "contents" in an +internal buffer. Assume we have a class that represents an EEPROM: .. code-block:: c @@ -316,7 +277,7 @@ represents an EEPROM: ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count); }; -And we want to test some code that buffers writes to the EEPROM: +And we want to test code that buffers writes to the EEPROM: .. code-block:: c @@ -329,7 +290,7 @@ And we want to test some code that buffers writes to the EEPROM: struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom); void destroy_eeprom_buffer(struct eeprom *eeprom); -We can easily test this code by *faking out* the underlying EEPROM: +We can test this code by *faking out* the underlying EEPROM: .. code-block:: c @@ -456,14 +417,14 @@ We can now use it to test ``struct eeprom_buffer``: destroy_eeprom_buffer(ctx->eeprom_buffer); } -Testing against multiple inputs +Testing Against Multiple Inputs ------------------------------- -Testing just a few inputs might not be enough to have confidence that the code -works correctly, e.g. for a hash function. +Testing just a few inputs is not enough to ensure that the code works correctly, +for example: testing a hash function. -In such cases, it can be helpful to have a helper macro or function, e.g. this -fictitious example for ``sha1sum(1)`` +We can write a helper macro or function. The function is called for each input. +For example, to test ``sha1sum(1)``, we can write: .. code-block:: c @@ -475,16 +436,15 @@ fictitious example for ``sha1sum(1)`` TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"); TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169"); +Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more +detailed error and make the assertions clearer within the helper macros. -Note the use of ``KUNIT_EXPECT_STREQ_MSG`` to give more context when it fails -and make it easier to track down. (Yes, in this example, ``want`` is likely -going to be unique enough on its own). +The ``_MSG`` variants are useful when the same expectation is called multiple +times (in a loop or helper function) and thus the line number is not enough to +identify what failed, as shown below. -The ``_MSG`` variants are even more useful when the same expectation is called -multiple times (in a loop or helper function) and thus the line number isn't -enough to identify what failed, like below. - -In some cases, it can be helpful to write a *table-driven test* instead, e.g. +In complicated cases, we recommend using a *table-driven test* compared to the +helper macro variation, for example: .. code-block:: c @@ -513,17 +473,18 @@ In some cases, it can be helpful to write a *table-driven test* instead, e.g. } -There's more boilerplate involved, but it can: +There is more boilerplate code involved, but it can: + +* be more readable when there are multiple inputs/outputs (due to field names). -* be more readable when there are multiple inputs/outputs thanks to field names, + * For example, see ``fs/ext4/inode-test.c``. - * E.g. see ``fs/ext4/inode-test.c`` for an example of both. -* reduce duplication if test cases can be shared across multiple tests. +* reduce duplication if test cases are shared across multiple tests. - * E.g. if we wanted to also test ``sha256sum``, we could add a ``sha256`` + * For example: if we want to test ``sha256sum``, we could add a ``sha256`` field and reuse ``cases``. -* be converted to a "parameterized test", see below. +* be converted to a "parameterized test". Parameterized Testing ~~~~~~~~~~~~~~~~~~~~~ @@ -531,7 +492,7 @@ Parameterized Testing The table-driven testing pattern is common enough that KUnit has special support for it. -Reusing the same ``cases`` array from above, we can write the test as a +By reusing the same ``cases`` array from above, we can write the test as a "parameterized test" with the following. .. code-block:: c @@ -582,193 +543,160 @@ Reusing the same ``cases`` array from above, we can write the test as a .. _kunit-on-non-uml: -KUnit on non-UML architectures -============================== - -By default KUnit uses UML as a way to provide dependencies for code under test. -Under most circumstances KUnit's usage of UML should be treated as an -implementation detail of how KUnit works under the hood. Nevertheless, there -are instances where being able to run architecture-specific code or test -against real hardware is desirable. For these reasons KUnit supports running on -other architectures. - -Running existing KUnit tests on non-UML architectures ------------------------------------------------------ +Exiting Early on Failed Expectations +------------------------------------ -There are some special considerations when running existing KUnit tests on -non-UML architectures: +We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue +execution. In some cases, it is unsafe to continue. We can use the +``KUNIT_ASSERT`` variant to exit on failure. -* Hardware may not be deterministic, so a test that always passes or fails - when run under UML may not always do so on real hardware. -* Hardware and VM environments may not be hermetic. KUnit tries its best to - provide a hermetic environment to run tests; however, it cannot manage state - that it doesn't know about outside of the kernel. Consequently, tests that - may be hermetic on UML may not be hermetic on other architectures. -* Some features and tooling may not be supported outside of UML. -* Hardware and VMs are slower than UML. +.. code-block:: c -None of these are reasons not to run your KUnit tests on real hardware; they are -only things to be aware of when doing so. + void example_test_user_alloc_function(struct kunit *test) + { + void *object = alloc_some_object_for_me(); -Currently, the KUnit Wrapper (``tools/testing/kunit/kunit.py``) (aka -kunit_tool) only fully supports running tests inside of UML and QEMU; however, -this is only due to our own time limitations as humans working on KUnit. It is -entirely possible to support other emulators and even actual hardware, but for -now QEMU and UML is what is fully supported within the KUnit Wrapper. Again, to -be clear, this is just the Wrapper. The actualy KUnit tests and the KUnit -library they are written in is fully architecture agnostic and can be used in -virtually any setup, you just won't have the benefit of typing a single command -out of the box and having everything magically work perfectly. + /* Make sure we got a valid pointer back. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); + do_something_with_object(object); + } -Again, all core KUnit framework features are fully supported on all -architectures, and using them is straightforward: Most popular architectures -are supported directly in the KUnit Wrapper via QEMU. Currently, supported -architectures on QEMU include: +Allocating Memory +----------------- -* i386 -* x86_64 -* arm -* arm64 -* alpha -* powerpc -* riscv -* s390 -* sparc +Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit +will then ensure that the memory is freed once the test completes. -In order to run KUnit tests on one of these architectures via QEMU with the -KUnit wrapper, all you need to do is specify the flags ``--arch`` and -``--cross_compile`` when invoking the KUnit Wrapper. For example, we could run -the default KUnit tests on ARM in the following manner (assuming we have an ARM -toolchain installed): +This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit +early from a test without having to worry about remembering to call ``kfree``. +For example: -.. code-block:: bash +.. code-block:: c - tools/testing/kunit/kunit.py run --timeout=60 --jobs=12 --arch=arm --cross_compile=arm-linux-gnueabihf- + void example_test_allocation(struct kunit *test) + { + char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL); + /* Ensure allocation succeeded. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer); -Alternatively, if you want to run your tests on real hardware or in some other -emulation environment, all you need to do is to take your kunitconfig, your -Kconfig options for the tests you would like to run, and merge them into -whatever config your are using for your platform. That's it! + KUNIT_ASSERT_STREQ(test, buffer, ""); + } -For example, let's say you have the following kunitconfig: -.. code-block:: none +Testing Static Functions +------------------------ - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y +If we do not want to expose functions or variables for testing, one option is to +conditionally ``#include`` the test file at the end of your .c file. For +example: -If you wanted to run this test on an x86 VM, you might add the following config -options to your ``.config``: +.. code-block:: c -.. code-block:: none + /* In my_file.c */ - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y - CONFIG_SERIAL_8250=y - CONFIG_SERIAL_8250_CONSOLE=y + static int do_interesting_thing(); -All these new options do is enable support for a common serial console needed -for logging. + #ifdef CONFIG_MY_KUNIT_TEST + #include "my_kunit_test.c" + #endif -Next, you could build a kernel with these tests as follows: +Injecting Test-Only Code +------------------------ +Similar to as shown above, we can add test-specific logic. For example: -.. code-block:: bash +.. code-block:: c - make ARCH=x86 olddefconfig - make ARCH=x86 + /* In my_file.h */ -Once you have built a kernel, you could run it on QEMU as follows: + #ifdef CONFIG_MY_KUNIT_TEST + /* Defined in my_kunit_test.c */ + void test_only_hook(void); + #else + void test_only_hook(void) { } + #endif -.. code-block:: bash +This test-only code can be made more useful by accessing the current ``kunit_test`` +as shown in next section: *Accessing The Current Test*. - qemu-system-x86_64 -enable-kvm \ - -m 1024 \ - -kernel arch/x86_64/boot/bzImage \ - -append 'console=ttyS0' \ - --nographic +Accessing The Current Test +-------------------------- -Interspersed in the kernel logs you might see the following: +In some cases, we need to call test-only code from outside the test file. +For example, see example in section *Injecting Test-Only Code* or if +we are providing a fake implementation of an ops struct. Using +``kunit_test`` field in ``task_struct``, we can access it via +``current->kunit_test``. -.. code-block:: none +The example below includes how to implement "mocking": - TAP version 14 - # Subtest: example - 1..1 - # example_simple_test: initializing - ok 1 - example_simple_test - ok 1 - example +.. code-block:: c -Congratulations, you just ran a KUnit test on the x86 architecture! + #include <linux/sched.h> /* for current */ -In a similar manner, kunit and kunit tests can also be built as modules, -so if you wanted to run tests in this way you might add the following config -options to your ``.config``: + struct test_data { + int foo_result; + int want_foo_called_with; + }; -.. code-block:: none + static int fake_foo(int arg) + { + struct kunit *test = current->kunit_test; + struct test_data *test_data = test->priv; - CONFIG_KUNIT=m - CONFIG_KUNIT_EXAMPLE_TEST=m + KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); + return test_data->foo_result; + } -Once the kernel is built and installed, a simple + static void example_simple_test(struct kunit *test) + { + /* Assume priv (private, a member used to pass test data from + * the init function) is allocated in the suite's .init */ + struct test_data *test_data = test->priv; -.. code-block:: bash + test_data->foo_result = 42; + test_data->want_foo_called_with = 1; - modprobe example-test + /* In a real test, we'd probably pass a pointer to fake_foo somewhere + * like an ops struct, etc. instead of calling it directly. */ + KUNIT_EXPECT_EQ(test, fake_foo(1), 42); + } -...will run the tests. +In this example, we are using the ``priv`` member of ``struct kunit`` as a way +of passing data to the test from the init function. In general ``priv`` is +pointer that can be used for any user data. This is preferred over static +variables, as it avoids concurrency issues. -.. note:: - Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig - if the test does not support module build. Otherwise, it will trigger - compile errors if ``CONFIG_KUNIT`` is ``m``. +Had we wanted something more flexible, we could have used a named ``kunit_resource``. +Each test can have multiple resources which have string names providing the same +flexibility as a ``priv`` member, but also, for example, allowing helper +functions to create resources without conflicting with each other. It is also +possible to define a clean up function for each resource, making it easy to +avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst. -Writing new tests for other architectures ------------------------------------------ +Failing The Current Test +------------------------ -The first thing you must do is ask yourself whether it is necessary to write a -KUnit test for a specific architecture, and then whether it is necessary to -write that test for a particular piece of hardware. In general, writing a test -that depends on having access to a particular piece of hardware or software (not -included in the Linux source repo) should be avoided at all costs. +If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)`` +which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``. +For example, we have an option to enable some extra debug checks on some data +structures as shown below: -Even if you only ever plan on running your KUnit test on your hardware -configuration, other people may want to run your tests and may not have access -to your hardware. If you write your test to run on UML, then anyone can run your -tests without knowing anything about your particular setup, and you can still -run your tests on your hardware setup just by compiling for your architecture. +.. code-block:: c -.. important:: - Always prefer tests that run on UML to tests that only run under a particular - architecture, and always prefer tests that run under QEMU or another easy - (and monetarily free) to obtain software environment to a specific piece of - hardware. - -Nevertheless, there are still valid reasons to write an architecture or hardware -specific test: for example, you might want to test some code that really belongs -in ``arch/some-arch/*``. Even so, try your best to write the test so that it -does not depend on physical hardware: if some of your test cases don't need the -hardware, only require the hardware for tests that actually need it. - -Now that you have narrowed down exactly what bits are hardware specific, the -actual procedure for writing and running the tests is pretty much the same as -writing normal KUnit tests. One special caveat is that you have to reset -hardware state in between test cases; if this is not possible, you may only be -able to run one test case per invocation. + #include <kunit/test-bug.h> -.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- - dependent KUnit test. + #ifdef CONFIG_EXTRA_DEBUG_CHECKS + static void validate_my_data(struct data *data) + { + if (is_valid(data)) + return; -KUnit debugfs representation -============================ -When kunit test suites are initialized, they create an associated directory -in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file + kunit_fail_current_test("data %p is invalid", data); -- results: "cat results" displays results of each test case and the results - of the entire suite for the last test run. + /* Normal, non-KUnit, error reporting code here. */ + } + #else + static void my_debug_function(void) { } + #endif -The debugfs representation is primarily of use when kunit test suites are -run in a native environment, either as modules or builtin. Having a way -to display results like this is valuable as otherwise results can be -intermixed with other events in dmesg output. The maximum size of each -results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``). diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index c9abfbe3f0aa..41c555181b6f 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -65,7 +65,9 @@ DT_DOCS = $(patsubst $(srctree)/%,%,$(shell $(find_all_cmd))) override DTC_FLAGS := \ -Wno-avoid_unnecessary_addr_size \ -Wno-graph_child_address \ - -Wno-interrupt_provider + -Wno-interrupt_provider \ + -Wno-unique_unit_address \ + -Wunique_unit_address_if_enabled # Disable undocumented compatible checks until warning free override DT_CHECKER_FLAGS ?= diff --git a/Documentation/devicetree/bindings/arm/arm,cci-400.yaml b/Documentation/devicetree/bindings/arm/arm,cci-400.yaml index 4682f991a5c8..f8530a50863a 100644 --- a/Documentation/devicetree/bindings/arm/arm,cci-400.yaml +++ b/Documentation/devicetree/bindings/arm/arm,cci-400.yaml @@ -166,16 +166,6 @@ examples: }; }; - dma0: dma@3000000 { - /* compatible = "arm,pl330", "arm,primecell"; */ - cci-control-port = <&cci_control0>; - reg = <0x0 0x3000000 0x0 0x1000>; - interrupts = <10>; - #dma-cells = <1>; - #dma-channels = <8>; - #dma-requests = <32>; - }; - cci@2c090000 { compatible = "arm,cci-400"; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt b/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt deleted file mode 100644 index 6efabba530f1..000000000000 --- a/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt +++ /dev/null @@ -1,27 +0,0 @@ -* ARM DynamIQ Shared Unit (DSU) Performance Monitor Unit (PMU) - -ARM DyanmIQ Shared Unit (DSU) integrates one or more CPU cores -with a shared L3 memory system, control logic and external interfaces to -form a multicore cluster. The PMU enables to gather various statistics on -the operations of the DSU. The PMU provides independent 32bit counters that -can count any of the supported events, along with a 64bit cycle counter. -The PMU is accessed via CPU system registers and has no MMIO component. - -** DSU PMU required properties: - -- compatible : should be one of : - - "arm,dsu-pmu" - -- interrupts : Exactly 1 SPI must be listed. - -- cpus : List of phandles for the CPUs connected to this DSU instance. - - -** Example: - -dsu-pmu-0 { - compatible = "arm,dsu-pmu"; - interrupts = <GIC_SPI 02 IRQ_TYPE_LEVEL_HIGH>; - cpus = <&cpu_0>, <&cpu_1>; -}; diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index c612e1f48dba..ff91df04f9f4 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -8,7 +8,8 @@ title: Atmel AT91 device tree bindings. maintainers: - Alexandre Belloni <alexandre.belloni@bootlin.com> - - Ludovic Desroches <ludovic.desroches@microchip.com> + - Claudiu Beznea <claudiu.beznea@microchip.com> + - Nicolas Ferre <nicolas.ferre@microchip.com> description: | Boards with a SoC of the Atmel AT91 or SMART family shall have the following diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index dfa28e3525cb..0dcebc48ea22 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -137,6 +137,9 @@ properties: - arm,cortex-a75 - arm,cortex-a76 - arm,cortex-a77 + - arm,cortex-a78 + - arm,cortex-a510 + - arm,cortex-a710 - arm,cortex-m0 - arm,cortex-m0+ - arm,cortex-m1 @@ -145,8 +148,12 @@ properties: - arm,cortex-r4 - arm,cortex-r5 - arm,cortex-r7 + - arm,cortex-x1 + - arm,cortex-x2 - arm,neoverse-e1 - arm,neoverse-n1 + - arm,neoverse-n2 + - arm,neoverse-v1 - brcm,brahma-b15 - brcm,brahma-b53 - brcm,vulcan diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt index b5cb374dc47d..10a91cc8b997 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt @@ -8,7 +8,7 @@ Required properties: - compatible: Should contain a chip-specific compatible string, Chip-specific strings are of the form "fsl,<chip>-dcfg", The following <chip>s are known to be supported: - ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. + ls1012a, ls1021a, ls1043a, ls1046a, ls2080a, lx2160a - reg : should contain base address and length of DCFG memory-mapped registers diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index ea827e8763de..3fa755866528 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -14,6 +14,7 @@ Required Properties: - "mediatek,mt7622-apmixedsys" - "mediatek,mt7623-apmixedsys", "mediatek,mt2701-apmixedsys" - "mediatek,mt7629-apmixedsys" + - "mediatek,mt7986-apmixedsys" - "mediatek,mt8135-apmixedsys" - "mediatek,mt8167-apmixedsys", "syscon" - "mediatek,mt8173-apmixedsys" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt index 6b7e8067e7aa..0502db73686b 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt @@ -10,6 +10,7 @@ Required Properties: - "mediatek,mt7622-ethsys", "syscon" - "mediatek,mt7623-ethsys", "mediatek,mt2701-ethsys", "syscon" - "mediatek,mt7629-ethsys", "syscon" + - "mediatek,mt7986-ethsys", "syscon" - #clock-cells: Must be 1 - #reset-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index eb3523c7a7be..f66bd720571d 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -15,6 +15,7 @@ Required Properties: - "mediatek,mt7622-infracfg", "syscon" - "mediatek,mt7623-infracfg", "mediatek,mt2701-infracfg", "syscon" - "mediatek,mt7629-infracfg", "syscon" + - "mediatek,mt7986-infracfg", "syscon" - "mediatek,mt8135-infracfg", "syscon" - "mediatek,mt8167-infracfg", "syscon" - "mediatek,mt8173-infracfg", "syscon" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt index 30cb645c0e54..29ca7a10b315 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt @@ -8,6 +8,8 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-sgmiisys", "syscon" - "mediatek,mt7629-sgmiisys", "syscon" + - "mediatek,mt7986-sgmiisys_0", "syscon" + - "mediatek,mt7986-sgmiisys_1", "syscon" - #clock-cells: Must be 1 The SGMIISYS controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index 5ce7578cf274..b82422bb717f 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -14,6 +14,7 @@ Required Properties: - "mediatek,mt7622-topckgen" - "mediatek,mt7623-topckgen", "mediatek,mt2701-topckgen" - "mediatek,mt7629-topckgen" + - "mediatek,mt7986-topckgen", "syscon" - "mediatek,mt8135-topckgen" - "mediatek,mt8167-topckgen", "syscon" - "mediatek,mt8173-topckgen" diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index e77635c5422c..fa8b31660cad 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -119,6 +119,9 @@ Boards (incomplete list of examples): - OMAP3 BeagleBoard : Low cost community board compatible = "ti,omap3-beagle", "ti,omap3430", "ti,omap3" +- OMAP3 BeagleBoard A to B4 : Early BeagleBoard revisions A to B4 with a timer quirk + compatible = "ti,omap3-beagle-ab4", "ti,omap3-beagle", "ti,omap3430", "ti,omap3" + - OMAP3 Tobi with Overo : Commercial expansion board with daughter board compatible = "gumstix,omap3-overo-tobi", "gumstix,omap3-overo", "ti,omap3430", "ti,omap3" diff --git a/Documentation/devicetree/bindings/arm/pmu.yaml b/Documentation/devicetree/bindings/arm/pmu.yaml index e17ac049e890..7a04b8aaaec3 100644 --- a/Documentation/devicetree/bindings/arm/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/pmu.yaml @@ -20,6 +20,8 @@ properties: items: - enum: - apm,potenza-pmu + - apple,firestorm-pmu + - apple,icestorm-pmu - arm,armv8-pmuv3 # Only for s/w models - arm,arm1136-pmu - arm,arm1176-pmu @@ -44,10 +46,18 @@ properties: - arm,cortex-a76-pmu - arm,cortex-a77-pmu - arm,cortex-a78-pmu + - arm,cortex-a510-pmu + - arm,cortex-a710-pmu + - arm,cortex-x1-pmu + - arm,cortex-x2-pmu - arm,neoverse-e1-pmu - arm,neoverse-n1-pmu + - arm,neoverse-n2-pmu + - arm,neoverse-v1-pmu - brcm,vulcan-pmu - cavium,thunder-pmu + - nvidia,denver-pmu + - nvidia,carmel-pmu - qcom,krait-pmu - qcom,scorpion-pmu - qcom,scorpion-mp-pmu diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 370aab274cd1..04ff0b55bb85 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -48,7 +48,6 @@ description: | sdx65 sm7225 sm8150 - sdx65 sm8250 sm8350 sm8450 @@ -230,11 +229,6 @@ properties: - items: - enum: - - qcom,sdx65-mtp - - const: qcom,sdx65 - - - items: - - enum: - qcom,ipq6018-cp01 - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 diff --git a/Documentation/devicetree/bindings/arm/ux500.yaml b/Documentation/devicetree/bindings/arm/ux500.yaml index 5db7cfba81a4..a46193ad94e0 100644 --- a/Documentation/devicetree/bindings/arm/ux500.yaml +++ b/Documentation/devicetree/bindings/arm/ux500.yaml @@ -20,6 +20,11 @@ properties: - const: st-ericsson,mop500 - const: st-ericsson,u8500 + - description: ST-Ericsson HREF520 + items: + - const: st-ericsson,href520 + - const: st-ericsson,u8500 + - description: ST-Ericsson HREF (v60+) items: - const: st-ericsson,hrefv60+ @@ -30,9 +35,34 @@ properties: - const: calaosystems,snowball-a9500 - const: st-ericsson,u9500 + - description: Samsung Galaxy Ace 2 (GT-I8160) + items: + - const: samsung,codina + - const: st-ericsson,u8500 + + - description: Samsung Galaxy Beam (GT-I8530) + items: + - const: samsung,gavini + - const: st-ericsson,u8500 + - description: Samsung Galaxy S III mini (GT-I8190) items: - const: samsung,golden - const: st-ericsson,u8500 + - description: Samsung Galaxy S Advance (GT-I9070) + items: + - const: samsung,janice + - const: st-ericsson,u8500 + + - description: Samsung Galaxy Amp (SGH-I407) + items: + - const: samsung,kyle + - const: st-ericsson,u8500 + + - description: Samsung Galaxy XCover 2 (GT-S7710) + items: + - const: samsung,skomer + - const: st-ericsson,u8500 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt index db5c56db30ec..61d77acbeb5e 100644 --- a/Documentation/devicetree/bindings/arm/xen.txt +++ b/Documentation/devicetree/bindings/arm/xen.txt @@ -7,15 +7,17 @@ the following properties: compatible = "xen,xen-<version>", "xen,xen"; where <version> is the version of the Xen ABI of the platform. -- reg: specifies the base physical address and size of a region in - memory where the grant table should be mapped to, using an - HYPERVISOR_memory_op hypercall. The memory region is large enough to map - the whole grant table (it is larger or equal to gnttab_max_grant_frames()). - This property is unnecessary when booting Dom0 using ACPI. +- reg: specifies the base physical address and size of the regions in memory + where the special resources should be mapped to, using an HYPERVISOR_memory_op + hypercall. + Region 0 is reserved for mapping grant table, it must be always present. + The memory region is large enough to map the whole grant table (it is larger + or equal to gnttab_max_grant_frames()). + Regions 1...N are extended regions (unused address space) for mapping foreign + GFNs and grants, they might be absent if there is nothing to expose. - interrupts: the interrupt used by Xen to inject event notifications. A GIC node is also required. - This property is unnecessary when booting Dom0 using ACPI. To support UEFI on Xen ARM virtual platforms, Xen populates the FDT "uefi" node under /hypervisor with following parameters: diff --git a/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt deleted file mode 100644 index b9ae4ce4a0a0..000000000000 --- a/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt +++ /dev/null @@ -1,45 +0,0 @@ -* Broadcom SATA3 AHCI Controller - -SATA nodes are defined to describe on-chip Serial ATA controllers. -Each SATA controller should have its own node. - -Required properties: -- compatible : should be one or more of - "brcm,bcm7216-ahci" - "brcm,bcm7425-ahci" - "brcm,bcm7445-ahci" - "brcm,bcm-nsp-ahci" - "brcm,sata3-ahci" - "brcm,bcm63138-ahci" -- reg : register mappings for AHCI and SATA_TOP_CTRL -- reg-names : "ahci" and "top-ctrl" -- interrupts : interrupt mapping for SATA IRQ - -Optional properties: - -- reset: for "brcm,bcm7216-ahci" must be a valid reset phandle - pointing to the RESCAL reset controller provider node. -- reset-names: for "brcm,bcm7216-ahci", must be "rescal". - -Also see ahci-platform.txt. - -Example: - - sata@f045a000 { - compatible = "brcm,bcm7445-ahci", "brcm,sata3-ahci"; - reg = <0xf045a000 0xa9c>, <0xf0458040 0x24>; - reg-names = "ahci", "top-ctrl"; - interrupts = <0 30 0>; - #address-cells = <1>; - #size-cells = <0>; - - sata0: sata-port@0 { - reg = <0>; - phys = <&sata_phy 0>; - }; - - sata1: sata-port@1 { - reg = <1>; - phys = <&sata_phy 1>; - }; - }; diff --git a/Documentation/devicetree/bindings/ata/brcm,sata-brcm.yaml b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.yaml new file mode 100644 index 000000000000..235a93ac86b0 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/brcm,sata-brcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom SATA3 AHCI Controller + +description: + SATA nodes are defined to describe on-chip Serial ATA controllers. + Each SATA controller should have its own node. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: sata-common.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm7216-ahci + - brcm,bcm7445-ahci + - brcm,bcm7425-ahci + - brcm,bcm63138-ahci + - const: brcm,sata3-ahci + - items: + - const: brcm,bcm-nsp-ahci + + reg: + minItems: 2 + maxItems: 2 + + reg-names: + items: + - const: ahci + - const: top-ctrl + + interrupts: + maxItems: 1 + + dma-coherent: true + +if: + properties: + compatible: + contains: + enum: + - brcm,bcm7216-ahci + - brcm,bcm63138-ahci +then: + properties: + resets: + maxItems: 1 + reset-names: + enum: + - rescal + - ahci + +required: + - compatible + - reg + - interrupts + - "#address-cells" + - "#size-cells" + +unevaluatedProperties: false + +examples: + - | + sata@f045a000 { + compatible = "brcm,bcm7445-ahci", "brcm,sata3-ahci"; + reg = <0xf045a000 0xa9c>, <0xf0458040 0x24>; + reg-names = "ahci", "top-ctrl"; + interrupts = <0 30 0>; + #address-cells = <1>; + #size-cells = <0>; + + sata0: sata-port@0 { + reg = <0>; + phys = <&sata_phy 0>; + }; + + sata1: sata-port@1 { + reg = <1>; + phys = <&sata_phy 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt deleted file mode 100644 index 10f6d0a8159d..000000000000 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt +++ /dev/null @@ -1,34 +0,0 @@ -Broadcom GISB bus Arbiter controller - -Required properties: - -- compatible: - "brcm,bcm7278-gisb-arb" for V7 28nm chips - "brcm,gisb-arb" or "brcm,bcm7445-gisb-arb" for other 28nm chips - "brcm,bcm7435-gisb-arb" for newer 40nm chips - "brcm,bcm7400-gisb-arb" for older 40nm chips and all 65nm chips - "brcm,bcm7038-gisb-arb" for 130nm chips -- reg: specifies the base physical address and size of the registers -- interrupts: specifies the two interrupts (timeout and TEA) to be used from - the parent interrupt controller. A third optional interrupt may be specified - for breakpoints. - -Optional properties: - -- brcm,gisb-arb-master-mask: 32-bits wide bitmask used to specify which GISB - masters are valid at the system level -- brcm,gisb-arb-master-names: string list of the litteral name of the GISB - masters. Should match the number of bits set in brcm,gisb-master-mask and - the order in which they appear - -Example: - -gisb-arb@f0400000 { - compatible = "brcm,gisb-arb"; - reg = <0xf0400000 0x800>; - interrupts = <0>, <2>; - interrupt-parent = <&sun_l2_intc>; - - brcm,gisb-arb-master-mask = <0x7>; - brcm,gisb-arb-master-names = "bsp_0", "scpu_0", "cpu_0"; -}; diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml new file mode 100644 index 000000000000..b23c3001991e --- /dev/null +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/brcm,gisb-arb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom GISB bus Arbiter controller + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm7445-gisb-arb # for other 28nm chips + - const: brcm,gisb-arb + - items: + - enum: + - brcm,bcm7278-gisb-arb # for V7 28nm chips + - brcm,bcm7435-gisb-arb # for newer 40nm chips + - brcm,bcm7400-gisb-arb # for older 40nm chips and all 65nm chips + - brcm,bcm7038-gisb-arb # for 130nm chips + - brcm,gisb-arb # fallback compatible + + reg: + maxItems: 1 + + interrupts: + minItems: 2 + items: + - description: timeout interrupt line + - description: target abort interrupt line + - description: breakpoint interrupt line + + brcm,gisb-arb-master-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + 32-bits wide bitmask used to specify which GISB masters are valid at the + system level + + brcm,gisb-arb-master-names: + $ref: /schemas/types.yaml#/definitions/string-array + description: > + String list of the litteral name of the GISB masters. Should match the + number of bits set in brcm,gisb-master-mask and the order in which they + appear from MSB to LSB. + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + gisb-arb@f0400000 { + compatible = "brcm,gisb-arb"; + reg = <0xf0400000 0x800>; + interrupts = <0>, <2>; + interrupt-parent = <&sun_l2_intc>; + brcm,gisb-arb-master-mask = <0x7>; + brcm,gisb-arb-master-names = "bsp_0", "scpu_0", "cpu_0"; + }; diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml index c4b7243ddcf2..15ed64d35261 100644 --- a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml @@ -34,6 +34,8 @@ properties: - allwinner,sun8i-v3-ccu - allwinner,sun8i-v3s-ccu - allwinner,sun9i-a80-ccu + - allwinner,sun20i-d1-ccu + - allwinner,sun20i-d1-r-ccu - allwinner,sun50i-a64-ccu - allwinner,sun50i-a64-r-ccu - allwinner,sun50i-a100-ccu @@ -79,6 +81,7 @@ if: enum: - allwinner,sun8i-a83t-r-ccu - allwinner,sun8i-h3-r-ccu + - allwinner,sun20i-d1-r-ccu - allwinner,sun50i-a64-r-ccu - allwinner,sun50i-a100-r-ccu - allwinner,sun50i-h6-r-ccu @@ -99,6 +102,7 @@ else: properties: compatible: enum: + - allwinner,sun20i-d1-ccu - allwinner,sun50i-a100-ccu - allwinner,sun50i-h6-ccu - allwinner,sun50i-h616-ccu diff --git a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt b/Documentation/devicetree/bindings/clock/exynos5260-clock.txt deleted file mode 100644 index c79d31f7f66e..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt +++ /dev/null @@ -1,190 +0,0 @@ -* Samsung Exynos5260 Clock Controller - -Exynos5260 has 13 clock controllers which are instantiated -independently from the device-tree. These clock controllers -generate and supply clocks to various hardware blocks within -the SoC. - -Each clock is assigned an identifier and client nodes can use -this identifier to specify the clock which they consume. All -available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos5260-clk.h header and can be used in -device tree sources. - -External clocks: - -There are several clocks that are generated outside the SoC. It -is expected that they are defined using standard clock bindings -with following clock-output-names: - - - "fin_pll" - PLL input clock from XXTI - - "xrtcxti" - input clock from XRTCXTI - - "ioclk_pcm_extclk" - pcm external operation clock - - "ioclk_spdif_extclk" - spdif external operation clock - - "ioclk_i2s_cdclk" - i2s0 codec clock - -Phy clocks: - -There are several clocks which are generated by specific PHYs. -These clocks are fed into the clock controller and then routed to -the hardware blocks. These clocks are defined as fixed clocks in the -driver with following names: - - - "phyclk_dptx_phy_ch3_txd_clk" - dp phy clock for channel 3 - - "phyclk_dptx_phy_ch2_txd_clk" - dp phy clock for channel 2 - - "phyclk_dptx_phy_ch1_txd_clk" - dp phy clock for channel 1 - - "phyclk_dptx_phy_ch0_txd_clk" - dp phy clock for channel 0 - - "phyclk_hdmi_phy_tmds_clko" - hdmi phy tmds clock - - "phyclk_hdmi_phy_pixel_clko" - hdmi phy pixel clock - - "phyclk_hdmi_link_o_tmds_clkhi" - hdmi phy for hdmi link - - "phyclk_dptx_phy_o_ref_clk_24m" - dp phy reference clock - - "phyclk_dptx_phy_clk_div2" - - "phyclk_mipi_dphy_4l_m_rxclkesc0" - - "phyclk_usbhost20_phy_phyclock" - usb 2.0 phy clock - - "phyclk_usbhost20_phy_freeclk" - - "phyclk_usbhost20_phy_clk48mohci" - - "phyclk_usbdrd30_udrd30_pipe_pclk" - - "phyclk_usbdrd30_udrd30_phyclock" - usb 3.0 phy clock - -Required Properties for Clock Controller: - - - compatible: should be one of the following. - 1) "samsung,exynos5260-clock-top" - 2) "samsung,exynos5260-clock-peri" - 3) "samsung,exynos5260-clock-egl" - 4) "samsung,exynos5260-clock-kfc" - 5) "samsung,exynos5260-clock-g2d" - 6) "samsung,exynos5260-clock-mif" - 7) "samsung,exynos5260-clock-mfc" - 8) "samsung,exynos5260-clock-g3d" - 9) "samsung,exynos5260-clock-fsys" - 10) "samsung,exynos5260-clock-aud" - 11) "samsung,exynos5260-clock-isp" - 12) "samsung,exynos5260-clock-gscl" - 13) "samsung,exynos5260-clock-disp" - - - reg: physical base address of the controller and the length of - memory mapped region. - - - #clock-cells: should be 1. - - - clocks: list of clock identifiers which are fed as the input to - the given clock controller. Please refer the next section to find - the input clocks for a given controller. - - - clock-names: list of names of clocks which are fed as the input - to the given clock controller. - -Input clocks for top clock controller: - - fin_pll - - dout_mem_pll - - dout_bus_pll - - dout_media_pll - -Input clocks for peri clock controller: - - fin_pll - - ioclk_pcm_extclk - - ioclk_i2s_cdclk - - ioclk_spdif_extclk - - phyclk_hdmi_phy_ref_cko - - dout_aclk_peri_66 - - dout_sclk_peri_uart0 - - dout_sclk_peri_uart1 - - dout_sclk_peri_uart2 - - dout_sclk_peri_spi0_b - - dout_sclk_peri_spi1_b - - dout_sclk_peri_spi2_b - - dout_aclk_peri_aud - - dout_sclk_peri_spi0_b - -Input clocks for egl clock controller: - - fin_pll - - dout_bus_pll - -Input clocks for kfc clock controller: - - fin_pll - - dout_media_pll - -Input clocks for g2d clock controller: - - fin_pll - - dout_aclk_g2d_333 - -Input clocks for mif clock controller: - - fin_pll - -Input clocks for mfc clock controller: - - fin_pll - - dout_aclk_mfc_333 - -Input clocks for g3d clock controller: - - fin_pll - -Input clocks for fsys clock controller: - - fin_pll - - phyclk_usbhost20_phy_phyclock - - phyclk_usbhost20_phy_freeclk - - phyclk_usbhost20_phy_clk48mohci - - phyclk_usbdrd30_udrd30_pipe_pclk - - phyclk_usbdrd30_udrd30_phyclock - - dout_aclk_fsys_200 - -Input clocks for aud clock controller: - - fin_pll - - fout_aud_pll - - ioclk_i2s_cdclk - - ioclk_pcm_extclk - -Input clocks for isp clock controller: - - fin_pll - - dout_aclk_isp1_266 - - dout_aclk_isp1_400 - - mout_aclk_isp1_266 - -Input clocks for gscl clock controller: - - fin_pll - - dout_aclk_gscl_400 - - dout_aclk_gscl_333 - -Input clocks for disp clock controller: - - fin_pll - - phyclk_dptx_phy_ch3_txd_clk - - phyclk_dptx_phy_ch2_txd_clk - - phyclk_dptx_phy_ch1_txd_clk - - phyclk_dptx_phy_ch0_txd_clk - - phyclk_hdmi_phy_tmds_clko - - phyclk_hdmi_phy_ref_clko - - phyclk_hdmi_phy_pixel_clko - - phyclk_hdmi_link_o_tmds_clkhi - - phyclk_mipi_dphy_4l_m_txbyte_clkhs - - phyclk_dptx_phy_o_ref_clk_24m - - phyclk_dptx_phy_clk_div2 - - phyclk_mipi_dphy_4l_m_rxclkesc0 - - phyclk_hdmi_phy_ref_cko - - ioclk_spdif_extclk - - dout_aclk_peri_aud - - dout_aclk_disp_222 - - dout_sclk_disp_pixel - - dout_aclk_disp_333 - -Example 1: An example of a clock controller node is listed below. - - clock_mfc: clock-controller@11090000 { - compatible = "samsung,exynos5260-clock-mfc"; - clock = <&fin_pll>, <&clock_top TOP_DOUT_ACLK_MFC_333>; - clock-names = "fin_pll", "dout_aclk_mfc_333"; - reg = <0x11090000 0x10000>; - #clock-cells = <1>; - }; - -Example 2: UART controller node that consumes the clock generated by the - peri clock controller. Refer to the standard clock bindings for - information about 'clocks' and 'clock-names' property. - - serial@12c00000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x12C00000 0x100>; - interrupts = <0 146 0>; - clocks = <&clock_peri PERI_PCLK_UART0>, <&clock_peri PERI_SCLK_UART0>; - clock-names = "uart", "clk_uart_baud0"; - }; - diff --git a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt deleted file mode 100644 index 217beb27c30e..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt +++ /dev/null @@ -1,50 +0,0 @@ -* Samsung Exynos5410 Clock Controller - -The Exynos5410 clock controller generates and supplies clock to various -controllers within the Exynos5410 SoC. - -Required Properties: - -- compatible: should be "samsung,exynos5410-clock" - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -- clocks: should contain an entry specifying the root clock from external - oscillator supplied through XXTI or XusbXTI pin. This clock should be - defined using standard clock bindings with "fin_pll" clock-output-name. - That clock is being passed internally to the 9 PLLs. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos5410.h header and can be used in device -tree sources. - -Example 1: An example of a clock controller node is listed below. - - fin_pll: xxti { - compatible = "fixed-clock"; - clock-frequency = <24000000>; - clock-output-names = "fin_pll"; - #clock-cells = <0>; - }; - - clock: clock-controller@10010000 { - compatible = "samsung,exynos5410-clock"; - reg = <0x10010000 0x30000>; - #clock-cells = <1>; - clocks = <&fin_pll>; - }; - -Example 2: UART controller node that consumes the clock generated by the clock - controller. Refer to the standard clock bindings for information - about 'clocks' and 'clock-names' property. - - serial@12c20000 { - compatible = "samsung,exynos4210-uart"; - reg = <0x12C00000 0x100>; - interrupts = <0 51 0>; - clocks = <&clock CLK_UART0>, <&clock CLK_SCLK_UART0>; - clock-names = "uart", "clk_uart_baud0"; - }; diff --git a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt b/Documentation/devicetree/bindings/clock/exynos5433-clock.txt deleted file mode 100644 index 183c327a7d6b..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt +++ /dev/null @@ -1,507 +0,0 @@ -* Samsung Exynos5433 CMU (Clock Management Units) - -The Exynos5433 clock controller generates and supplies clock to various -controllers within the Exynos5433 SoC. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,exynos5433-cmu-top" - clock controller compatible for CMU_TOP - which generates clocks for IMEM/FSYS/G3D/GSCL/HEVC/MSCL/G2D/MFC/PERIC/PERIS - domains and bus clocks. - - "samsung,exynos5433-cmu-cpif" - clock controller compatible for CMU_CPIF - which generates clocks for LLI (Low Latency Interface) IP. - - "samsung,exynos5433-cmu-mif" - clock controller compatible for CMU_MIF - which generates clocks for DRAM Memory Controller domain. - - "samsung,exynos5433-cmu-peric" - clock controller compatible for CMU_PERIC - which generates clocks for UART/I2C/SPI/I2S/PCM/SPDIF/PWM/SLIMBUS IPs. - - "samsung,exynos5433-cmu-peris" - clock controller compatible for CMU_PERIS - which generates clocks for PMU/TMU/MCT/WDT/RTC/SECKEY/TZPC IPs. - - "samsung,exynos5433-cmu-fsys" - clock controller compatible for CMU_FSYS - which generates clocks for USB/UFS/SDMMC/TSI/PDMA IPs. - - "samsung,exynos5433-cmu-g2d" - clock controller compatible for CMU_G2D - which generates clocks for G2D/MDMA IPs. - - "samsung,exynos5433-cmu-disp" - clock controller compatible for CMU_DISP - which generates clocks for Display (DECON/HDMI/DSIM/MIXER) IPs. - - "samsung,exynos5433-cmu-aud" - clock controller compatible for CMU_AUD - which generates clocks for Cortex-A5/BUS/AUDIO clocks. - - "samsung,exynos5433-cmu-bus0", "samsung,exynos5433-cmu-bus1" - and "samsung,exynos5433-cmu-bus2" - clock controller compatible for CMU_BUS - which generates global data buses clock and global peripheral buses clock. - - "samsung,exynos5433-cmu-g3d" - clock controller compatible for CMU_G3D - which generates clocks for 3D Graphics Engine IP. - - "samsung,exynos5433-cmu-gscl" - clock controller compatible for CMU_GSCL - which generates clocks for GSCALER IPs. - - "samsung,exynos5433-cmu-apollo"- clock controller compatible for CMU_APOLLO - which generates clocks for Cortex-A53 Quad-core processor. - - "samsung,exynos5433-cmu-atlas" - clock controller compatible for CMU_ATLAS - which generates clocks for Cortex-A57 Quad-core processor, CoreSight and - L2 cache controller. - - "samsung,exynos5433-cmu-mscl" - clock controller compatible for CMU_MSCL - which generates clocks for M2M (Memory to Memory) scaler and JPEG IPs. - - "samsung,exynos5433-cmu-mfc" - clock controller compatible for CMU_MFC - which generates clocks for MFC(Multi-Format Codec) IP. - - "samsung,exynos5433-cmu-hevc" - clock controller compatible for CMU_HEVC - which generates clocks for HEVC(High Efficiency Video Codec) decoder IP. - - "samsung,exynos5433-cmu-isp" - clock controller compatible for CMU_ISP - which generates clocks for FIMC-ISP/DRC/SCLC/DIS/3DNR IPs. - - "samsung,exynos5433-cmu-cam0" - clock controller compatible for CMU_CAM0 - which generates clocks for MIPI_CSIS{0|1}/FIMC_LITE_{A|B|D}/FIMC_3AA{0|1} - IPs. - - "samsung,exynos5433-cmu-cam1" - clock controller compatible for CMU_CAM1 - which generates clocks for Cortex-A5/MIPI_CSIS2/FIMC-LITE_C/FIMC-FD IPs. - - "samsung,exynos5433-cmu-imem" - clock controller compatible for CMU_IMEM - which generates clocks for SSS (Security SubSystem) and SlimSSS IPs. - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -- clocks: list of the clock controller input clock identifiers, - from common clock bindings. Please refer the next section - to find the input clocks for a given controller. - -- clock-names: list of the clock controller input clock names, - as described in clock-bindings.txt. - - Input clocks for top clock controller: - - oscclk - - sclk_mphy_pll - - sclk_mfc_pll - - sclk_bus_pll - - Input clocks for cpif clock controller: - - oscclk - - Input clocks for mif clock controller: - - oscclk - - sclk_mphy_pll - - Input clocks for fsys clock controller: - - oscclk - - sclk_ufs_mphy - - aclk_fsys_200 - - sclk_pcie_100_fsys - - sclk_ufsunipro_fsys - - sclk_mmc2_fsys - - sclk_mmc1_fsys - - sclk_mmc0_fsys - - sclk_usbhost30_fsys - - sclk_usbdrd30_fsys - - Input clocks for g2d clock controller: - - oscclk - - aclk_g2d_266 - - aclk_g2d_400 - - Input clocks for disp clock controller: - - oscclk - - sclk_dsim1_disp - - sclk_dsim0_disp - - sclk_dsd_disp - - sclk_decon_tv_eclk_disp - - sclk_decon_vclk_disp - - sclk_decon_eclk_disp - - sclk_decon_tv_vclk_disp - - aclk_disp_333 - - Input clocks for audio clock controller: - - oscclk - - fout_aud_pll - - Input clocks for bus0 clock controller: - - aclk_bus0_400 - - Input clocks for bus1 clock controller: - - aclk_bus1_400 - - Input clocks for bus2 clock controller: - - oscclk - - aclk_bus2_400 - - Input clocks for g3d clock controller: - - oscclk - - aclk_g3d_400 - - Input clocks for gscl clock controller: - - oscclk - - aclk_gscl_111 - - aclk_gscl_333 - - Input clocks for apollo clock controller: - - oscclk - - sclk_bus_pll_apollo - - Input clocks for atlas clock controller: - - oscclk - - sclk_bus_pll_atlas - - Input clocks for mscl clock controller: - - oscclk - - sclk_jpeg_mscl - - aclk_mscl_400 - - Input clocks for mfc clock controller: - - oscclk - - aclk_mfc_400 - - Input clocks for hevc clock controller: - - oscclk - - aclk_hevc_400 - - Input clocks for isp clock controller: - - oscclk - - aclk_isp_dis_400 - - aclk_isp_400 - - Input clocks for cam0 clock controller: - - oscclk - - aclk_cam0_333 - - aclk_cam0_400 - - aclk_cam0_552 - - Input clocks for cam1 clock controller: - - oscclk - - sclk_isp_uart_cam1 - - sclk_isp_spi1_cam1 - - sclk_isp_spi0_cam1 - - aclk_cam1_333 - - aclk_cam1_400 - - aclk_cam1_552 - - Input clocks for imem clock controller: - - oscclk - - aclk_imem_sssx_266 - - aclk_imem_266 - - aclk_imem_200 - -Optional properties: - - power-domains: a phandle to respective power domain node as described by - generic PM domain bindings (see power/power_domain.txt for more - information). - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos5433.h header and can be used in device -tree sources. - -Example 1: Examples of 'oscclk' source clock node are listed below. - - xxti: xxti { - compatible = "fixed-clock"; - clock-output-names = "oscclk"; - #clock-cells = <0>; - }; - -Example 2: Examples of clock controller nodes are listed below. - - cmu_top: clock-controller@10030000 { - compatible = "samsung,exynos5433-cmu-top"; - reg = <0x10030000 0x0c04>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_mphy_pll", - "sclk_mfc_pll", - "sclk_bus_pll"; - clocks = <&xxti>, - <&cmu_cpif CLK_SCLK_MPHY_PLL>, - <&cmu_mif CLK_SCLK_MFC_PLL>, - <&cmu_mif CLK_SCLK_BUS_PLL>; - }; - - cmu_cpif: clock-controller@10fc0000 { - compatible = "samsung,exynos5433-cmu-cpif"; - reg = <0x10fc0000 0x0c04>; - #clock-cells = <1>; - - clock-names = "oscclk"; - clocks = <&xxti>; - }; - - cmu_mif: clock-controller@105b0000 { - compatible = "samsung,exynos5433-cmu-mif"; - reg = <0x105b0000 0x100c>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_mphy_pll"; - clocks = <&xxti>, - <&cmu_cpif CLK_SCLK_MPHY_PLL>; - }; - - cmu_peric: clock-controller@14c80000 { - compatible = "samsung,exynos5433-cmu-peric"; - reg = <0x14c80000 0x0b08>; - #clock-cells = <1>; - }; - - cmu_peris: clock-controller@10040000 { - compatible = "samsung,exynos5433-cmu-peris"; - reg = <0x10040000 0x0b20>; - #clock-cells = <1>; - }; - - cmu_fsys: clock-controller@156e0000 { - compatible = "samsung,exynos5433-cmu-fsys"; - reg = <0x156e0000 0x0b04>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_ufs_mphy", - "aclk_fsys_200", - "sclk_pcie_100_fsys", - "sclk_ufsunipro_fsys", - "sclk_mmc2_fsys", - "sclk_mmc1_fsys", - "sclk_mmc0_fsys", - "sclk_usbhost30_fsys", - "sclk_usbdrd30_fsys"; - clocks = <&xxti>, - <&cmu_cpif CLK_SCLK_UFS_MPHY>, - <&cmu_top CLK_ACLK_FSYS_200>, - <&cmu_top CLK_SCLK_PCIE_100_FSYS>, - <&cmu_top CLK_SCLK_UFSUNIPRO_FSYS>, - <&cmu_top CLK_SCLK_MMC2_FSYS>, - <&cmu_top CLK_SCLK_MMC1_FSYS>, - <&cmu_top CLK_SCLK_MMC0_FSYS>, - <&cmu_top CLK_SCLK_USBHOST30_FSYS>, - <&cmu_top CLK_SCLK_USBDRD30_FSYS>; - }; - - cmu_g2d: clock-controller@12460000 { - compatible = "samsung,exynos5433-cmu-g2d"; - reg = <0x12460000 0x0b08>; - #clock-cells = <1>; - - clock-names = "oscclk", - "aclk_g2d_266", - "aclk_g2d_400"; - clocks = <&xxti>, - <&cmu_top CLK_ACLK_G2D_266>, - <&cmu_top CLK_ACLK_G2D_400>; - power-domains = <&pd_g2d>; - }; - - cmu_disp: clock-controller@13b90000 { - compatible = "samsung,exynos5433-cmu-disp"; - reg = <0x13b90000 0x0c04>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_dsim1_disp", - "sclk_dsim0_disp", - "sclk_dsd_disp", - "sclk_decon_tv_eclk_disp", - "sclk_decon_vclk_disp", - "sclk_decon_eclk_disp", - "sclk_decon_tv_vclk_disp", - "aclk_disp_333"; - clocks = <&xxti>, - <&cmu_mif CLK_SCLK_DSIM1_DISP>, - <&cmu_mif CLK_SCLK_DSIM0_DISP>, - <&cmu_mif CLK_SCLK_DSD_DISP>, - <&cmu_mif CLK_SCLK_DECON_TV_ECLK_DISP>, - <&cmu_mif CLK_SCLK_DECON_VCLK_DISP>, - <&cmu_mif CLK_SCLK_DECON_ECLK_DISP>, - <&cmu_mif CLK_SCLK_DECON_TV_VCLK_DISP>, - <&cmu_mif CLK_ACLK_DISP_333>; - power-domains = <&pd_disp>; - }; - - cmu_aud: clock-controller@114c0000 { - compatible = "samsung,exynos5433-cmu-aud"; - reg = <0x114c0000 0x0b04>; - #clock-cells = <1>; - - clock-names = "oscclk", "fout_aud_pll"; - clocks = <&xxti>, <&cmu_top CLK_FOUT_AUD_PLL>; - power-domains = <&pd_aud>; - }; - - cmu_bus0: clock-controller@13600000 { - compatible = "samsung,exynos5433-cmu-bus0"; - reg = <0x13600000 0x0b04>; - #clock-cells = <1>; - - clock-names = "aclk_bus0_400"; - clocks = <&cmu_top CLK_ACLK_BUS0_400>; - }; - - cmu_bus1: clock-controller@14800000 { - compatible = "samsung,exynos5433-cmu-bus1"; - reg = <0x14800000 0x0b04>; - #clock-cells = <1>; - - clock-names = "aclk_bus1_400"; - clocks = <&cmu_top CLK_ACLK_BUS1_400>; - }; - - cmu_bus2: clock-controller@13400000 { - compatible = "samsung,exynos5433-cmu-bus2"; - reg = <0x13400000 0x0b04>; - #clock-cells = <1>; - - clock-names = "oscclk", "aclk_bus2_400"; - clocks = <&xxti>, <&cmu_mif CLK_ACLK_BUS2_400>; - }; - - cmu_g3d: clock-controller@14aa0000 { - compatible = "samsung,exynos5433-cmu-g3d"; - reg = <0x14aa0000 0x1000>; - #clock-cells = <1>; - - clock-names = "oscclk", "aclk_g3d_400"; - clocks = <&xxti>, <&cmu_top CLK_ACLK_G3D_400>; - power-domains = <&pd_g3d>; - }; - - cmu_gscl: clock-controller@13cf0000 { - compatible = "samsung,exynos5433-cmu-gscl"; - reg = <0x13cf0000 0x0b10>; - #clock-cells = <1>; - - clock-names = "oscclk", - "aclk_gscl_111", - "aclk_gscl_333"; - clocks = <&xxti>, - <&cmu_top CLK_ACLK_GSCL_111>, - <&cmu_top CLK_ACLK_GSCL_333>; - power-domains = <&pd_gscl>; - }; - - cmu_apollo: clock-controller@11900000 { - compatible = "samsung,exynos5433-cmu-apollo"; - reg = <0x11900000 0x1088>; - #clock-cells = <1>; - - clock-names = "oscclk", "sclk_bus_pll_apollo"; - clocks = <&xxti>, <&cmu_mif CLK_SCLK_BUS_PLL_APOLLO>; - }; - - cmu_atlas: clock-controller@11800000 { - compatible = "samsung,exynos5433-cmu-atlas"; - reg = <0x11800000 0x1088>; - #clock-cells = <1>; - - clock-names = "oscclk", "sclk_bus_pll_atlas"; - clocks = <&xxti>, <&cmu_mif CLK_SCLK_BUS_PLL_ATLAS>; - }; - - cmu_mscl: clock-controller@105d0000 { - compatible = "samsung,exynos5433-cmu-mscl"; - reg = <0x105d0000 0x0b10>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_jpeg_mscl", - "aclk_mscl_400"; - clocks = <&xxti>, - <&cmu_top CLK_SCLK_JPEG_MSCL>, - <&cmu_top CLK_ACLK_MSCL_400>; - power-domains = <&pd_mscl>; - }; - - cmu_mfc: clock-controller@15280000 { - compatible = "samsung,exynos5433-cmu-mfc"; - reg = <0x15280000 0x0b08>; - #clock-cells = <1>; - - clock-names = "oscclk", "aclk_mfc_400"; - clocks = <&xxti>, <&cmu_top CLK_ACLK_MFC_400>; - power-domains = <&pd_mfc>; - }; - - cmu_hevc: clock-controller@14f80000 { - compatible = "samsung,exynos5433-cmu-hevc"; - reg = <0x14f80000 0x0b08>; - #clock-cells = <1>; - - clock-names = "oscclk", "aclk_hevc_400"; - clocks = <&xxti>, <&cmu_top CLK_ACLK_HEVC_400>; - power-domains = <&pd_hevc>; - }; - - cmu_isp: clock-controller@146d0000 { - compatible = "samsung,exynos5433-cmu-isp"; - reg = <0x146d0000 0x0b0c>; - #clock-cells = <1>; - - clock-names = "oscclk", - "aclk_isp_dis_400", - "aclk_isp_400"; - clocks = <&xxti>, - <&cmu_top CLK_ACLK_ISP_DIS_400>, - <&cmu_top CLK_ACLK_ISP_400>; - power-domains = <&pd_isp>; - }; - - cmu_cam0: clock-controller@120d0000 { - compatible = "samsung,exynos5433-cmu-cam0"; - reg = <0x120d0000 0x0b0c>; - #clock-cells = <1>; - - clock-names = "oscclk", - "aclk_cam0_333", - "aclk_cam0_400", - "aclk_cam0_552"; - clocks = <&xxti>, - <&cmu_top CLK_ACLK_CAM0_333>, - <&cmu_top CLK_ACLK_CAM0_400>, - <&cmu_top CLK_ACLK_CAM0_552>; - power-domains = <&pd_cam0>; - }; - - cmu_cam1: clock-controller@145d0000 { - compatible = "samsung,exynos5433-cmu-cam1"; - reg = <0x145d0000 0x0b08>; - #clock-cells = <1>; - - clock-names = "oscclk", - "sclk_isp_uart_cam1", - "sclk_isp_spi1_cam1", - "sclk_isp_spi0_cam1", - "aclk_cam1_333", - "aclk_cam1_400", - "aclk_cam1_552"; - clocks = <&xxti>, - <&cmu_top CLK_SCLK_ISP_UART_CAM1>, - <&cmu_top CLK_SCLK_ISP_SPI1_CAM1>, - <&cmu_top CLK_SCLK_ISP_SPI0_CAM1>, - <&cmu_top CLK_ACLK_CAM1_333>, - <&cmu_top CLK_ACLK_CAM1_400>, - <&cmu_top CLK_ACLK_CAM1_552>; - power-domains = <&pd_cam1>; - }; - - cmu_imem: clock-controller@11060000 { - compatible = "samsung,exynos5433-cmu-imem"; - reg = <0x11060000 0x1000>; - #clock-cells = <1>; - - clock-names = "oscclk", - "aclk_imem_sssx_266", - "aclk_imem_266", - "aclk_imem_200"; - clocks = <&xxti>, - <&cmu_top CLK_DIV_ACLK_IMEM_SSSX_266>, - <&cmu_top CLK_DIV_ACLK_IMEM_266>, - <&cmu_top CLK_DIV_ACLK_IMEM_200>; - }; - -Example 3: UART controller node that consumes the clock generated by the clock - controller. - - serial_0: serial@14c10000 { - compatible = "samsung,exynos5433-uart"; - reg = <0x14C10000 0x100>; - interrupts = <0 421 0>; - clocks = <&cmu_peric CLK_PCLK_UART0>, - <&cmu_peric CLK_SCLK_UART0>; - clock-names = "uart", "clk_uart_baud0"; - pinctrl-names = "default"; - pinctrl-0 = <&uart0_bus>; - }; diff --git a/Documentation/devicetree/bindings/clock/exynos7-clock.txt b/Documentation/devicetree/bindings/clock/exynos7-clock.txt deleted file mode 100644 index 6bf1e7493f61..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos7-clock.txt +++ /dev/null @@ -1,108 +0,0 @@ -* Samsung Exynos7 Clock Controller - -Exynos7 clock controller has various blocks which are instantiated -independently from the device-tree. These clock controllers -generate and supply clocks to various hardware blocks within -the SoC. - -Each clock is assigned an identifier and client nodes can use -this identifier to specify the clock which they consume. All -available clocks are defined as preprocessor macros in -dt-bindings/clock/exynos7-clk.h header and can be used in -device tree sources. - -External clocks: - -There are several clocks that are generated outside the SoC. It -is expected that they are defined using standard clock bindings -with following clock-output-names: - - - "fin_pll" - PLL input clock from XXTI - -Required Properties for Clock Controller: - - - compatible: clock controllers will use one of the following - compatible strings to indicate the clock controller - functionality. - - - "samsung,exynos7-clock-topc" - - "samsung,exynos7-clock-top0" - - "samsung,exynos7-clock-top1" - - "samsung,exynos7-clock-ccore" - - "samsung,exynos7-clock-peric0" - - "samsung,exynos7-clock-peric1" - - "samsung,exynos7-clock-peris" - - "samsung,exynos7-clock-fsys0" - - "samsung,exynos7-clock-fsys1" - - "samsung,exynos7-clock-mscl" - - "samsung,exynos7-clock-aud" - - - reg: physical base address of the controller and the length of - memory mapped region. - - - #clock-cells: should be 1. - - - clocks: list of clock identifiers which are fed as the input to - the given clock controller. Please refer the next section to - find the input clocks for a given controller. - -- clock-names: list of names of clocks which are fed as the input - to the given clock controller. - -Input clocks for top0 clock controller: - - fin_pll - - dout_sclk_bus0_pll - - dout_sclk_bus1_pll - - dout_sclk_cc_pll - - dout_sclk_mfc_pll - - dout_sclk_aud_pll - -Input clocks for top1 clock controller: - - fin_pll - - dout_sclk_bus0_pll - - dout_sclk_bus1_pll - - dout_sclk_cc_pll - - dout_sclk_mfc_pll - -Input clocks for ccore clock controller: - - fin_pll - - dout_aclk_ccore_133 - -Input clocks for peric0 clock controller: - - fin_pll - - dout_aclk_peric0_66 - - sclk_uart0 - -Input clocks for peric1 clock controller: - - fin_pll - - dout_aclk_peric1_66 - - sclk_uart1 - - sclk_uart2 - - sclk_uart3 - - sclk_spi0 - - sclk_spi1 - - sclk_spi2 - - sclk_spi3 - - sclk_spi4 - - sclk_i2s1 - - sclk_pcm1 - - sclk_spdif - -Input clocks for peris clock controller: - - fin_pll - - dout_aclk_peris_66 - -Input clocks for fsys0 clock controller: - - fin_pll - - dout_aclk_fsys0_200 - - dout_sclk_mmc2 - -Input clocks for fsys1 clock controller: - - fin_pll - - dout_aclk_fsys1_200 - - dout_sclk_mmc0 - - dout_sclk_mmc1 - -Input clocks for aud clock controller: - - fin_pll - - fout_aud_pll diff --git a/Documentation/devicetree/bindings/clock/imx5-clock.yaml b/Documentation/devicetree/bindings/clock/imx5-clock.yaml index b1740d7abe68..c0e19ff92c76 100644 --- a/Documentation/devicetree/bindings/clock/imx5-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx5-clock.yaml @@ -55,11 +55,4 @@ examples: <0 72 IRQ_TYPE_LEVEL_HIGH>; #clock-cells = <1>; }; - - can@53fc8000 { - compatible = "fsl,imx53-flexcan", "fsl,imx25-flexcan"; - reg = <0x53fc8000 0x4000>; - interrupts = <82>; - clocks = <&clks IMX5_CLK_CAN1_IPG_GATE>, <&clks IMX5_CLK_CAN1_SERIAL_GATE>; - clock-names = "ipg", "per"; - }; +... diff --git a/Documentation/devicetree/bindings/clock/microchip,lan966x-gck.yaml b/Documentation/devicetree/bindings/clock/microchip,lan966x-gck.yaml new file mode 100644 index 000000000000..df2bec188706 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/microchip,lan966x-gck.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/microchip,lan966x-gck.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip LAN966X Generic Clock Controller + +maintainers: + - Kavyasree Kotagiri <kavyasree.kotagiri@microchip.com> + +description: | + The LAN966X Generic clock controller contains 3 PLLs - cpu_clk, + ddr_clk and sys_clk. This clock controller generates and supplies + clock to various peripherals within the SoC. + +properties: + compatible: + const: microchip,lan966x-gck + + reg: + minItems: 1 + items: + - description: Generic clock registers + - description: Optional gate clock registers + + clocks: + items: + - description: CPU clock source + - description: DDR clock source + - description: System clock source + + clock-names: + items: + - const: cpu + - const: ddr + - const: sys + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clks: clock-controller@e00c00a8 { + compatible = "microchip,lan966x-gck"; + #clock-cells = <1>; + clocks = <&cpu_clk>, <&ddr_clk>, <&sys_clk>; + clock-names = "cpu", "ddr", "sys"; + reg = <0xe00c00a8 0x38>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml new file mode 100644 index 000000000000..f3430b159caa --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-msm8976.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for MSM8976 + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <tdas@codeaurora.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on MSM8976. + + See also: + - dt-bindings/clock/qcom,gcc-msm8976.h + +properties: + compatible: + enum: + - qcom,gcc-msm8976 + - qcom,gcc-msm8976-v1.1 + + clocks: + items: + - description: XO source + - description: Always-on XO source + - description: Pixel clock from DSI PHY0 + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY1 + - description: Byte clock from DSI PHY1 + + clock-names: + items: + - const: xo + - const: xo_a + - const: dsi0pll + - const: dsi0pllbyte + - const: dsi1pll + - const: dsi1pllbyte + + vdd_gfx-supply: + description: + Phandle to voltage regulator providing power to the GX domain. + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - vdd_gfx-supply + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + clock-controller@1800000 { + compatible = "qcom,gcc-msm8976"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + reg = <0x1800000 0x80000>; + + clocks = <&xo_board>, + <&xo_board>, + <&dsi0_phy 1>, + <&dsi0_phy 0>, + <&dsi1_phy 1>, + <&dsi1_phy 0>; + + clock-names = "xo", + "xo_a", + "dsi0pll", + "dsi0pllbyte", + "dsi1pll", + "dsi1pllbyte"; + + vdd_gfx-supply = <&pm8004_s5>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 72212970e6f5..8406dde17937 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -22,10 +22,12 @@ properties: - qcom,sc8180x-rpmh-clk - qcom,sdm845-rpmh-clk - qcom,sdx55-rpmh-clk + - qcom,sdx65-rpmh-clk - qcom,sm6350-rpmh-clk - qcom,sm8150-rpmh-clk - qcom,sm8250-rpmh-clk - qcom,sm8350-rpmh-clk + - qcom,sm8450-rpmh-clk clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index f7d48f23da44..10119d9ef4b1 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -44,6 +44,7 @@ Required properties: * "fsl,ls1046a-clockgen" * "fsl,ls1088a-clockgen" * "fsl,ls2080a-clockgen" + * "fsl,lx2160a-clockgen" Chassis-version clock strings include: * "fsl,qoriq-clockgen-1.0": for chassis 1.0 clocks * "fsl,qoriq-clockgen-2.0": for chassis 2.0 clocks diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml index 9b414fbde6d7..e0b86214f0f5 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -48,6 +48,7 @@ properties: - renesas,r8a77990-cpg-mssr # R-Car E3 - renesas,r8a77995-cpg-mssr # R-Car D3 - renesas,r8a779a0-cpg-mssr # R-Car V3U + - renesas,r8a779f0-cpg-mssr # R-Car S4-8 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos5260-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos5260-clock.yaml new file mode 100644 index 000000000000..a3fac5c6809d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos5260-clock.yaml @@ -0,0 +1,382 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos5260-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos5260 SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Expected external clocks, defined in DTS as fixed-rate clocks with a matching + name:: + - "fin_pll" - PLL input clock from XXTI + - "xrtcxti" - input clock from XRTCXTI + - "ioclk_pcm_extclk" - pcm external operation clock + - "ioclk_spdif_extclk" - spdif external operation clock + - "ioclk_i2s_cdclk" - i2s0 codec clock + + Phy clocks:: + There are several clocks which are generated by specific PHYs. These clocks + are fed into the clock controller and then routed to the hardware blocks. + These clocks are defined as fixed clocks in the driver with following names:: + - "phyclk_dptx_phy_ch3_txd_clk" - dp phy clock for channel 3 + - "phyclk_dptx_phy_ch2_txd_clk" - dp phy clock for channel 2 + - "phyclk_dptx_phy_ch1_txd_clk" - dp phy clock for channel 1 + - "phyclk_dptx_phy_ch0_txd_clk" - dp phy clock for channel 0 + - "phyclk_hdmi_phy_tmds_clko" - hdmi phy tmds clock + - "phyclk_hdmi_phy_pixel_clko" - hdmi phy pixel clock + - "phyclk_hdmi_link_o_tmds_clkhi" - hdmi phy for hdmi link + - "phyclk_dptx_phy_o_ref_clk_24m" - dp phy reference clock + - "phyclk_dptx_phy_clk_div2" + - "phyclk_mipi_dphy_4l_m_rxclkesc0" + - "phyclk_usbhost20_phy_phyclock" - usb 2.0 phy clock + - "phyclk_usbhost20_phy_freeclk" + - "phyclk_usbhost20_phy_clk48mohci" + - "phyclk_usbdrd30_udrd30_pipe_pclk" + - "phyclk_usbdrd30_udrd30_phyclock" - usb 3.0 phy clock + + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/exynos5260-clk.h header. + +properties: + compatible: + enum: + - samsung,exynos5260-clock-top + - samsung,exynos5260-clock-peri + - samsung,exynos5260-clock-egl + - samsung,exynos5260-clock-kfc + - samsung,exynos5260-clock-g2d + - samsung,exynos5260-clock-mif + - samsung,exynos5260-clock-mfc + - samsung,exynos5260-clock-g3d + - samsung,exynos5260-clock-fsys + - samsung,exynos5260-clock-aud + - samsung,exynos5260-clock-isp + - samsung,exynos5260-clock-gscl + - samsung,exynos5260-clock-disp + + clocks: + minItems: 1 + maxItems: 19 + + clock-names: + minItems: 1 + maxItems: 19 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-top + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: fin_pll + - const: dout_mem_pll + - const: dout_bus_pll + - const: dout_media_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-peri + then: + properties: + clocks: + minItems: 13 + maxItems: 13 + clock-names: + items: + - const: fin_pll + - const: ioclk_pcm_extclk + - const: ioclk_i2s_cdclk + - const: ioclk_spdif_extclk + - const: phyclk_hdmi_phy_ref_cko + - const: dout_aclk_peri_66 + - const: dout_sclk_peri_uart0 + - const: dout_sclk_peri_uart1 + - const: dout_sclk_peri_uart2 + - const: dout_sclk_peri_spi0_b + - const: dout_sclk_peri_spi1_b + - const: dout_sclk_peri_spi2_b + - const: dout_aclk_peri_aud + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-egl + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_bus_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-kfc + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_media_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-g2d + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_g2d_333 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-mif + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + items: + - const: fin_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-mfc + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_mfc_333 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-g3d + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + items: + - const: fin_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-fsys + then: + properties: + clocks: + minItems: 7 + maxItems: 7 + clock-names: + items: + - const: fin_pll + - const: phyclk_usbhost20_phy_phyclock + - const: phyclk_usbhost20_phy_freeclk + - const: phyclk_usbhost20_phy_clk48mohci + - const: phyclk_usbdrd30_udrd30_pipe_pclk + - const: phyclk_usbdrd30_udrd30_phyclock + - const: dout_aclk_fsys_200 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-aud + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: fin_pll + - const: fout_aud_pll + - const: ioclk_i2s_cdclk + - const: ioclk_pcm_extclk + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-isp + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_isp1_266 + - const: dout_aclk_isp1_400 + - const: mout_aclk_isp1_266 + + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-gscl + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_gscl_400 + - const: dout_aclk_gscl_333 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5260-clock-disp + then: + properties: + clocks: + minItems: 19 + maxItems: 19 + clock-names: + items: + - const: fin_pll + - const: phyclk_dptx_phy_ch3_txd_clk + - const: phyclk_dptx_phy_ch2_txd_clk + - const: phyclk_dptx_phy_ch1_txd_clk + - const: phyclk_dptx_phy_ch0_txd_clk + - const: phyclk_hdmi_phy_tmds_clko + - const: phyclk_hdmi_phy_ref_clko + - const: phyclk_hdmi_phy_pixel_clko + - const: phyclk_hdmi_link_o_tmds_clkhi + - const: phyclk_mipi_dphy_4l_m_txbyte_clkhs + - const: phyclk_dptx_phy_o_ref_clk_24m + - const: phyclk_dptx_phy_clk_div2 + - const: phyclk_mipi_dphy_4l_m_rxclkesc0 + - const: phyclk_hdmi_phy_ref_cko + - const: ioclk_spdif_extclk + - const: dout_aclk_peri_aud + - const: dout_aclk_disp_222 + - const: dout_sclk_disp_pixel + - const: dout_aclk_disp_333 + required: + - clock-names + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5260-clk.h> + + fin_pll: clock { + compatible = "fixed-clock"; + clock-output-names = "fin_pll"; + #clock-cells = <0>; + clock-frequency = <24000000>; + }; + + clock-controller@10010000 { + compatible = "samsung,exynos5260-clock-top"; + reg = <0x10010000 0x10000>; + #clock-cells = <1>; + clocks = <&fin_pll>, + <&clock_mif MIF_DOUT_MEM_PLL>, + <&clock_mif MIF_DOUT_BUS_PLL>, + <&clock_mif MIF_DOUT_MEDIA_PLL>; + clock-names = "fin_pll", + "dout_mem_pll", + "dout_bus_pll", + "dout_media_pll"; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos5410-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos5410-clock.yaml new file mode 100644 index 000000000000..032862e9f55b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos5410-clock.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos5410-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos5410 SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Expected external clocks, defined in DTS as fixed-rate clocks with a matching + name:: + - "fin_pll" - PLL input clock from XXTI + + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/exynos5410.h header. + +properties: + compatible: + oneOf: + - enum: + - samsung,exynos5410-clock + + clocks: + description: + Should contain an entry specifying the root clock from external + oscillator supplied through XXTI or XusbXTI pin. This clock should be + defined using standard clock bindings with "fin_pll" clock-output-name. + That clock is being passed internally to the 9 PLLs. + maxItems: 1 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5410.h> + + fin_pll: osc-clock { + compatible = "fixed-clock"; + clock-frequency = <24000000>; + clock-output-names = "fin_pll"; + #clock-cells = <0>; + }; + + clock-controller@10010000 { + compatible = "samsung,exynos5410-clock"; + reg = <0x10010000 0x30000>; + #clock-cells = <1>; + clocks = <&fin_pll>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos5433-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos5433-clock.yaml new file mode 100644 index 000000000000..edd1b4ac4334 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos5433-clock.yaml @@ -0,0 +1,524 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos5433-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos5433 SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Expected external clocks, defined in DTS as fixed-rate clocks with a matching + name:: + - "oscclk" - PLL input clock from XXTI + + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/exynos5433.h header. + +properties: + compatible: + enum: + # CMU_TOP which generates clocks for + # IMEM/FSYS/G3D/GSCL/HEVC/MSCL/G2D/MFC/PERIC/PERIS domains and bus + # clocks + - samsung,exynos5433-cmu-top + # CMU_CPIF which generates clocks for LLI (Low Latency Interface) IP + - samsung,exynos5433-cmu-cpif + # CMU_MIF which generates clocks for DRAM Memory Controller domain + - samsung,exynos5433-cmu-mif + # CMU_PERIC which generates clocks for + # UART/I2C/SPI/I2S/PCM/SPDIF/PWM/SLIMBUS IPs + - samsung,exynos5433-cmu-peric + # CMU_PERIS which generates clocks for PMU/TMU/MCT/WDT/RTC/SECKEY/TZPC IPs + - samsung,exynos5433-cmu-peris + # CMU_FSYS which generates clocks for USB/UFS/SDMMC/TSI/PDMA IPs + - samsung,exynos5433-cmu-fsys + - samsung,exynos5433-cmu-g2d + # CMU_DISP which generates clocks for Display (DECON/HDMI/DSIM/MIXER) IPs + - samsung,exynos5433-cmu-disp + - samsung,exynos5433-cmu-aud + - samsung,exynos5433-cmu-bus0 + - samsung,exynos5433-cmu-bus1 + - samsung,exynos5433-cmu-bus2 + - samsung,exynos5433-cmu-g3d + - samsung,exynos5433-cmu-gscl + - samsung,exynos5433-cmu-apollo + # CMU_ATLAS which generates clocks for Cortex-A57 Quad-core processor, + # CoreSight and L2 cache controller + - samsung,exynos5433-cmu-atlas + # CMU_MSCL which generates clocks for M2M (Memory to Memory) scaler and + # JPEG IPs + - samsung,exynos5433-cmu-mscl + - samsung,exynos5433-cmu-mfc + - samsung,exynos5433-cmu-hevc + # CMU_ISP which generates clocks for FIMC-ISP/DRC/SCLC/DIS/3DNR IPs + - samsung,exynos5433-cmu-isp + # CMU_CAM0 which generates clocks for + # MIPI_CSIS{0|1}/FIMC_LITE_{A|B|D}/FIMC_3AA{0|1} IPs + - samsung,exynos5433-cmu-cam0 + # CMU_CAM1 which generates clocks for + # Cortex-A5/MIPI_CSIS2/FIMC-LITE_C/FIMC-FD IPs + - samsung,exynos5433-cmu-cam1 + # CMU_IMEM which generates clocks for SSS (Security SubSystem) and + # SlimSSS IPs + - samsung,exynos5433-cmu-imem + + clocks: + minItems: 1 + maxItems: 10 + + clock-names: + minItems: 1 + maxItems: 10 + + "#clock-cells": + const: 1 + + power-domains: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-top + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: oscclk + - const: sclk_mphy_pll + - const: sclk_mfc_pll + - const: sclk_bus_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-cpif + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + items: + - const: oscclk + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-mif + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: sclk_mphy_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-fsys + then: + properties: + clocks: + minItems: 10 + maxItems: 10 + clock-names: + items: + - const: oscclk + - const: sclk_ufs_mphy + - const: aclk_fsys_200 + - const: sclk_pcie_100_fsys + - const: sclk_ufsunipro_fsys + - const: sclk_mmc2_fsys + - const: sclk_mmc1_fsys + - const: sclk_mmc0_fsys + - const: sclk_usbhost30_fsys + - const: sclk_usbdrd30_fsys + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-g2d + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: oscclk + - const: aclk_g2d_266 + - const: aclk_g2d_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-disp + then: + properties: + clocks: + minItems: 9 + maxItems: 9 + clock-names: + items: + - const: oscclk + - const: sclk_dsim1_disp + - const: sclk_dsim0_disp + - const: sclk_dsd_disp + - const: sclk_decon_tv_eclk_disp + - const: sclk_decon_vclk_disp + - const: sclk_decon_eclk_disp + - const: sclk_decon_tv_vclk_disp + - const: aclk_disp_333 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-aud + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: fout_aud_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-bus0 + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + items: + - const: aclk_bus0_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-bus1 + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + items: + - const: aclk_bus1_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-bus2 + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: aclk_bus2_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-g3d + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: aclk_g3d_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-gscl + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: oscclk + - const: aclk_gscl_111 + - const: aclk_gscl_333 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-apollo + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: sclk_bus_pll_apollo + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-atlas + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: sclk_bus_pll_atlas + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-mscl + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: oscclk + - const: sclk_jpeg_mscl + - const: aclk_mscl_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-mfc + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: aclk_mfc_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-hevc + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: oscclk + - const: aclk_hevc_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-isp + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: oscclk + - const: aclk_isp_dis_400 + - const: aclk_isp_400 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-cam0 + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: oscclk + - const: aclk_cam0_333 + - const: aclk_cam0_400 + - const: aclk_cam0_552 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-cam1 + then: + properties: + clocks: + minItems: 7 + maxItems: 7 + clock-names: + items: + - const: oscclk + - const: sclk_isp_uart_cam1 + - const: sclk_isp_spi1_cam1 + - const: sclk_isp_spi0_cam1 + - const: aclk_cam1_333 + - const: aclk_cam1_400 + - const: aclk_cam1_552 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-cmu-imem + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: oscclk + - const: aclk_imem_sssx_266 + - const: aclk_imem_266 + - const: aclk_imem_200 + required: + - clock-names + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5433.h> + xxti: clock { + compatible = "fixed-clock"; + clock-output-names = "oscclk"; + #clock-cells = <0>; + clock-frequency = <24000000>; + }; + + clock-controller@10030000 { + compatible = "samsung,exynos5433-cmu-top"; + reg = <0x10030000 0x1000>; + #clock-cells = <1>; + + clock-names = "oscclk", + "sclk_mphy_pll", + "sclk_mfc_pll", + "sclk_bus_pll"; + clocks = <&xxti>, + <&cmu_cpif CLK_SCLK_MPHY_PLL>, + <&cmu_mif CLK_SCLK_MFC_PLL>, + <&cmu_mif CLK_SCLK_BUS_PLL>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos7-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos7-clock.yaml new file mode 100644 index 000000000000..599baf0b7231 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos7-clock.yaml @@ -0,0 +1,272 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos7-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos7 SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Expected external clocks, defined in DTS as fixed-rate clocks with a matching + name:: + - "fin_pll" - PLL input clock from XXTI + + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/exynos7-clk.h header. + +properties: + compatible: + enum: + - samsung,exynos7-clock-topc + - samsung,exynos7-clock-top0 + - samsung,exynos7-clock-top1 + - samsung,exynos7-clock-ccore + - samsung,exynos7-clock-peric0 + - samsung,exynos7-clock-peric1 + - samsung,exynos7-clock-peris + - samsung,exynos7-clock-fsys0 + - samsung,exynos7-clock-fsys1 + - samsung,exynos7-clock-mscl + - samsung,exynos7-clock-aud + + clocks: + minItems: 1 + maxItems: 13 + + clock-names: + minItems: 1 + maxItems: 13 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-top0 + then: + properties: + clocks: + minItems: 6 + maxItems: 6 + clock-names: + items: + - const: fin_pll + - const: dout_sclk_bus0_pll + - const: dout_sclk_bus1_pll + - const: dout_sclk_cc_pll + - const: dout_sclk_mfc_pll + - const: dout_sclk_aud_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-top1 + then: + properties: + clocks: + minItems: 5 + maxItems: 5 + clock-names: + items: + - const: fin_pll + - const: dout_sclk_bus0_pll + - const: dout_sclk_bus1_pll + - const: dout_sclk_cc_pll + - const: dout_sclk_mfc_pll + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-ccore + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_ccore_133 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-peric0 + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_peric0_66 + - const: sclk_uart0 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-peric1 + then: + properties: + clocks: + minItems: 13 + maxItems: 13 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_peric1_66 + - const: sclk_uart1 + - const: sclk_uart2 + - const: sclk_uart3 + - const: sclk_spi0 + - const: sclk_spi1 + - const: sclk_spi2 + - const: sclk_spi3 + - const: sclk_spi4 + - const: sclk_i2s1 + - const: sclk_pcm1 + - const: sclk_spdif + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-peris + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_peris_66 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-fsys0 + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_fsys0_200 + - const: dout_sclk_mmc2 + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-fsys1 + then: + properties: + clocks: + minItems: 7 + maxItems: 7 + clock-names: + items: + - const: fin_pll + - const: dout_aclk_fsys1_200 + - const: dout_sclk_mmc0 + - const: dout_sclk_mmc1 + - const: dout_sclk_ufsunipro20 + - const: dout_sclk_phy_fsys1 + - const: dout_sclk_phy_fsys1_26m + required: + - clock-names + - clocks + + - if: + properties: + compatible: + contains: + const: samsung,exynos7-clock-aud + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: fin_pll + - const: fout_aud_pll + required: + - clock-names + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos7-clk.h> + + fin_pll: clock { + compatible = "fixed-clock"; + clock-output-names = "fin_pll"; + #clock-cells = <0>; + clock-frequency = <24000000>; + }; + + clock-controller@105e0000 { + compatible = "samsung,exynos7-clock-top1"; + reg = <0x105e0000 0xb000>; + #clock-cells = <1>; + clocks = <&fin_pll>, + <&clock_topc DOUT_SCLK_BUS0_PLL>, + <&clock_topc DOUT_SCLK_BUS1_PLL>, + <&clock_topc DOUT_SCLK_CC_PLL>, + <&clock_topc DOUT_SCLK_MFC_PLL>; + clock-names = "fin_pll", + "dout_sclk_bus0_pll", + "dout_sclk_bus1_pll", + "dout_sclk_cc_pll", + "dout_sclk_mfc_pll"; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml new file mode 100644 index 000000000000..7e5a9cac2fd2 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml @@ -0,0 +1,166 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,exynos7885-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos7885 SoC clock controller + +maintainers: + - Dávid Virág <virag.david003@gmail.com> + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Exynos7885 clock controller is comprised of several CMU units, generating + clocks for different domains. Those CMU units are modeled as separate device + tree nodes, and might depend on each other. The root clock in that root tree + is an external clock: OSCCLK (26 MHz). This external clock must be defined + as a fixed-rate clock in dts. + + CMU_TOP is a top-level CMU, where all base clocks are prepared using PLLs and + dividers; all other leaf clocks (other CMUs) are usually derived from CMU_TOP. + + Each clock is assigned an identifier and client nodes can use this identifier + to specify the clock which they consume. All clocks available for usage + in clock consumer nodes are defined as preprocessor macros in + 'dt-bindings/clock/exynos7885.h' header. + +properties: + compatible: + enum: + - samsung,exynos7885-cmu-top + - samsung,exynos7885-cmu-core + - samsung,exynos7885-cmu-peri + + clocks: + minItems: 1 + maxItems: 10 + + clock-names: + minItems: 1 + maxItems: 10 + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +allOf: + - if: + properties: + compatible: + contains: + const: samsung,exynos7885-cmu-top + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + + clock-names: + items: + - const: oscclk + + - if: + properties: + compatible: + contains: + const: samsung,exynos7885-cmu-core + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + - description: CMU_CORE bus clock (from CMU_TOP) + - description: CCI clock (from CMU_TOP) + - description: G3D clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: dout_core_bus + - const: dout_core_cci + - const: dout_core_g3d + + - if: + properties: + compatible: + contains: + const: samsung,exynos7885-cmu-peri + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + - description: CMU_PERI bus clock (from CMU_TOP) + - description: SPI0 clock (from CMU_TOP) + - description: SPI1 clock (from CMU_TOP) + - description: UART0 clock (from CMU_TOP) + - description: UART1 clock (from CMU_TOP) + - description: UART2 clock (from CMU_TOP) + - description: USI0 clock (from CMU_TOP) + - description: USI1 clock (from CMU_TOP) + - description: USI2 clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: dout_peri_bus + - const: dout_peri_spi0 + - const: dout_peri_spi1 + - const: dout_peri_uart0 + - const: dout_peri_uart1 + - const: dout_peri_uart2 + - const: dout_peri_usi0 + - const: dout_peri_usi1 + - const: dout_peri_usi2 + +required: + - compatible + - "#clock-cells" + - clocks + - clock-names + - reg + +additionalProperties: false + +examples: + # Clock controller node for CMU_PERI + - | + #include <dt-bindings/clock/exynos7885.h> + + cmu_peri: clock-controller@10010000 { + compatible = "samsung,exynos7885-cmu-peri"; + reg = <0x10010000 0x8000>; + #clock-cells = <1>; + + clocks = <&oscclk>, + <&cmu_top CLK_DOUT_PERI_BUS>, + <&cmu_top CLK_DOUT_PERI_SPI0>, + <&cmu_top CLK_DOUT_PERI_SPI1>, + <&cmu_top CLK_DOUT_PERI_UART0>, + <&cmu_top CLK_DOUT_PERI_UART1>, + <&cmu_top CLK_DOUT_PERI_UART2>, + <&cmu_top CLK_DOUT_PERI_USI0>, + <&cmu_top CLK_DOUT_PERI_USI1>, + <&cmu_top CLK_DOUT_PERI_USI2>; + clock-names = "oscclk", + "dout_peri_bus", + "dout_peri_spi0", + "dout_peri_spi1", + "dout_peri_uart0", + "dout_peri_uart1", + "dout_peri_uart2", + "dout_peri_usi0", + "dout_peri_usi1", + "dout_peri_usi2"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos850-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos850-clock.yaml index 7f8c91a29b91..80ba60838f2b 100644 --- a/Documentation/devicetree/bindings/clock/samsung,exynos850-clock.yaml +++ b/Documentation/devicetree/bindings/clock/samsung,exynos850-clock.yaml @@ -32,6 +32,8 @@ properties: compatible: enum: - samsung,exynos850-cmu-top + - samsung,exynos850-cmu-apm + - samsung,exynos850-cmu-cmgp - samsung,exynos850-cmu-core - samsung,exynos850-cmu-dpu - samsung,exynos850-cmu-hsi @@ -72,6 +74,42 @@ allOf: properties: compatible: contains: + const: samsung,exynos850-cmu-apm + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + - description: CMU_APM bus clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: dout_clkcmu_apm_bus + + - if: + properties: + compatible: + contains: + const: samsung,exynos850-cmu-cmgp + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + - description: CMU_CMGP bus clock (from CMU_APM) + + clock-names: + items: + - const: oscclk + - const: gout_clkcmu_cmgp_bus + + - if: + properties: + compatible: + contains: const: samsung,exynos850-cmu-core then: diff --git a/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.txt b/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.txt deleted file mode 100644 index a86c83bf9d4e..000000000000 --- a/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.txt +++ /dev/null @@ -1,77 +0,0 @@ -* Samsung S5P6442/S5PC110/S5PV210 Clock Controller - -Samsung S5P6442, S5PC110 and S5PV210 SoCs contain integrated clock -controller, which generates and supplies clock to various controllers -within the SoC. - -Required Properties: - -- compatible: should be one of following: - - "samsung,s5pv210-clock" : for clock controller of Samsung - S5PC110/S5PV210 SoCs, - - "samsung,s5p6442-clock" : for clock controller of Samsung - S5P6442 SoC. - -- reg: physical base address of the controller and length of memory mapped - region. - -- #clock-cells: should be 1. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/s5pv210.h header and can be used in device tree sources. - -External clocks: - -There are several clocks that are generated outside the SoC. It is expected -that they are defined using standard clock bindings with following -clock-output-names: - - "xxti": external crystal oscillator connected to XXTI and XXTO pins of -the SoC, - - "xusbxti": external crystal oscillator connected to XUSBXTI and XUSBXTO -pins of the SoC, - -A subset of above clocks available on given board shall be specified in -board device tree, including the system base clock, as selected by XOM[0] -pin of the SoC. Refer to generic fixed rate clock bindings -documentation[1] for more information how to specify these clocks. - -[1] Documentation/devicetree/bindings/clock/fixed-clock.yaml - -Example: Clock controller node: - - clock: clock-controller@7e00f000 { - compatible = "samsung,s5pv210-clock"; - reg = <0x7e00f000 0x1000>; - #clock-cells = <1>; - }; - -Example: Required external clocks: - - xxti: clock-xxti { - compatible = "fixed-clock"; - clock-output-names = "xxti"; - clock-frequency = <24000000>; - #clock-cells = <0>; - }; - - xusbxti: clock-xusbxti { - compatible = "fixed-clock"; - clock-output-names = "xusbxti"; - clock-frequency = <24000000>; - #clock-cells = <0>; - }; - -Example: UART controller node that consumes the clock generated by the clock - controller (refer to the standard clock bindings for information about - "clocks" and "clock-names" properties): - - uart0: serial@e2900000 { - compatible = "samsung,s5pv210-uart"; - reg = <0xe2900000 0x400>; - interrupt-parent = <&vic1>; - interrupts = <10>; - clock-names = "uart", "clk_uart_baud0", - "clk_uart_baud1"; - clocks = <&clocks UART0>, <&clocks UART0>, - <&clocks SCLK_UART0>; - }; diff --git a/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.yaml new file mode 100644 index 000000000000..dcb29a2d1159 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/samsung,s5pv210-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S5P6442/S5PC110/S5PV210 SoC clock controller + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + - Sylwester Nawrocki <s.nawrocki@samsung.com> + - Tomasz Figa <tomasz.figa@gmail.com> + +description: | + Expected external clocks, defined in DTS as fixed-rate clocks with a matching + name:: + - "xxti" - external crystal oscillator connected to XXTI and XXTO pins of + the SoC, + - "xusbxti" - external crystal oscillator connected to XUSBXTI and XUSBXTO + pins of the SoC, + + All available clocks are defined as preprocessor macros in + include/dt-bindings/clock/s5pv210.h header. + +properties: + compatible: + enum: + - samsung,s5pv210-clock + - samsung,s5p6442-clock + + clocks: + items: + - description: xxti clock + - description: xusbxti clock + + clock-names: + items: + - const: xxti + - const: xusbxti + + "#clock-cells": + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - "#clock-cells" + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/s5pv210.h> + + xxti: clock-0 { + compatible = "fixed-clock"; + clock-frequency = <0>; + clock-output-names = "xxti"; + #clock-cells = <0>; + }; + + xusbxti: clock-1 { + compatible = "fixed-clock"; + clock-frequency = <0>; + clock-output-names = "xusbxti"; + #clock-cells = <0>; + }; + + clock-controller@e0100000 { + compatible = "samsung,s5pv210-clock"; + reg = <0xe0100000 0x10000>; + clock-names = "xxti", "xusbxti"; + clocks = <&xxti>, <&xusbxti>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pipllct.yaml b/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pipllct.yaml new file mode 100644 index 000000000000..7b7300ce96d6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pipllct.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/toshiba,tmpv770x-pipllct.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba Visconti5 TMPV770X PLL Controller Device Tree Bindings + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +description: + Toshia Visconti5 PLL controller which supports the PLLs on TMPV770X. + +properties: + compatible: + const: toshiba,tmpv7708-pipllct + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + description: External reference clock (OSC2) + maxItems: 1 + +required: + - compatible + - reg + - "#clock-cells" + - clocks + +additionalProperties: false + +examples: + - | + + osc2_clk: osc2-clk { + compatible = "fixed-clock"; + clock-frequency = <20000000>; + #clock-cells = <0>; + }; + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pipllct: clock-controller@24220000 { + compatible = "toshiba,tmpv7708-pipllct"; + reg = <0 0x24220000 0 0x820>; + #clock-cells = <1>; + clocks = <&osc2_clk>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pismu.yaml b/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pismu.yaml new file mode 100644 index 000000000000..ed79f16fe6bc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pismu.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/toshiba,tmpv770x-pismu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba Visconti5 TMPV770x SMU controller Device Tree Bindings + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +description: + Toshia Visconti5 SMU (System Management Unit) which supports the clock + and resets on TMPV770x. + +properties: + compatible: + items: + - const: toshiba,tmpv7708-pismu + - const: syscon + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + +required: + - compatible + - reg + - "#clock-cells" + - "#reset-cells" + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + pismu: syscon@24200000 { + compatible = "toshiba,tmpv7708-pismu", "syscon"; + reg = <0 0x24200000 0 0x2140>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/crypto/qcom,prng.txt b/Documentation/devicetree/bindings/crypto/qcom,prng.txt deleted file mode 100644 index 7ee0e9eac973..000000000000 --- a/Documentation/devicetree/bindings/crypto/qcom,prng.txt +++ /dev/null @@ -1,19 +0,0 @@ -Qualcomm MSM pseudo random number generator. - -Required properties: - -- compatible : should be "qcom,prng" for 8916 etc - : should be "qcom,prng-ee" for 8996 and later using EE - (Execution Environment) slice of prng -- reg : specifies base physical address and size of the registers map -- clocks : phandle to clock-controller plus clock-specifier pair -- clock-names : "core" clocks all registers, FIFO and circuits in PRNG IP block - -Example: - - rng@f9bff000 { - compatible = "qcom,prng"; - reg = <0xf9bff000 0x200>; - clocks = <&clock GCC_PRNG_AHB_CLK>; - clock-names = "core"; - }; diff --git a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml new file mode 100644 index 000000000000..bb42f4588b40 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/qcom,prng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Pseudo Random Number Generator + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +properties: + compatible: + enum: + - qcom,prng # 8916 etc. + - qcom,prng-ee # 8996 and later using EE + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: core + +required: + - compatible + - reg + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + rng@f9bff000 { + compatible = "qcom,prng"; + reg = <0xf9bff000 0x200>; + clocks = <&clk 125>; + clock-names = "core"; + }; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml index cf5a208f2f10..343598c9f473 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml @@ -10,6 +10,9 @@ title: Amlogic specific extensions to the Synopsys Designware HDMI Controller maintainers: - Neil Armstrong <narmstrong@baylibre.com> +allOf: + - $ref: /schemas/sound/name-prefix.yaml# + description: | The Amlogic Meson Synopsys Designware Integration is composed of - A Synopsys DesignWare HDMI Controller IP @@ -99,6 +102,8 @@ properties: "#sound-dai-cells": const: 0 + sound-name-prefix: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml index 851cb0781217..047fd69e0377 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml @@ -78,6 +78,10 @@ properties: interrupts: maxItems: 1 + amlogic,canvas: + description: should point to a canvas provider node + $ref: /schemas/types.yaml#/definitions/phandle + power-domains: maxItems: 1 description: phandle to the associated power domain @@ -106,6 +110,7 @@ required: - port@1 - "#address-cells" - "#size-cells" + - amlogic,canvas additionalProperties: false @@ -118,6 +123,7 @@ examples: interrupts = <3>; #address-cells = <1>; #size-cells = <0>; + amlogic,canvas = <&canvas>; /* CVBS VDAC output port */ port@0 { diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml index 1d3e88daca04..25b5ef3f759c 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -91,22 +91,7 @@ properties: $ref: /schemas/graph.yaml#/$defs/port-base unevaluatedProperties: false description: - MIPI DSI/DPI input. - - properties: - endpoint: - $ref: /schemas/media/video-interfaces.yaml# - type: object - additionalProperties: false - - properties: - remote-endpoint: true - - bus-type: - enum: [1, 5] - default: 1 - - data-lanes: true + Video port for MIPI DSI input. port@1: $ref: /schemas/graph.yaml#/properties/port @@ -155,8 +140,6 @@ examples: reg = <0>; anx7625_in: endpoint { remote-endpoint = <&mipi_dsi>; - bus-type = <5>; - data-lanes = <0 1 2 3>; }; }; diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml index 8e13f27b28ed..bce96b5b0db0 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml @@ -7,7 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Analogix ANX7814 SlimPort (Full-HD Transmitter) maintainers: - - Enric Balletbo i Serra <enric.balletbo@collabora.com> + - Andrzej Hajda <andrzej.hajda@intel.com> + - Neil Armstrong <narmstrong@baylibre.com> + - Robert Foss <robert.foss@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/display/bridge/google,cros-ec-anx7688.yaml b/Documentation/devicetree/bindings/display/bridge/google,cros-ec-anx7688.yaml index 9f7cc6b757cb..a88a5d8c7ba5 100644 --- a/Documentation/devicetree/bindings/display/bridge/google,cros-ec-anx7688.yaml +++ b/Documentation/devicetree/bindings/display/bridge/google,cros-ec-anx7688.yaml @@ -8,7 +8,6 @@ title: ChromeOS EC ANX7688 HDMI to DP Converter through Type-C Port maintainers: - Nicolas Boichat <drinkcat@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | ChromeOS EC ANX7688 is a display bridge that converts HDMI 2.0 to diff --git a/Documentation/devicetree/bindings/display/bridge/ps8640.yaml b/Documentation/devicetree/bindings/display/bridge/ps8640.yaml index cdaf7a7a8f88..186e17be51fb 100644 --- a/Documentation/devicetree/bindings/display/bridge/ps8640.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ps8640.yaml @@ -8,7 +8,6 @@ title: MIPI DSI to eDP Video Format Converter Device Tree Bindings maintainers: - Nicolas Boichat <drinkcat@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | The PS8640 is a low power MIPI-to-eDP video format converter supporting diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml index b4ea7c92fb3d..0dca4b3d66e4 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml @@ -31,13 +31,11 @@ properties: clocks: items: - description: Display AHB clock from gcc - - description: Display AXI clock - description: Display core clock clock-names: items: - const: iface - - const: bus - const: core interrupts: @@ -160,9 +158,8 @@ examples: power-domains = <&dispcc MDSS_GDSC>; clocks = <&gcc GCC_DISP_AHB_CLK>, - <&gcc GCC_DISP_AXI_CLK>, <&dispcc DISP_CC_MDSS_MDP_CLK>; - clock-names = "iface", "bus", "core"; + clock-names = "iface", "core"; interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; interrupt-controller; diff --git a/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml index a108029ecfab..acd2f3faa6b9 100644 --- a/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml +++ b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Asia Better Technology 3.0" (320x480 pixels) 24-bit IPS LCD panel -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Paul Cercueil <paul@crapouillou.net> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml index e89c1ea62ffa..7d221ef35443 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml @@ -15,11 +15,9 @@ description: | 960 TFT source driver pins and 240 TFT gate driver pins, VCOM, VCOML and VCOMH outputs. - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml b/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml index cda36c04e85c..72788e3e6c59 100644 --- a/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml +++ b/Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Innolux EJ030NA 3.0" (320x480 pixels) 24-bit TFT LCD panel -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Paul Cercueil <paul@crapouillou.net> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.yaml b/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.yaml index 4f92365e888a..63c82a4378ff 100644 --- a/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.yaml +++ b/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.yaml @@ -35,6 +35,8 @@ properties: phandle of the gpio for power ic line Power IC supply enable, High active + port: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml index c45c92a3d41f..2a2756d19681 100644 --- a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml +++ b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: King Display KD035G6-54NT 3.5" (320x240 pixels) 24-bit TFT LCD panel -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Paul Cercueil <paul@crapouillou.net> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml index 830e335ddb53..5e4e0e552c2f 100644 --- a/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml +++ b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: LG.Philips LB035Q02 Panel -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Tomi Valkeinen <tomi.valkeinen@ti.com> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml index ef4c0a24512d..563766d283f6 100644 --- a/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml @@ -34,7 +34,7 @@ properties: description: phandle of gpio for reset line - This should be 8mA, gpio can be configured using mux, pinctrl, pinctrl-names (active high) - vddio-supply: + vddi0-supply: description: phandle of the regulator that provides the supply voltage Power IC supply @@ -75,8 +75,6 @@ examples: reset-gpios = <&tlmm 6 GPIO_ACTIVE_HIGH>; - #address-cells = <1>; - #size-cells = <0>; port { tianma_nt36672a_in_0: endpoint { remote-endpoint = <&dsi0_out>; diff --git a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml index 060ee27a4749..d525165d6d63 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Samsung LD9040 AMOLED LCD parallel RGB panel with SPI control bus -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Andrzej Hajda <a.hajda@samsung.com> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -63,8 +60,6 @@ examples: lcd@0 { compatible = "samsung,ld9040"; - #address-cells = <1>; - #size-cells = <0>; reg = <0>; vdd3-supply = <&ldo7_reg>; diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml index ea58df49263a..940f7f88526f 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: panel-common.yaml# - $ref: /schemas/leds/backlight/common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml index fa46d151e7b3..9e1d707c2ace 100644 --- a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Sitronix ST7789V RGB panel with SPI control bus -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Maxime Ripard <mripard@kernel.org> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/sony,acx565akm.yaml b/Documentation/devicetree/bindings/display/panel/sony,acx565akm.yaml index 95d053c548ab..98abdf4ddeac 100644 --- a/Documentation/devicetree/bindings/display/panel/sony,acx565akm.yaml +++ b/Documentation/devicetree/bindings/display/panel/sony,acx565akm.yaml @@ -6,15 +6,12 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Sony ACX565AKM SDI Panel -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Tomi Valkeinen <tomi.valkeinen@ti.com> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/tpo,td.yaml b/Documentation/devicetree/bindings/display/panel/tpo,td.yaml index 4aa605613445..f902a9d74141 100644 --- a/Documentation/devicetree/bindings/display/panel/tpo,td.yaml +++ b/Documentation/devicetree/bindings/display/panel/tpo,td.yaml @@ -6,16 +6,13 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Toppoly TD Panels -description: | - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml - maintainers: - Marek Belisko <marek@goldelico.com> - H. Nikolaus Schaller <hns@goldelico.com> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml index 008c144257cb..1a68a940d165 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml @@ -26,14 +26,6 @@ properties: clock-names: const: hclk - pinctrl-0: - maxItems: 2 - - pinctrl-names: - const: default - description: - Switch the iomux for the HPD/I2C pins to HDMI function. - power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index c2499a7906f5..44a29d813f14 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -83,13 +83,25 @@ properties: format: description: > Format of the framebuffer: + * `a1r5g5b5` - 16-bit pixels, d[15]=a, d[14:10]=r, d[9:5]=g, d[4:0]=b + * `a2r10g10b10` - 32-bit pixels, d[31:30]=a, d[29:20]=r, d[19:10]=g, d[9:0]=b * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r + * `a8r8g8b8` - 32-bit pixels, d[31:24]=a, d[23:16]=r, d[15:8]=g, d[7:0]=b * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b + * `r5g5b5a1` - 16-bit pixels, d[15:11]=r, d[10:6]=g, d[5:1]=b d[1:0]=a + * `r8g8b8` - 24-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b + * `x1r5g5b5` - 16-bit pixels, d[14:10]=r, d[9:5]=g, d[4:0]=b * `x2r10g10b10` - 32-bit pixels, d[29:20]=r, d[19:10]=g, d[9:0]=b * `x8r8g8b8` - 32-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b enum: + - a1r5g5b5 + - a2r10g10b10 - a8b8g8r8 + - a8r8g8b8 - r5g6b5 + - r5g5b5a1 + - r8g8b8 + - x1r5g5b5 - x2r10g10b10 - x8r8g8b8 diff --git a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml index ce1ef93cce93..54f67cb51040 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml +++ b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml @@ -110,7 +110,7 @@ examples: }; }; - panel-dsi@0 { + panel@0 { compatible = "orisetech,otm8009a"; reg = <0>; reset-gpios = <&gpioe 4 GPIO_ACTIVE_LOW>; @@ -125,4 +125,3 @@ examples: }; ... - diff --git a/Documentation/devicetree/bindings/dma/arm,pl330.yaml b/Documentation/devicetree/bindings/dma/arm,pl330.yaml new file mode 100644 index 000000000000..decab185cf4d --- /dev/null +++ b/Documentation/devicetree/bindings/dma/arm,pl330.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/arm,pl330.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM PrimeCell PL330 DMA Controller + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +description: + The ARM PrimeCell PL330 DMA controller can move blocks of memory contents + between memory and peripherals or memory to memory. + +# We need a select here so we don't match all nodes with 'arm,primecell' +select: + properties: + compatible: + contains: + const: arm,pl330 + required: + - compatible + +allOf: + - $ref: dma-controller.yaml# + - $ref: /schemas/arm/primecell.yaml# + +properties: + compatible: + items: + - enum: + - arm,pl330 + - const: arm,primecell + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 32 + description: A single combined interrupt or an interrupt per event + + '#dma-cells': + const: 1 + description: Contains the DMA request number for the consumer + + arm,pl330-broken-no-flushp: + type: boolean + description: quirk for avoiding to execute DMAFLUSHP + + arm,pl330-periph-burst: + type: boolean + description: quirk for performing burst transfer only + + dma-coherent: true + + resets: + minItems: 1 + maxItems: 2 + + reset-names: + minItems: 1 + items: + - const: dma + - const: dma-ocp + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + dma-controller@12680000 { + compatible = "arm,pl330", "arm,primecell"; + reg = <0x12680000 0x1000>; + interrupts = <99>; + #dma-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/dma/arm-pl08x.yaml b/Documentation/devicetree/bindings/dma/arm-pl08x.yaml index 3bd9eea543ca..9193b18fb75f 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl08x.yaml +++ b/Documentation/devicetree/bindings/dma/arm-pl08x.yaml @@ -10,6 +10,7 @@ maintainers: - Vinod Koul <vkoul@kernel.org> allOf: + - $ref: /schemas/arm/primecell.yaml# - $ref: "dma-controller.yaml#" # We need a select here so we don't match all nodes with 'arm,primecell' @@ -89,6 +90,9 @@ properties: - 64 description: bus width used for memcpy in bits. FTDMAC020 also accept 64 bits + resets: + maxItems: 1 + required: - reg - interrupts diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt deleted file mode 100644 index 315e90122afa..000000000000 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ /dev/null @@ -1,49 +0,0 @@ -* ARM PrimeCell PL330 DMA Controller - -The ARM PrimeCell PL330 DMA controller can move blocks of memory contents -between memory and peripherals or memory to memory. - -Required properties: - - compatible: should include both "arm,pl330" and "arm,primecell". - - reg: physical base address of the controller and length of memory mapped - region. - - interrupts: interrupt number to the cpu. - -Optional properties: - - dma-coherent : Present if dma operations are coherent - - #dma-cells: must be <1>. used to represent the number of integer - cells in the dmas property of client device. - - dma-channels: contains the total number of DMA channels supported by the DMAC - - dma-requests: contains the total number of DMA requests supported by the DMAC - - arm,pl330-broken-no-flushp: quirk for avoiding to execute DMAFLUSHP - - arm,pl330-periph-burst: quirk for performing burst transfer only - - resets: contains an entry for each entry in reset-names. - See ../reset/reset.txt for details. - - reset-names: must contain at least "dma", and optional is "dma-ocp". - -Example: - - pdma0: pdma@12680000 { - compatible = "arm,pl330", "arm,primecell"; - reg = <0x12680000 0x1000>; - interrupts = <99>; - #dma-cells = <1>; - #dma-channels = <8>; - #dma-requests = <32>; - }; - -Client drivers (device nodes requiring dma transfers from dev-to-mem or -mem-to-dev) should specify the DMA channel numbers and dma channel names -as shown below. - - [property name] = <[phandle of the dma controller] [dma request id]>; - [property name] = <[dma channel name]> - - where 'dma request id' is the dma request number which is connected - to the client controller. The 'property name' 'dmas' and 'dma-names' - as required by the generic dma device tree binding helpers. The dma - names correspond 1:1 with the dma request ids in the dmas property. - - Example: dmas = <&pdma0 12 - &pdma1 11>; - dma-names = "tx", "rx"; diff --git a/Documentation/devicetree/bindings/dma/dma-controller.yaml b/Documentation/devicetree/bindings/dma/dma-controller.yaml index 0043b91da95e..6d3727267fa8 100644 --- a/Documentation/devicetree/bindings/dma/dma-controller.yaml +++ b/Documentation/devicetree/bindings/dma/dma-controller.yaml @@ -24,10 +24,10 @@ examples: dma: dma-controller@48000000 { compatible = "ti,omap-sdma"; reg = <0x48000000 0x1000>; - interrupts = <0 12 0x4 - 0 13 0x4 - 0 14 0x4 - 0 15 0x4>; + interrupts = <0 12 0x4>, + <0 13 0x4>, + <0 14 0x4>, + <0 15 0x4>; #dma-cells = <1>; dma-channels = <32>; dma-requests = <127>; diff --git a/Documentation/devicetree/bindings/dma/ingenic,dma.yaml b/Documentation/devicetree/bindings/dma/ingenic,dma.yaml index dc059d6fd037..3b0b3b919af8 100644 --- a/Documentation/devicetree/bindings/dma/ingenic,dma.yaml +++ b/Documentation/devicetree/bindings/dma/ingenic,dma.yaml @@ -14,15 +14,23 @@ allOf: properties: compatible: - enum: - - ingenic,jz4740-dma - - ingenic,jz4725b-dma - - ingenic,jz4760-dma - - ingenic,jz4760b-dma - - ingenic,jz4770-dma - - ingenic,jz4780-dma - - ingenic,x1000-dma - - ingenic,x1830-dma + oneOf: + - enum: + - ingenic,jz4740-dma + - ingenic,jz4725b-dma + - ingenic,jz4760-dma + - ingenic,jz4760-bdma + - ingenic,jz4760-mdma + - ingenic,jz4760b-dma + - ingenic,jz4760b-bdma + - ingenic,jz4760b-mdma + - ingenic,jz4770-dma + - ingenic,jz4780-dma + - ingenic,x1000-dma + - ingenic,x1830-dma + - items: + - const: ingenic,jz4770-bdma + - const: ingenic,jz4760b-bdma reg: items: @@ -36,13 +44,19 @@ properties: maxItems: 1 "#dma-cells": - const: 2 + enum: [2, 3] description: > DMA clients must use the format described in dma.txt, giving a phandle - to the DMA controller plus the following 2 integer cells: - - - Request type: The DMA request type for transfers to/from the - device on the allocated channel, as defined in the SoC documentation. + to the DMA controller plus the following integer cells: + + - Request type: The DMA request type specifies the device endpoint that + will be the source or destination of the DMA transfer. + If "#dma-cells" is 2, the request type is a single cell, and the + direction will be unidirectional (either RX or TX but not both). + If "#dma-cells" is 3, the request type has two cells; the first + one corresponds to the host to device direction (TX), the second one + corresponds to the device to host direction (RX). The DMA channel is + then bidirectional. - Channel: If set to 0xffffffff, any available channel will be allocated for the client. Otherwise, the exact channel specified will be used. diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml index d8142cbd13d3..7c6badf39921 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml @@ -44,6 +44,10 @@ properties: - items: - const: renesas,dmac-r8a779a0 # R-Car V3U + - items: + - const: renesas,dmac-r8a779f0 # R-Car S4-8 + - const: renesas,rcar-gen4-dmac + reg: true interrupts: @@ -118,6 +122,7 @@ if: contains: enum: - renesas,dmac-r8a779a0 + - renesas,rcar-gen4-dmac then: properties: reg: diff --git a/Documentation/devicetree/bindings/dma/sifive,fu540-c000-pdma.yaml b/Documentation/devicetree/bindings/dma/sifive,fu540-c000-pdma.yaml index d32a71b975fe..75ad898c59bc 100644 --- a/Documentation/devicetree/bindings/dma/sifive,fu540-c000-pdma.yaml +++ b/Documentation/devicetree/bindings/dma/sifive,fu540-c000-pdma.yaml @@ -50,7 +50,7 @@ examples: dma@3000000 { compatible = "sifive,fu540-c000-pdma"; reg = <0x3000000 0x8000>; - interrupts = <23 24 25 26 27 28 29 30>; + interrupts = <23>, <24>, <25>, <26>, <27>, <28>, <29>, <30>; #dma-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml index 79e241498e25..4324a94b26b2 100644 --- a/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml @@ -53,6 +53,9 @@ properties: minimum: 1 maximum: 8 + resets: + maxItems: 1 + snps,dma-masters: description: | Number of AXI masters supported by the hardware. diff --git a/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml index df29d59d13a8..08627d91e607 100644 --- a/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml +++ b/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml @@ -30,6 +30,7 @@ description: | allOf: - $ref: /schemas/dma/dma-controller.yaml# + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml index ea19d12a9337..507d16d84ade 100644 --- a/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml +++ b/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml @@ -25,6 +25,7 @@ description: | allOf: - $ref: /schemas/dma/dma-controller.yaml# + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index 4c5396a9744f..6b61a8cf6137 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -87,6 +87,10 @@ properties: - items: pattern: cs1024$ - items: + pattern: c1025$ + - items: + pattern: cs1025$ + - items: pattern: c2048$ - items: pattern: cs2048$ @@ -95,18 +99,21 @@ properties: # These are special cases that don't conform to the above pattern. # Each requires a standard at24 model as fallback. - items: - - const: nxp,se97b - - const: atmel,24c02 + - enum: + - rohm,br24g01 + - rohm,br24t01 + - const: atmel,24c01 - items: - - const: onnn,cat24c04 - - const: atmel,24c04 + - enum: + - nxp,se97b + - renesas,r1ex24002 + - const: atmel,24c02 - items: - - const: onnn,cat24c05 + - enum: + - onnn,cat24c04 + - onnn,cat24c05 - const: atmel,24c04 - items: - - const: renesas,r1ex24002 - - const: atmel,24c02 - - items: - const: renesas,r1ex24016 - const: atmel,24c16 - items: @@ -115,12 +122,6 @@ properties: - items: - const: renesas,r1ex24128 - const: atmel,24c128 - - items: - - const: rohm,br24g01 - - const: atmel,24c01 - - items: - - const: rohm,br24t01 - - const: atmel,24c01 label: description: Descriptive name of the EEPROM. diff --git a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml index 20e1ccfc8630..2d82b44268db 100644 --- a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml +++ b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml @@ -8,7 +8,6 @@ title: ChromeOS EC USB Type-C cable and accessories detection maintainers: - Benson Leung <bleung@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | On ChromeOS systems with USB Type C ports, the ChromeOS Embedded Controller is diff --git a/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml new file mode 100644 index 000000000000..f9ffe3d6f957 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/extcon/maxim,max77843.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77843 MicroUSB and Companion Power Management IC Extcon + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77843 MicroUSB + Integrated Circuit (MUIC). + + See also Documentation/devicetree/bindings/mfd/maxim,max77843.yaml for + additional information and example. + +properties: + compatible: + const: maxim,max77843-muic + + connector: + $ref: /schemas/connector/usb-connector.yaml# + + ports: + $ref: /schemas/graph.yaml#/properties/port + description: + Any connector to the data bus of this controller should be modelled using + the OF graph bindings specified + properties: + port: + $ref: /schemas/graph.yaml#/properties/port + +required: + - compatible + - connector + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt deleted file mode 100644 index 5d468ecd1809..000000000000 --- a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt +++ /dev/null @@ -1,83 +0,0 @@ -Broadcom STB "UPG GIO" GPIO controller - -The controller's registers are organized as sets of eight 32-bit -registers with each set controlling a bank of up to 32 pins. A single -interrupt is shared for all of the banks handled by the controller. - -Required properties: - -- compatible: - Must be "brcm,brcmstb-gpio" - -- reg: - Define the base and range of the I/O address space containing - the brcmstb GPIO controller registers - -- #gpio-cells: - Should be <2>. The first cell is the pin number (within the controller's - pin space), and the second is used for the following: - bit[0]: polarity (0 for active-high, 1 for active-low) - -- gpio-controller: - Specifies that the node is a GPIO controller. - -- brcm,gpio-bank-widths: - Number of GPIO lines for each bank. Number of elements must - correspond to number of banks suggested by the 'reg' property. - -Optional properties: - -- interrupts: - The interrupt shared by all GPIO lines for this controller. - -- interrupts-extended: - Alternate form of specifying interrupts and parents that allows for - multiple parents. This takes precedence over 'interrupts' and - 'interrupt-parent'. Wakeup-capable GPIO controllers often route their - wakeup interrupt lines through a different interrupt controller than the - primary interrupt line, making this property necessary. - -- #interrupt-cells: - Should be <2>. The first cell is the GPIO number, the second should specify - flags. The following subset of flags is supported: - - bits[3:0] trigger type and level flags - 1 = low-to-high edge triggered - 2 = high-to-low edge triggered - 4 = active high level-sensitive - 8 = active low level-sensitive - Valid combinations are 1, 2, 3, 4, 8. - See also Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - -- interrupt-controller: - Marks the device node as an interrupt controller - -- wakeup-source: - GPIOs for this controller can be used as a wakeup source - -Example: - upg_gio: gpio@f040a700 { - #gpio-cells = <2>; - #interrupt-cells = <2>; - compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio"; - gpio-controller; - interrupt-controller; - reg = <0xf040a700 0x80>; - interrupt-parent = <&irq0_intc>; - interrupts = <0x6>; - brcm,gpio-bank-widths = <32 32 32 24>; - }; - - upg_gio_aon: gpio@f04172c0 { - #gpio-cells = <2>; - #interrupt-cells = <2>; - compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio"; - gpio-controller; - interrupt-controller; - reg = <0xf04172c0 0x40>; - interrupt-parent = <&irq0_aon_intc>; - interrupts = <0x6>; - interrupts-extended = <&irq0_aon_intc 0x6>, - <&aon_pm_l2_intc 0x5>; - wakeup-source; - brcm,gpio-bank-widths = <18 4>; - }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml new file mode 100644 index 000000000000..4a896ff7edc5 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/brcm,brcmstb-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom STB "UPG GIO" GPIO controller + +description: > + The controller's registers are organized as sets of eight 32-bit + registers with each set controlling a bank of up to 32 pins. A single + interrupt is shared for all of the banks handled by the controller. + +maintainers: + - Doug Berger <opendmb@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + items: + - enum: + - brcm,bcm7445-gpio + - const: brcm,brcmstb-gpio + + reg: + maxItems: 1 + description: > + Define the base and range of the I/O address space containing + the brcmstb GPIO controller registers + + "#gpio-cells": + const: 2 + description: > + The first cell is the pin number (within the controller's + pin space), and the second is used for the following: + bit[0]: polarity (0 for active-high, 1 for active-low) + + gpio-controller: true + + brcm,gpio-bank-widths: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: > + Number of GPIO lines for each bank. Number of elements must + correspond to number of banks suggested by the 'reg' property. + + interrupts: + maxItems: 1 + description: > + The interrupt shared by all GPIO lines for this controller. + + "#interrupt-cells": + const: 2 + description: | + The first cell is the GPIO number, the second should specify + flags. The following subset of flags is supported: + - bits[3:0] trigger type and level flags + 1 = low-to-high edge triggered + 2 = high-to-low edge triggered + 4 = active high level-sensitive + 8 = active low level-sensitive + Valid combinations are 1, 2, 3, 4, 8. + + interrupt-controller: true + + wakeup-source: + type: boolean + description: > + GPIOs for this controller can be used as a wakeup source + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - "brcm,gpio-bank-widths" + +additionalProperties: false + +examples: + - | + upg_gio: gpio@f040a700 { + #gpio-cells = <2>; + #interrupt-cells = <2>; + compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio"; + gpio-controller; + interrupt-controller; + reg = <0xf040a700 0x80>; + interrupt-parent = <&irq0_intc>; + interrupts = <0x6>; + brcm,gpio-bank-widths = <32 32 32 24>; + }; + + upg_gio_aon: gpio@f04172c0 { + #gpio-cells = <2>; + #interrupt-cells = <2>; + compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio"; + gpio-controller; + interrupt-controller; + reg = <0xf04172c0 0x40>; + interrupt-parent = <&irq0_aon_intc>; + interrupts = <0x6>; + wakeup-source; + brcm,gpio-bank-widths = <18 4>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt deleted file mode 100644 index 5375625e8cd2..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt +++ /dev/null @@ -1,41 +0,0 @@ -Samsung Exynos4 GPIO Controller - -Required properties: -- compatible: Compatible property value should be "samsung,exynos4-gpio>". - -- reg: Physical base address of the controller and length of memory mapped - region. - -- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes - should be the following with values derived from the SoC user manual. - <[phandle of the gpio controller node] - [pin number within the gpio controller] - [mux function] - [flags and pull up/down] - [drive strength]> - - Values for gpio specifier: - - Pin number: is a value between 0 to 7. - - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled. - 1 - Pull Down Enabled. - 3 - Pull Up Enabled. - Bit 16 (0x00010000) - Input is active low. - - Drive Strength: 0 - 1x, - 1 - 3x, - 2 - 2x, - 3 - 4x - -- gpio-controller: Specifies that the node is a gpio controller. -- #address-cells: should be 1. -- #size-cells: should be 1. - -Example: - - gpa0: gpio-controller@11400000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "samsung,exynos4-gpio"; - reg = <0x11400000 0x20>; - #gpio-cells = <4>; - gpio-controller; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index 19738a457a58..e1359391d3a4 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -24,6 +24,9 @@ properties: - items: - const: fsl,imx7ulp-gpio - const: fsl,vf610-gpio + - items: + - const: fsl,imx8ulp-gpio + - const: fsl,imx7ulp-gpio reg: description: The first reg tuple represents the PORT module, the second tuple diff --git a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml index fe1e1c63ffe3..18fe90387b87 100644 --- a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml @@ -14,7 +14,9 @@ properties: pattern: "^gpio@[0-9a-f]+$" compatible: - const: mstar,msc313-gpio + enum: + - mstar,msc313-gpio + - sstar,ssd20xd-gpio reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt deleted file mode 100644 index adff16c71d21..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt +++ /dev/null @@ -1,165 +0,0 @@ -NVIDIA Tegra186 GPIO controllers - -Tegra186 contains two GPIO controllers; a main controller and an "AON" -controller. This binding document applies to both controllers. The register -layouts for the controllers share many similarities, but also some significant -differences. Hence, this document describes closely related but different -bindings and compatible values. - -The Tegra186 GPIO controller allows software to set the IO direction of, and -read/write the value of, numerous GPIO signals. Routing of GPIO signals to -package balls is under the control of a separate pin controller HW block. Two -major sets of registers exist: - -a) Security registers, which allow configuration of allowed access to the GPIO -register set. These registers exist in a single contiguous block of physical -address space. The size of this block, and the security features available, -varies between the different GPIO controllers. - -Access to this set of registers is not necessary in all circumstances. Code -that wishes to configure access to the GPIO registers needs access to these -registers to do so. Code which simply wishes to read or write GPIO data does not -need access to these registers. - -b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO -controllers, these registers are exposed via multiple "physical aliases" in -address space, each of which access the same underlying state. See the hardware -documentation for rationale. Any particular GPIO client is expected to access -just one of these physical aliases. - -Tegra HW documentation describes a unified naming convention for all GPIOs -implemented by the SoC. Each GPIO is assigned to a port, and a port may control -a number of GPIOs. Thus, each GPIO is named according to an alphabetical port -name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6, -or GPIO_PCC3. - -The number of ports implemented by each GPIO controller varies. The number of -implemented GPIOs within each port varies. GPIO registers within a controller -are grouped and laid out according to the port they affect. - -The mapping from port name to the GPIO controller that implements that port, and -the mapping from port name to register offset within a controller, are both -extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h> -describes the port-level mapping. In that file, the naming convention for ports -matches the HW documentation. The values chosen for the names are alphabetically -sorted within a particular controller. Drivers need to map between the DT GPIO -IDs and HW register offsets using a lookup table. - -Each GPIO controller can generate a number of interrupt signals. Each signal -represents the aggregate status for all GPIOs within a set of ports. Thus, the -number of interrupt signals generated by a controller varies as a rough function -of the number of ports it implements. Note that the HW documentation refers to -both the overall controller HW module and the sets-of-ports as "controllers". - -Each GPIO controller in fact generates multiple interrupts signals for each set -of ports. Each GPIO may be configured to feed into a specific one of the -interrupt signals generated by a set-of-ports. The intent is for each generated -signal to be routed to a different CPU, thus allowing different CPUs to each -handle subsets of the interrupts within a port. The status of each of these -per-port-set signals is reported via a separate register. Thus, a driver needs -to know which status register to observe. This binding currently defines no -configuration mechanism for this. By default, drivers should use register -GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could -define a property to configure this. - -Required properties: -- compatible - Array of strings. - One of: - - "nvidia,tegra186-gpio". - - "nvidia,tegra186-gpio-aon". - - "nvidia,tegra194-gpio". - - "nvidia,tegra194-gpio-aon". -- reg-names - Array of strings. - Contains a list of names for the register spaces described by the reg - property. May contain the following entries, in any order: - - "gpio": Mandatory. GPIO control registers. This may cover either: - a) The single physical alias that this OS should use. - b) All physical aliases that exist in the controller. This is - appropriate when the OS is responsible for managing assignment of - the physical aliases. - - "security": Optional. Security configuration registers. - Users of this binding MUST look up entries in the reg property by name, - using this reg-names property to do so. -- reg - Array of (physical base address, length) tuples. - Must contain one entry per entry in the reg-names property, in a matching - order. -- interrupts - Array of interrupt specifiers. - The interrupt outputs from the HW block, one per set of ports, in the - order the HW manual describes them. The number of entries required varies - depending on compatible value: - - "nvidia,tegra186-gpio": 6 entries. - - "nvidia,tegra186-gpio-aon": 1 entry. - - "nvidia,tegra194-gpio": 6 entries. - - "nvidia,tegra194-gpio-aon": 1 entry. -- gpio-controller - Boolean. - Marks the device node as a GPIO controller/provider. -- #gpio-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's GPIO specifier. - In the specifier: - - The first cell is the pin number. - See <dt-bindings/gpio/tegra186-gpio.h>. - - The second cell contains flags: - - Bit 0 specifies polarity - - 0: Active-high (normal). - - 1: Active-low (inverted). -- interrupt-controller - Boolean. - Marks the device node as an interrupt controller/provider. -- #interrupt-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's interrupt specifier. - In the specifier: - - The first cell is the GPIO number. - See <dt-bindings/gpio/tegra186-gpio.h>. - - The second cell is contains flags: - - Bits [3:0] indicate trigger type and level: - - 1: Low-to-high edge triggered. - - 2: High-to-low edge triggered. - - 4: Active high level-sensitive. - - 8: Active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. - -Example: - -#include <dt-bindings/interrupt-controller/irq.h> - -gpio@2200000 { - compatible = "nvidia,tegra186-gpio"; - reg-names = "security", "gpio"; - reg = - <0x0 0x2200000 0x0 0x10000>, - <0x0 0x2210000 0x0 0x10000>; - interrupts = - <0 47 IRQ_TYPE_LEVEL_HIGH>, - <0 50 IRQ_TYPE_LEVEL_HIGH>, - <0 53 IRQ_TYPE_LEVEL_HIGH>, - <0 56 IRQ_TYPE_LEVEL_HIGH>, - <0 59 IRQ_TYPE_LEVEL_HIGH>, - <0 180 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; - -gpio@c2f0000 { - compatible = "nvidia,tegra186-gpio-aon"; - reg-names = "security", "gpio"; - reg = - <0x0 0xc2f0000 0x0 0x1000>, - <0x0 0xc2f1000 0x0 0x1000>; - interrupts = - <0 60 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml new file mode 100644 index 000000000000..4ef06b2ff1ff --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra186 and later) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + Tegra186 contains two GPIO controllers; a main controller and an "AON" + controller. This binding document applies to both controllers. The register + layouts for the controllers share many similarities, but also some + significant differences. Hence, this document describes closely related but + different bindings and compatible values. + + The Tegra186 GPIO controller allows software to set the IO direction of, + and read/write the value of, numerous GPIO signals. Routing of GPIO signals + to package balls is under the control of a separate pin controller hardware + block. Two major sets of registers exist: + + a) Security registers, which allow configuration of allowed access to the + GPIO register set. These registers exist in a single contiguous block + of physical address space. The size of this block, and the security + features available, varies between the different GPIO controllers. + + Access to this set of registers is not necessary in all circumstances. + Code that wishes to configure access to the GPIO registers needs access + to these registers to do so. Code which simply wishes to read or write + GPIO data does not need access to these registers. + + b) GPIO registers, which allow manipulation of the GPIO signals. In some + GPIO controllers, these registers are exposed via multiple "physical + aliases" in address space, each of which access the same underlying + state. See the hardware documentation for rationale. Any particular + GPIO client is expected to access just one of these physical aliases. + + Tegra HW documentation describes a unified naming convention for all GPIOs + implemented by the SoC. Each GPIO is assigned to a port, and a port may + control a number of GPIOs. Thus, each GPIO is named according to an + alphabetical port name and an integer GPIO name within the port. For + example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3. + + The number of ports implemented by each GPIO controller varies. The number + of implemented GPIOs within each port varies. GPIO registers within a + controller are grouped and laid out according to the port they affect. + + The mapping from port name to the GPIO controller that implements that + port, and the mapping from port name to register offset within a + controller, are both extremely non-linear. The header file + <dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In + that file, the naming convention for ports matches the HW documentation. + The values chosen for the names are alphabetically sorted within a + particular controller. Drivers need to map between the DT GPIO IDs and HW + register offsets using a lookup table. + + Each GPIO controller can generate a number of interrupt signals. Each + signal represents the aggregate status for all GPIOs within a set of + ports. Thus, the number of interrupt signals generated by a controller + varies as a rough function of the number of ports it implements. Note + that the HW documentation refers to both the overall controller HW + module and the sets-of-ports as "controllers". + + Each GPIO controller in fact generates multiple interrupts signals for + each set of ports. Each GPIO may be configured to feed into a specific + one of the interrupt signals generated by a set-of-ports. The intent is + for each generated signal to be routed to a different CPU, thus allowing + different CPUs to each handle subsets of the interrupts within a port. + The status of each of these per-port-set signals is reported via a + separate register. Thus, a driver needs to know which status register to + observe. This binding currently defines no configuration mechanism for + this. By default, drivers should use register + GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could + define a property to configure this. + +properties: + compatible: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio + - nvidia,tegra234-gpio-aon + + reg-names: + items: + - const: security + - const: gpio + minItems: 1 + + reg: + items: + - description: Security configuration registers. + - description: | + GPIO control registers. This may cover either: + + a) The single physical alias that this OS should use. + b) All physical aliases that exist in the controller. This is + appropriate when the OS is responsible for managing assignment + of the physical aliases. + minItems: 1 + + interrupts: + description: The interrupt outputs from the HW block, one per set of + ports, in the order the HW manual describes them. The number of entries + required varies depending on compatible value. + + gpio-controller: true + + "#gpio-cells": + description: | + Indicates how many cells are used in a consumer's GPIO specifier. In the + specifier: + + - The first cell is the pin number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell contains flags: + - Bit 0 specifies polarity + - 0: Active-high (normal). + - 1: Active-low (inverted). + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + description: | + Indicates how many cells are used in a consumer's interrupt specifier. + In the specifier: + + - The first cell is the GPIO number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell is contains flags: + - Bits [3:0] indicate trigger type and level: + - 1: Low-to-high edge triggered. + - 2: High-to-low edge triggered. + - 4: Active high level-sensitive. + - 8: Active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + +allOf: + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra194-gpio + - nvidia,tegra234-gpio + then: + properties: + interrupts: + minItems: 6 + maxItems: 48 + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio-aon + then: + properties: + interrupts: + minItems: 1 + maxItems: 4 + +required: + - compatible + - reg + - reg-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + gpio@2200000 { + compatible = "nvidia,tegra186-gpio"; + reg-names = "security", "gpio"; + reg = <0x2200000 0x10000>, + <0x2210000 0x10000>; + interrupts = <0 47 IRQ_TYPE_LEVEL_HIGH>, + <0 50 IRQ_TYPE_LEVEL_HIGH>, + <0 53 IRQ_TYPE_LEVEL_HIGH>, + <0 56 IRQ_TYPE_LEVEL_HIGH>, + <0 59 IRQ_TYPE_LEVEL_HIGH>, + <0 180 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + gpio@c2f0000 { + compatible = "nvidia,tegra186-gpio-aon"; + reg-names = "security", "gpio"; + reg = <0xc2f0000 0x1000>, + <0xc2f1000 0x1000>; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt deleted file mode 100644 index 023c9526e5f8..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra GPIO controller - -Required properties: -- compatible : "nvidia,tegra<chip>-gpio" -- reg : Physical base address and length of the controller's registers. -- interrupts : The interrupt outputs from the controller. For Tegra20, - there should be 7 interrupts specified, and for Tegra30, there should - be 8 interrupts specified. -- #gpio-cells : Should be two. The first cell is the pin number and the - second cell is used to specify optional parameters: - - bit 0 specifies polarity (0 for normal, 1 for inverted) -- gpio-controller : Marks the device node as a GPIO controller. -- #interrupt-cells : Should be 2. - The first cell is the GPIO number. - The second cell is used to specify flags: - bits[3:0] trigger type and level flags: - 1 = low-to-high edge triggered. - 2 = high-to-low edge triggered. - 4 = active high level-sensitive. - 8 = active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. -- interrupt-controller : Marks the device node as an interrupt controller. - -Example: - -gpio: gpio@6000d000 { - compatible = "nvidia,tegra20-gpio"; - reg = < 0x6000d000 0x1000 >; - interrupts = < 0 32 0x04 - 0 33 0x04 - 0 34 0x04 - 0 35 0x04 - 0 55 0x04 - 0 87 0x04 - 0 89 0x04 >; - #gpio-cells = <2>; - gpio-controller; - #interrupt-cells = <2>; - interrupt-controller; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml new file mode 100644 index 000000000000..94b51749ee76 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra20-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra20 - Tegra210) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-gpio + - nvidia,tegra30-gpio + + - items: + - enum: + - nvidia,tegra114-gpio + - nvidia,tegra124-gpio + - nvidia,tegra210-gpio + - const: nvidia,tegra30-gpio + + reg: + maxItems: 1 + + interrupts: + description: The interrupt outputs from the controller. For Tegra20, + there should be 7 interrupts specified, and for Tegra30, there should + be 8 interrupts specified. + + "#gpio-cells": + description: The first cell is the pin number and the second cell is used + to specify the GPIO polarity (0 = active high, 1 = active low). + const: 2 + + gpio-controller: true + + gpio-ranges: + maxItems: 1 + + "#interrupt-cells": + description: | + Should be 2. The first cell is the GPIO number. The second cell is + used to specify flags: + + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + + interrupt-controller: true + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra30-gpio + then: + properties: + interrupts: + minItems: 8 + maxItems: 8 + else: + properties: + interrupts: + minItems: 7 + maxItems: 7 + +required: + - compatible + - reg + - interrupts + - "#gpio-cells" + - gpio-controller + - "#interrupt-cells" + - interrupt-controller + +additionalProperties: + type: object + required: + - gpio-hog + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + gpio: gpio@6000d000 { + compatible = "nvidia,tegra20-gpio"; + reg = <0x6000d000 0x1000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; + #gpio-cells = <2>; + gpio-controller; + #interrupt-cells = <2>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml index c2902aac2514..427c5873f96a 100644 --- a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml @@ -7,7 +7,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SiFive GPIO controller maintainers: - - Yash Shah <yash.shah@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> properties: @@ -77,7 +76,8 @@ examples: gpio@10060000 { compatible = "sifive,fu540-c000-gpio", "sifive,gpio0"; interrupt-parent = <&plic>; - interrupts = <7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22>; + interrupts = <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>, <15>, <16>, + <17>, <18>, <19>, <20>, <21>, <22>; reg = <0x10060000 0x1000>; clocks = <&tlclk PRCI_CLK_TLCLK>; gpio-controller; diff --git a/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml b/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml index 9ad470e01953..b085450b527f 100644 --- a/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml +++ b/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml @@ -43,7 +43,6 @@ required: - gpio-controller - interrupt-controller - "#interrupt-cells" - - interrupt-parent additionalProperties: false diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index 6f98dd55fb4c..63a08f3f321d 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -19,6 +19,7 @@ properties: - amlogic,meson-g12a-mali - mediatek,mt8183-mali - realtek,rtd1619-mali + - renesas,r9a07g044-mali - rockchip,px30-mali - rockchip,rk3568-mali - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable @@ -27,19 +28,26 @@ properties: maxItems: 1 interrupts: + minItems: 3 items: - description: Job interrupt - description: MMU interrupt - description: GPU interrupt + - description: Event interrupt interrupt-names: + minItems: 3 items: - const: job - const: mmu - const: gpu + - const: event clocks: - maxItems: 1 + minItems: 1 + maxItems: 3 + + clock-names: true mali-supply: true @@ -52,7 +60,10 @@ properties: maxItems: 3 resets: - maxItems: 2 + minItems: 1 + maxItems: 3 + + reset-names: true "#cooling-cells": const: 2 @@ -98,6 +109,36 @@ allOf: properties: compatible: contains: + const: renesas,r9a07g044-mali + then: + properties: + interrupts: + minItems: 4 + interrupt-names: + minItems: 4 + clocks: + minItems: 3 + clock-names: + items: + - const: gpu + - const: bus + - const: bus_ace + resets: + minItems: 3 + reset-names: + items: + - const: rst + - const: axi_rst + - const: ace_rst + required: + - clock-names + - power-domains + - resets + - reset-names + - if: + properties: + compatible: + contains: const: mediatek,mt8183-mali then: properties: diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml index 223393d7cafd..ab87f51c5aef 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml @@ -37,6 +37,72 @@ properties: 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. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8, 16, 32, 64, 128] + + adi,power-sample-average: + description: | + Number of samples to be used to report power values. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8, 16, 32, 64, 128] + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,adm1075 + - adi,adm1276 + then: + properties: + adi,volt-curr-sample-average: + default: 128 + adi,power-sample-average: false + + - if: + properties: + compatible: + contains: + enum: + - adi,adm1275 + then: + properties: + adi,volt-curr-sample-average: + default: 16 + adi,power-sample-average: false + + - if: + properties: + compatible: + contains: + enum: + - adi,adm1272 + then: + properties: + adi,volt-curr-sample-average: + default: 128 + adi,power-sample-average: + default: 128 + + - if: + properties: + compatible: + contains: + enum: + - adi,adm1278 + - adi,adm1293 + - adi,adm1294 + then: + properties: + adi,volt-curr-sample-average: + default: 128 + adi,power-sample-average: + default: 1 + required: - compatible - reg @@ -53,5 +119,7 @@ examples: compatible = "adi,adm1272"; reg = <0x10>; shunt-resistor-micro-ohms = <500>; + adi,volt-curr-sample-average = <128>; + adi,power-sample-average = <128>; }; }; diff --git a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml index 6e1d54ff5d5b..30db92977937 100644 --- a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml +++ b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml @@ -60,7 +60,6 @@ additionalProperties: false examples: - | - #include <dt-bindings/gpio/tegra-gpio.h> #include <dt-bindings/interrupt-controller/irq.h> i2c { @@ -71,8 +70,7 @@ examples: compatible = "onnn,nct1008"; reg = <0x4c>; vcc-supply = <&palmas_ldo6_reg>; - interrupt-parent = <&gpio>; - interrupts = <TEGRA_GPIO(O, 4) IRQ_TYPE_LEVEL_LOW>; + interrupts = <4 IRQ_TYPE_LEVEL_LOW>; #thermal-sensor-cells = <1>; }; }; diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml index 9e77cee07dbc..3d3b139a91a2 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml +++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml @@ -76,6 +76,7 @@ properties: - const: murata,ncp15wl333 - const: murata,ncp03wf104 - const: murata,ncp15xh103 + - const: samsung,1404-001221 # Deprecated "ntp," compatible strings - const: ntc,ncp15wb473 deprecated: true diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 6f0443322a36..47af97bb4ced 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -26,6 +26,7 @@ properties: - ti,ina226 - ti,ina230 - ti,ina231 + - ti,ina238 reg: maxItems: 1 @@ -35,6 +36,27 @@ properties: Shunt resistor value in micro-Ohm. $ref: /schemas/types.yaml#/definitions/uint32 + ti,shunt-gain: + description: | + Programmable gain divisor for the shunt voltage accuracy and range. This + property only applies to devices that have configurable PGA/ADCRANGE. The + gain value is used configure the gain and to convert the shunt voltage, + current and power register values when reading measurements from the + device. + + For devices that have a configurable PGA (e.g. INA209, INA219, INA220), + the gain value maps directly with the PG bits of the config register. + + For devices that have ADCRANGE configuration (e.g. INA238) a shunt-gain + value of 1 maps to ADCRANGE=1 where no gain divisor is applied to the + shunt voltage, and a value of 4 maps to ADCRANGE=0 such that a wider + voltage range is used. + + The default value is device dependent, and is defined by the reset value + of PGA/ADCRANGE in the respective configuration registers. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml new file mode 100644 index 000000000000..801ca9ba7d34 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/ti,tmp464.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TMP464 and TMP468 temperature sensors + +maintainers: + - Agathe Porte <agathe.porte@nokia.com> + +description: | + ±0.0625°C Remote and Local temperature sensor + https://www.ti.com/lit/ds/symlink/tmp464.pdf + https://www.ti.com/lit/ds/symlink/tmp468.pdf + +properties: + compatible: + enum: + - ti,tmp464 + - ti,tmp468 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + "^channel@([0-8])$": + type: object + description: | + Represents channels of the device and their specific configuration. + + properties: + reg: + description: | + The channel number. 0 is local channel, 1-8 are remote channels. + items: + minimum: 0 + maximum: 8 + + label: + description: | + A descriptive name for this channel, like "ambient" or "psu". + + ti,n-factor: + description: | + The value (two's complement) to be programmed in the channel specific N correction register. + For remote channels only. + $ref: /schemas/types.yaml#/definitions/int32 + items: + minimum: -128 + maximum: 127 + + required: + - reg + + additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@4b { + compatible = "ti,tmp464"; + reg = <0x4b>; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@4b { + compatible = "ti,tmp464"; + reg = <0x4b>; + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0x0>; + label = "local"; + }; + + channel@1 { + reg = <0x1>; + ti,n-factor = <(-10)>; + label = "external"; + }; + + channel@2 { + reg = <0x2>; + ti,n-factor = <0x10>; + label = "somelabel"; + }; + + channel@3 { + reg = <0x3>; + status = "disabled"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml b/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml index ea643e6c3ef5..f597f73ccd87 100644 --- a/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml @@ -63,7 +63,6 @@ examples: i2c0: i2c-bus@40 { #address-cells = <1>; #size-cells = <0>; - #interrupt-cells = <1>; compatible = "aspeed,ast2500-i2c-bus"; reg = <0x40 0x40>; clocks = <&syscon ASPEED_CLK_APB>; diff --git a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt deleted file mode 100644 index a8a35df41951..000000000000 --- a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt +++ /dev/null @@ -1,22 +0,0 @@ -Broadcom BCM2835 I2C controller - -Required properties: -- compatible : Should be one of: - "brcm,bcm2711-i2c" - "brcm,bcm2835-i2c" -- reg: Should contain register location and length. -- interrupts: Should contain interrupt. -- clocks : The clock feeding the I2C controller. - -Recommended properties: -- clock-frequency : desired I2C bus clock frequency in Hz. - -Example: - -i2c@7e205000 { - compatible = "brcm,bcm2835-i2c"; - reg = <0x7e205000 0x1000>; - interrupts = <2 21>; - clocks = <&clk_i2c>; - clock-frequency = <100000>; -}; diff --git a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml new file mode 100644 index 000000000000..8256490a7af2 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/brcm,bcm2835-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM2835 I2C controller + +maintainers: + - Stephen Warren <swarren@wwwdotorg.org> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + oneOf: + - enum: + - brcm,bcm2835-i2c + - items: + - const: brcm,bcm2711-i2c + - const: brcm,bcm2835-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-names: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-frequency: true + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + i2c@7e205000 { + compatible = "brcm,bcm2835-i2c"; + reg = <0x7e205000 0x1000>; + interrupts = <2 21>; + clocks = <&clk_i2c>; + clock-frequency = <100000>; + }; diff --git a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml index b386e4128a79..6e1c70e9275e 100644 --- a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml +++ b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml @@ -10,7 +10,6 @@ title: I2C bus that tunnels through the ChromeOS EC (cros-ec) maintainers: - Doug Anderson <dianders@chromium.org> - Benson Leung <bleung@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | On some ChromeOS board designs we've got a connection to the EC diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt b/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt deleted file mode 100644 index 2dbc0b62daa6..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Samsung's High Speed I2C controller - -The Samsung's High Speed I2C controller is used to interface with I2C devices -at various speeds ranging from 100khz to 3.4Mhz. - -Required properties: - - compatible: value should be. - -> "samsung,exynos5-hsi2c", (DEPRECATED) - for i2c compatible with HSI2C available - on Exynos5250 and Exynos5420 SoCs. - -> "samsung,exynos5250-hsi2c", for i2c compatible with HSI2C available - on Exynos5250 and Exynos5420 SoCs. - -> "samsung,exynos5260-hsi2c", for i2c compatible with HSI2C available - on Exynos5260 SoCs. - -> "samsung,exynos7-hsi2c", for i2c compatible with HSI2C available - on Exynos7 SoCs. - - - reg: physical base address of the controller and length of memory mapped - region. - - interrupts: interrupt number to the cpu. - - #address-cells: always 1 (for i2c addresses) - - #size-cells: always 0 - - - Pinctrl: - - pinctrl-0: Pin control group to be used for this controller. - - pinctrl-names: Should contain only one value - "default". - -Optional properties: - - clock-frequency: Desired operating frequency in Hz of the bus. - -> If not specified, the bus operates in fast-speed mode at - at 100khz. - -> If specified, the bus operates in high-speed mode only if the - clock-frequency is >= 1Mhz. - -Example: - -hsi2c@12ca0000 { - compatible = "samsung,exynos5250-hsi2c"; - reg = <0x12ca0000 0x100>; - interrupts = <56>; - clock-frequency = <100000>; - - pinctrl-0 = <&i2c4_bus>; - pinctrl-names = "default"; - - #address-cells = <1>; - #size-cells = <0>; - - s2mps11_pmic@66 { - compatible = "samsung,s2mps11-pmic"; - reg = <0x66>; - }; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml new file mode 100644 index 000000000000..19874e8b73b9 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-exynos5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung's High Speed I2C controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + The Samsung's High Speed I2C controller is used to interface with I2C devices + at various speeds ranging from 100kHz to 3.4MHz. + + In case the HSI2C controller is encapsulated within USI block (it's the case + e.g. for Exynos850 and Exynos Auto V9 SoCs), it might be also necessary to + define USI node in device tree file, choosing "i2c" configuration. Please see + Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml for details. + +properties: + compatible: + oneOf: + - enum: + - samsung,exynos5250-hsi2c # Exynos5250 and Exynos5420 + - samsung,exynos5260-hsi2c # Exynos5260 + - samsung,exynos7-hsi2c # Exynos7 + - samsung,exynosautov9-hsi2c # ExynosAutoV9 and Exynos850 + - const: samsung,exynos5-hsi2c # Exynos5250 and Exynos5420 + deprecated: true + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-frequency: + default: 100000 + description: + Desired operating frequency in Hz of the bus. + + If not specified, the bus operates in fast-speed mode at 100kHz. + + If specified, the bus operates in high-speed mode only if the + clock-frequency is >= 1MHz. + + clocks: + minItems: 1 + items: + - description: I2C operating clock + - description: Bus clock (APB) + + clock-names: + minItems: 1 + items: + - const: hsi2c + - const: hsi2c_pclk + +required: + - compatible + - reg + - interrupts + - clocks + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - if: + properties: + compatible: + contains: + enum: + - samsung,exynosautov9-hsi2c + + then: + properties: + clocks: + minItems: 2 + + clock-names: + minItems: 2 + + required: + - clock-names + + else: + properties: + clocks: + maxItems: 1 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5420.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + hsi2c_8: i2c@12e00000 { + compatible = "samsung,exynos5250-hsi2c"; + reg = <0x12e00000 0x1000>; + interrupts = <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clock-frequency = <100000>; + clocks = <&clock CLK_USI4>; + clock-names = "hsi2c"; + + pmic@66 { + /* compatible = "samsung,s2mps11-pmic"; */ + reg = <0x66>; + }; + }; + + - | + #include <dt-bindings/clock/exynos850.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + hsi2c_2: i2c@138c0000 { + compatible = "samsung,exynosautov9-hsi2c"; + reg = <0x138c0000 0xc0>; + interrupts = <GIC_SPI 195 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cmu_peri CLK_GOUT_HSI2C2_IPCLK>, + <&cmu_peri CLK_GOUT_HSI2C2_PCLK>; + clock-names = "hsi2c", "hsi2c_pclk"; + + pmic@66 { + /* compatible = "samsung,s2mps11-pmic"; */ + reg = <0x66>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-gate.yaml b/Documentation/devicetree/bindings/i2c/i2c-gate.yaml index 66472f12a7e2..bd67b0766599 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-gate.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-gate.yaml @@ -31,7 +31,7 @@ examples: #address-cells = <1>; #size-cells = <0>; ak8975@c { - compatible = "ak,ak8975"; + compatible = "asahi-kasei,ak8975"; reg = <0x0c>; }; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml index fe0c89edf7c1..529bea56d324 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml @@ -20,7 +20,9 @@ properties: - items: - enum: - fsl,imx8qxp-lpi2c + - fsl,imx8dxl-lpi2c - fsl,imx8qm-lpi2c + - fsl,imx8ulp-lpi2c - const: fsl,imx7ulp-lpi2c reg: diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt deleted file mode 100644 index d4cf10582a26..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt +++ /dev/null @@ -1,80 +0,0 @@ -GPIO-based I2C Bus Mux - -This binding describes an I2C bus multiplexer that uses GPIOs to -route the I2C signals. - - +-----+ +-----+ - | dev | | dev | - +------------+ +-----+ +-----+ - | SoC | | | - | | /--------+--------+ - | +------+ | +------+ child bus A, on GPIO value set to 0 - | | I2C |-|--| Mux | - | +------+ | +--+---+ child bus B, on GPIO value set to 1 - | | | \----------+--------+--------+ - | +------+ | | | | | - | | GPIO |-|-----+ +-----+ +-----+ +-----+ - | +------+ | | dev | | dev | | dev | - +------------+ +-----+ +-----+ +-----+ - -Required properties: -- compatible: i2c-mux-gpio -- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side - port is connected to. -- mux-gpios: list of gpios used to control the muxer -* Standard I2C mux properties. See i2c-mux.yaml in this directory. -* I2C child bus nodes. See i2c-mux.yaml in this directory. - -Optional properties: -- idle-state: value to set the muxer to when idle. When no value is - given, it defaults to the last value used. - -For each i2c child node, an I2C child bus will be created. They will -be numbered based on their order in the device tree. - -Whenever an access is made to a device on a child bus, the value set -in the relevant node's reg property will be output using the list of -GPIOs, the first in the list holding the least-significant value. - -If an idle state is defined, using the idle-state (optional) property, -whenever an access is not being made to a device on a child bus, the -GPIOs will be set according to the idle value. - -If an idle state is not defined, the most recently used value will be -left programmed into hardware whenever no access is being made to a -device on a child bus. - -Example: - i2cmux { - compatible = "i2c-mux-gpio"; - #address-cells = <1>; - #size-cells = <0>; - mux-gpios = <&gpio1 22 0 &gpio1 23 0>; - i2c-parent = <&i2c1>; - - i2c@1 { - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - - ssd1307: oled@3c { - compatible = "solomon,ssd1307fb-i2c"; - reg = <0x3c>; - pwms = <&pwm 4 3000>; - reset-gpios = <&gpio2 7 1>; - }; - }; - - i2c@3 { - reg = <3>; - #address-cells = <1>; - #size-cells = <0>; - - pca9555: pca9555@20 { - compatible = "nxp,pca9555"; - gpio-controller; - #gpio-cells = <2>; - reg = <0x20>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml new file mode 100644 index 000000000000..6e0a5686af04 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-mux-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO-based I2C Bus Mux + +maintainers: + - Wolfram Sang <wsa@kernel.org> + +description: | + This binding describes an I2C bus multiplexer that uses GPIOs to route the I2C signals. + + +-----+ +-----+ + | dev | | dev | + +------------+ +-----+ +-----+ + | SoC | | | + | | /--------+--------+ + | +------+ | +------+ child bus A, on GPIO value set to 0 + | | I2C |-|--| Mux | + | +------+ | +--+---+ child bus B, on GPIO value set to 1 + | | | \----------+--------+--------+ + | +------+ | | | | | + | | GPIO |-|-----+ +-----+ +-----+ +-----+ + | +------+ | | dev | | dev | | dev | + +------------+ +-----+ +-----+ +-----+ + + For each I2C child node, an I2C child bus will be created. They will be numbered based on their + order in the device tree. + + Whenever an access is made to a device on a child bus, the value set in the relevant node's reg + property will be output using the list of GPIOs, the first in the list holding the least- + significant value. + + If an idle state is defined, using the idle-state (optional) property, whenever an access is not + being made to a device on a child bus, the GPIOs will be set according to the idle value. + + If an idle state is not defined, the most recently used value will be left programmed into + hardware whenever no access is being made to a device on a child bus. + +properties: + compatible: + const: i2c-mux-gpio + + i2c-parent: + description: phandle of the I2C bus that this multiplexer's master-side port is connected to + $ref: "/schemas/types.yaml#/definitions/phandle" + + mux-gpios: + description: list of GPIOs used to control the muxer + minItems: 1 + maxItems: 4 # Should be enough + + idle-state: + description: Value to set the muxer to when idle. When no value is given, it defaults to the + last value used. + $ref: "/schemas/types.yaml#/definitions/uint32" + +allOf: + - $ref: i2c-mux.yaml + +unevaluatedProperties: false + +required: + - compatible + - i2c-parent + - mux-gpios + +examples: + - | + i2cmux { + compatible = "i2c-mux-gpio"; + #address-cells = <1>; + #size-cells = <0>; + mux-gpios = <&gpio1 22 0>, <&gpio1 23 0>; + i2c-parent = <&i2c1>; + + i2c@1 { + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + ssd1307: oled@3c { + compatible = "solomon,ssd1307fb-i2c"; + reg = <0x3c>; + pwms = <&pwm 4 3000>; + reset-gpios = <&gpio2 7 1>; + }; + }; + + i2c@3 { + reg = <3>; + #address-cells = <1>; + #size-cells = <0>; + + pca9555: pca9555@20 { + compatible = "nxp,pca9555"; + gpio-controller; + #gpio-cells = <2>; + reg = <0x20>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt deleted file mode 100644 index 997a287ed3f6..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt +++ /dev/null @@ -1,93 +0,0 @@ -Pinctrl-based I2C Bus Mux - -This binding describes an I2C bus multiplexer that uses pin multiplexing to -route the I2C signals, and represents the pin multiplexing configuration -using the pinctrl device tree bindings. - - +-----+ +-----+ - | dev | | dev | - +------------------------+ +-----+ +-----+ - | SoC | | | - | /----|------+--------+ - | +---+ +------+ | child bus A, on first set of pins - | |I2C|---|Pinmux| | - | +---+ +------+ | child bus B, on second set of pins - | \----|------+--------+--------+ - | | | | | - +------------------------+ +-----+ +-----+ +-----+ - | dev | | dev | | dev | - +-----+ +-----+ +-----+ - -Required properties: -- compatible: i2c-mux-pinctrl -- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side - port is connected to. - -Also required are: - -* Standard pinctrl properties that specify the pin mux state for each child - bus. See ../pinctrl/pinctrl-bindings.txt. - -* Standard I2C mux properties. See i2c-mux.yaml in this directory. - -* I2C child bus nodes. See i2c-mux.yaml in this directory. - -For each named state defined in the pinctrl-names property, an I2C child bus -will be created. I2C child bus numbers are assigned based on the index into -the pinctrl-names property. - -The only exception is that no bus will be created for a state named "idle". If -such a state is defined, it must be the last entry in pinctrl-names. For -example: - - pinctrl-names = "ddc", "pta", "idle" -> ddc = bus 0, pta = bus 1 - pinctrl-names = "ddc", "idle", "pta" -> Invalid ("idle" not last) - pinctrl-names = "idle", "ddc", "pta" -> Invalid ("idle" not last) - -Whenever an access is made to a device on a child bus, the relevant pinctrl -state will be programmed into hardware. - -If an idle state is defined, whenever an access is not being made to a device -on a child bus, the idle pinctrl state will be programmed into hardware. - -If an idle state is not defined, the most recently used pinctrl state will be -left programmed into hardware whenever no access is being made of a device on -a child bus. - -Example: - - i2cmux { - compatible = "i2c-mux-pinctrl"; - #address-cells = <1>; - #size-cells = <0>; - - i2c-parent = <&i2c1>; - - pinctrl-names = "ddc", "pta", "idle"; - pinctrl-0 = <&state_i2cmux_ddc>; - pinctrl-1 = <&state_i2cmux_pta>; - pinctrl-2 = <&state_i2cmux_idle>; - - i2c@0 { - reg = <0>; - #address-cells = <1>; - #size-cells = <0>; - - eeprom { - compatible = "eeprom"; - reg = <0x50>; - }; - }; - - i2c@1 { - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - - eeprom { - compatible = "eeprom"; - reg = <0x50>; - }; - }; - }; - diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml new file mode 100644 index 000000000000..2e3d555eb96c --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-mux-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pinctrl-based I2C Bus Mux + +maintainers: + - Wolfram Sang <wsa@kernel.org> + +description: | + This binding describes an I2C bus multiplexer that uses pin multiplexing to route the I2C + signals, and represents the pin multiplexing configuration using the pinctrl device tree + bindings. + + +-----+ +-----+ + | dev | | dev | + +------------------------+ +-----+ +-----+ + | SoC | | | + | /----|------+--------+ + | +---+ +------+ | child bus A, on first set of pins + | |I2C|---|Pinmux| | + | +---+ +------+ | child bus B, on second set of pins + | \----|------+--------+--------+ + | | | | | + +------------------------+ +-----+ +-----+ +-----+ + | dev | | dev | | dev | + +-----+ +-----+ +-----+ + + For each named state defined in the pinctrl-names property, an I2C child bus will be created. + I2C child bus numbers are assigned based on the index into the pinctrl-names property. + + The only exception is that no bus will be created for a state named "idle". If such a state is + defined, it must be the last entry in pinctrl-names. For example: + + pinctrl-names = "ddc", "pta", "idle" -> ddc = bus 0, pta = bus 1 + pinctrl-names = "ddc", "idle", "pta" -> Invalid ("idle" not last) + pinctrl-names = "idle", "ddc", "pta" -> Invalid ("idle" not last) + + Whenever an access is made to a device on a child bus, the relevant pinctrl state will be + programmed into hardware. + + If an idle state is defined, whenever an access is not being made to a device on a child bus, + the idle pinctrl state will be programmed into hardware. + + If an idle state is not defined, the most recently used pinctrl state will be left programmed + into hardware whenever no access is being made of a device on a child bus. + +properties: + compatible: + const: i2c-mux-pinctrl + + i2c-parent: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the I2C bus that this multiplexer's master-side port is connected + to. + +allOf: + - $ref: i2c-mux.yaml + +unevaluatedProperties: false + +required: + - compatible + - i2c-parent + +examples: + - | + i2cmux { + compatible = "i2c-mux-pinctrl"; + #address-cells = <1>; + #size-cells = <0>; + + i2c-parent = <&i2c1>; + + pinctrl-names = "ddc", "pta", "idle"; + pinctrl-0 = <&state_i2cmux_ddc>; + pinctrl-1 = <&state_i2cmux_pta>; + pinctrl-2 = <&state_i2cmux_idle>; + + i2c@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + eeprom@50 { + compatible = "atmel,24c02"; + reg = <0x50>; + }; + }; + + i2c@1 { + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + eeprom@50 { + compatible = "atmel,24c02"; + reg = <0x50>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt deleted file mode 100644 index ab240e10debc..000000000000 --- a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt +++ /dev/null @@ -1,42 +0,0 @@ -NVIDIA Tegra186 BPMP I2C controller - -In Tegra186, the BPMP (Boot and Power Management Processor) owns certain HW -devices, such as the I2C controller for the power management I2C bus. Software -running on other CPUs must perform IPC to the BPMP in order to execute -transactions on that I2C bus. This binding describes an I2C bus that is -accessed in such a fashion. - -The BPMP I2C node must be located directly inside the main BPMP node. See -../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding. - -This node represents an I2C controller. See ../i2c/i2c.txt for details of the -core I2C binding. - -Required properties: -- compatible: - Array of strings. - One of: - - "nvidia,tegra186-bpmp-i2c". -- #address-cells: Address cells for I2C device address. - Single-cell integer. - Must be <1>. -- #size-cells: - Single-cell integer. - Must be <0>. -- nvidia,bpmp-bus-id: - Single-cell integer. - Indicates the I2C bus number this DT node represent, as defined by the - BPMP firmware. - -Example: - -bpmp { - ... - - i2c { - compatible = "nvidia,tegra186-bpmp-i2c"; - #address-cells = <1>; - #size-cells = <0>; - nvidia,bpmp-bus-id = <5>; - }; -}; diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml new file mode 100644 index 000000000000..b8319dcf3d8a --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/nvidia,tegra186-bpmp-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 (and later) BPMP I2C controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + In Tegra186 and later, the BPMP (Boot and Power Management Processor) + owns certain HW devices, such as the I2C controller for the power + management I2C bus. Software running on other CPUs must perform IPC to + the BPMP in order to execute transactions on that I2C bus. This + binding describes an I2C bus that is accessed in such a fashion. + + The BPMP I2C node must be located directly inside the main BPMP node. + See ../firmware/nvidia,tegra186-bpmp.yaml for details of the BPMP + binding. + + This node represents an I2C controller. See ../i2c/i2c.txt for details + of the core I2C binding. + +properties: + compatible: + const: nvidia,tegra186-bpmp-i2c + + nvidia,bpmp-bus-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Indicates the I2C bus number this DT node represents, + as defined by the BPMP firmware. + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml + +unevaluatedProperties: false + +required: + - compatible + - "#address-cells" + - "#size-cells" + - nvidia,bpmp-bus-id diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt deleted file mode 100644 index 3f2f990c2e62..000000000000 --- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt +++ /dev/null @@ -1,87 +0,0 @@ -NVIDIA Tegra20/Tegra30/Tegra114 I2C controller driver. - -Required properties: -- compatible : For Tegra20, must be one of "nvidia,tegra20-i2c-dvc" or - "nvidia,tegra20-i2c". For Tegra30, must be "nvidia,tegra30-i2c". - For Tegra114, must be "nvidia,tegra114-i2c". Otherwise, must be - "nvidia,<chip>-i2c", plus at least one of the above, where <chip> is - tegra124, tegra132, or tegra210. - Details of compatible are as follows: - nvidia,tegra20-i2c-dvc: Tegra20 has specific I2C controller called as DVC I2C - controller. This only support master mode of I2C communication. Register - interface/offset and interrupts handling are different than generic I2C - controller. Driver of DVC I2C controller is only compatible with - "nvidia,tegra20-i2c-dvc". - nvidia,tegra20-i2c: Tegra20 has 4 generic I2C controller. This can support - master and slave mode of I2C communication. The i2c-tegra driver only - support master mode of I2C communication. Driver of I2C controller is - only compatible with "nvidia,tegra20-i2c". - nvidia,tegra30-i2c: Tegra30 has 5 generic I2C controller. This controller is - very much similar to Tegra20 I2C controller with additional feature: - Continue Transfer Support. This feature helps to implement M_NO_START - as per I2C core API transfer flags. Driver of I2C controller is - compatible with "nvidia,tegra30-i2c" to enable the continue transfer - support. This is also compatible with "nvidia,tegra20-i2c" without - continue transfer support. - nvidia,tegra114-i2c: Tegra114 has 5 generic I2C controller. This controller is - very much similar to Tegra30 I2C controller with some hardware - modification: - - Tegra30/Tegra20 I2C controller has 2 clock source called div-clk and - fast-clk. Tegra114 has only one clock source called as div-clk and - hence clock mechanism is changed in I2C controller. - - Tegra30/Tegra20 I2C controller has enabled per packet transfer by - default and there is no way to disable it. Tegra114 has this - interrupt disable by default and SW need to enable explicitly. - Due to above changes, Tegra114 I2C driver makes incompatible with - previous hardware driver. Hence, tegra114 I2C controller is compatible - with "nvidia,tegra114-i2c". - nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is on host1x bus - and is part of VE power domain and typically used for camera use-cases. - This VI I2C controller is mostly compatible with the programming model - of the regular I2C controllers with a few exceptions. The I2C registers - start at an offset of 0xc00 (instead of 0), registers are 16 bytes - apart (rather than 4) and the controller does not support slave mode. -- reg: Should contain I2C controller registers physical address and length. -- interrupts: Should contain I2C controller interrupts. -- address-cells: Address cells for I2C device address. -- size-cells: Size of the I2C device address. -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - Tegra20/Tegra30: - - div-clk - - fast-clk - Tegra114: - - div-clk - Tegra210: - - div-clk - - slow (only for nvidia,tegra210-i2c-vi compatible node) -- resets: Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following entries: - - i2c -- power-domains: Only for nvidia,tegra210-i2c-vi compatible node and must - include venc powergate node as vi i2c is part of VE power domain. - tegra210-i2c-vi: - - pd_venc -- dmas: Must contain an entry for each entry in clock-names. - See ../dma/dma.txt for details. -- dma-names: Must include the following entries: - - rx - - tx - -Example: - - i2c@7000c000 { - compatible = "nvidia,tegra20-i2c"; - reg = <0x7000c000 0x100>; - interrupts = <0 38 0x04>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&tegra_car 12>, <&tegra_car 124>; - clock-names = "div-clk", "fast-clk"; - resets = <&tegra_car 12>; - reset-names = "i2c"; - dmas = <&apbdma 16>, <&apbdma 16>; - dma-names = "rx", "tx"; - }; diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml new file mode 100644 index 000000000000..424a4fc218b6 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml @@ -0,0 +1,192 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/nvidia,tegra20-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +title: NVIDIA Tegra I2C controller driver + +properties: + compatible: + oneOf: + - description: Tegra20 has 4 generic I2C controller. This can support + master and slave mode of I2C communication. The i2c-tegra driver + only support master mode of I2C communication. Driver of I2C + controller is only compatible with "nvidia,tegra20-i2c". + const: nvidia,tegra20-i2c + - description: Tegra20 has specific I2C controller called as DVC I2C + controller. This only support master mode of I2C communication. + Register interface/offset and interrupts handling are different than + generic I2C controller. Driver of DVC I2C controller is only + compatible with "nvidia,tegra20-i2c-dvc". + const: nvidia,tegra20-i2c-dvc + - description: | + Tegra30 has 5 generic I2C controller. This controller is very much + similar to Tegra20 I2C controller with additional feature: Continue + Transfer Support. This feature helps to implement M_NO_START as per + I2C core API transfer flags. Driver of I2C controller is compatible + with "nvidia,tegra30-i2c" to enable the continue transfer support. + This is also compatible with "nvidia,tegra20-i2c" without continue + transfer support. + items: + - const: nvidia,tegra30-i2c + - const: nvidia,tegra20-i2c + - description: | + Tegra114 has 5 generic I2C controllers. This controller is very much + similar to Tegra30 I2C controller with some hardware modification: + - Tegra30/Tegra20 I2C controller has 2 clock source called div-clk + and fast-clk. Tegra114 has only one clock source called as + div-clk and hence clock mechanism is changed in I2C controller. + - Tegra30/Tegra20 I2C controller has enabled per packet transfer + by default and there is no way to disable it. Tegra114 has this + interrupt disable by default and SW need to enable explicitly. + Due to above changes, Tegra114 I2C driver makes incompatible with + previous hardware driver. Hence, Tegra114 I2C controller is + compatible with "nvidia,tegra114-i2c". + const: nvidia,tegra114-i2c + - description: | + Tegra124 has 6 generic I2C controllers. These controllers are very + similar to those found on Tegra114 but also contain several hardware + improvements and new registers. + const: nvidia,tegra124-i2c + - description: | + Tegra210 has 6 generic I2C controllers. These controllers are very + similar to those found on Tegra124. + items: + - const: nvidia,tegra210-i2c + - const: nvidia,tegra124-i2c + - description: | + Tegra210 has one I2C controller that is on host1x bus and is part of + the VE power domain and typically used for camera use-cases. This VI + I2C controller is mostly compatible with the programming model of + the regular I2C controllers with a few exceptions. The I2C registers + start at an offset of 0xc00 (instead of 0), registers are 16 bytes + apart (rather than 4) and the controller does not support slave + mode. + const: nvidia,tegra210-i2c-vi + - description: | + Tegra186 has 9 generic I2C controllers, two of which are in the AON + (always-on) partition of the SoC. All of these controllers are very + similar to those found on Tegra210. + const: nvidia,tegra186-i2c + - description: | + Tegra194 has 8 generic I2C controllers, two of which are in the AON + (always-on) partition of the SoC. All of these controllers are very + similar to those found on Tegra186. However, these controllers have + support for 64 KiB transactions whereas earlier chips supported no + more than 4 KiB per transactions. + const: nvidia,tegra194-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + + resets: + items: + - description: module reset + + reset-names: + items: + - const: i2c + + dmas: + items: + - description: DMA channel for the reception FIFO + - description: DMA channel for the transmission FIFO + + dma-names: + items: + - const: rx + - const: tx + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra20-i2c + - nvidia,tegra30-i2c + then: + properties: + clock-names: + items: + - const: div-clk + - const: fast-clk + + - if: + properties: + compatible: + contains: + const: nvidia,tegra114-i2c + then: + properties: + clock-names: + items: + - const: div-clk + + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-i2c + then: + properties: + clock-names: + items: + - const: div-clk + + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-i2c-vi + then: + properties: + clock-names: + items: + - const: div-clk + - const: slow + power-domains: + items: + - description: phandle to the VENC power domain + +unevaluatedProperties: false + +examples: + - | + i2c@7000c000 { + compatible = "nvidia,tegra20-i2c"; + reg = <0x7000c000 0x100>; + interrupts = <0 38 0x04>; + clocks = <&tegra_car 12>, <&tegra_car 124>; + clock-names = "div-clk", "fast-clk"; + resets = <&tegra_car 12>; + reset-names = "i2c"; + dmas = <&apbdma 16>, <&apbdma 16>; + dma-names = "rx", "tx"; + + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml index c07289a643d8..46b62e1c9273 100644 --- a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml @@ -112,6 +112,9 @@ examples: clocks = <&rcc 0 149>; }; + - | + #include <dt-bindings/mfd/stm32f7-rcc.h> + #include <dt-bindings/clock/stm32fx-clock.h> //Example 2 (with st,stm32f7-i2c compatible) i2c@40005800 { compatible = "st,stm32f7-i2c"; @@ -124,6 +127,9 @@ examples: clocks = <&rcc 1 CLK_I2C1>; }; + - | + #include <dt-bindings/mfd/stm32f7-rcc.h> + #include <dt-bindings/clock/stm32fx-clock.h> //Example 3 (with st,stm32mp15-i2c compatible on stm32mp) #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/stm32mp1-clks.h> diff --git a/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml b/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml index 1ca571056ea9..925f355cc21f 100644 --- a/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: ADC found on Freescale vf610 and similar SoCs maintainers: - - Fugang Duan <fugang.duan@nxp.com> + - Haibo Chen <haibo.chen@nxp.com> description: ADCs found on vf610/i.MX6slx and upward SoCs from Freescale. diff --git a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml index e759a5da708d..d6d3d8590171 100644 --- a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml @@ -27,6 +27,7 @@ description: | 8 | batt_v 9 | batt_chrg_i 10 | batt_dischrg_i + 11 | ts_v AXP22x ------ @@ -34,6 +35,7 @@ description: | 1 | batt_v 2 | batt_chrg_i 3 | batt_dischrg_i + 4 | ts_v AXP813 ------ @@ -42,6 +44,7 @@ description: | 2 | batt_v 3 | batt_chrg_i 4 | batt_dischrg_i + 5 | ts_v properties: diff --git a/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml new file mode 100644 index 000000000000..87992db389b2 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml @@ -0,0 +1,227 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/xlnx,zynqmp-ams.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq Ultrascale AMS controller + +maintainers: + - Anand Ashok Dumbre <anand.ashok.dumbre@xilinx.com> + +description: | + The AMS (Analog Monitoring System) includes an ADC as well as on-chip sensors + that can be used to sample external voltages and monitor on-die operating + conditions, such as temperature and supply voltage levels. + The AMS has two SYSMON blocks which are PL (Programmable Logic) SYSMON and + PS (Processing System) SYSMON. + All designs should have AMS registers, but PS and PL are optional. The + AMS controller can work with only PS, only PL and both PS and PL + configurations. Please specify registers according to your design. Devicetree + should always have AMS module property. Providing PS & PL module is optional. + + AMS Channel Details + ``````````````````` + Sysmon Block |Channel| Details |Measurement + |Number | |Type + --------------------------------------------------------------------------------------------------------- + AMS CTRL |0 |System PLLs voltage measurement, VCC_PSPLL. |Voltage + |1 |Battery voltage measurement, VCC_PSBATT. |Voltage + |2 |PL Internal voltage measurement, VCCINT. |Voltage + |3 |Block RAM voltage measurement, VCCBRAM. |Voltage + |4 |PL Aux voltage measurement, VCCAUX. |Voltage + |5 |Voltage measurement for six DDR I/O PLLs, VCC_PSDDR_PLL. |Voltage + |6 |VCC_PSINTFP_DDR voltage measurement. |Voltage + --------------------------------------------------------------------------------------------------------- + PS Sysmon |7 |LPD temperature measurement. |Temperature + |8 |FPD temperature measurement (REMOTE). |Temperature + |9 |VCC PS LPD voltage measurement (supply1). |Voltage + |10 |VCC PS FPD voltage measurement (supply2). |Voltage + |11 |PS Aux voltage reference (supply3). |Voltage + |12 |DDR I/O VCC voltage measurement. |Voltage + |13 |PS IO Bank 503 voltage measurement (supply5). |Voltage + |14 |PS IO Bank 500 voltage measurement (supply6). |Voltage + |15 |VCCO_PSIO1 voltage measurement. |Voltage + |16 |VCCO_PSIO2 voltage measurement. |Voltage + |17 |VCC_PS_GTR voltage measurement (VPS_MGTRAVCC). |Voltage + |18 |VTT_PS_GTR voltage measurement (VPS_MGTRAVTT). |Voltage + |19 |VCC_PSADC voltage measurement. |Voltage + --------------------------------------------------------------------------------------------------------- + PL Sysmon |20 |PL temperature measurement. |Temperature + |21 |PL Internal voltage measurement, VCCINT. |Voltage + |22 |PL Auxiliary voltage measurement, VCCAUX. |Voltage + |23 |ADC Reference P+ voltage measurement. |Voltage + |24 |ADC Reference N- voltage measurement. |Voltage + |25 |PL Block RAM voltage measurement, VCCBRAM. |Voltage + |26 |LPD Internal voltage measurement, VCC_PSINTLP (supply4). |Voltage + |27 |FPD Internal voltage measurement, VCC_PSINTFP (supply5). |Voltage + |28 |PS Auxiliary voltage measurement (supply6). |Voltage + |29 |PL VCCADC voltage measurement (vccams). |Voltage + |30 |Differential analog input signal voltage measurment. |Voltage + |31 |VUser0 voltage measurement (supply7). |Voltage + |32 |VUser1 voltage measurement (supply8). |Voltage + |33 |VUser2 voltage measurement (supply9). |Voltage + |34 |VUser3 voltage measurement (supply10). |Voltage + |35 |Auxiliary ch 0 voltage measurement (VAux0). |Voltage + |36 |Auxiliary ch 1 voltage measurement (VAux1). |Voltage + |37 |Auxiliary ch 2 voltage measurement (VAux2). |Voltage + |38 |Auxiliary ch 3 voltage measurement (VAux3). |Voltage + |39 |Auxiliary ch 4 voltage measurement (VAux4). |Voltage + |40 |Auxiliary ch 5 voltage measurement (VAux5). |Voltage + |41 |Auxiliary ch 6 voltage measurement (VAux6). |Voltage + |42 |Auxiliary ch 7 voltage measurement (VAux7). |Voltage + |43 |Auxiliary ch 8 voltage measurement (VAux8). |Voltage + |44 |Auxiliary ch 9 voltage measurement (VAux9). |Voltage + |45 |Auxiliary ch 10 voltage measurement (VAux10). |Voltage + |46 |Auxiliary ch 11 voltage measurement (VAux11). |Voltage + |47 |Auxiliary ch 12 voltage measurement (VAux12). |Voltage + |48 |Auxiliary ch 13 voltage measurement (VAux13). |Voltage + |49 |Auxiliary ch 14 voltage measurement (VAux14). |Voltage + |50 |Auxiliary ch 15 voltage measurement (VAux15). |Voltage + -------------------------------------------------------------------------------------------------------- + +properties: + compatible: + enum: + - xlnx,zynqmp-ams + + interrupts: + maxItems: 1 + + reg: + description: AMS Controller register space + maxItems: 1 + + ranges: + description: + Maps the child address space for PS and/or PL. + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + '#io-channel-cells': + const: 1 + + ams-ps@0: + type: object + description: | + PS (Processing System) SYSMON is memory mapped to PS. This block has + built-in alarm generation logic that is used to interrupt the processor + based on condition set. + + properties: + compatible: + enum: + - xlnx,zynqmp-ams-ps + + reg: + description: Register Space for PS-SYSMON + maxItems: 1 + + required: + - compatible + - reg + + additionalProperties: false + + ams-pl@400: + type: object + description: + PL-SYSMON is capable of monitoring off chip voltage and temperature. + PL-SYSMON block has DRP, JTAG and I2C interface to enable monitoring + from external master. Out of this interface currently only DRP is + supported. This block has alarm generation logic that is used to + interrupt the processor based on condition set. + + properties: + compatible: + items: + - enum: + - xlnx,zynqmp-ams-pl + + reg: + description: Register Space for PL-SYSMON. + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + "^channel@([2-4][0-9]|50)$": + type: object + description: + Describes the external channels connected. + + properties: + reg: + description: + Pair of pins the channel is connected to. This value is + same as Channel Number for a particular channel. + minimum: 20 + maximum: 50 + + xlnx,bipolar: + $ref: /schemas/types.yaml#/definitions/flag + type: boolean + description: + If the set channel is used in bipolar mode. + + required: + - reg + + additionalProperties: false + +required: + - compatible + - reg + - ranges + +additionalProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + xilinx_ams: ams@ffa50000 { + compatible = "xlnx,zynqmp-ams"; + interrupt-parent = <&gic>; + interrupts = <0 56 4>; + reg = <0x0 0xffa50000 0x0 0x800>; + #address-cells = <1>; + #size-cells = <1>; + #io-channel-cells = <1>; + ranges = <0 0 0xffa50800 0x800>; + + ams_ps: ams-ps@0 { + compatible = "xlnx,zynqmp-ams-ps"; + reg = <0 0x400>; + }; + + ams_pl: ams-pl@400 { + compatible = "xlnx,zynqmp-ams-pl"; + reg = <0x400 0x400>; + #address-cells = <1>; + #size-cells = <0>; + channel@30 { + reg = <30>; + xlnx,bipolar; + }; + channel@31 { + reg = <31>; + }; + channel@38 { + reg = <38>; + xlnx,bipolar; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml new file mode 100644 index 000000000000..baa65a521bad --- /dev/null +++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml @@ -0,0 +1,158 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/addac/adi,ad74413r.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD74412R/AD74413R device + +maintainers: + - Cosmin Tanislav <cosmin.tanislav@analog.com> + +description: | + The AD74412R and AD74413R are quad-channel software configurable input/output + solutions for building and process control applications. They contain + functionality for analog output, analog input, digital input, resistance + temperature detector, and thermocouple measurements integrated + into a single chip solution with an SPI interface. + The devices feature a 16-bit ADC and four configurable 13-bit DACs to provide + four configurable input/output channels and a suite of diagnostic functions. + The AD74413R differentiates itself from the AD74412R by being HART-compatible. + https://www.analog.com/en/products/ad74412r.html + https://www.analog.com/en/products/ad74413r.html + +properties: + compatible: + enum: + - adi,ad74412r + - adi,ad74413r + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + spi-max-frequency: + maximum: 1000000 + + spi-cpol: true + + interrupts: + maxItems: 1 + + refin-supply: true + + shunt-resistor-micro-ohms: + description: + Shunt (sense) resistor value in micro-Ohms. + default: 100000000 + +required: + - compatible + - reg + - spi-max-frequency + - spi-cpol + - refin-supply + +additionalProperties: false + +patternProperties: + "^channel@[0-3]$": + type: object + description: Represents the external channels which are connected to the device. + + properties: + reg: + description: | + The channel number. It can have up to 4 channels numbered from 0 to 3. + minimum: 0 + maximum: 3 + + adi,ch-func: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Channel function. + HART functions are not supported on AD74412R. + 0 - CH_FUNC_HIGH_IMPEDANCE + 1 - CH_FUNC_VOLTAGE_OUTPUT + 2 - CH_FUNC_CURRENT_OUTPUT + 3 - CH_FUNC_VOLTAGE_INPUT + 4 - CH_FUNC_CURRENT_INPUT_EXT_POWER + 5 - CH_FUNC_CURRENT_INPUT_LOOP_POWER + 6 - CH_FUNC_RESISTANCE_INPUT + 7 - CH_FUNC_DIGITAL_INPUT_LOGIC + 8 - CH_FUNC_DIGITAL_INPUT_LOOP_POWER + 9 - CH_FUNC_CURRENT_INPUT_EXT_POWER_HART + 10 - CH_FUNC_CURRENT_INPUT_LOOP_POWER_HART + minimum: 0 + maximum: 10 + default: 0 + + adi,gpo-comparator: + type: boolean + description: | + Whether to configure GPO as a comparator or not. + When not configured as a comparator, the GPO will be treated as an + output-only GPIO. + + required: + - reg + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/iio/addac/adi,ad74413r.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + cs-gpios = <&gpio 17 GPIO_ACTIVE_LOW>; + status = "okay"; + + ad74413r@0 { + compatible = "adi,ad74413r"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + + #address-cells = <1>; + #size-cells = <0>; + + interrupt-parent = <&gpio>; + interrupts = <26 IRQ_TYPE_EDGE_FALLING>; + + refin-supply = <&ad74413r_refin>; + + channel@0 { + reg = <0>; + + adi,ch-func = <CH_FUNC_VOLTAGE_OUTPUT>; + }; + + channel@1 { + reg = <1>; + + adi,ch-func = <CH_FUNC_CURRENT_OUTPUT>; + }; + + channel@2 { + reg = <2>; + + adi,ch-func = <CH_FUNC_DIGITAL_INPUT_LOGIC>; + adi,gpo-comparator; + }; + + channel@3 { + reg = <3>; + + adi,ch-func = <CH_FUNC_CURRENT_INPUT_EXT_POWER>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml new file mode 100644 index 000000000000..501a463e5d88 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml @@ -0,0 +1,217 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 Analog Devices Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad3552r.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD2552R DAC device driver + +maintainers: + - Mihail Chindris <mihail.chindris@analog.com> + +description: | + Bindings for the Analog Devices AD3552R DAC device and similar. + Datasheet can be found here: + https://www.analog.com/media/en/technical-documentation/data-sheets/ad3542r.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad3552r.pdf + +properties: + compatible: + enum: + - adi,ad3542r + - adi,ad3552r + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 30000000 + + reset-gpios: + maxItems: 1 + + ldac-gpios: + description: | + LDAC pin to be used as a hardware trigger to update the DAC channels. + maxItems: 1 + + vref-supply: + description: + The regulator to use as an external reference. If it does not exists the + internal reference will be used. External reference must be 2.5V + + adi,vref-out-en: + description: Vref I/O driven by internal vref to 2.5V. If not set, Vref pin + will be floating. + type: boolean + + adi,sdo-drive-strength: + description: | + Configure SDIO0 and SDIO1 strength levels: + - 0: low SDO drive strength. + - 1: medium low SDO drive strength. + - 2: medium high SDO drive strength. + - 3: high SDO drive strength + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + "^channel@([0-1])$": + type: object + description: Configurations of the DAC Channels + + additionalProperties: false + + properties: + reg: + description: Channel number + enum: [0, 1] + + adi,output-range-microvolt: true + + custom-output-range-config: + type: object + description: Configuration of custom range when + adi,output-range-microvolt is not present. + The formulas for calculation the output voltages are + Vout_fs = 2.5 + [(GainN + Offset/1024) * 2.5 * Rfbx * 1.03] + Vout_zs = 2.5 - [(GainP + Offset/1024) * 2.5 * Rfbx * 1.03] + + properties: + adi,gain-offset: + description: Gain offset used in the above formula + $ref: /schemas/types.yaml#/definitions/int32 + maximum: 511 + minimum: -511 + + adi,gain-scaling-p-inv-log2: + description: GainP = 1 / ( 2 ^ adi,gain-scaling-p-inv-log2) + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + adi,gain-scaling-n-inv-log2: + description: GainN = 1 / ( 2 ^ adi,gain-scaling-n-inv-log2) + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + adi,rfb-ohms: + description: Feedback Resistor + + required: + - adi,gain-offset + - adi,gain-scaling-p-inv-log2 + - adi,gain-scaling-n-inv-log2 + - adi,rfb-ohms + + required: + - reg + + oneOf: + # If adi,output-range-microvolt is missing, + # custom-output-range-config must be used + - required: + - adi,output-range-microvolt + + - required: + - custom-output-range-config + +allOf: + - if: + properties: + compatible: + contains: + const: adi,ad3542r + then: + patternProperties: + "^channel@([0-1])$": + type: object + properties: + adi,output-range-microvolt: + description: | + Voltage output range of the channel as <minimum, maximum> + Required connections: + Rfb1x for: 0 to 2.5 V; 0 to 3V; 0 to 5 V; + Rfb2x for: 0 to 10 V; 2.5 to 7.5V; -5 to 5 V; + oneOf: + - items: + - const: 0 + - enum: [2500000, 3000000, 5000000, 10000000] + - items: + - const: -2500000 + - const: 7500000 + - items: + - const: -5000000 + - const: 5000000 + + required: + - adi,output-range-microvolt + + - if: + properties: + compatible: + contains: + const: adi,ad3552r + then: + patternProperties: + "^channel@([0-1])$": + type: object + properties: + adi,output-range-microvolt: + description: | + Voltage output range of the channel as <minimum, maximum> + Required connections: + Rfb1x for: 0 to 2.5 V; 0 to 5 V; + Rfb2x for: 0 to 10 V; -5 to 5 V; + Rfb4x for: -10 to 10V + oneOf: + - items: + - const: 0 + - enum: [2500000, 5000000, 10000000] + - items: + - const: -5000000 + - const: 5000000 + - items: + - const: -10000000 + - const: 10000000 + +required: + - compatible + - reg + - spi-max-frequency + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + ad3552r@0 { + compatible = "adi,ad3552r"; + reg = <0>; + spi-max-frequency = <20000000>; + #address-cells = <1>; + #size-cells = <0>; + channel@0 { + reg = <0>; + adi,output-range-microvolt = <0 10000000>; + }; + channel@1 { + reg = <1>; + custom-output-range-config { + adi,gain-offset = <5>; + adi,gain-scaling-p-inv-log2 = <1>; + adi,gain-scaling-n-inv-log2 = <2>; + adi,rfb-ohms = <1>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml index be419ac46caa..f866b88e1440 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml @@ -125,7 +125,6 @@ oneOf: examples: - | - #include <dt-bindings/iio/adi,ad5592r.h> spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml new file mode 100644 index 000000000000..5ee80bf6aa11 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad7293.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AD7293 12-Bit Power Amplifier Current Controller with ADC, + DACs, Temperature and Current Sensors + +maintainers: + - Antoniu Miclaus <antoniu.miclaus@analog.com> + +description: | + Power Amplifier drain current controller containing functionality + for general-purpose monitoring and control of current, voltage, + and temperature, integrated into a single chip solution with an + SPI-compatible interface. + + https://www.analog.com/en/products/ad7293.html + +properties: + compatible: + enum: + - adi,ad7293 + + avdd-supply: true + + vdrive-supply: true + + reset-gpios: + maxItems: 1 + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 1000000 + +required: + - compatible + - reg + - avdd-supply + - vdrive-supply + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + ad7293@0 { + compatible = "adi,ad7293"; + reg = <0>; + spi-max-frequency = <1000000>; + avdd-supply = <&avdd>; + vdrive-supply = <&vdrive>; + reset-gpios = <&gpio 10 0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml b/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml new file mode 100644 index 000000000000..b77e855bd594 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/filter/adi,admv8818.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ADMV8818 Digitally Tunable, High-Pass and Low-Pass Filter + +maintainers: + - Antoniu Miclaus <antoniu.miclaus@analog.com> + +description: | + Fully monolithic microwave integrated circuit (MMIC) that + features a digitally selectable frequency of operation. + The device features four independently controlled high-pass + filters (HPFs) and four independently controlled low-pass filters + (LPFs) that span the 2 GHz to 18 GHz frequency range. + + https://www.analog.com/en/products/admv8818.html + +properties: + compatible: + enum: + - adi,admv8818 + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 10000000 + + clocks: + description: + Definition of the external clock. + minItems: 1 + + clock-names: + items: + - const: rf_in + + clock-output-names: + maxItems: 1 + + '#clock-cells': + const: 0 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + admv8818@0 { + compatible = "adi,admv8818"; + reg = <0>; + spi-max-frequency = <10000000>; + clocks = <&admv8818_rfin>; + clock-names = "rf_in"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml new file mode 100644 index 000000000000..23f1f3b55abb --- /dev/null +++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/frequency/adi,admv1013.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ADMV1013 Microwave Upconverter + +maintainers: + - Antoniu Miclaus <antoniu.miclaus@analog.com> + +description: | + Wideband, microwave upconverter optimized for point to point microwave + radio designs operating in the 24 GHz to 44 GHz frequency range. + + https://www.analog.com/en/products/admv1013.html + +properties: + compatible: + enum: + - adi,admv1013 + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 1000000 + + clocks: + description: + Definition of the external clock. + minItems: 1 + + clock-names: + items: + - const: lo_in + + vcm-supply: + description: + Analog voltage regulator. + + adi,detector-enable: + description: + Enable the Envelope Detector available at output pins VENV_P and + VENV_N. Disable to reduce power consumption. + type: boolean + + adi,input-mode: + description: + Select the input mode. + iq - in-phase quadrature (I/Q) input + if - complex intermediate frequency (IF) input + enum: [iq, if] + + adi,quad-se-mode: + description: + Switch the LO path from differential to single-ended operation. + se-neg - Single-Ended Mode, Negative Side Disabled. + se-pos - Single-Ended Mode, Positive Side Disabled. + diff - Differential Mode. + enum: [se-neg, se-pos, diff] + + '#clock-cells': + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - vcm-supply + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + admv1013@0{ + compatible = "adi,admv1013"; + reg = <0>; + spi-max-frequency = <1000000>; + clocks = <&admv1013_lo>; + clock-names = "lo_in"; + vcm-supply = <&vcm>; + adi,quad-se-mode = "diff"; + adi,detector-enable; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml index 7e2accc3d5ce..d1a6103fc37a 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml @@ -61,7 +61,7 @@ examples: #size-cells = <0>; magnetometer@c { - compatible = "ak,ak8975"; + compatible = "asahi-kasei,ak8975"; reg = <0x0c>; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml index edbc2921aabd..d69595a524c1 100644 --- a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml +++ b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml @@ -95,7 +95,7 @@ examples: #address-cells = <1>; #size-cells = <0>; magnetometer@c { - compatible = "ak,ak8975"; + compatible = "asahi-kasei,ak8975"; reg = <0x0c>; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml index d9b3213318fb..0750f700a143 100644 --- a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml +++ b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml @@ -61,6 +61,13 @@ properties: type: boolean description: enable/disable internal i2c controller pullup resistors. + st,disable-sensor-hub: + type: boolean + description: + Enable/disable internal i2c controller slave autoprobing at bootstrap. + Disable sensor-hub is useful if i2c controller clock/data lines are + connected through a pull-up with other chip lines (e.g. SDO/SA0). + drive-open-drain: type: boolean description: diff --git a/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml b/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml index db0407bc9209..c8074f180a79 100644 --- a/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml +++ b/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml @@ -9,6 +9,9 @@ title: LiteON LTR501 I2C Proximity and Light sensor maintainers: - Nikita Travkin <nikita@trvn.ru> +allOf: + - $ref: ../common.yaml# + properties: compatible: enum: @@ -25,6 +28,8 @@ properties: interrupts: maxItems: 1 + proximity-near-level: true + additionalProperties: false required: @@ -42,6 +47,8 @@ examples: light-sensor@23 { compatible = "liteon,ltr559"; reg = <0x23>; + proximity-near-level = <75>; + vdd-supply = <&pm8916_l17>; vddio-supply = <&pm8916_l6>; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml index 4b0ef1ef5445..9438fffaf0ba 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml +++ b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml @@ -96,7 +96,7 @@ examples: vdd-supply = <&ldo1_reg>; iovdd-supply = <&ldo2_reg>; reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>; - interrupts = <&gpio6 13 IRQ_TYPE_EDGE_RISING>; + interrupts = <13 IRQ_TYPE_EDGE_RISING>; }; }; diff --git a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml index 099b4be927d4..00e3b59641d2 100644 --- a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml @@ -10,7 +10,6 @@ title: ChromeOS EC MKBP Proximity Sensor maintainers: - Stephen Boyd <swboyd@chromium.org> - Benson Leung <bleung@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | Google's ChromeOS EC sometimes has the ability to detect user proximity. diff --git a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml index 0f79d9a01c49..722781aa4697 100644 --- a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml +++ b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml @@ -448,17 +448,17 @@ examples: reg = <20>; adi,sensor-type = <9>; //custom thermocouple adi,single-ended; - adi,custom-thermocouple = /bits/ 64 - <(-50220000) 0>, - <(-30200000) 99100000>, - <(-5300000) 135400000>, - <0 273150000>, - <40200000 361200000>, - <55300000 522100000>, - <88300000 720300000>, - <132200000 811200000>, - <188700000 922500000>, - <460400000 1000000000>; //10 pairs + adi,custom-thermocouple = + /bits/ 64 <(-50220000) 0>, + /bits/ 64 <(-30200000) 99100000>, + /bits/ 64 <(-5300000) 135400000>, + /bits/ 64 <0 273150000>, + /bits/ 64 <40200000 361200000>, + /bits/ 64 <55300000 522100000>, + /bits/ 64 <88300000 720300000>, + /bits/ 64 <132200000 811200000>, + /bits/ 64 <188700000 922500000>, + /bits/ 64 <460400000 1000000000>; //10 pairs }; }; diff --git a/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml index 5377b232fa10..e8f137abb03c 100644 --- a/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml +++ b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml @@ -10,7 +10,6 @@ title: ChromeOS EC Keyboard maintainers: - Simon Glass <sjg@chromium.org> - Benson Leung <bleung@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> description: | Google's ChromeOS EC Keyboard is a simple matrix keyboard diff --git a/Documentation/devicetree/bindings/input/gpio-keys.yaml b/Documentation/devicetree/bindings/input/gpio-keys.yaml index dbe7ecc19ccb..7fe1966ea28a 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys.yaml +++ b/Documentation/devicetree/bindings/input/gpio-keys.yaml @@ -88,12 +88,6 @@ patternProperties: which can be disabled to suppress events from the button. type: boolean - pinctrl-0: - maxItems: 1 - - pinctrl-names: - maxItems: 1 - required: - linux,code diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index c76bafaf98d2..34c43d3bddfd 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -32,6 +32,8 @@ device-specific compatible properties, which should be used in addition to the - vdd-supply: phandle of the regulator that provides the supply voltage. - post-power-on-delay-ms: time required by the device after enabling its regulators or powering it on, before it is ready for communication. +- touchscreen-inverted-x: See touchscreen.txt +- touchscreen-inverted-y: See touchscreen.txt Example: diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.txt b/Documentation/devicetree/bindings/input/pwm-vibrator.txt deleted file mode 100644 index 88c775a3fe21..000000000000 --- a/Documentation/devicetree/bindings/input/pwm-vibrator.txt +++ /dev/null @@ -1,66 +0,0 @@ -* PWM vibrator device tree bindings - -Registers a PWM device as vibrator. It is expected, that the vibrator's -strength increases based on the duty cycle of the enable PWM channel -(100% duty cycle meaning strongest vibration, 0% meaning no vibration). - -The binding supports an optional direction PWM channel, that can be -driven at fixed duty cycle. If available this is can be used to increase -the vibration effect of some devices. - -Required properties: -- compatible: should contain "pwm-vibrator" -- pwm-names: Should contain "enable" and optionally "direction" -- pwms: Should contain a PWM handle for each entry in pwm-names - -Optional properties: -- vcc-supply: Phandle for the regulator supplying power -- direction-duty-cycle-ns: Duty cycle of the direction PWM channel in - nanoseconds, defaults to 50% of the channel's - period. - -Example from Motorola Droid 4: - -&omap4_pmx_core { - vibrator_direction_pin: pinmux_vibrator_direction_pin { - pinctrl-single,pins = < - OMAP4_IOPAD(0x1ce, PIN_OUTPUT | MUX_MODE1) /* dmtimer8_pwm_evt (gpio_27) */ - >; - }; - - vibrator_enable_pin: pinmux_vibrator_enable_pin { - pinctrl-single,pins = < - OMAP4_IOPAD(0X1d0, PIN_OUTPUT | MUX_MODE1) /* dmtimer9_pwm_evt (gpio_28) */ - >; - }; -}; - -/ { - pwm8: dmtimer-pwm { - pinctrl-names = "default"; - pinctrl-0 = <&vibrator_direction_pin>; - - compatible = "ti,omap-dmtimer-pwm"; - #pwm-cells = <3>; - ti,timers = <&timer8>; - ti,clock-source = <0x01>; - }; - - pwm9: dmtimer-pwm { - pinctrl-names = "default"; - pinctrl-0 = <&vibrator_enable_pin>; - - compatible = "ti,omap-dmtimer-pwm"; - #pwm-cells = <3>; - ti,timers = <&timer9>; - ti,clock-source = <0x01>; - }; - - vibrator { - compatible = "pwm-vibrator"; - pwms = <&pwm9 0 1000000000 0>, - <&pwm8 0 1000000000 0>; - pwm-names = "enable", "direction"; - direction-duty-cycle-ns = <1000000000>; - }; -}; diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.yaml b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml new file mode 100644 index 000000000000..a70a636ee112 --- /dev/null +++ b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/input/pwm-vibrator.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: PWM vibrator + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: > + Registers a PWM device as vibrator. It is expected, that the vibrator's + strength increases based on the duty cycle of the enable PWM channel + (100% duty cycle meaning strongest vibration, 0% meaning no vibration). + + The binding supports an optional direction PWM channel, that can be + driven at fixed duty cycle. If available this is can be used to increase + the vibration effect of some devices. + +properties: + compatible: + const: pwm-vibrator + + pwm-names: + items: + - const: enable + - const: direction + minItems: 1 + + pwms: + minItems: 1 + maxItems: 2 + + vcc-supply: true + + direction-duty-cycle-ns: + description: > + Duty cycle of the direction PWM channel in nanoseconds, + defaults to 50% of the channel's period. + +required: + - compatible + - pwm-names + - pwms + +additionalProperties: false + +examples: + - | + vibrator { + compatible = "pwm-vibrator"; + pwms = <&pwm9 0 1000000000 0>, + <&pwm8 0 1000000000 0>; + pwm-names = "enable", "direction"; + direction-duty-cycle-ns = <1000000000>; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml b/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml new file mode 100644 index 000000000000..b4e5ba7c0b49 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/zinitix,bt400.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Zinitix BT4xx and BT5xx series touchscreen controller bindings + +description: The Zinitix BT4xx and BT5xx series of touchscreen controllers + are Korea-produced touchscreens with embedded microcontrollers. The + BT4xx series was produced 2010-2013 and the BT5xx series 2013-2014. + +maintainers: + - Michael Srba <Michael.Srba@seznam.cz> + - Linus Walleij <linus.walleij@linaro.org> + +allOf: + - $ref: touchscreen.yaml# + +properties: + $nodename: + pattern: "^touchscreen(@.*)?$" + + compatible: + enum: + - zinitix,bt402 + - zinitix,bt403 + - zinitix,bt404 + - zinitix,bt412 + - zinitix,bt413 + - zinitix,bt431 + - zinitix,bt432 + - zinitix,bt531 + - zinitix,bt532 + - zinitix,bt538 + - zinitix,bt541 + - zinitix,bt548 + - zinitix,bt554 + - zinitix,at100 + + reg: + description: I2C address on the I2C bus + + clock-frequency: + description: I2C client clock frequency, defined for host when using + the device on the I2C bus + minimum: 0 + maximum: 400000 + + interrupts: + description: Interrupt to host + maxItems: 1 + + vcca-supply: + description: Analog power supply regulator on the VCCA pin + + vdd-supply: + description: Digital power supply regulator on the VDD pin. + In older device trees this can be the accidental name for the analog + supply on the VCCA pin, and in that case the deprecated vddo-supply is + used for the digital power supply. + + vddo-supply: + description: Deprecated name for the digital power supply, use vdd-supply + as this reflects the real name of the pin. If this supply is present, + the vdd-supply represents VCCA instead of VDD. Implementers should first + check for this property, and if it is present assume that the vdd-supply + represents the analog supply. + deprecated: true + + reset-gpios: + description: Reset line for the touchscreen, should be tagged + as GPIO_ACTIVE_LOW + + zinitix,mode: + description: Mode of reporting touch points. Some modes may not work + with a particular ts firmware for unknown reasons. Available modes are + 1 and 2. Mode 2 is the default and preferred. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2] + + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-fuzz-x: true + touchscreen-fuzz-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@20 { + compatible = "zinitix,bt541"; + reg = <0x20>; + interrupt-parent = <&gpio>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + vcca-supply = <®_vcca_tsp>; + vdd-supply = <®_vdd_tsp>; + touchscreen-size-x = <540>; + touchscreen-size-y = <960>; + zinitix,mode = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt b/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt deleted file mode 100644 index 446efb9f5f55..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt +++ /dev/null @@ -1,40 +0,0 @@ -Device tree bindings for Zinitx BT541 touchscreen controller - -Required properties: - - - compatible : Should be "zinitix,bt541" - - reg : I2C address of the chip. Should be 0x20 - - interrupts : Interrupt to which the chip is connected - -Optional properties: - - - vdd-supply : Analog power supply regulator on VCCA pin - - vddo-supply : Digital power supply regulator on VDD pin - - zinitix,mode : Mode of reporting touch points. Some modes may not work - with a particular ts firmware for unknown reasons. Available - modes are 1 and 2. Mode 2 is the default and preferred. - -The touchscreen-* properties are documented in touchscreen.txt in this -directory. - -Example: - - i2c@00000000 { - /* ... */ - - bt541@20 { - compatible = "zinitix,bt541"; - reg = <0x20>; - interrupt-parent = <&msmgpio>; - interrupts = <13 IRQ_TYPE_EDGE_FALLING>; - pinctrl-names = "default"; - pinctrl-0 = <&tsp_default>; - vdd-supply = <®_vdd_tsp>; - vddo-supply = <&pm8916_l6>; - touchscreen-size-x = <540>; - touchscreen-size-y = <960>; - zinitix,mode = <2>; - }; - - /* ... */ - }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml index e701524ee811..116e434d0daa 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml @@ -18,6 +18,7 @@ properties: compatible: enum: - qcom,sc7180-osm-l3 + - qcom,sc7280-epss-l3 - qcom,sc8180x-osm-l3 - qcom,sdm845-osm-l3 - qcom,sm8150-osm-l3 diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml new file mode 100644 index 000000000000..f65a2fe846de --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,qcm2290.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QCM2290 Network-On-Chip interconnect + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +description: | + The Qualcomm QCM2290 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + reg: + maxItems: 1 + + compatible: + enum: + - qcom,qcm2290-bimc + - qcom,qcm2290-cnoc + - qcom,qcm2290-snoc + + '#interconnect-cells': + const: 1 + + clock-names: + items: + - const: bus + - const: bus_a + + clocks: + items: + - description: Bus Clock + - description: Bus A Clock + +# Child node's properties +patternProperties: + '^interconnect-[a-z0-9]+$': + type: object + description: + The interconnect providers do not have a separate QoS register space, + but share parent's space. + + properties: + compatible: + enum: + - qcom,qcm2290-qup-virt + - qcom,qcm2290-mmrt-virt + - qcom,qcm2290-mmnrt-virt + + '#interconnect-cells': + const: 1 + + clock-names: + items: + - const: bus + - const: bus_a + + clocks: + items: + - description: Bus Clock + - description: Bus A Clock + + required: + - compatible + - '#interconnect-cells' + - clock-names + - clocks + + additionalProperties: false + +required: + - compatible + - reg + - '#interconnect-cells' + - clock-names + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + + snoc: interconnect@1880000 { + compatible = "qcom,qcm2290-snoc"; + reg = <0x01880000 0x60200>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_SNOC_CLK>, + <&rpmcc RPM_SMD_SNOC_A_CLK>; + + qup_virt: interconnect-qup { + compatible = "qcom,qcm2290-qup-virt"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_QUP_CLK>, + <&rpmcc RPM_SMD_QUP_A_CLK>; + }; + + mmnrt_virt: interconnect-mmnrt { + compatible = "qcom,qcm2290-mmnrt-virt"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_MMNRT_CLK>, + <&rpmcc RPM_SMD_MMNRT_A_CLK>; + }; + + mmrt_virt: interconnect-mmrt { + compatible = "qcom,qcm2290-mmrt-virt"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_MMRT_CLK>, + <&rpmcc RPM_SMD_MMRT_A_CLK>; + }; + }; + + cnoc: interconnect@1900000 { + compatible = "qcom,qcm2290-cnoc"; + reg = <0x01900000 0x8200>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_CNOC_CLK>, + <&rpmcc RPM_SMD_CNOC_A_CLK>; + }; + + bimc: interconnect@4480000 { + compatible = "qcom,qcm2290-bimc"; + reg = <0x04480000 0x80000>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_BIMC_CLK>, + <&rpmcc RPM_SMD_BIMC_A_CLK>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml index 983d71fb5399..e4c3c2818119 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml @@ -27,22 +27,37 @@ properties: - qcom,msm8939-pcnoc - qcom,msm8939-snoc - qcom,msm8939-snoc-mm + - qcom,msm8996-a0noc + - qcom,msm8996-a1noc + - qcom,msm8996-a2noc + - qcom,msm8996-bimc + - qcom,msm8996-cnoc + - qcom,msm8996-mnoc + - qcom,msm8996-pnoc + - qcom,msm8996-snoc - qcom,qcs404-bimc - qcom,qcs404-pcnoc - qcom,qcs404-snoc + - qcom,sdm660-a2noc + - qcom,sdm660-bimc + - qcom,sdm660-cnoc + - qcom,sdm660-gnoc + - qcom,sdm660-mnoc + - qcom,sdm660-snoc '#interconnect-cells': const: 1 + clocks: + minItems: 2 + maxItems: 7 + clock-names: - items: - - const: bus - - const: bus_a + minItems: 2 + maxItems: 7 - clocks: - items: - - description: Bus Clock - - description: Bus A Clock + power-domains: + maxItems: 1 required: - compatible @@ -53,6 +68,120 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8916-bimc + - qcom,msm8916-pcnoc + - qcom,msm8916-snoc + - qcom,msm8939-bimc + - qcom,msm8939-pcnoc + - qcom,msm8939-snoc + - qcom,msm8939-snoc-mm + - qcom,msm8996-a1noc + - qcom,msm8996-a2noc + - qcom,msm8996-bimc + - qcom,msm8996-cnoc + - qcom,msm8996-pnoc + - qcom,msm8996-snoc + - qcom,qcs404-bimc + - qcom,qcs404-pcnoc + - qcom,qcs404-snoc + - qcom,sdm660-bimc + - qcom,sdm660-cnoc + - qcom,sdm660-gnoc + - qcom,sdm660-snoc + + then: + properties: + clock-names: + items: + - const: bus + - const: bus_a + + clocks: + items: + - description: Bus Clock + - description: Bus A Clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8996-mnoc + - qcom,sdm660-mnoc + + then: + properties: + clock-names: + items: + - const: bus + - const: bus_a + - const: iface + + clocks: + items: + - description: Bus Clock. + - description: Bus A Clock. + - description: CPU-NoC High-performance Bus Clock. + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8996-a0noc + + then: + properties: + clock-names: + items: + - const: aggre0_snoc_axi + - const: aggre0_cnoc_ahb + - const: aggre0_noc_mpu_cfg + + clocks: + items: + - description: Aggregate0 System NoC AXI Clock. + - description: Aggregate0 Config NoC AHB Clock. + - description: Aggregate0 NoC MPU Clock. + + required: + - power-domains + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm660-a2noc + + then: + properties: + clock-names: + items: + - const: bus + - const: bus_a + - const: ipa + - const: ufs_axi + - const: aggre2_ufs_axi + - const: aggre2_usb3_axi + - const: cfg_noc_usb2_axi + + clocks: + items: + - description: Bus Clock. + - description: Bus A Clock. + - description: IPA Clock. + - description: UFS AXI Clock. + - description: Aggregate2 UFS AXI Clock. + - description: Aggregate2 USB3 AXI Clock. + - description: Config NoC USB2 AXI Clock. + examples: - | #include <dt-bindings/clock/qcom,rpmcc.h> diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index 3fd1a134162d..cbb24f9bb609 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -104,6 +104,17 @@ properties: - qcom,sm8350-mmss-noc - qcom,sm8350-compute-noc - qcom,sm8350-system-noc + - qcom,sm8450-aggre1-noc + - qcom,sm8450-aggre2-noc + - qcom,sm8450-clk-virt + - qcom,sm8450-config-noc + - qcom,sm8450-gem-noc + - qcom,sm8450-lpass-ag-noc + - qcom,sm8450-mc-virt + - qcom,sm8450-mmss-noc + - qcom,sm8450-nsp-noc + - qcom,sm8450-pcie-anoc + - qcom,sm8450-system-noc '#interconnect-cells': enum: [ 1, 2 ] diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml deleted file mode 100644 index bcd41e491f1d..000000000000 --- a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml +++ /dev/null @@ -1,185 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/interconnect/qcom,sdm660.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm SDM660 Network-On-Chip interconnect - -maintainers: - - AngeloGioacchino Del Regno <kholk11@gmail.com> - -description: | - The Qualcomm SDM660 interconnect providers support adjusting the - bandwidth requirements between the various NoC fabrics. - -properties: - reg: - maxItems: 1 - - compatible: - enum: - - qcom,sdm660-a2noc - - qcom,sdm660-bimc - - qcom,sdm660-cnoc - - qcom,sdm660-gnoc - - qcom,sdm660-mnoc - - qcom,sdm660-snoc - - '#interconnect-cells': - const: 1 - - clocks: - minItems: 1 - maxItems: 7 - - clock-names: - minItems: 1 - maxItems: 7 - -required: - - compatible - - reg - - '#interconnect-cells' - - clock-names - - clocks - -additionalProperties: false - -allOf: - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm660-mnoc - then: - properties: - clocks: - items: - - description: Bus Clock. - - description: Bus A Clock. - - description: CPU-NoC High-performance Bus Clock. - clock-names: - items: - - const: bus - - const: bus_a - - const: iface - - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm660-a2noc - then: - properties: - clocks: - items: - - description: Bus Clock. - - description: Bus A Clock. - - description: IPA Clock. - - description: UFS AXI Clock. - - description: Aggregate2 UFS AXI Clock. - - description: Aggregate2 USB3 AXI Clock. - - description: Config NoC USB2 AXI Clock. - clock-names: - items: - - const: bus - - const: bus_a - - const: ipa - - const: ufs_axi - - const: aggre2_ufs_axi - - const: aggre2_usb3_axi - - const: cfg_noc_usb2_axi - - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm660-bimc - - qcom,sdm660-cnoc - - qcom,sdm660-gnoc - - qcom,sdm660-snoc - then: - properties: - clocks: - items: - - description: Bus Clock. - - description: Bus A Clock. - clock-names: - items: - - const: bus - - const: bus_a - -examples: - - | - #include <dt-bindings/clock/qcom,rpmcc.h> - #include <dt-bindings/clock/qcom,mmcc-sdm660.h> - #include <dt-bindings/clock/qcom,gcc-sdm660.h> - - bimc: interconnect@1008000 { - compatible = "qcom,sdm660-bimc"; - reg = <0x01008000 0x78000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_BIMC_CLK>, - <&rpmcc RPM_SMD_BIMC_A_CLK>; - }; - - cnoc: interconnect@1500000 { - compatible = "qcom,sdm660-cnoc"; - reg = <0x01500000 0x10000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_CNOC_CLK>, - <&rpmcc RPM_SMD_CNOC_A_CLK>; - }; - - snoc: interconnect@1626000 { - compatible = "qcom,sdm660-snoc"; - reg = <0x01626000 0x7090>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_SNOC_CLK>, - <&rpmcc RPM_SMD_SNOC_A_CLK>; - }; - - a2noc: interconnect@1704000 { - compatible = "qcom,sdm660-a2noc"; - reg = <0x01704000 0xc100>; - #interconnect-cells = <1>; - clock-names = "bus", - "bus_a", - "ipa", - "ufs_axi", - "aggre2_ufs_axi", - "aggre2_usb3_axi", - "cfg_noc_usb2_axi"; - clocks = <&rpmcc RPM_SMD_AGGR2_NOC_CLK>, - <&rpmcc RPM_SMD_AGGR2_NOC_A_CLK>, - <&rpmcc RPM_SMD_IPA_CLK>, - <&gcc GCC_UFS_AXI_CLK>, - <&gcc GCC_AGGRE2_UFS_AXI_CLK>, - <&gcc GCC_AGGRE2_USB3_AXI_CLK>, - <&gcc GCC_CFG_NOC_USB2_AXI_CLK>; - }; - - mnoc: interconnect@1745000 { - compatible = "qcom,sdm660-mnoc"; - reg = <0x01745000 0xa010>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a", "iface"; - clocks = <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK>, - <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK_A>, - <&mmcc AHB_CLK_SRC>; - }; - - gnoc: interconnect@17900000 { - compatible = "qcom,sdm660-gnoc"; - reg = <0x17900000 0xe000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&xo_board>, <&xo_board>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt index 23b18b92c558..bde63f8f090e 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt @@ -18,6 +18,7 @@ Required properties: "amlogic,meson-g12a-gpio-intc" for G12A SoCs (S905D2, S905X2, S905Y2) "amlogic,meson-sm1-gpio-intc" for SM1 SoCs (S905D3, S905X3, S905Y3) "amlogic,meson-a1-gpio-intc" for A1 SoCs (A113L) + "amlogic,meson-s4-gpio-intc" for S4 SoCs (S802X2, S905Y4, S805X2G, S905W2) - reg : Specifies base physical address and size of the registers. - interrupt-controller : Identifies the node as an interrupt controller. - #interrupt-cells : Specifies the number of cells needed to encode an diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml index 97359024709a..85c85b694217 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -56,6 +56,8 @@ properties: - 1: virtual HV timer - 2: physical guest timer - 3: virtual guest timer + - 4: 'efficient' CPU PMU + - 5: 'performance' CPU PMU The 3rd cell contains the interrupt flags. This is normally IRQ_TYPE_LEVEL_HIGH (4). @@ -68,6 +70,35 @@ properties: power-domains: maxItems: 1 + affinities: + type: object + additionalProperties: false + description: + FIQ affinity can be expressed as a single "affinities" node, + containing a set of sub-nodes, one per FIQ with a non-default + affinity. + patternProperties: + "^.+-affinity$": + type: object + additionalProperties: false + properties: + apple,fiq-index: + description: + The interrupt number specified as a FIQ, and for which + the affinity is not the default. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 5 + + cpus: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should be a list of phandles to CPU nodes (as described in + Documentation/devicetree/bindings/arm/cpus.yaml). + + required: + - fiq-index + - cpus + required: - compatible - '#interrupt-cells' diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml new file mode 100644 index 000000000000..47a78a167aba --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/apple,aic2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple Interrupt Controller 2 + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + The Apple Interrupt Controller 2 is a simple interrupt controller present on + Apple ARM SoC platforms starting with t600x (M1 Pro and Max). + + It provides the following features: + + - Level-triggered hardware IRQs wired to SoC blocks + - Single mask bit per IRQ + - Automatic masking on event delivery (auto-ack) + - Software triggering (ORed with hw line) + - Automatic prioritization (single event/ack register per CPU, lower IRQs = + higher priority) + - Automatic masking on ack + - Support for multiple dies + + This device also represents the FIQ interrupt sources on platforms using AIC, + which do not go through a discrete interrupt controller. It also handles + FIQ-based Fast IPIs. + +properties: + compatible: + items: + - const: apple,t6000-aic + - const: apple,aic2 + + interrupt-controller: true + + '#interrupt-cells': + const: 4 + description: | + The 1st cell contains the interrupt type: + - 0: Hardware IRQ + - 1: FIQ + + The 2nd cell contains the die ID. + + The next cell contains the interrupt number. + - HW IRQs: interrupt number + - FIQs: + - 0: physical HV timer + - 1: virtual HV timer + - 2: physical guest timer + - 3: virtual guest timer + + The last cell contains the interrupt flags. This is normally + IRQ_TYPE_LEVEL_HIGH (4). + + reg: + items: + - description: Address and size of the main AIC2 registers. + - description: Address and size of the AIC2 Event register. + + reg-names: + items: + - const: core + - const: event + + power-domains: + maxItems: 1 + +required: + - compatible + - '#interrupt-cells' + - interrupt-controller + - reg + - reg-names + +additionalProperties: false + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + aic: interrupt-controller@28e100000 { + compatible = "apple,t6000-aic", "apple,aic2"; + #interrupt-cells = <4>; + interrupt-controller; + reg = <0x2 0x8e100000 0x0 0xc000>, + <0x2 0x8e10c000 0x0 0x4>; + reg-names = "core", "event"; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml index c84f9fe7f254..cfb3ec27bd2b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml @@ -239,6 +239,7 @@ examples: }; }; + - | interrupt-controller@2c010000 { compatible = "arm,gic-v3"; #interrupt-cells = <4>; @@ -254,7 +255,7 @@ examples: <0x2c040000 0x2000>, // GICC <0x2c060000 0x2000>, // GICH <0x2c080000 0x2000>; // GICV - interrupts = <1 9 4>; + interrupts = <1 9 4 0>; msi-controller@2c200000 { compatible = "arm,gic-v3-its"; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt deleted file mode 100644 index 37aea40d5430..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt +++ /dev/null @@ -1,39 +0,0 @@ -Broadcom BCM3380-style Level 1 / Level 2 interrupt controller - -This interrupt controller shows up in various forms on many BCM338x/BCM63xx -chipsets. It has the following properties: - -- outputs a single interrupt signal to its interrupt controller parent - -- contains one or more enable/status word pairs, which often appear at - different offsets in different blocks - -- no atomic set/clear operations - -Required properties: - -- compatible: should be "brcm,bcm3380-l2-intc" -- reg: specifies one or more enable/status pairs, in the following format: - <enable_reg 0x4 status_reg 0x4>... -- interrupt-controller: identifies the node as an interrupt controller -- #interrupt-cells: specifies the number of cells needed to encode an interrupt - source, should be 1. -- interrupts: specifies the interrupt line in the interrupt-parent controller - node, valid values depend on the type of parent interrupt controller - -Optional properties: - -- brcm,irq-can-wake: if present, this means the L2 controller can be used as a - wakeup source for system suspend/resume. - -Example: - -irq0_intc: interrupt-controller@10000020 { - compatible = "brcm,bcm3380-l2-intc"; - reg = <0x10000024 0x4 0x1000002c 0x4>, - <0x10000020 0x4 0x10000028 0x4>; - interrupt-controller; - #interrupt-cells = <1>; - interrupt-parent = <&cpu_intc>; - interrupts = <2>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt deleted file mode 100644 index 5ddef1dc0c1a..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt +++ /dev/null @@ -1,61 +0,0 @@ -Broadcom BCM7038-style Level 1 interrupt controller - -This block is a first level interrupt controller that is typically connected -directly to one of the HW INT lines on each CPU. Every BCM7xxx set-top chip -since BCM7038 has contained this hardware. - -Key elements of the hardware design include: - -- 64, 96, 128, or 160 incoming level IRQ lines - -- Most onchip peripherals are wired directly to an L1 input - -- A separate instance of the register set for each CPU, allowing individual - peripheral IRQs to be routed to any CPU - -- Atomic mask/unmask operations - -- No polarity/level/edge settings - -- No FIFO or priority encoder logic; software is expected to read all - 2-5 status words to determine which IRQs are pending - -Required properties: - -- compatible: should be "brcm,bcm7038-l1-intc" -- reg: specifies the base physical address and size of the registers; - the number of supported IRQs is inferred from the size argument -- interrupt-controller: identifies the node as an interrupt controller -- #interrupt-cells: specifies the number of cells needed to encode an interrupt - source, should be 1. -- interrupts: specifies the interrupt line(s) in the interrupt-parent controller - node; valid values depend on the type of parent interrupt controller - -Optional properties: - -- brcm,irq-can-wake: If present, this means the L1 controller can be used as a - wakeup source for system suspend/resume. - -Optional properties: - -- brcm,int-fwd-mask: if present, a bit mask to indicate which interrupts - have already been configured by the firmware and should be left unmanaged. - This should have one 32-bit word per status/set/clear/mask group. - -If multiple reg ranges and interrupt-parent entries are present on an SMP -system, the driver will allow IRQ SMP affinity to be set up through the -/proc/irq/ interface. In the simplest possible configuration, only one -reg range and one interrupt-parent is needed. - -Example: - -periph_intc: periph_intc@1041a400 { - compatible = "brcm,bcm7038-l1-intc"; - reg = <0x1041a400 0x30 0x1041a600 0x30>; - - interrupt-controller; - #interrupt-cells = <1>; - - interrupt-parent = <&cpu_intc>; - interrupts = <2>, <3>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml new file mode 100644 index 000000000000..5ecb6faa70dc --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm7038-l1-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM7038-style Level 1 interrupt controller + +description: > + This block is a first level interrupt controller that is typically connected + directly to one of the HW INT lines on each CPU. Every BCM7xxx set-top chip + since BCM7038 has contained this hardware. + + Key elements of the hardware design include: + + - 64, 96, 128, or 160 incoming level IRQ lines + + - Most onchip peripherals are wired directly to an L1 input + + - A separate instance of the register set for each CPU, allowing individual + peripheral IRQs to be routed to any CPU + + - Atomic mask/unmask operations + + - No polarity/level/edge settings + + - No FIFO or priority encoder logic; software is expected to read all + 2-5 status words to determine which IRQs are pending + + If multiple reg ranges and interrupt-parent entries are present on an SMP + system, the driver will allow IRQ SMP affinity to be set up through the + /proc/irq/ interface. In the simplest possible configuration, only one + reg range and one interrupt-parent is needed. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + const: brcm,bcm7038-l1-intc + + reg: + description: > + Specifies the base physical address and size of the registers + the number of supported IRQs is inferred from the size argument + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + interrupts: + description: > + Specifies the interrupt line(s) in the interrupt-parent controller node; + valid values depend on the type of parent interrupt controller + + brcm,irq-can-wake: + type: boolean + description: > + If present, this means the L1 controller can be used as a + wakeup source for system suspend/resume. + + brcm,int-fwd-mask: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + If present, a bit mask to indicate which interrupts have already been + configured by the firmware and should be left unmanaged. This should + have one 32-bit word per status/set/clear/mask group. + +required: + - compatible + - reg + - interrupt-controller + - "#interrupt-cells" + - interrupts + +additionalProperties: false + +examples: + - | + periph_intc: interrupt-controller@1041a400 { + compatible = "brcm,bcm7038-l1-intc"; + reg = <0x1041a400 0x30>, <0x1041a600 0x30>; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&cpu_intc>; + interrupts = <2>, <3>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt deleted file mode 100644 index addd86b6ca2f..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt +++ /dev/null @@ -1,88 +0,0 @@ -Broadcom BCM7120-style Level 2 interrupt controller - -This interrupt controller hardware is a second level interrupt controller that -is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based -platforms. It can be found on BCM7xxx products starting with BCM7120. - -Such an interrupt controller has the following hardware design: - -- outputs multiple interrupts signals towards its interrupt controller parent - -- controls how some of the interrupts will be flowing, whether they will - directly output an interrupt signal towards the interrupt controller parent, - or if they will output an interrupt signal at this 2nd level interrupt - controller, in particular for UARTs - -- has one 32-bit enable word and one 32-bit status word - -- no atomic set/clear operations - -- not all bits within the interrupt controller actually map to an interrupt - -The typical hardware layout for this controller is represented below: - -2nd level interrupt line Outputs for the parent controller (e.g: ARM GIC) - -0 -----[ MUX ] ------------|==========> GIC interrupt 75 - \-----------\ - | -1 -----[ MUX ] --------)---|==========> GIC interrupt 76 - \------------| - | -2 -----[ MUX ] --------)---|==========> GIC interrupt 77 - \------------| - | -3 ---------------------| -4 ---------------------| -5 ---------------------| -7 ---------------------|---|===========> GIC interrupt 66 -9 ---------------------| -10 --------------------| -11 --------------------/ - -6 ------------------------\ - |===========> GIC interrupt 64 -8 ------------------------/ - -12 ........................ X -13 ........................ X (not connected) -.. -31 ........................ X - -Required properties: - -- compatible: should be "brcm,bcm7120-l2-intc" -- reg: specifies the base physical address and size of the registers -- interrupt-controller: identifies the node as an interrupt controller -- #interrupt-cells: specifies the number of cells needed to encode an interrupt - source, should be 1. -- interrupts: specifies the interrupt line(s) in the interrupt-parent controller - node, valid values depend on the type of parent interrupt controller -- brcm,int-map-mask: 32-bits bit mask describing how many and which interrupts - are wired to this 2nd level interrupt controller, and how they match their - respective interrupt parents. Should match exactly the number of interrupts - specified in the 'interrupts' property. - -Optional properties: - -- brcm,irq-can-wake: if present, this means the L2 controller can be used as a - wakeup source for system suspend/resume. - -- brcm,int-fwd-mask: if present, a bit mask to configure the interrupts which - have a mux gate, typically UARTs. Setting these bits will make their - respective interrupt outputs bypass this 2nd level interrupt controller - completely; it is completely transparent for the interrupt controller - parent. This should have one 32-bit word per enable/status pair. - -Example: - -irq0_intc: interrupt-controller@f0406800 { - compatible = "brcm,bcm7120-l2-intc"; - interrupt-parent = <&intc>; - #interrupt-cells = <1>; - reg = <0xf0406800 0x8>; - interrupt-controller; - interrupts = <0x0 0x42 0x0>, <0x0 0x40 0x0>; - brcm,int-map-mask = <0xeb8>, <0x140>; - brcm,int-fwd-mask = <0x7>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml new file mode 100644 index 000000000000..46b2eb3c43ee --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml @@ -0,0 +1,151 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm7120-l2-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM7120-style Level 2 and Broadcom BCM3380 Level 1 / Level 2 + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +description: > + This interrupt controller hardware is a second level interrupt controller that + is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based + platforms. It can be found on BCM7xxx products starting with BCM7120. + + Such an interrupt controller has the following hardware design: + + - outputs multiple interrupts signals towards its interrupt controller parent + + - controls how some of the interrupts will be flowing, whether they will + directly output an interrupt signal towards the interrupt controller parent, + or if they will output an interrupt signal at this 2nd level interrupt + controller, in particular for UARTs + + - has one 32-bit enable word and one 32-bit status word + + - no atomic set/clear operations + + - not all bits within the interrupt controller actually map to an interrupt + + The typical hardware layout for this controller is represented below: + + 2nd level interrupt line Outputs for the parent controller (e.g: ARM GIC) + + 0 -----[ MUX ] ------------|==========> GIC interrupt 75 + \-----------\ + | + 1 -----[ MUX ] --------)---|==========> GIC interrupt 76 + \------------| + | + 2 -----[ MUX ] --------)---|==========> GIC interrupt 77 + \------------| + | + 3 ---------------------| + 4 ---------------------| + 5 ---------------------| + 7 ---------------------|---|===========> GIC interrupt 66 + 9 ---------------------| + 10 --------------------| + 11 --------------------/ + + 6 ------------------------\ + |===========> GIC interrupt 64 + 8 ------------------------/ + + 12 ........................ X + 13 ........................ X (not connected) + .. + 31 ........................ X + + The BCM3380 Level 1 / Level 2 interrrupt controller shows up in various forms + on many BCM338x/BCM63xx chipsets. It has the following properties: + + - outputs a single interrupt signal to its interrupt controller parent + + - contains one or more enable/status word pairs, which often appear at + different offsets in different blocks + + - no atomic set/clear operations + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - enum: + - brcm,bcm7120-l2-intc + - brcm,bcm3380-l2-intc + + reg: + minItems: 1 + maxItems: 4 + description: > + Specifies the base physical address and size of the registers + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + interrupts: + minItems: 1 + maxItems: 32 + + brcm,int-map-mask: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: > + 32-bits bit mask describing how many and which interrupts are wired to + this 2nd level interrupt controller, and how they match their respective + interrupt parents. Should match exactly the number of interrupts + specified in the 'interrupts' property. + + brcm,irq-can-wake: + type: boolean + description: > + If present, this means the L2 controller can be used as a wakeup source + for system suspend/resume. + + brcm,int-fwd-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + if present, a bit mask to configure the interrupts which have a mux gate, + typically UARTs. Setting these bits will make their respective interrupt + outputs bypass this 2nd level interrupt controller completely; it is + completely transparent for the interrupt controller parent. This should + have one 32-bit word per enable/status pair. + +additionalProperties: false + +required: + - compatible + - reg + - interrupt-controller + - "#interrupt-cells" + - interrupts + +examples: + - | + irq0_intc: interrupt-controller@f0406800 { + compatible = "brcm,bcm7120-l2-intc"; + interrupt-parent = <&intc>; + #interrupt-cells = <1>; + reg = <0xf0406800 0x8>; + interrupt-controller; + interrupts = <0x0 0x42 0x0>, <0x0 0x40 0x0>; + brcm,int-map-mask = <0xeb8>, <0x140>; + brcm,int-fwd-mask = <0x7>; + }; + + - | + irq1_intc: interrupt-controller@10000020 { + compatible = "brcm,bcm3380-l2-intc"; + reg = <0x10000024 0x4>, <0x1000002c 0x4>, + <0x10000020 0x4>, <0x10000028 0x4>; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&cpu_intc>; + interrupts = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt deleted file mode 100644 index 021cf822395c..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt +++ /dev/null @@ -1,31 +0,0 @@ -Broadcom Generic Level 2 Interrupt Controller - -Required properties: - -- compatible: should be one of: - "brcm,hif-spi-l2-intc" or - "brcm,upg-aux-aon-l2-intc" or - "brcm,l2-intc" for latched interrupt controllers - should be "brcm,bcm7271-l2-intc" for level interrupt controllers -- reg: specifies the base physical address and size of the registers -- interrupt-controller: identifies the node as an interrupt controller -- #interrupt-cells: specifies the number of cells needed to encode an - interrupt source. Should be 1. -- interrupts: specifies the interrupt line in the interrupt-parent irq space - to be used for cascading - -Optional properties: - -- brcm,irq-can-wake: If present, this means the L2 controller can be used as a - wakeup source for system suspend/resume. - -Example: - -hif_intr2_intc: interrupt-controller@f0441000 { - compatible = "brcm,l2-intc"; - reg = <0xf0441000 0x30>; - interrupt-controller; - #interrupt-cells = <1>; - interrupt-parent = <&intc>; - interrupts = <0x0 0x20 0x0>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml new file mode 100644 index 000000000000..8961afca96f1 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/brcm,l2-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Generic Level 2 Interrupt Controller + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,hif-spi-l2-intc + - brcm,upg-aux-aon-l2-intc + - const: brcm,l2-intc + - items: + - enum: + - brcm,bcm2711-l2-intc + - const: brcm,l2-intc + - items: + - const: brcm,bcm7271-l2-intc + - items: + - const: brcm,l2-intc + + reg: + maxItems: 1 + description: > + Specifies the base physical address and size of the registers + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + interrupts: + maxItems: 1 + + interrupt-names: + maxItems: 1 + + brcm,irq-can-wake: + type: boolean + description: > + If present, this means the L2 controller can be used as a wakeup source + for system suspend/resume. + +additionalProperties: false + +required: + - compatible + - reg + - interrupt-controller + - "#interrupt-cells" + - interrupts + +examples: + - | + hif_intr2_intc: interrupt-controller@f0441000 { + compatible = "brcm,l2-intc"; + reg = <0xf0441000 0x30>; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&intc>; + interrupts = <0x0 0x20 0x0>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml new file mode 100644 index 000000000000..509d20c091af --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/qcom,mpm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcom MPM Interrupt Controller + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +description: + Qualcomm Technologies Inc. SoCs based on the RPM architecture have a + MSM Power Manager (MPM) that is in always-on domain. In addition to managing + resources during sleep, the hardware also has an interrupt controller that + monitors the interrupts when the system is asleep, wakes up the APSS when + one of these interrupts occur and replays it to GIC interrupt controller + after GIC becomes operational. + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - const: qcom,mpm + + reg: + maxItems: 1 + description: + Specifies the base address and size of vMPM registers in RPM MSG RAM. + + interrupts: + maxItems: 1 + description: + Specify the IRQ used by RPM to wakeup APSS. + + mboxes: + maxItems: 1 + description: + Specify the mailbox used to notify RPM for writing vMPM registers. + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + description: + The first cell is the MPM pin number for the interrupt, and the second + is the trigger type. + + qcom,mpm-pin-count: + description: + Specify the total MPM pin count that a SoC supports. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,mpm-pin-map: + description: + A set of MPM pin numbers and the corresponding GIC SPIs. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: MPM pin number + - description: GIC SPI number for the MPM pin + +required: + - compatible + - reg + - interrupts + - mboxes + - interrupt-controller + - '#interrupt-cells' + - qcom,mpm-pin-count + - qcom,mpm-pin-map + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + mpm: interrupt-controller@45f01b8 { + compatible = "qcom,mpm"; + interrupts = <GIC_SPI 197 IRQ_TYPE_EDGE_RISING>; + reg = <0x45f01b8 0x1000>; + mboxes = <&apcs_glb 1>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&intc>; + qcom,mpm-pin-count = <96>; + qcom,mpm-pin-map = <2 275>, + <5 296>, + <12 422>, + <24 79>, + <86 183>, + <90 260>, + <91 260>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml index 79d0358e2f61..620f01775e42 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml @@ -36,6 +36,7 @@ properties: - renesas,intc-ex-r8a77980 # R-Car V3H - renesas,intc-ex-r8a77990 # R-Car E3 - renesas,intc-ex-r8a77995 # R-Car D3 + - renesas,intc-ex-r8a779a0 # R-Car V3U - const: renesas,irqc '#interrupt-cells': diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index 28b6b17fe4b2..27092c6a86c4 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -35,6 +35,10 @@ description: contains a specific memory layout, which is documented in chapter 8 of the SiFive U5 Coreplex Series Manual <https://static.dev.sifive.com/U54-MC-RVCoreIP.pdf>. + The thead,c900-plic is different from sifive,plic-1.0.0 in opensbi, the + T-HEAD PLIC implementation requires setting a delegation bit to allow access + from S-mode. So add thead,c900-plic to distinguish them. + maintainers: - Sagar Kadam <sagar.kadam@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> @@ -42,12 +46,17 @@ maintainers: properties: compatible: - items: - - enum: - - sifive,fu540-c000-plic - - starfive,jh7100-plic - - canaan,k210-plic - - const: sifive,plic-1.0.0 + oneOf: + - items: + - enum: + - sifive,fu540-c000-plic + - starfive,jh7100-plic + - canaan,k210-plic + - const: sifive,plic-1.0.0 + - items: + - enum: + - allwinner,sun20i-d1-plic + - const: thead,c900-plic reg: maxItems: 1 @@ -62,6 +71,7 @@ properties: interrupts-extended: minItems: 1 + maxItems: 15872 description: Specifies which contexts are connected to the PLIC, with "-1" specifying that a context is not present. Each node pointed to should be a @@ -90,12 +100,11 @@ examples: #interrupt-cells = <1>; compatible = "sifive,fu540-c000-plic", "sifive,plic-1.0.0"; interrupt-controller; - interrupts-extended = < - &cpu0_intc 11 - &cpu1_intc 11 &cpu1_intc 9 - &cpu2_intc 11 &cpu2_intc 9 - &cpu3_intc 11 &cpu3_intc 9 - &cpu4_intc 11 &cpu4_intc 9>; + interrupts-extended = <&cpu0_intc 11>, + <&cpu1_intc 11>, <&cpu1_intc 9>, + <&cpu2_intc 11>, <&cpu2_intc 9>, + <&cpu3_intc 11>, <&cpu3_intc 9>, + <&cpu4_intc 11>, <&cpu4_intc 9>; reg = <0xc000000 0x4000000>; riscv,ndev = <10>; }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml index d19c881b4abc..e44daa09b137 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml @@ -20,6 +20,7 @@ properties: - items: - enum: - st,stm32mp1-exti + - st,stm32mp13-exti - const: syscon "#interrupt-cells": diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index f66a3effba73..da5381c8ee11 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -38,10 +38,12 @@ properties: - qcom,sc7280-smmu-500 - qcom,sc8180x-smmu-500 - qcom,sdm845-smmu-500 + - qcom,sdx55-smmu-500 - qcom,sm6350-smmu-500 - qcom,sm8150-smmu-500 - qcom,sm8250-smmu-500 - qcom,sm8350-smmu-500 + - qcom,sm8450-smmu-500 - const: arm,mmu-500 - description: Qcom Adreno GPUs implementing "arm,smmu-v2" items: diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt deleted file mode 100644 index a555d94084b7..000000000000 --- a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt +++ /dev/null @@ -1,319 +0,0 @@ -LEDs connected to Broadcom BCM6328 controller - -This controller is present on BCM6318, BCM6328, BCM6362 and BCM63268. -In these SoCs it's possible to control LEDs both as GPIOs or by hardware. -However, on some devices there are Serial LEDs (LEDs connected to a 74x164 -controller), which can either be controlled by software (exporting the 74x164 -as spi-gpio. See Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml), -or by hardware using this driver. -Some of these Serial LEDs are hardware controlled (e.g. ethernet LEDs) and -exporting the 74x164 as spi-gpio prevents those LEDs to be hardware -controlled, so the only chance to keep them working is by using this driver. - -BCM6328 LED controller has a HWDIS register, which controls whether a LED -should be controlled by a hardware signal instead of the MODE register value, -with 0 meaning hardware control enabled and 1 hardware control disabled. This -is usually 1:1 for hardware to LED signals, but through the activity/link -registers you have some limited control over rerouting the LEDs (as -explained later in brcm,link-signal-sources). Even if a LED is hardware -controlled you are still able to make it blink or light it up if it isn't, -but you can't turn it off if the hardware decides to light it up. For this -reason, hardware controlled LEDs aren't registered as LED class devices. - -Required properties: - - compatible : should be "brcm,bcm6328-leds". - - #address-cells : must be 1. - - #size-cells : must be 0. - - reg : BCM6328 LED controller address and size. - -Optional properties: - - brcm,serial-leds : Boolean, enables Serial LEDs. - Default : false - - brcm,serial-mux : Boolean, enables Serial LEDs multiplexing. - Default : false - - brcm,serial-clk-low : Boolean, makes clock signal active low. - Default : false - - brcm,serial-dat-low : Boolean, makes data signal active low. - Default : false - - brcm,serial-shift-inv : Boolean, inverts Serial LEDs shift direction. - Default : false - -Each LED is represented as a sub-node of the brcm,bcm6328-leds device. - -LED sub-node required properties: - - reg : LED pin number (only LEDs 0 to 23 are valid). - -LED sub-node optional properties: - a) Optional properties for sub-nodes related to software controlled LEDs: - - label : see Documentation/devicetree/bindings/leds/common.txt - - active-low : Boolean, makes LED active low. - Default : false - - default-state : see - Documentation/devicetree/bindings/leds/common.txt - - linux,default-trigger : see - Documentation/devicetree/bindings/leds/common.txt - - b) Optional properties for sub-nodes related to hardware controlled LEDs: - - brcm,hardware-controlled : Boolean, makes this LED hardware controlled. - Default : false - - brcm,link-signal-sources : An array of hardware link - signal sources. Up to four link hardware signals can get muxed into - these LEDs. Only valid for LEDs 0 to 7, where LED signals 0 to 3 may - be muxed to LEDs 0 to 3, and signals 4 to 7 may be muxed to LEDs - 4 to 7. A signal can be muxed to more than one LED, and one LED can - have more than one source signal. - - brcm,activity-signal-sources : An array of hardware activity - signal sources. Up to four activity hardware signals can get muxed into - these LEDs. Only valid for LEDs 0 to 7, where LED signals 0 to 3 may - be muxed to LEDs 0 to 3, and signals 4 to 7 may be muxed to LEDs - 4 to 7. A signal can be muxed to more than one LED, and one LED can - have more than one source signal. - -Examples: -Scenario 1 : BCM6328 with 4 EPHY LEDs - leds0: led-controller@10000800 { - compatible = "brcm,bcm6328-leds"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x10000800 0x24>; - - alarm_red@2 { - reg = <2>; - active-low; - label = "red:alarm"; - }; - inet_green@3 { - reg = <3>; - active-low; - label = "green:inet"; - }; - power_green@4 { - reg = <4>; - active-low; - label = "green:power"; - default-state = "on"; - }; - ephy0_spd@17 { - reg = <17>; - brcm,hardware-controlled; - }; - ephy1_spd@18 { - reg = <18>; - brcm,hardware-controlled; - }; - ephy2_spd@19 { - reg = <19>; - brcm,hardware-controlled; - }; - ephy3_spd@20 { - reg = <20>; - brcm,hardware-controlled; - }; - }; - -Scenario 2 : BCM63268 with Serial/GPHY0 LEDs - leds0: led-controller@10001900 { - compatible = "brcm,bcm6328-leds"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x10001900 0x24>; - brcm,serial-leds; - brcm,serial-dat-low; - brcm,serial-shift-inv; - - gphy0_spd0@0 { - reg = <0>; - brcm,hardware-controlled; - brcm,link-signal-sources = <0>; - }; - gphy0_spd1@1 { - reg = <1>; - brcm,hardware-controlled; - brcm,link-signal-sources = <1>; - }; - inet_red@2 { - reg = <2>; - active-low; - label = "red:inet"; - }; - dsl_green@3 { - reg = <3>; - active-low; - label = "green:dsl"; - }; - usb_green@4 { - reg = <4>; - active-low; - label = "green:usb"; - }; - wps_green@7 { - reg = <7>; - active-low; - label = "green:wps"; - }; - inet_green@8 { - reg = <8>; - active-low; - label = "green:inet"; - }; - ephy0_act@9 { - reg = <9>; - brcm,hardware-controlled; - }; - ephy1_act@10 { - reg = <10>; - brcm,hardware-controlled; - }; - ephy2_act@11 { - reg = <11>; - brcm,hardware-controlled; - }; - gphy0_act@12 { - reg = <12>; - brcm,hardware-controlled; - }; - ephy0_spd@13 { - reg = <13>; - brcm,hardware-controlled; - }; - ephy1_spd@14 { - reg = <14>; - brcm,hardware-controlled; - }; - ephy2_spd@15 { - reg = <15>; - brcm,hardware-controlled; - }; - power_green@20 { - reg = <20>; - active-low; - label = "green:power"; - default-state = "on"; - }; - }; - -Scenario 3 : BCM6362 with 1 LED for each EPHY - leds0: led-controller@10001900 { - compatible = "brcm,bcm6328-leds"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x10001900 0x24>; - - usb@0 { - reg = <0>; - brcm,hardware-controlled; - brcm,link-signal-sources = <0>; - brcm,activity-signal-sources = <0>; - /* USB link/activity routed to USB LED */ - }; - inet@1 { - reg = <1>; - brcm,hardware-controlled; - brcm,activity-signal-sources = <1>; - /* INET activity routed to INET LED */ - }; - ephy0@4 { - reg = <4>; - brcm,hardware-controlled; - brcm,link-signal-sources = <4>; - /* EPHY0 link routed to EPHY0 LED */ - }; - ephy1@5 { - reg = <5>; - brcm,hardware-controlled; - brcm,link-signal-sources = <5>; - /* EPHY1 link routed to EPHY1 LED */ - }; - ephy2@6 { - reg = <6>; - brcm,hardware-controlled; - brcm,link-signal-sources = <6>; - /* EPHY2 link routed to EPHY2 LED */ - }; - ephy3@7 { - reg = <7>; - brcm,hardware-controlled; - brcm,link-signal-sources = <7>; - /* EPHY3 link routed to EPHY3 LED */ - }; - power_green@20 { - reg = <20>; - active-low; - label = "green:power"; - default-state = "on"; - }; - }; - -Scenario 4 : BCM6362 with 1 LED for all EPHYs - leds0: led-controller@10001900 { - compatible = "brcm,bcm6328-leds"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x10001900 0x24>; - - usb@0 { - reg = <0>; - brcm,hardware-controlled; - brcm,link-signal-sources = <0 1>; - brcm,activity-signal-sources = <0 1>; - /* USB/INET link/activity routed to USB LED */ - }; - ephy@4 { - reg = <4>; - brcm,hardware-controlled; - brcm,link-signal-sources = <4 5 6 7>; - /* EPHY0/1/2/3 link routed to EPHY0 LED */ - }; - power_green@20 { - reg = <20>; - active-low; - label = "green:power"; - default-state = "on"; - }; - }; - -Scenario 5 : BCM6362 with EPHY LEDs swapped - leds0: led-controller@10001900 { - compatible = "brcm,bcm6328-leds"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x10001900 0x24>; - - usb@0 { - reg = <0>; - brcm,hardware-controlled; - brcm,link-signal-sources = <0>; - brcm,activity-signal-sources = <0 1>; - /* USB link/act and INET act routed to USB LED */ - }; - ephy0@4 { - reg = <4>; - brcm,hardware-controlled; - brcm,link-signal-sources = <7>; - /* EPHY3 link routed to EPHY0 LED */ - }; - ephy1@5 { - reg = <5>; - brcm,hardware-controlled; - brcm,link-signal-sources = <6>; - /* EPHY2 link routed to EPHY1 LED */ - }; - ephy2@6 { - reg = <6>; - brcm,hardware-controlled; - brcm,link-signal-sources = <5>; - /* EPHY1 link routed to EPHY2 LED */ - }; - ephy3@7 { - reg = <7>; - brcm,hardware-controlled; - brcm,link-signal-sources = <4>; - /* EPHY0 link routed to EPHY3 LED */ - }; - power_green@20 { - reg = <20>; - active-low; - label = "green:power"; - default-state = "on"; - }; - }; diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml new file mode 100644 index 000000000000..51cc0d82c12e --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml @@ -0,0 +1,404 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-bcm6328.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LEDs connected to Broadcom BCM6328 controller + +maintainers: + - Ãlvaro Fernández Rojas <noltari@gmail.com> + +description: | + This controller is present on BCM6318, BCM6328, BCM6362 and BCM63268. + In these SoCs it's possible to control LEDs both as GPIOs or by hardware. + However, on some devices there are Serial LEDs (LEDs connected to a 74x164 + controller), which can either be controlled by software (exporting the 74x164 + as spi-gpio. See + Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml), or by hardware + using this driver. + Some of these Serial LEDs are hardware controlled (e.g. ethernet LEDs) and + exporting the 74x164 as spi-gpio prevents those LEDs to be hardware + controlled, so the only chance to keep them working is by using this driver. + + BCM6328 LED controller has a HWDIS register, which controls whether a LED + should be controlled by a hardware signal instead of the MODE register value, + with 0 meaning hardware control enabled and 1 hardware control disabled. This + is usually 1:1 for hardware to LED signals, but through the activity/link + registers you have some limited control over rerouting the LEDs (as + explained later in brcm,link-signal-sources). Even if a LED is hardware + controlled you are still able to make it blink or light it up if it isn't, + but you can't turn it off if the hardware decides to light it up. For this + reason, hardware controlled LEDs aren't registered as LED class devices. + + Each LED is represented as a sub-node of the brcm,bcm6328-leds device. + +properties: + compatible: + const: brcm,bcm6328-leds + + reg: + maxItems: 1 + + brcm,serial-leds: + type: boolean + description: Enables Serial LEDs. + + brcm,serial-mux: + type: boolean + description: Enables Serial LEDs multiplexing. + + brcm,serial-clk-low: + type: boolean + description: Makes clock signal active low. + + brcm,serial-dat-low: + type: boolean + description: Makes data signal active low. + + brcm,serial-shift-inv: + type: boolean + description: Inverts Serial LEDs shift direction. + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "@[a-f0-9]+$": + type: object + + $ref: common.yaml# + + properties: + reg: + items: + - maximum: 23 + description: LED pin number (only LEDs 0 to 23 are valid). + + active-low: + type: boolean + description: Makes LED active low. + + brcm,hardware-controlled: + type: boolean + description: Makes this LED hardware controlled. + + brcm,link-signal-sources: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + description: > + An array of hardware link signal sources. Up to four link hardware + signals can get muxed into these LEDs. Only valid for LEDs 0 to 7, + where LED signals 0 to 3 may be muxed to LEDs 0 to 3, and signals 4 to + 7 may be muxed to LEDs 4 to 7. A signal can be muxed to more than one + LED, and one LED can have more than one source signal. + + brcm,activity-signal-sources: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + description: > + An array of hardware activity signal sources. Up to four activity + hardware signals can get muxed into these LEDs. Only valid for LEDs 0 + to 7, where LED signals 0 to 3 may be muxed to LEDs 0 to 3, and + signals 4 to 7 may be muxed to LEDs 4 to 7. A signal can be muxed to + more than one LED, and one LED can have more than one source signal. + + required: + - reg + + unevaluatedProperties: false + +required: + - reg + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + /* BCM6328 with 4 EPHY LEDs */ + led-controller@10000800 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10000800 0x24>; + + alarm_red@2 { + reg = <2>; + active-low; + label = "red:alarm"; + }; + + inet_green@3 { + reg = <3>; + active-low; + label = "green:inet"; + }; + + power_green@4 { + reg = <4>; + active-low; + label = "green:power"; + default-state = "on"; + }; + + ephy0_spd@17 { + reg = <17>; + brcm,hardware-controlled; + }; + + ephy1_spd@18 { + reg = <18>; + brcm,hardware-controlled; + }; + + ephy2_spd@19 { + reg = <19>; + brcm,hardware-controlled; + }; + + ephy3_spd@20 { + reg = <20>; + brcm,hardware-controlled; + }; + }; + - | + /* BCM63268 with Serial/GPHY0 LEDs */ + led-controller@10001900 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10001900 0x24>; + brcm,serial-leds; + brcm,serial-dat-low; + brcm,serial-shift-inv; + + gphy0_spd0@0 { + reg = <0>; + brcm,hardware-controlled; + brcm,link-signal-sources = <0>; + }; + + gphy0_spd1@1 { + reg = <1>; + brcm,hardware-controlled; + brcm,link-signal-sources = <1>; + }; + + inet_red@2 { + reg = <2>; + active-low; + label = "red:inet"; + }; + + dsl_green@3 { + reg = <3>; + active-low; + label = "green:dsl"; + }; + + usb_green@4 { + reg = <4>; + active-low; + label = "green:usb"; + }; + + wps_green@7 { + reg = <7>; + active-low; + label = "green:wps"; + }; + + inet_green@8 { + reg = <8>; + active-low; + label = "green:inet"; + }; + + ephy0_act@9 { + reg = <9>; + brcm,hardware-controlled; + }; + + ephy1_act@10 { + reg = <10>; + brcm,hardware-controlled; + }; + + ephy2_act@11 { + reg = <11>; + brcm,hardware-controlled; + }; + + gphy0_act@12 { + reg = <12>; + brcm,hardware-controlled; + }; + + ephy0_spd@13 { + reg = <13>; + brcm,hardware-controlled; + }; + + ephy1_spd@14 { + reg = <14>; + brcm,hardware-controlled; + }; + + ephy2_spd@15 { + reg = <15>; + brcm,hardware-controlled; + }; + + power_green@20 { + reg = <20>; + active-low; + label = "green:power"; + default-state = "on"; + }; + }; + - | + /* BCM6362 with 1 LED for each EPHY */ + led-controller@10001900 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10001900 0x24>; + + usb@0 { + reg = <0>; + brcm,hardware-controlled; + brcm,link-signal-sources = <0>; + brcm,activity-signal-sources = <0>; + /* USB link/activity routed to USB LED */ + }; + + inet@1 { + reg = <1>; + brcm,hardware-controlled; + brcm,activity-signal-sources = <1>; + /* INET activity routed to INET LED */ + }; + + ephy0@4 { + reg = <4>; + brcm,hardware-controlled; + brcm,link-signal-sources = <4>; + /* EPHY0 link routed to EPHY0 LED */ + }; + + ephy1@5 { + reg = <5>; + brcm,hardware-controlled; + brcm,link-signal-sources = <5>; + /* EPHY1 link routed to EPHY1 LED */ + }; + + ephy2@6 { + reg = <6>; + brcm,hardware-controlled; + brcm,link-signal-sources = <6>; + /* EPHY2 link routed to EPHY2 LED */ + }; + + ephy3@7 { + reg = <7>; + brcm,hardware-controlled; + brcm,link-signal-sources = <7>; + /* EPHY3 link routed to EPHY3 LED */ + }; + + power_green@20 { + reg = <20>; + active-low; + label = "green:power"; + default-state = "on"; + }; + }; + - | + /* BCM6362 with 1 LED for all EPHYs */ + led-controller@10001900 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10001900 0x24>; + + usb@0 { + reg = <0>; + brcm,hardware-controlled; + brcm,link-signal-sources = <0 1>; + brcm,activity-signal-sources = <0 1>; + /* USB/INET link/activity routed to USB LED */ + }; + + ephy@4 { + reg = <4>; + brcm,hardware-controlled; + brcm,link-signal-sources = <4 5 6 7>; + /* EPHY0/1/2/3 link routed to EPHY0 LED */ + }; + + power_green@20 { + reg = <20>; + active-low; + label = "green:power"; + default-state = "on"; + }; + }; + - | + /* BCM6362 with EPHY LEDs swapped */ + led-controller@10001900 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10001900 0x24>; + + usb@0 { + reg = <0>; + brcm,hardware-controlled; + brcm,link-signal-sources = <0>; + brcm,activity-signal-sources = <0 1>; + /* USB link/act and INET act routed to USB LED */ + }; + + ephy0@4 { + reg = <4>; + brcm,hardware-controlled; + brcm,link-signal-sources = <7>; + /* EPHY3 link routed to EPHY0 LED */ + }; + + ephy1@5 { + reg = <5>; + brcm,hardware-controlled; + brcm,link-signal-sources = <6>; + /* EPHY2 link routed to EPHY1 LED */ + }; + + ephy2@6 { + reg = <6>; + brcm,hardware-controlled; + brcm,link-signal-sources = <5>; + /* EPHY1 link routed to EPHY2 LED */ + }; + + ephy3@7 { + reg = <7>; + brcm,hardware-controlled; + brcm,link-signal-sources = <4>; + /* EPHY0 link routed to EPHY3 LED */ + }; + + power_green@20 { + reg = <20>; + active-low; + label = "green:power"; + default-state = "on"; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/leds-mt6360.yaml b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml new file mode 100644 index 000000000000..b2fe6eb89389 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-mt6360.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LED driver for MT6360 PMIC from MediaTek Integrated. + +maintainers: + - Gene Chen <gene_chen@richtek.com> + +description: | + This module is part of the MT6360 MFD device. + see Documentation/devicetree/bindings/mfd/mt6360.yaml + Add MT6360 LED driver include 2-channel Flash LED with torch/strobe mode, + and 4-channel RGB LED support Register/Flash/Breath Mode + +properties: + compatible: + const: mediatek,mt6360-led + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^(multi-)?led@[0-5]$": + type: object + $ref: common.yaml# + description: + Properties for a single LED. + + properties: + reg: + description: Index of the LED. + enum: + - 0 # LED output ISINK1 + - 1 # LED output ISINK2 + - 2 # LED output ISINK3 + - 3 # LED output ISINKML + - 4 # LED output FLASH1 + - 5 # LED output FLASH2 + +unevaluatedProperties: false + +required: + - compatible + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + led-controller { + compatible = "mediatek,mt6360-led"; + #address-cells = <1>; + #size-cells = <0>; + + multi-led@0 { + reg = <0>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_RGB>; + led-max-microamp = <24000>; + #address-cells = <1>; + #size-cells = <0>; + led@0 { + reg = <0>; + color = <LED_COLOR_ID_RED>; + }; + led@1 { + reg = <1>; + color = <LED_COLOR_ID_GREEN>; + }; + led@2 { + reg = <2>; + color = <LED_COLOR_ID_BLUE>; + }; + }; + led@3 { + reg = <3>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_WHITE>; + led-max-microamp = <150000>; + }; + led@4 { + reg = <4>; + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + function-enumerator = <1>; + led-max-microamp = <200000>; + flash-max-microamp = <500000>; + flash-max-timeout-us = <1024000>; + }; + led@5 { + reg = <5>; + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + function-enumerator = <2>; + led-max-microamp = <200000>; + flash-max-microamp = <500000>; + flash-max-timeout-us = <1024000>; + }; + }; + + - | + + led-controller { + compatible = "mediatek,mt6360-led"; + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_RED>; + led-max-microamp = <24000>; + }; + led@1 { + reg = <1>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_GREEN>; + led-max-microamp = <24000>; + }; + led@2 { + reg = <2>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_BLUE>; + led-max-microamp = <24000>; + }; + led@3 { + reg = <3>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_WHITE>; + led-max-microamp = <150000>; + }; + led@4 { + reg = <4>; + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + function-enumerator = <1>; + led-max-microamp = <200000>; + flash-max-microamp = <500000>; + flash-max-timeout-us = <1024000>; + }; + led@5 { + reg = <5>; + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + function-enumerator = <2>; + led-max-microamp = <200000>; + flash-max-microamp = <500000>; + flash-max-timeout-us = <1024000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml index c4255f42e801..5c5c328b3134 100644 --- a/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml @@ -27,14 +27,20 @@ properties: for example for the display controller, the system management controller and the NVMe coprocessor. items: - - const: apple,t8103-asc-mailbox + - enum: + - apple,t8103-asc-mailbox + - apple,t6000-asc-mailbox + - const: apple,asc-mailbox-v4 - description: M3 mailboxes are an older variant with a slightly different MMIO interface still found on the M1. It is used for the Thunderbolt co-processors. items: - - const: apple,t8103-m3-mailbox + - enum: + - apple,t8103-m3-mailbox + - apple,t6000-m3-mailbox + - const: apple,m3-mailbox-v2 reg: maxItems: 1 @@ -71,7 +77,7 @@ additionalProperties: false examples: - | mailbox@77408000 { - compatible = "apple,t8103-asc-mailbox"; + compatible = "apple,t8103-asc-mailbox", "apple,asc-mailbox-v4"; reg = <0x77408000 0x4000>; interrupts = <1 583 4>, <1 584 4>, <1 585 4>, <1 586 4>; interrupt-names = "send-empty", "send-not-empty", diff --git a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml index e864d798168d..d433e496ec6e 100644 --- a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml @@ -180,15 +180,6 @@ allOf: compatible: enum: - ti,am654-mailbox - then: - required: - - interrupt-parent - - - if: - properties: - compatible: - enum: - - ti,am654-mailbox - ti,am64-mailbox then: properties: diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml new file mode 100644 index 000000000000..444f24838d3d --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2021 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/maxim,max96712.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Quad GMSL2 to CSI-2 Deserializer with GMSL1 Compatibility + +maintainers: + - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se> + +description: | + The MAX96712 deserializer converts GMSL2 or GMSL1 serial inputs into MIPI + CSI-2 D-PHY or C-PHY formatted outputs. The device allows each link to + simultaneously transmit bidirectional control-channel data while forward + video transmissions are in progress. The MAX96712 can accommodate as many as + four remotely located sensors using industry-standard coax or STP + interconnects. + + Each GMSL2 serial link operates at a fixed rate of 3Gbps or 6Gbps in the + forward direction and 187.5Mbps in the reverse direction. In GMSL1 mode, the + MAX96712 can be paired with first-generation 3.12Gbps or 1.5Gbps GMSL1 + serializers or operate up to 3.12Gbps with GMSL2 serializers in GMSL1 mode. + +properties: + compatible: + const: maxim,max96712 + + reg: + description: I2C device address + maxItems: 1 + + enable-gpios: true + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 0 + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 1 + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 2 + + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 3 + + port@4: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 Output + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + + required: + - data-lanes + + required: + - port@4 + +required: + - compatible + - reg + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c@e6508000 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <0 0xe6508000>; + + gmsl0: gmsl-deserializer@49 { + compatible = "maxim,max96712"; + reg = <0x49>; + enable-gpios = <&pca9654_a 0 GPIO_ACTIVE_HIGH>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@4 { + reg = <4>; + max96712_out0: endpoint { + clock-lanes = <0>; + data-lanes = <1 2 3 4>; + remote-endpoint = <&csi40_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index 1ef849dc74d7..e2e6e9aa0fe6 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -81,14 +81,12 @@ properties: data-lanes: description: Note that 'fsl,imx7-mipi-csi2' only supports up to 2 data lines. + minItems: 1 items: - minItems: 1 - maxItems: 4 - items: - - const: 1 - - const: 2 - - const: 3 - - const: 4 + - const: 1 + - const: 2 + - const: 3 + - const: 4 required: - data-lanes diff --git a/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml index 9c04fa85ee5c..1b3e1c4b99ed 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml @@ -87,14 +87,12 @@ properties: properties: data-lanes: + minItems: 1 items: - minItems: 1 - maxItems: 4 - items: - - const: 1 - - const: 2 - - const: 3 - - const: 4 + - const: 1 + - const: 2 + - const: 3 + - const: 4 required: - data-lanes diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index 25b42d68f9b3..e188a4bf755c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -23,13 +23,20 @@ properties: items: - enum: - ti,am3352-gpmc + - ti,am64-gpmc - ti,omap2420-gpmc - ti,omap2430-gpmc - ti,omap3430-gpmc - ti,omap4430-gpmc reg: - maxItems: 1 + minItems: 1 + maxItems: 2 + + reg-names: + items: + - const: cfg + - const: data interrupts: maxItems: 1 @@ -44,6 +51,9 @@ properties: items: - const: fck + power-domains: + maxItems: 1 + dmas: items: - description: DMA channel for GPMC NAND prefetch @@ -119,11 +129,8 @@ patternProperties: The child device node represents the device connected to the GPMC bus. The device can be a NAND chip, SRAM device, NOR device or an ASIC. + $ref: "ti,gpmc-child.yaml" - allOf: - - $ref: "ti,gpmc-child.yaml" - - unevaluatedProperties: false required: - compatible @@ -133,6 +140,17 @@ required: - "#address-cells" - "#size-cells" +allOf: + - if: + properties: + compatible: + contains: + const: ti,am64-gpmc + then: + required: + - reg-names + - power-domains + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt b/Documentation/devicetree/bindings/mfd/bd9571mwv.txt deleted file mode 100644 index 1d6413e96c37..000000000000 --- a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt +++ /dev/null @@ -1,69 +0,0 @@ -* ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) bindings - -Required properties: - - compatible : Should be "rohm,bd9571mwv" or "rohm,bd9574mwf". - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : Marks the device node as an interrupt controller. - - #interrupt-cells : The number of cells to describe an IRQ, should be 2. - The first cell is the IRQ number. - The second cell is the flags, encoded as trigger - masks from ../interrupt-controller/interrupts.txt. - - gpio-controller : Marks the device node as a GPIO Controller. - - #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. - See ../gpio/gpio.txt for more information. - - regulators: : List of child nodes that specify the regulator - initialization data. Child nodes must be named - after their hardware counterparts: - - vd09 - - vd18 - - vd25 - - vd33 - - dvfs - Each child node is defined using the standard - binding for regulators. - -Optional properties: - - rohm,ddr-backup-power : Value to use for DDR-Backup Power (default 0). - This is a bitmask that specifies which DDR power - rails need to be kept powered when backup mode is - entered, for system suspend: - - bit 0: DDR0 - - bit 1: DDR1 - - bit 2: DDR0C - - bit 3: DDR1C - These bits match the KEEPON_DDR* bits in the - documentation for the "BKUP Mode Cnt" register. - - rohm,rstbmode-level: The RSTB signal is configured for level mode, to - accommodate a toggle power switch (the RSTBMODE pin is - strapped low). - - rohm,rstbmode-pulse: The RSTB signal is configured for pulse mode, to - accommodate a momentary power switch (the RSTBMODE pin - is strapped high). - The two properties above are mutually exclusive. - -Example: - - pmic: pmic@30 { - compatible = "rohm,bd9571mwv"; - reg = <0x30>; - interrupt-parent = <&gpio2>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - rohm,ddr-backup-power = <0xf>; - rohm,rstbmode-pulse; - - regulators { - dvfs: dvfs { - regulator-name = "dvfs"; - regulator-min-microvolt = <750000>; - regulator-max-microvolt = <1030000>; - regulator-boot-on; - regulator-always-on; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,cru.yaml b/Documentation/devicetree/bindings/mfd/brcm,cru.yaml index be4a2df71c25..b85819fbb07c 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,cru.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,cru.yaml @@ -39,7 +39,7 @@ patternProperties: '^phy@[a-f0-9]+$': $ref: ../phy/bcm-ns-usb2-phy.yaml - '^pin-controller@[a-f0-9]+$': + '^pinctrl@[a-f0-9]+$': $ref: ../pinctrl/brcm,ns-pinmux.yaml '^syscon@[a-f0-9]+$': @@ -94,7 +94,7 @@ examples: reg = <0x180 0x4>; }; - pin-controller@1c0 { + pinctrl@1c0 { compatible = "brcm,bcm4708-pinmux"; reg = <0x1c0 0x24>; reg-names = "cru_gpio_control"; diff --git a/Documentation/devicetree/bindings/mfd/brcm,twd.yaml b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml new file mode 100644 index 000000000000..634526f790b8 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,twd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom's Timer-Watchdog (aka TWD) + +maintainers: + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +description: | + Broadcom has a Timer-Watchdog block used in multiple SoCs (e.g., BCM4908, + BCM63xx, BCM7038). There are few variants available (they differ slightly in + registers layout). This block consists of: timers, watchdog and optionally a + software reset handler. + +properties: + compatible: + items: + - enum: + - brcm,bcm4908-twd + - brcm,bcm7038-twd + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + ranges: true + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + +patternProperties: + '^watchdog@[a-f0-9]+$': + $ref: /schemas/watchdog/brcm,bcm7038-wdt.yaml + +additionalProperties: false + +required: + - reg + +examples: + - | + timer-mfd@ff800400 { + compatible = "brcm,bcm4908-twd", "simple-mfd", "syscon"; + reg = <0xff800400 0x4c>; + ranges = <0x00000000 0xff800400 0x4c>; + + #address-cells = <1>; + #size-cells = <1>; + + watchdog@28 { + compatible = "brcm,bcm7038-wdt"; + reg = <0x28 0x8>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.yaml b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.yaml index c00ad3e21c21..ad285cb480c9 100644 --- a/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.yaml +++ b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.yaml @@ -126,7 +126,7 @@ properties: clock-frequency: const: 12288000 - lochnagar-pinctrl: + pinctrl: type: object $ref: /schemas/pinctrl/cirrus,lochnagar.yaml# @@ -255,7 +255,7 @@ required: - reg - reset-gpios - lochnagar-clk - - lochnagar-pinctrl + - pinctrl additionalProperties: false @@ -293,7 +293,7 @@ examples: clock-frequency = <32768>; }; - lochnagar-pinctrl { + pinctrl { compatible = "cirrus,lochnagar-pinctrl"; gpio-controller; diff --git a/Documentation/devicetree/bindings/mfd/cirrus,madera.yaml b/Documentation/devicetree/bindings/mfd/cirrus,madera.yaml index 499c62c04daa..68c75a517c92 100644 --- a/Documentation/devicetree/bindings/mfd/cirrus,madera.yaml +++ b/Documentation/devicetree/bindings/mfd/cirrus,madera.yaml @@ -221,7 +221,6 @@ required: - '#gpio-cells' - interrupt-controller - '#interrupt-cells' - - interrupt-parent - interrupts - AVDD-supply - DBVDD1-supply @@ -246,8 +245,7 @@ examples: interrupt-controller; #interrupt-cells = <2>; - interrupts = <&host_irq1>; - interrupt-parent = <&gic>; + interrupts = <4 1 0>; gpio-controller; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/mfd/da9063.txt b/Documentation/devicetree/bindings/mfd/da9063.txt index 8da879935c59..91b79a21d403 100644 --- a/Documentation/devicetree/bindings/mfd/da9063.txt +++ b/Documentation/devicetree/bindings/mfd/da9063.txt @@ -1,6 +1,6 @@ * Dialog DA9063/DA9063L Power Management Integrated Circuit (PMIC) -DA9093 consists of a large and varied group of sub-devices (I2C Only): +DA9063 consists of a large and varied group of sub-devices (I2C Only): Device Supply Names Description ------ ------------ ----------- diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index d793dd0316b7..4caadf73fc4a 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -8,7 +8,6 @@ title: ChromeOS Embedded Controller maintainers: - Benson Leung <bleung@chromium.org> - - Enric Balletbo i Serra <enric.balletbo@collabora.com> - Guenter Roeck <groeck@chromium.org> description: @@ -32,7 +31,7 @@ properties: controller-data: description: - SPI controller data, see bindings/spi/spi-samsung.txt + SPI controller data, see bindings/spi/samsung,spi-peripheral-props.yaml type: object google,cros-ec-spi-pre-delay: @@ -59,7 +58,7 @@ properties: whether this nvram is present or not. type: boolean - mtk,rpmsg-name: + mediatek,rpmsg-name: description: Must be defined if the cros-ec is a rpmsg device for a Mediatek ARM Cortex M4 Co-processor. Contains the name pf the rpmsg @@ -149,18 +148,21 @@ patternProperties: required: - compatible -if: - properties: - compatible: - contains: - enum: - - google,cros-ec-i2c - - google,cros-ec-rpmsg -then: - properties: - google,cros-ec-spi-pre-delay: false - google,cros-ec-spi-msg-delay: false - spi-max-frequency: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - google,cros-ec-i2c + - google,cros-ec-rpmsg + then: + properties: + google,cros-ec-spi-pre-delay: false + google,cros-ec-spi-msg-delay: false + spi-max-frequency: false + else: + $ref: /schemas/spi/spi-peripheral-props.yaml additionalProperties: false @@ -201,7 +203,7 @@ examples: spi-max-frequency = <5000000>; proximity { - compatible = "google,cros-ec-mkbp-proximity"; + compatible = "google,cros-ec-mkbp-proximity"; }; cbas { diff --git a/Documentation/devicetree/bindings/mfd/max14577.txt b/Documentation/devicetree/bindings/mfd/max14577.txt deleted file mode 100644 index be11943a0560..000000000000 --- a/Documentation/devicetree/bindings/mfd/max14577.txt +++ /dev/null @@ -1,147 +0,0 @@ -Maxim MAX14577/77836 Multi-Function Device - -MAX14577 is a Multi-Function Device with Micro-USB Interface Circuit, Li+ -Battery Charger and SFOUT LDO output for powering USB devices. It is -interfaced to host controller using I2C. - -MAX77836 additionally contains PMIC (with two LDO regulators) and Fuel Gauge. -For the description of Fuel Gauge low SOC alert interrupt see: -../power/supply/max17040_battery.txt - - -Required properties: -- compatible : Must be "maxim,max14577" or "maxim,max77836". -- reg : I2C slave address for the max14577 chip (0x25 for max14577/max77836) -- interrupts : IRQ line for the chip. - - -Required nodes: - - charger : - Node for configuring the charger driver. - Required properties: - - compatible : "maxim,max14577-charger" - or "maxim,max77836-charger" - - maxim,fast-charge-uamp : Current in uA for Fast Charge; - Valid values: - - for max14577: 90000 - 950000; - - for max77836: 45000 - 475000; - - maxim,eoc-uamp : Current in uA for End-Of-Charge mode; - Valid values: - - for max14577: 50000 - 200000; - - for max77836: 5000 - 100000; - - maxim,ovp-uvolt : OverVoltage Protection Threshold in uV; - In an overvoltage condition, INT asserts and charging - stops. Valid values: - - 6000000, 6500000, 7000000, 7500000; - - maxim,constant-uvolt : Battery Constant Voltage in uV; - Valid values: - - 4000000 - 4280000 (step by 20000); - - 4350000; - - -Optional nodes: -- max14577-muic/max77836-muic : - Node used only by extcon consumers. - Required properties: - - compatible : "maxim,max14577-muic" or "maxim,max77836-muic" - -- regulators : - Required properties: - - compatible : "maxim,max14577-regulator" - or "maxim,max77836-regulator" - - May contain a sub-node per regulator from the list below. Each - sub-node should contain the constraints and initialization information - for that regulator. See regulator.txt for a description of standard - properties for these sub-nodes. - - List of valid regulator names: - - for max14577: CHARGER, SAFEOUT. - - for max77836: CHARGER, SAFEOUT, LDO1, LDO2. - - The SAFEOUT is a fixed voltage regulator so there is no need to specify - voltages for it. - - -Example: - -#include <dt-bindings/interrupt-controller/irq.h> - -max14577@25 { - compatible = "maxim,max14577"; - reg = <0x25>; - interrupt-parent = <&gpx1>; - interrupts = <5 IRQ_TYPE_LEVEL_LOW>; - - muic: max14577-muic { - compatible = "maxim,max14577-muic"; - }; - - regulators { - compatible = "maxim,max14577-regulator"; - - SAFEOUT { - regulator-name = "SAFEOUT"; - }; - CHARGER { - regulator-name = "CHARGER"; - regulator-min-microamp = <90000>; - regulator-max-microamp = <950000>; - regulator-boot-on; - }; - }; - - charger { - compatible = "maxim,max14577-charger"; - - maxim,constant-uvolt = <4350000>; - maxim,fast-charge-uamp = <450000>; - maxim,eoc-uamp = <50000>; - maxim,ovp-uvolt = <6500000>; - }; -}; - - -max77836@25 { - compatible = "maxim,max77836"; - reg = <0x25>; - interrupt-parent = <&gpx1>; - interrupts = <5 IRQ_TYPE_LEVEL_LOW>; - - muic: max77836-muic { - compatible = "maxim,max77836-muic"; - }; - - regulators { - compatible = "maxim,max77836-regulator"; - - SAFEOUT { - regulator-name = "SAFEOUT"; - }; - CHARGER { - regulator-name = "CHARGER"; - regulator-min-microamp = <90000>; - regulator-max-microamp = <950000>; - regulator-boot-on; - }; - LDO1 { - regulator-name = "LDO1"; - regulator-min-microvolt = <2700000>; - regulator-max-microvolt = <2700000>; - }; - LDO2 { - regulator-name = "LDO2"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <3950000>; - }; - }; - - charger { - compatible = "maxim,max77836-charger"; - - maxim,constant-uvolt = <4350000>; - maxim,fast-charge-uamp = <225000>; - maxim,eoc-uamp = <7500>; - maxim,ovp-uvolt = <6500000>; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt deleted file mode 100644 index 4447d074894a..000000000000 --- a/Documentation/devicetree/bindings/mfd/max77686.txt +++ /dev/null @@ -1,26 +0,0 @@ -Maxim MAX77686 multi-function device - -MAX77686 is a Multifunction device with PMIC, RTC and Charger on chip. It is -interfaced to host controller using i2c interface. PMIC and Charger submodules -are addressed using same i2c slave address whereas RTC submodule uses -different i2c slave address,presently for which we are statically creating i2c -client while probing.This document describes the binding for mfd device and -PMIC submodule. - -Bindings for the built-in 32k clock generator block and -regulators are defined in ../clk/maxim,max77686.txt and -../regulator/max77686.txt respectively. - -Required properties: -- compatible : Must be "maxim,max77686"; -- reg : Specifies the i2c slave address of PMIC block. -- interrupts : This i2c device has an IRQ line connected to the main SoC. - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - }; diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt deleted file mode 100644 index 09decac20d91..000000000000 --- a/Documentation/devicetree/bindings/mfd/max77802.txt +++ /dev/null @@ -1,25 +0,0 @@ -Maxim MAX77802 multi-function device - -The Maxim MAX77802 is a Power Management IC (PMIC) that contains 10 high -efficiency Buck regulators, 32 Low-DropOut (LDO) regulators used to power -up application processors and peripherals, a 2-channel 32kHz clock outputs, -a Real-Time-Clock (RTC) and a I2C interface to program the individual -regulators, clocks outputs and the RTC. - -Bindings for the built-in 32k clock generator block and -regulators are defined in ../clk/maxim,max77802.txt and -../regulator/max77802.txt respectively. - -Required properties: -- compatible : Must be "maxim,max77802" -- reg : Specifies the I2C slave address of PMIC block. -- interrupts : I2C device IRQ line connected to the main SoC. - -Example: - - max77802: pmic@9 { - compatible = "maxim,max77802"; - interrupt-parent = <&intc>; - interrupts = <26 IRQ_TYPE_NONE>; - reg = <0x09>; - }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max14577.yaml b/Documentation/devicetree/bindings/mfd/maxim,max14577.yaml new file mode 100644 index 000000000000..27870b8760a6 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max14577.yaml @@ -0,0 +1,195 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max14577.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX14577/MAX77836 MicroUSB and Companion Power Management IC + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX14577/MAX77836 MicroUSB + Integrated Circuit (MUIC). + + The Maxim MAX14577 is a MicroUSB and Companion Power Management IC which + includes voltage safeout regulators, charger and MicroUSB management IC. + + The Maxim MAX77836 is a MicroUSB and Companion Power Management IC which + includes voltage safeout and LDO regulators, charger, fuel-gauge and MicroUSB + management IC. + +properties: + compatible: + enum: + - maxim,max14577 + - maxim,max77836 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + wakeup-source: true + + charger: + $ref: /schemas/power/supply/maxim,max14577.yaml + + extcon: + type: object + properties: + compatible: + enum: + - maxim,max14577-muic + - maxim,max77836-muic + + required: + - compatible + + regulators: + $ref: /schemas/regulator/maxim,max14577.yaml + +required: + - compatible + - interrupts + - reg + - charger + +allOf: + - if: + properties: + compatible: + contains: + const: maxim,max14577 + then: + properties: + charger: + properties: + compatible: + const: maxim,max14577-charger + extcon: + properties: + compatible: + const: maxim,max14577-muic + regulator: + properties: + compatible: + const: maxim,max14577-regulator + else: + properties: + charger: + properties: + compatible: + const: maxim,max77836-charger + extcon: + properties: + compatible: + const: maxim,max77836-muic + regulator: + properties: + compatible: + const: maxim,max77836-regulator + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@25 { + compatible = "maxim,max14577"; + reg = <0x25>; + interrupt-parent = <&gpx1>; + interrupts = <5 IRQ_TYPE_LEVEL_LOW>; + + extcon { + compatible = "maxim,max14577-muic"; + }; + + regulators { + compatible = "maxim,max14577-regulator"; + + SAFEOUT { + regulator-name = "SAFEOUT"; + }; + + CHARGER { + regulator-name = "CHARGER"; + regulator-min-microamp = <90000>; + regulator-max-microamp = <950000>; + regulator-boot-on; + }; + }; + + charger { + compatible = "maxim,max14577-charger"; + + maxim,constant-uvolt = <4350000>; + maxim,fast-charge-uamp = <450000>; + maxim,eoc-uamp = <50000>; + maxim,ovp-uvolt = <6500000>; + }; + }; + }; + + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@25 { + compatible = "maxim,max77836"; + interrupt-parent = <&gpx1>; + interrupts = <5 IRQ_TYPE_NONE>; + reg = <0x25>; + wakeup-source; + + extcon { + compatible = "maxim,max77836-muic"; + }; + + regulators { + compatible = "maxim,max77836-regulator"; + + SAFEOUT { + regulator-name = "SAFEOUT"; + }; + + CHARGER { + regulator-name = "CHARGER"; + regulator-min-microamp = <45000>; + regulator-max-microamp = <475000>; + regulator-boot-on; + }; + + LDO1 { + regulator-name = "MOT_2.7V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <2700000>; + }; + + LDO2 { + regulator-name = "UNUSED_LDO2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3950000>; + }; + }; + + charger { + compatible = "maxim,max77836-charger"; + + maxim,constant-uvolt = <4350000>; + maxim,fast-charge-uamp = <225000>; + maxim,eoc-uamp = <7500>; + maxim,ovp-uvolt = <6500000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml new file mode 100644 index 000000000000..859655a789c3 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 is a Power Management IC which includes voltage and + current regulators, RTC and clock outputs. + + The MAX77686 provides three 32.768khz clock outputs that can be controlled + (gated/ungated) over I2C. The clock IDs are defined as preprocessor macros + in dt-bindings/clock/maxim,max77686.h. + +properties: + compatible: + const: maxim,max77686 + + '#clock-cells': + const: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + voltage-regulators: + $ref: ../regulator/maxim,max77686.yaml + description: + List of child nodes that specify the regulators. + + wakeup-source: true + +required: + - compatible + - '#clock-cells' + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + max77686: pmic@9 { + compatible = "maxim,max77686"; + reg = <0x09>; + + interrupt-parent = <&gpx0>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-0 = <&max77686_irq>; + pinctrl-names = "default"; + wakeup-source; + #clock-cells = <1>; + + voltage-regulators { + LDO1 { + regulator-name = "VALIVE_1.0V_AP"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + LDO2 { + regulator-name = "VM1M2_1.2V_AP"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + LDO22 { + regulator-name = "VMEM_VDD_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + maxim,ena-gpios = <&gpk0 2 GPIO_ACTIVE_HIGH>; + }; + + // ... + + BUCK1 { + regulator-name = "VDD_MIF"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + BUCK2 { + regulator-name = "VDD_ARM"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1500000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + BUCK9 { + regulator-name = "CAM_ISP_CORE_1.2V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1200000>; + maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77802.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77802.yaml new file mode 100644 index 000000000000..baa1346ac5d5 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max77802.yaml @@ -0,0 +1,194 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max77802.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77802 Power Management IC + +maintainers: + - Javier Martinez Canillas <javier@dowhile0.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77802 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77802 is a Power Management IC which includes voltage and + current regulators (10 high efficiency Buck regulators and 32 Low-DropOut + (LDO)), RTC and clock outputs. + + The MAX77802 provides two 32.768khz clock outputs that can be controlled + (gated/ungated) over I2C. The clock IDs are defined as preprocessor macros + in dt-bindings/clock/maxim,max77802.h. + +properties: + compatible: + const: maxim,max77802 + + '#clock-cells': + const: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + regulators: + $ref: /schemas/regulator/maxim,max77802.yaml + description: + List of child nodes that specify the regulators. + + inb1-supply: + description: Power supply for buck1 + inb2-supply: + description: Power supply for buck2 + inb3-supply: + description: Power supply for buck3 + inb4-supply: + description: Power supply for buck4 + inb5-supply: + description: Power supply for buck5 + inb6-supply: + description: Power supply for buck6 + inb7-supply: + description: Power supply for buck7 + inb8-supply: + description: Power supply for buck8 + inb9-supply: + description: Power supply for buck9 + inb10-supply: + description: Power supply for buck10 + + inl1-supply: + description: Power supply for LDO8, LDO15 + inl2-supply: + description: Power supply for LDO17, LDO27, LDO30, LDO35 + inl3-supply: + description: Power supply for LDO3, LDO5, LDO7, LDO7 + inl4-supply: + description: Power supply for LDO10, LDO11, LDO13, LDO14 + inl5-supply: + description: Power supply for LDO9, LDO19 + inl6-supply: + description: Power supply for LDO4, LDO21, LDO24, LDO33 + inl7-supply: + description: Power supply for LDO18, LDO20, LDO28, LDO29 + inl9-supply: + description: Power supply for LDO12, LDO23, LDO25, LDO26, LDO32, LDO34 + inl10-supply: + description: Power supply for LDO1, LDO2 + + wakeup-source: true + +required: + - compatible + - '#clock-cells' + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/regulator/maxim,max77802.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@9 { + compatible = "maxim,max77802"; + interrupt-parent = <&gpx3>; + interrupts = <1 IRQ_TYPE_NONE>; + pinctrl-names = "default"; + pinctrl-0 = <&max77802_irq>, <&pmic_selb>, + <&pmic_dvs_1>, <&pmic_dvs_2>, <&pmic_dvs_3>; + wakeup-source; + reg = <0x9>; + #clock-cells = <1>; + + inb1-supply = <&tps65090_dcdc2>; + inb2-supply = <&tps65090_dcdc1>; + inb3-supply = <&tps65090_dcdc2>; + inb4-supply = <&tps65090_dcdc2>; + inb5-supply = <&tps65090_dcdc1>; + inb6-supply = <&tps65090_dcdc2>; + inb7-supply = <&tps65090_dcdc1>; + inb8-supply = <&tps65090_dcdc1>; + inb9-supply = <&tps65090_dcdc1>; + inb10-supply = <&tps65090_dcdc1>; + + inl1-supply = <&buck5_reg>; + inl2-supply = <&buck7_reg>; + inl3-supply = <&buck9_reg>; + inl4-supply = <&buck9_reg>; + inl5-supply = <&buck9_reg>; + inl6-supply = <&tps65090_dcdc2>; + inl7-supply = <&buck9_reg>; + inl9-supply = <&tps65090_dcdc2>; + inl10-supply = <&buck7_reg>; + + regulators { + BUCK1 { + regulator-name = "vdd_mif"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <12500>; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + BUCK2 { + regulator-name = "vdd_arm"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1500000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <12500>; + regulator-coupled-with = <&buck3_reg>; + regulator-coupled-max-spread = <300000>; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + // ... + + BUCK10 { + regulator-name = "vdd_1v8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + LDO1 { + regulator-name = "vdd_1v0"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + regulator-initial-mode = <MAX77802_OPMODE_NORMAL>; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <MAX77802_OPMODE_LP>; + }; + }; + + // ... + + LDO35 { + regulator-name = "ldo_35"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77843.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77843.yaml new file mode 100644 index 000000000000..61a0f9dcb983 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max77843.yaml @@ -0,0 +1,144 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max77843.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77843 MicroUSB and Companion Power Management IC + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77843 MicroUSB + Integrated Circuit (MUIC). + + The Maxim MAX77843 is a MicroUSB and Companion Power Management IC which + includes voltage current regulators, charger, fuel-gauge, haptic motor driver + and MicroUSB management IC. + +properties: + compatible: + const: maxim,max77843 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + extcon: + $ref: /schemas/extcon/maxim,max77843.yaml + + motor-driver: + type: object + properties: + compatible: + const: maxim,max77843-haptic + + haptic-supply: + description: Power supply to the haptic motor + + pwms: + maxItems: 1 + + required: + - compatible + - haptic-supply + - pwms + + regulators: + $ref: /schemas/regulator/maxim,max77843.yaml + +required: + - compatible + - interrupts + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@66 { + compatible = "maxim,max77843"; + interrupt-parent = <&gpa1>; + interrupts = <5 IRQ_TYPE_EDGE_FALLING>; + reg = <0x66>; + + extcon { + compatible = "maxim,max77843-muic"; + + connector { + compatible = "samsung,usb-connector-11pin", + "usb-b-connector"; + label = "micro-USB"; + type = "micro"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + /* + * TODO: The DTS this is based on does not have + * port@0 which is a required property. The ports + * look incomplete and need fixing. + * Add a disabled port just to satisfy dtschema. + */ + reg = <0>; + status = "disabled"; + }; + + port@3 { + reg = <3>; + endpoint { + remote-endpoint = <&mhl_to_musb_con>; + }; + }; + }; + }; + + ports { + port { + endpoint { + remote-endpoint = <&usb_to_muic>; + }; + }; + }; + }; + + regulators { + compatible = "maxim,max77843-regulator"; + + SAFEOUT1 { + regulator-name = "SAFEOUT1"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <4950000>; + }; + + SAFEOUT2 { + regulator-name = "SAFEOUT2"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <4950000>; + }; + + CHARGER { + regulator-name = "CHARGER"; + regulator-min-microamp = <100000>; + regulator-max-microamp = <3150000>; + }; + }; + + motor-driver { + compatible = "maxim,max77843-haptic"; + haptic-supply = <&ldo38_reg>; + pwms = <&pwm 0 33670 0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt deleted file mode 100644 index 386eec06cf08..000000000000 --- a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt +++ /dev/null @@ -1,102 +0,0 @@ -* ROHM BD70528 Power Management Integrated Circuit bindings - -BD70528MWV is an ultra-low quiescent current general purpose, single-chip, -power management IC for battery-powered portable devices. The IC -integrates 3 ultra-low current consumption buck converters, 3 LDOs and 2 -LED Drivers. Also included are 4 GPIOs, a real-time clock (RTC), a 32kHz -clock gate, high-accuracy VREF for use with an external ADC, flexible -dual-input power path, 10 bit SAR ADC for battery temperature monitor and -1S battery charger with scalable charge currents. - -Required properties: - - compatible : Should be "rohm,bd70528" - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : To indicate BD70528 acts as an interrupt controller. - - #interrupt-cells : Should be 2. Usage is compliant to the 2 cells - variant of ../interrupt-controller/interrupts.txt - - gpio-controller : To indicate BD70528 acts as a GPIO controller. - - #gpio-cells : Should be 2. The first cell is the pin number and - the second cell is used to specify flags. See - ../gpio/gpio.txt for more information. - - #clock-cells : Should be 0. - - regulators: : List of child nodes that specify the regulators. - Please see ../regulator/rohm,bd70528-regulator.txt - -Optional properties: - - clock-output-names : Should contain name for output clock. - -Example: -/* External oscillator */ -osc: oscillator { - compatible = "fixed-clock"; - #clock-cells = <1>; - clock-frequency = <32768>; - clock-output-names = "osc"; -}; - -pmic: pmic@4b { - compatible = "rohm,bd70528"; - reg = <0x4b>; - interrupt-parent = <&gpio1>; - interrupts = <29 IRQ_TYPE_LEVEL_LOW>; - clocks = <&osc 0>; - #clock-cells = <0>; - clock-output-names = "bd70528-32k-out"; - #gpio-cells = <2>; - gpio-controller; - interrupt-controller; - #interrupt-cells = <2>; - - regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml new file mode 100644 index 000000000000..89f9efee465b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd9571mwv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) + +maintainers: + - Marek Vasut <marek.vasut@gmail.com> + +properties: + compatible: + enum: + - rohm,bd9571mwv + - rohm,bd9574mwf + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + rohm,ddr-backup-power: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x0 + maximum: 0xf + description: | + Value to use for DDR-Backup Power (default 0). + This is a bitmask that specifies which DDR power rails need to be kept + powered when backup mode is entered, for system suspend: + - bit 0: DDR0 + - bit 1: DDR1 + - bit 2: DDR0C + - bit 3: DDR1C + These bits match the KEEPON_DDR* bits in the documentation for the "BKUP + Mode Cnt" register. + + rohm,rstbmode-level: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for level mode, to accommodate a toggle + power switch (the RSTBMODE pin is strapped low). + + rohm,rstbmode-pulse: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for pulse mode, to accommodate a momentary + power switch (the RSTBMODE pin is strapped high). + + regulators: + type: object + description: + List of child nodes that specify the regulator initialization data. + Child nodes must be named after their hardware counterparts. + + patternProperties: + "^(vd09|vd18|vd25|vd33|dvfs)$": + type: object + $ref: ../regulator/regulator.yaml# + + properties: + regulator-name: + pattern: "^(vd09|vd18|vd25|vd33|dvfs)$" + + unevaluatedProperties: false + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + +oneOf: + - required: + - rohm,rstbmode-level + - required: + - rohm,rstbmode-pulse + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic: pmic@30 { + compatible = "rohm,bd9571mwv"; + reg = <0x30>; + interrupt-parent = <&gpio2>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + rohm,ddr-backup-power = <0xf>; + rohm,rstbmode-pulse; + + regulators { + dvfs: dvfs { + regulator-name = "dvfs"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1030000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 5de16388a089..eeac1cbc5a17 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -39,6 +39,7 @@ properties: - allwinner,sun8i-v3s-system-controller - allwinner,sun50i-a64-system-controller - brcm,cru-clkset + - freecom,fsg-cs2-system-controller - hisilicon,dsa-subctrl - hisilicon,hi6220-sramctrl - hisilicon,pcie-sas-subctrl @@ -57,6 +58,7 @@ properties: - samsung,exynos4-sysreg - samsung,exynos5-sysreg - samsung,exynos5433-sysreg + - samsung,exynos850-sysreg - samsung,exynosautov9-sysreg - const: syscon diff --git a/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml index 272832e9f8f2..fa86691ebf16 100644 --- a/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml @@ -20,7 +20,7 @@ description: | maintainers: - Kishon Vijay Abraham I <kishon@ti.com> - - Roger Quadros <rogerq@ti.com + - Roger Quadros <rogerq@kernel.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml b/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml new file mode 100644 index 000000000000..20b5836efd90 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mips/loongson/ls2k-reset.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Loongson 2K1000 PM Controller + +maintainers: + - Qing Zhang <zhangqing@loongson.cn> + +description: | + This controller can be found in Loongson-2K1000 Soc systems. + +properties: + compatible: + const: loongson,ls2k-pm + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + pm: reset-controller@1fe07000 { + compatible = "loongson,ls2k-pm"; + reg = <0 0x1fe07000 0 0x422>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml index de6f076e0ece..83be9e93d221 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -118,6 +118,9 @@ properties: phy-names: const: phy_arasan + resets: + maxItems: 1 + arasan,soc-ctl-syscon: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 47595cb483be..1e69a5a42439 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -53,6 +53,12 @@ properties: items: - const: arm,pl18x - const: arm,primecell + - description: Entry for STMicroelectronics variant of PL18x. + This dedicated compatible is used by bootloaders. + items: + - const: st,stm32-sdmmc2 + - const: arm,pl18x + - const: arm,primecell clocks: description: One or two clocks, the "apb_pclk" and the "MCLK" @@ -60,6 +66,18 @@ properties: minItems: 1 maxItems: 2 + dmas: + maxItems: 2 + + dma-names: + oneOf: + - items: + - const: tx + - const: rx + - items: + - const: rx + - const: tx + power-domains: true resets: @@ -167,6 +185,9 @@ examples: clock-names = "mclk", "apb_pclk"; }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + mmc@80126000 { compatible = "arm,pl18x", "arm,primecell"; reg = <0x80126000 0x1000>; @@ -188,12 +209,12 @@ examples: vqmmc-supply = <&vmmci>; }; + - | mmc@101f6000 { compatible = "arm,pl18x", "arm,primecell"; reg = <0x101f6000 0x1000>; clocks = <&sdiclk>, <&pclksdi>; clock-names = "mclk", "apb_pclk"; - interrupt-parent = <&vica>; interrupts = <22>; max-frequency = <400000>; bus-width = <4>; @@ -208,12 +229,12 @@ examples: vmmc-supply = <&vmmc_regulator>; }; + - | mmc@52007000 { compatible = "arm,pl18x", "arm,primecell"; arm,primecell-periphid = <0x10153180>; reg = <0x52007000 0x1000>; interrupts = <49>; - interrupt-names = "cmd_irq"; clocks = <&rcc 0>; clock-names = "apb_pclk"; resets = <&rcc 1>; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt deleted file mode 100644 index ae2074184528..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt +++ /dev/null @@ -1,53 +0,0 @@ -* BROADCOM BRCMSTB/BMIPS SDHCI Controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-brcmstb driver. - -NOTE: The driver disables all UHS speed modes by default and depends -on Device Tree properties to enable them for SoC/Board combinations -that support them. - -Required properties: -- compatible: should be one of the following - - "brcm,bcm7425-sdhci" - - "brcm,bcm7445-sdhci" - - "brcm,bcm7216-sdhci" - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - - sdhci@84b0000 { - sd-uhs-sdr50; - sd-uhs-ddr50; - sd-uhs-sdr104; - sdhci,auto-cmd12; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b0000 0x260 0x84b0300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x26 0x4>; - interrupt-names = "sdio0_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; - - sdhci@84b1000 { - mmc-ddr-1_8v; - mmc-hs200-1_8v; - mmc-hs400-1_8v; - mmc-hs400-enhanced-strobe; - supports-cqe; - non-removable; - bus-width = <0x8>; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b1000 0x260 0x84b1300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x27 0x4>; - interrupt-names = "sdio1_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml new file mode 100644 index 000000000000..dccd5ad96981 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,sdhci-brcmstb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BRCMSTB/BMIPS SDHCI Controller binding + +maintainers: + - Al Cooper <alcooperx@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm7216-sdhci + - const: brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7425-sdhci + - const: brcm,sdhci-brcmstb + + reg: + minItems: 2 + + reg-names: + items: + - const: host + - const: cfg + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: + handle to core clock for the sdhci controller. + + clock-names: + items: + - const: sw_sdio + + sdhci,auto-cmd12: + type: boolean + description: Specifies that controller should use auto CMD12 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + mmc@84b0000 { + sd-uhs-sdr50; + sd-uhs-ddr50; + sd-uhs-sdr104; + sdhci,auto-cmd12; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b0000 0x260>, <0x84b0300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x26 0x4>; + interrupt-names = "sdio0_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; + + mmc@84b1000 { + mmc-ddr-1_8v; + mmc-hs200-1_8v; + mmc-hs400-1_8v; + mmc-hs400-enhanced-strobe; + supports-cqe; + non-removable; + bus-width = <0x8>; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b1000 0x260>, <0x84b1300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x27 0x4>; + interrupt-names = "sdio1_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt index 0419a63f73a0..753e9d7d8956 100644 --- a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -22,6 +22,8 @@ Required Properties: specific extensions. - "samsung,exynos7-dw-mshc-smu": for controllers with Samsung Exynos7 specific extensions having an SMU. + - "axis,artpec8-dw-mshc": for controllers with ARTPEC-8 specific + extensions. * samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface unit (ciu) clock. This property is applicable only for Exynos5 SoC's and diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 19621a2f8beb..17acbc665f5a 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -34,6 +34,7 @@ properties: - fsl,imx6ull-usdhc - fsl,imx7d-usdhc - fsl,imx7ulp-usdhc + - fsl,imxrt1050-usdhc - nxp,s32g2-usdhc - items: - enum: @@ -44,6 +45,10 @@ properties: - fsl,imx8qm-usdhc - fsl,imx8qxp-usdhc - const: fsl,imx7d-usdhc + - items: + - enum: + - fsl,imx8ulp-usdhc + - const: fsl,imx8mm-usdhc reg: maxItems: 1 @@ -116,6 +121,9 @@ properties: - const: ahb - const: per + power-domains: + maxItems: 1 + pinctrl-names: oneOf: - minItems: 3 diff --git a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt deleted file mode 100644 index c54e577eea07..000000000000 --- a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt +++ /dev/null @@ -1,28 +0,0 @@ -* Imagination specific extensions to the Synopsys Designware Mobile Storage - Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Imagination specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "img,pistachio-dw-mshc": for Pistachio SoCs - -Example: - - mmc@18142000 { - compatible = "img,pistachio-dw-mshc"; - reg = <0x18142000 0x400>; - interrupts = <GIC_SHARED 39 IRQ_TYPE_LEVEL_HIGH>; - - clocks = <&system_clk>, <&sdhost_clk>; - clock-names = "biu", "ciu"; - - fifo-depth = <0x20>; - bus-width = <4>; - disable-wp; - }; diff --git a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml index 01d5c6da0eeb..2d10aedf2e00 100644 --- a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml @@ -39,14 +39,15 @@ properties: const: mmc dmas: - items: - - description: DMA controller phandle and request line for RX - - description: DMA controller phandle and request line for TX + minItems: 1 + maxItems: 2 dma-names: - items: - - const: rx - - const: tx + oneOf: + - items: + - const: rx + - const: tx + - const: tx-rx required: - compatible @@ -80,3 +81,27 @@ examples: <&dma JZ4780_DMA_MSC0_TX 0xffffffff>; dma-names = "rx", "tx"; }; + - | + #include <dt-bindings/clock/ingenic,jz4780-cgu.h> + #include <dt-bindings/dma/jz4780-dma.h> + /* + * Alternative version of the example above, + * but using one single DMA channel for both + * TX and RX. + */ + mmc1: mmc@13460000 { + compatible = "ingenic,jz4780-mmc"; + reg = <0x13460000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <36>; + + clocks = <&cgu JZ4780_CLK_MSC1>; + clock-names = "mmc"; + + cap-sd-highspeed; + cap-mmc-highspeed; + cap-sdio-irq; + dmas = <&dma JZ4780_DMA_MSC1_TX JZ4780_DMA_MSC1_RX 0xffffffff>; + dma-names = "tx-rx"; + }; diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 82768a807294..faf89b0c918f 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -36,6 +36,9 @@ properties: - const: mediatek,mt8195-mmc - const: mediatek,mt8183-mmc + reg: + maxItems: 1 + clocks: description: Should contain phandle for the clock feeding the MMC controller. @@ -62,6 +65,9 @@ properties: - const: axi_cg - const: ahb_cg + interrupts: + maxItems: 1 + pinctrl-names: items: - const: default diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index 224303f5b913..9fbf16b3bc8d 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -48,6 +48,8 @@ properties: - const: clk_ahb - const: clk_xin + sdhci-caps-mask: true + # PHY output tap delays: # Used to delay the data valid window and align it to the sampling clock. # Binding needs to be provided for each supported speed mode otherwise the diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 50841e2843fc..6a8cc261bf61 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -17,6 +17,7 @@ Required properties: "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8916-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8992-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8994-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; diff --git a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt deleted file mode 100644 index 4897bea7e3f8..000000000000 --- a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt +++ /dev/null @@ -1,23 +0,0 @@ -* Altera SOCFPGA specific extensions to the Synopsys Designware Mobile - Storage Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Altera SOCFPGA specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "altr,socfpga-dw-mshc": for Altera's SOCFPGA platform - -Example: - - mmc: dwmmc0@ff704000 { - compatible = "altr,socfpga-dw-mshc"; - reg = <0xff704000 0x1000>; - interrupts = <0 129 4>; - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml index 56f9ff12742d..a586fad0a46b 100644 --- a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml @@ -26,6 +26,12 @@ properties: clocks: maxItems: 1 + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + reset-names: description: | There are three reset signals at maximum diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml index 240abb6f102c..ae6d6fca79e2 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml @@ -15,7 +15,10 @@ maintainers: # Everything else is described in the common file properties: compatible: - const: snps,dw-mshc + enum: + - altr,socfpga-dw-mshc + - img,pistachio-dw-mshc + - snps,dw-mshc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml index ed590d7c6e37..4abfb4cfc157 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: "mtd.yaml#" + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -46,7 +47,8 @@ properties: identified by the JEDEC READ ID opcode (0x9F). reg: - maxItems: 1 + minItems: 1 + maxItems: 2 spi-max-frequency: true spi-rx-bus-width: true @@ -88,7 +90,7 @@ patternProperties: "^otp(-[0-9]+)?$": type: object -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml new file mode 100644 index 000000000000..2870d36361c4 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/renesas-nandc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen3 & RZ/N1x NAND flash controller device tree bindings + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +allOf: + - $ref: "nand-controller.yaml" + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,r9a06g032-nandc + - const: renesas,rzn1-nandc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: APB host controller clock + - description: External NAND bus clock + + clock-names: + items: + - const: hclk + - const: eclk + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a06g032-sysctrl.h> + + nand-controller@40102000 { + compatible = "renesas,r9a06g032-nandc", "renesas,rzn1-nandc"; + reg = <0x40102000 0x2000>; + interrupts = <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&sysctrl R9A06G032_HCLK_NAND>, <&sysctrl R9A06G032_CLK_NAND>; + clock-names = "hclk", "eclk"; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml index beb26b9bcfb2..4ac198814b7a 100644 --- a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml @@ -16,7 +16,10 @@ description: properties: compatible: - const: ti,omap2-nand + items: + - enum: + - ti,am64-nand + - ti,omap2-nand reg: maxItems: 1 @@ -53,6 +56,11 @@ properties: enum: [8, 16] default: 8 + rb-gpios: + description: + GPIO connection to R/B signal from NAND chip + maxItems: 1 + patternProperties: "@[0-9a-f]+$": $ref: "/schemas/mtd/partitions/partition.yaml" diff --git a/Documentation/devicetree/bindings/mux/gpio-mux.yaml b/Documentation/devicetree/bindings/mux/gpio-mux.yaml index 0a7c8d64981a..ee4de9fbaf4d 100644 --- a/Documentation/devicetree/bindings/mux/gpio-mux.yaml +++ b/Documentation/devicetree/bindings/mux/gpio-mux.yaml @@ -26,7 +26,10 @@ properties: List of gpios used to control the multiplexer, least significant bit first. '#mux-control-cells': - const: 0 + enum: [ 0, 1 ] + + '#mux-state-cells': + enum: [ 1, 2 ] idle-state: default: -1 @@ -34,7 +37,11 @@ properties: required: - compatible - mux-gpios - - "#mux-control-cells" +anyOf: + - required: + - "#mux-control-cells" + - required: + - "#mux-state-cells" additionalProperties: false diff --git a/Documentation/devicetree/bindings/mux/mux-consumer.yaml b/Documentation/devicetree/bindings/mux/mux-consumer.yaml index 7af93298ab5c..d3d854967359 100644 --- a/Documentation/devicetree/bindings/mux/mux-consumer.yaml +++ b/Documentation/devicetree/bindings/mux/mux-consumer.yaml @@ -25,6 +25,17 @@ description: | strings to label each of the mux controllers listed in the "mux-controls" property. + If it is required to provide the state that the mux controller needs to + be set to, the property "mux-states" must be used. An optional property + "mux-state-names" can be used to provide a list of strings, to label + each of the multiplixer states listed in the "mux-states" property. + + Properties "mux-controls" and "mux-states" can be used depending on how + the consumers want to control the mux controller. If the consumer needs + needs to set multiple states in a mux controller, then property + "mux-controls" can be used. If the consumer needs to set the mux + controller to a given state then property "mux-states" can be used. + mux-ctrl-specifier typically encodes the chip-relative mux controller number. If the mux controller chip only provides a single mux controller, the mux-ctrl-specifier can typically be left out. @@ -35,12 +46,22 @@ properties: mux-controls: $ref: /schemas/types.yaml#/definitions/phandle-array + mux-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + mux-control-names: description: Devices that use more than a single mux controller can use the "mux-control-names" property to map the name of the requested mux controller to an index into the list given by the "mux-controls" property. + mux-state-names: + description: + Devices that use more than a single multiplexer state can use the + "mux-state-names" property to map the name of the requested mux + controller to an index into the list given by the "mux-states" + property. + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/mux/mux-controller.yaml b/Documentation/devicetree/bindings/mux/mux-controller.yaml index 736a84c3b6a5..c855fbad3884 100644 --- a/Documentation/devicetree/bindings/mux/mux-controller.yaml +++ b/Documentation/devicetree/bindings/mux/mux-controller.yaml @@ -25,7 +25,9 @@ description: | -------------------- Mux controller nodes must specify the number of cells used for the - specifier using the '#mux-control-cells' property. + specifier using the '#mux-control-cells' or '#mux-state-cells' property. + The value of '#mux-state-cells' will always be one greater than the value + of '#mux-control-cells'. Optionally, mux controller nodes can also specify the state the mux should have when it is idle. The idle-state property is used for this. If the @@ -67,6 +69,8 @@ select: pattern: '^mux-controller' - required: - '#mux-control-cells' + - required: + - '#mux-state-cells' properties: $nodename: @@ -75,6 +79,9 @@ properties: '#mux-control-cells': enum: [ 0, 1 ] + '#mux-state-cells': + enum: [ 1, 2 ] + idle-state: $ref: /schemas/types.yaml#/definitions/int32 minimum: -2 @@ -179,4 +186,21 @@ examples: }; }; }; + + - | + #include <dt-bindings/gpio/gpio.h> + + mux1: mux-controller { + compatible = "gpio-mux"; + #mux-state-cells = <1>; + mux-gpios = <&exp_som 2 GPIO_ACTIVE_HIGH>; + }; + + transceiver4: can-phy4 { + compatible = "ti,tcan1042"; + #phy-cells = <0>; + max-bitrate = <5000000>; + standby-gpios = <&exp_som 7 GPIO_ACTIVE_HIGH>; + mux-states = <&mux1 1>; + }; ... diff --git a/Documentation/devicetree/bindings/net/actions,owl-emac.yaml b/Documentation/devicetree/bindings/net/actions,owl-emac.yaml index 1626e0a821b0..d30fada2ac39 100644 --- a/Documentation/devicetree/bindings/net/actions,owl-emac.yaml +++ b/Documentation/devicetree/bindings/net/actions,owl-emac.yaml @@ -51,6 +51,10 @@ properties: description: Phandle to the device containing custom config. + mdio: + $ref: mdio.yaml# + unevaluatedProperties: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml index 407586bc366b..6a4831fd3616 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml @@ -122,6 +122,7 @@ allOf: mdio-mux: type: object + unevaluatedProperties: false properties: compatible: @@ -132,17 +133,18 @@ allOf: description: Phandle to EMAC MDIO. + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + mdio@1: - type: object + $ref: mdio.yaml# + unevaluatedProperties: false description: Internal MDIO Bus properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - compatible: const: allwinner,sun8i-h3-mdio-internal @@ -168,16 +170,11 @@ allOf: mdio@2: - type: object + $ref: mdio.yaml# + unevaluatedProperties: false description: External MDIO Bus (H3 only) properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - reg: const: 2 diff --git a/Documentation/devicetree/bindings/net/brcm,amac.txt b/Documentation/devicetree/bindings/net/brcm,amac.txt deleted file mode 100644 index 0120ebe93262..000000000000 --- a/Documentation/devicetree/bindings/net/brcm,amac.txt +++ /dev/null @@ -1,30 +0,0 @@ -Broadcom AMAC Ethernet Controller Device Tree Bindings -------------------------------------------------------------- - -Required properties: - - compatible: "brcm,amac" - "brcm,nsp-amac" - "brcm,ns2-amac" - - reg: Address and length of the register set for the device. It - contains the information of registers in the same order as - described by reg-names - - reg-names: Names of the registers. - "amac_base": Address and length of the GMAC registers - "idm_base": Address and length of the GMAC IDM registers - (required for NSP and Northstar2) - "nicpm_base": Address and length of the NIC Port Manager - registers (required for Northstar2) - - interrupts: Interrupt number - -The MAC address will be determined using the optional properties -defined in ethernet.txt. - -Examples: - -amac0: ethernet@18022000 { - compatible = "brcm,nsp-amac"; - reg = <0x18022000 0x1000>, - <0x18110000 0x1000>; - reg-names = "amac_base", "idm_base"; - interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/net/brcm,amac.yaml b/Documentation/devicetree/bindings/net/brcm,amac.yaml new file mode 100644 index 000000000000..8f031932c8af --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,amac.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,amac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom AMAC Ethernet Controller Device Tree Bindings + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: "ethernet-controller.yaml#" + - if: + properties: + compatible: + contains: + enum: + - brcm,amac + then: + properties: + reg: + maxItems: 2 + reg-names: + maxItems: 2 + + - if: + properties: + compatible: + contains: + enum: + - brcm,nsp-amac + then: + properties: + reg: + minItems: 2 + maxItems: 2 + reg-names: + minItems: 2 + maxItems: 2 + + - if: + properties: + compatible: + contains: + enum: + - brcm,ns2-amac + then: + properties: + reg: + minItems: 3 + reg-names: + minItems: 3 + +properties: + compatible: + enum: + - brcm,amac + - brcm,nsp-amac + - brcm,ns2-amac + + interrupts: + maxItems: 1 + + reg: + minItems: 1 + maxItems: 3 + + reg-names: + minItems: 1 + items: + - const: amac_base + - const: idm_base + - const: nicpm_base + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + amac0: ethernet@18022000 { + compatible = "brcm,nsp-amac"; + reg = <0x18022000 0x1000>, + <0x18110000 0x1000>; + reg-names = "amac_base", "idm_base"; + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml b/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml index 2f34fda55fd0..9ef28c2a0afc 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml +++ b/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml @@ -15,18 +15,12 @@ description: properties as well to generate desired MDIO transaction on appropriate bus. allOf: - - $ref: "mdio.yaml#" + - $ref: mdio-mux.yaml# properties: compatible: const: brcm,bcm6368-mdio-mux - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - reg: maxItems: 1 @@ -34,24 +28,6 @@ required: - compatible - reg -patternProperties: - '^mdio@[0-1]$': - type: object - properties: - reg: - maxItems: 1 - - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - - required: - - reg - - "#address-cells" - - "#size-cells" - unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt b/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt deleted file mode 100644 index 0b5994fba35f..000000000000 --- a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt +++ /dev/null @@ -1,125 +0,0 @@ -* Broadcom BCM7xxx Ethernet Controller (GENET) - -Required properties: -- compatible: should contain one of "brcm,genet-v1", "brcm,genet-v2", - "brcm,genet-v3", "brcm,genet-v4", "brcm,genet-v5", "brcm,bcm2711-genet-v5" or - "brcm,bcm7712-genet-v5". -- reg: address and length of the register set for the device -- interrupts and/or interrupts-extended: must be two cells, the first cell - is the general purpose interrupt line, while the second cell is the - interrupt for the ring RX and TX queues operating in ring mode. An - optional third interrupt cell for Wake-on-LAN can be specified. - See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - for information on the property specifics. -- phy-mode: see ethernet.txt file in the same directory -- #address-cells: should be 1 -- #size-cells: should be 1 - -Optional properties: -- clocks: When provided, must be two phandles to the functional clocks nodes - of the GENET block. The first phandle is the main GENET clock used during - normal operation, while the second phandle is the Wake-on-LAN clock. -- clock-names: When provided, names of the functional clock phandles, first - name should be "enet" and second should be "enet-wol". - -- phy-handle: See ethernet.txt file in the same directory; used to describe - configurations where a PHY (internal or external) is used. - -- fixed-link: When the GENET interface is connected to a MoCA hardware block or - when operating in a RGMII to RGMII type of connection, or when the MDIO bus is - voluntarily disabled, this property should be used to describe the "fixed link". - See Documentation/devicetree/bindings/net/fixed-link.txt for information on - the property specifics - -Required child nodes: - -- mdio bus node: this node should always be present regardless of the PHY - configuration of the GENET instance - -MDIO bus node required properties: - -- compatible: should contain one of "brcm,genet-mdio-v1", "brcm,genet-mdio-v2" - "brcm,genet-mdio-v3", "brcm,genet-mdio-v4", "brcm,genet-mdio-v5", the version - has to match the parent node compatible property (e.g: brcm,genet-v4 pairs - with brcm,genet-mdio-v4) -- reg: address and length relative to the parent node base register address -- #address-cells: address cell for MDIO bus addressing, should be 1 -- #size-cells: size of the cells for MDIO bus addressing, should be 0 - -Ethernet PHY node properties: - -See Documentation/devicetree/bindings/net/phy.txt for the list of required and -optional properties. - -Internal Gigabit PHY example: - -ethernet@f0b60000 { - phy-mode = "internal"; - phy-handle = <&phy1>; - mac-address = [ 00 10 18 36 23 1a ]; - compatible = "brcm,genet-v4"; - #address-cells = <0x1>; - #size-cells = <0x1>; - reg = <0xf0b60000 0xfc4c>; - interrupts = <0x0 0x14 0x0>, <0x0 0x15 0x0>; - - mdio@e14 { - compatible = "brcm,genet-mdio-v4"; - #address-cells = <0x1>; - #size-cells = <0x0>; - reg = <0xe14 0x8>; - - phy1: ethernet-phy@1 { - max-speed = <1000>; - reg = <0x1>; - compatible = "ethernet-phy-ieee802.3-c22"; - }; - }; -}; - -MoCA interface / MAC to MAC example: - -ethernet@f0b80000 { - phy-mode = "moca"; - fixed-link = <1 0 1000 0 0>; - mac-address = [ 00 10 18 36 24 1a ]; - compatible = "brcm,genet-v4"; - #address-cells = <0x1>; - #size-cells = <0x1>; - reg = <0xf0b80000 0xfc4c>; - interrupts = <0x0 0x16 0x0>, <0x0 0x17 0x0>; - - mdio@e14 { - compatible = "brcm,genet-mdio-v4"; - #address-cells = <0x1>; - #size-cells = <0x0>; - reg = <0xe14 0x8>; - }; -}; - - -External MDIO-connected Gigabit PHY/switch: - -ethernet@f0ba0000 { - phy-mode = "rgmii"; - phy-handle = <&phy0>; - mac-address = [ 00 10 18 36 26 1a ]; - compatible = "brcm,genet-v4"; - #address-cells = <0x1>; - #size-cells = <0x1>; - reg = <0xf0ba0000 0xfc4c>; - interrupts = <0x0 0x18 0x0>, <0x0 0x19 0x0>; - - mdio@e14 { - compatible = "brcm,genet-mdio-v4"; - #address-cells = <0x1>; - #size-cells = <0x0>; - reg = <0xe14 0x8>; - - phy0: ethernet-phy@0 { - max-speed = <1000>; - reg = <0x0>; - compatible = "ethernet-phy-ieee802.3-c22"; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/brcm,bcmgenet.yaml b/Documentation/devicetree/bindings/net/brcm,bcmgenet.yaml new file mode 100644 index 000000000000..e5af53508e25 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,bcmgenet.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,bcmgenet.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM7xxx Ethernet Controller (GENET) binding + +maintainers: + - Doug Berger <opendmb@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + enum: + - brcm,genet-v1 + - brcm,genet-v2 + - brcm,genet-v3 + - brcm,genet-v4 + - brcm,genet-v5 + - brcm,bcm2711-genet-v5 + - brcm,bcm7712-genet-v5 + + reg: + maxItems: 1 + + interrupts: + minItems: 2 + items: + - description: general purpose interrupt line + - description: RX and TX rings interrupt line + - description: Wake-on-LAN interrupt line + + + clocks: + minItems: 1 + items: + - description: main clock + - description: EEE clock + - description: Wake-on-LAN clock + + clock-names: + minItems: 1 + items: + - const: enet + - const: enet-eee + - const: enet-wol + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + +patternProperties: + "^mdio@[0-9a-f]+$": + type: object + $ref: "brcm,unimac-mdio.yaml" + + description: + GENET internal UniMAC MDIO bus + +required: + - reg + - interrupts + - phy-mode + - "#address-cells" + - "#size-cells" + +allOf: + - $ref: ethernet-controller.yaml + +unevaluatedProperties: false + +examples: + #include <dt-bindings/interrupt-controller/arm-gic.h> + + - | + ethernet@f0b60000 { + phy-mode = "internal"; + phy-handle = <&phy1>; + mac-address = [ 00 10 18 36 23 1a ]; + compatible = "brcm,genet-v4"; + reg = <0xf0b60000 0xfc4c>; + interrupts = <0x0 0x14 0x0>, <0x0 0x15 0x0>; + #address-cells = <1>; + #size-cells = <1>; + + mdio0: mdio@e14 { + compatible = "brcm,genet-mdio-v4"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xe14 0x8>; + + phy1: ethernet-phy@1 { + max-speed = <1000>; + reg = <1>; + compatible = "ethernet-phy-ieee802.3-c22"; + }; + }; + }; + + - | + ethernet@f0b80000 { + phy-mode = "moca"; + fixed-link = <1 0 1000 0 0>; + mac-address = [ 00 10 18 36 24 1a ]; + compatible = "brcm,genet-v4"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0xf0b80000 0xfc4c>; + interrupts = <0x0 0x16 0x0>, <0x0 0x17 0x0>; + + mdio1: mdio@e14 { + compatible = "brcm,genet-mdio-v4"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xe14 0x8>; + }; + }; + + - | + ethernet@f0ba0000 { + phy-mode = "rgmii"; + phy-handle = <&phy0>; + mac-address = [ 00 10 18 36 26 1a ]; + compatible = "brcm,genet-v4"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0xf0ba0000 0xfc4c>; + interrupts = <0x0 0x18 0x0>, <0x0 0x19 0x0>; + + mdio2: mdio@e14 { + compatible = "brcm,genet-mdio-v4"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xe14 0x8>; + + phy0: ethernet-phy@0 { + max-speed = <1000>; + reg = <0>; + compatible = "ethernet-phy-ieee802.3-c22"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.txt b/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.txt deleted file mode 100644 index deb9e852ea27..000000000000 --- a/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.txt +++ /dev/null @@ -1,62 +0,0 @@ -Properties for an MDIO bus multiplexer found in Broadcom iProc based SoCs. - -This MDIO bus multiplexer defines buses that could be internal as well as -external to SoCs and could accept MDIO transaction compatible to C-22 or -C-45 Clause. When child bus is selected, one needs to select these two -properties as well to generate desired MDIO transaction on appropriate bus. - -Required properties in addition to the generic multiplexer properties: - -MDIO multiplexer node: -- compatible: brcm,mdio-mux-iproc. - -Every non-ethernet PHY requires a compatible so that it could be probed based -on this compatible string. - -Optional properties: -- clocks: phandle of the core clock which drives the mdio block. - -Additional information regarding generic multiplexer properties can be found -at- Documentation/devicetree/bindings/net/mdio-mux.yaml - - -for example: - mdio_mux_iproc: mdio-mux@66020000 { - compatible = "brcm,mdio-mux-iproc"; - reg = <0x66020000 0x250>; - #address-cells = <1>; - #size-cells = <0>; - - mdio@0 { - reg = <0x0>; - #address-cells = <1>; - #size-cells = <0>; - - pci_phy0: pci-phy@0 { - compatible = "brcm,ns2-pcie-phy"; - reg = <0x0>; - #phy-cells = <0>; - }; - }; - - mdio@7 { - reg = <0x7>; - #address-cells = <1>; - #size-cells = <0>; - - pci_phy1: pci-phy@0 { - compatible = "brcm,ns2-pcie-phy"; - reg = <0x0>; - #phy-cells = <0>; - }; - }; - mdio@10 { - reg = <0x10>; - #address-cells = <1>; - #size-cells = <0>; - - gphy0: eth-phy@10 { - reg = <0x10>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.yaml b/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.yaml new file mode 100644 index 000000000000..af96b4fd89d5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,mdio-mux-iproc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MDIO bus multiplexer found in Broadcom iProc based SoCs. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +description: + This MDIO bus multiplexer defines buses that could be internal as well as + external to SoCs and could accept MDIO transaction compatible to C-22 or + C-45 Clause. When child bus is selected, one needs to select these two + properties as well to generate desired MDIO transaction on appropriate bus. + +allOf: + - $ref: /schemas/net/mdio-mux.yaml# + +properties: + compatible: + const: brcm,mdio-mux-iproc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + description: core clock driving the MDIO block + + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + mdio_mux_iproc: mdio-mux@66020000 { + compatible = "brcm,mdio-mux-iproc"; + reg = <0x66020000 0x250>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + + pci_phy0: pci-phy@0 { + compatible = "brcm,ns2-pcie-phy"; + reg = <0x0>; + #phy-cells = <0>; + }; + }; + + mdio@7 { + reg = <0x7>; + #address-cells = <1>; + #size-cells = <0>; + + pci_phy1: pci-phy@0 { + compatible = "brcm,ns2-pcie-phy"; + reg = <0x0>; + #phy-cells = <0>; + }; + }; + + mdio@10 { + reg = <0x10>; + #address-cells = <1>; + #size-cells = <0>; + + gphy0: eth-phy@10 { + reg = <0x10>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,systemport.txt b/Documentation/devicetree/bindings/net/brcm,systemport.txt deleted file mode 100644 index 75736739bfdd..000000000000 --- a/Documentation/devicetree/bindings/net/brcm,systemport.txt +++ /dev/null @@ -1,38 +0,0 @@ -* Broadcom BCM7xxx Ethernet Systemport Controller (SYSTEMPORT) - -Required properties: -- compatible: should be one of: - "brcm,systemport-v1.00" - "brcm,systemportlite-v1.00" or - "brcm,systemport" -- reg: address and length of the register set for the device. -- interrupts: interrupts for the device, first cell must be for the rx - interrupts, and the second cell should be for the transmit queues. An - optional third interrupt cell for Wake-on-LAN can be specified -- local-mac-address: Ethernet MAC address (48 bits) of this adapter -- phy-mode: Should be a string describing the PHY interface to the - Ethernet switch/PHY, see Documentation/devicetree/bindings/net/ethernet.txt -- fixed-link: see Documentation/devicetree/bindings/net/fixed-link.txt for - the property specific details - -Optional properties: -- systemport,num-tier2-arb: number of tier 2 arbiters, an integer -- systemport,num-tier1-arb: number of tier 1 arbiters, an integer -- systemport,num-txq: number of HW transmit queues, an integer -- systemport,num-rxq: number of HW receive queues, an integer -- clocks: When provided, must be two phandles to the functional clocks nodes of - the SYSTEMPORT block. The first phandle is the main SYSTEMPORT clock used - during normal operation, while the second phandle is the Wake-on-LAN clock. -- clock-names: When provided, names of the functional clock phandles, first - name should be "sw_sysport" and second should be "sw_sysportwol". - -Example: -ethernet@f04a0000 { - compatible = "brcm,systemport-v1.00"; - reg = <0xf04a0000 0x4650>; - local-mac-address = [ 00 11 22 33 44 55 ]; - fixed-link = <0 1 1000 0 0>; - phy-mode = "gmii"; - interrupts = <0x0 0x16 0x0>, - <0x0 0x17 0x0>; -}; diff --git a/Documentation/devicetree/bindings/net/brcm,systemport.yaml b/Documentation/devicetree/bindings/net/brcm,systemport.yaml new file mode 100644 index 000000000000..5fc9c9fafd85 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,systemport.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,systemport.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM7xxx Ethernet Systemport Controller (SYSTEMPORT) + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + enum: + - brcm,systemport-v1.00 + - brcm,systemportlite-v1.00 + - brcm,systemport + + reg: + maxItems: 1 + + interrupts: + minItems: 2 + items: + - description: interrupt line for RX queues + - description: interrupt line for TX queues + - description: interrupt line for Wake-on-LAN + + clocks: + items: + - description: main clock + - description: Wake-on-LAN clock + + clock-names: + items: + - const: sw_sysport + - const: sw_sysportwol + + systemport,num-tier2-arb: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Number of tier 2 arbiters + + systemport,num-tier1-arb: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Number of tier 2 arbiters + + systemport,num-txq: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 32 + description: + Number of HW transmit queues + + systemport,num-rxq: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 32 + description: + Number of HW receive queues + +required: + - reg + - interrupts + - phy-mode + +allOf: + - $ref: "ethernet-controller.yaml#" + +unevaluatedProperties: false + +examples: + - | + ethernet@f04a0000 { + compatible = "brcm,systemport-v1.00"; + reg = <0xf04a0000 0x4650>; + local-mac-address = [ 00 11 22 33 44 55 ]; + phy-mode = "gmii"; + interrupts = <0x0 0x16 0x0>, + <0x0 0x17 0x0>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml index f4f4c37f1d4e..0be426ee1e44 100644 --- a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml +++ b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml @@ -7,6 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Broadcom UniMAC MDIO bus controller maintainers: + - Doug Berger <opendmb@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> allOf: @@ -64,7 +66,6 @@ unevaluatedProperties: false required: - reg - - reg-names - '#address-cells' - '#size-cells' diff --git a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml index fb547e26c676..401ab7cdb379 100644 --- a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml +++ b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml @@ -76,33 +76,31 @@ properties: M_CAN user manual for details. $ref: /schemas/types.yaml#/definitions/int32-array items: - items: - - description: The 'offset' is an address offset of the Message RAM where - the following elements start from. This is usually set to 0x0 if - you're using a private Message RAM. - default: 0 - - description: 11-bit Filter 0-128 elements / 0-128 words - minimum: 0 - maximum: 128 - - description: 29-bit Filter 0-64 elements / 0-128 words - minimum: 0 - maximum: 64 - - description: Rx FIFO 0 0-64 elements / 0-1152 words - minimum: 0 - maximum: 64 - - description: Rx FIFO 1 0-64 elements / 0-1152 words - minimum: 0 - maximum: 64 - - description: Rx Buffers 0-64 elements / 0-1152 words - minimum: 0 - maximum: 64 - - description: Tx Event FIFO 0-32 elements / 0-64 words - minimum: 0 - maximum: 32 - - description: Tx Buffers 0-32 elements / 0-576 words - minimum: 0 - maximum: 32 - maxItems: 1 + - description: The 'offset' is an address offset of the Message RAM where + the following elements start from. This is usually set to 0x0 if + you're using a private Message RAM. + default: 0 + - description: 11-bit Filter 0-128 elements / 0-128 words + minimum: 0 + maximum: 128 + - description: 29-bit Filter 0-64 elements / 0-128 words + minimum: 0 + maximum: 64 + - description: Rx FIFO 0 0-64 elements / 0-1152 words + minimum: 0 + maximum: 64 + - description: Rx FIFO 1 0-64 elements / 0-1152 words + minimum: 0 + maximum: 64 + - description: Rx Buffers 0-64 elements / 0-1152 words + minimum: 0 + maximum: 64 + - description: Tx Event FIFO 0-32 elements / 0-64 words + minimum: 0 + maximum: 32 + - description: Tx Buffers 0-32 elements / 0-576 words + minimum: 0 + maximum: 32 power-domains: description: diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt index 0968b40aef1e..e3501bfa22e9 100644 --- a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -31,7 +31,7 @@ tcan4x5x: tcan4x5x@0 { #address-cells = <1>; #size-cells = <1>; spi-max-frequency = <10000000>; - bosch,mram-cfg = <0x0 0 0 32 0 0 1 1>; + bosch,mram-cfg = <0x0 0 0 16 0 0 1 1>; interrupt-parent = <&gpio1>; interrupts = <14 IRQ_TYPE_LEVEL_LOW>; device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/cdns,macb.yaml b/Documentation/devicetree/bindings/net/cdns,macb.yaml new file mode 100644 index 000000000000..8dd06db34169 --- /dev/null +++ b/Documentation/devicetree/bindings/net/cdns,macb.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/cdns,macb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence MACB/GEM Ethernet controller + +maintainers: + - Nicolas Ferre <nicolas.ferre@microchip.com> + - Claudiu Beznea <claudiu.beznea@microchip.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - cdns,at91rm9200-emac # Atmel at91rm9200 SoC + - const: cdns,emac # Generic + + - items: + - enum: + - cdns,zynq-gem # Xilinx Zynq-7xxx SoC + - cdns,zynqmp-gem # Xilinx Zynq Ultrascale+ MPSoC + - const: cdns,gem # Generic + + - items: + - enum: + - cdns,at91sam9260-macb # Atmel at91sam9 SoCs + - cdns,sam9x60-macb # Microchip sam9x60 SoC + - const: cdns,macb # Generic + + - items: + - enum: + - atmel,sama5d3-macb # 10/100Mbit IP on Atmel sama5d3 SoCs + - enum: + - cdns,at91sam9260-macb # Atmel at91sam9 SoCs. + - const: cdns,macb # Generic + + - enum: + - atmel,sama5d29-gem # GEM XL IP (10/100) on Atmel sama5d29 SoCs + - atmel,sama5d2-gem # GEM IP (10/100) on Atmel sama5d2 SoCs + - atmel,sama5d3-gem # Gigabit IP on Atmel sama5d3 SoCs + - atmel,sama5d4-gem # GEM IP (10/100) on Atmel sama5d4 SoCs + - cdns,at32ap7000-macb # Other 10/100 usage or use the generic form + - cdns,np4-macb # NP4 SoC devices + - microchip,sama7g5-emac # Microchip SAMA7G5 ethernet interface + - microchip,sama7g5-gem # Microchip SAMA7G5 gigabit ethernet interface + - sifive,fu540-c000-gem # SiFive FU540-C000 SoC + - cdns,emac # Generic + - cdns,gem # Generic + - cdns,macb # Generic + + reg: + minItems: 1 + items: + - description: Basic register set + - description: GEMGXL Management block registers on SiFive FU540-C000 SoC + + interrupts: + minItems: 1 + maxItems: 8 + description: One interrupt per available hardware queue + + clocks: + minItems: 1 + maxItems: 5 + + clock-names: + minItems: 1 + items: + - enum: [ ether_clk, hclk, pclk ] + - enum: [ hclk, pclk ] + - const: tx_clk + - enum: [ rx_clk, tsu_clk ] + - const: tsu_clk + + local-mac-address: true + + phy-mode: true + + phy-handle: true + + fixed-link: true + + iommus: + maxItems: 1 + + power-domains: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + mdio: + type: object + description: + Node containing PHY children. If this node is not present, then PHYs will + be direct children. + +patternProperties: + "^ethernet-phy@[0-9a-f]$": + type: object + $ref: ethernet-phy.yaml# + + properties: + reset-gpios: true + + magic-packet: + description: + Indicates that the hardware supports waking up via magic packet. + + unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - phy-mode + +allOf: + - $ref: ethernet-controller.yaml# + + - if: + not: + properties: + compatible: + contains: + const: sifive,fu540-c000-gem + then: + properties: + reg: + maxItems: 1 + +unevaluatedProperties: false + +examples: + - | + macb0: ethernet@fffc4000 { + compatible = "cdns,at32ap7000-macb"; + reg = <0xfffc4000 0x4000>; + interrupts = <21>; + phy-mode = "rmii"; + local-mac-address = [3a 0e 03 04 05 06]; + clock-names = "pclk", "hclk", "tx_clk"; + clocks = <&clkc 30>, <&clkc 30>, <&clkc 13>; + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@1 { + reg = <0x1>; + reset-gpios = <&pioE 6 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml index 24cd733c11d1..1ea0bd490473 100644 --- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml +++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml @@ -52,10 +52,8 @@ properties: patternProperties: "^mdio@[0-1]$": - type: object - - allOf: - - $ref: "http://devicetree.org/schemas/net/mdio.yaml#" + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false properties: compatible: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index 89c21b289447..f3c88371d76c 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -58,33 +58,14 @@ properties: B68 on the QCA832x and B49 on the QCA833x. mdio: - type: object + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false description: Qca8k switch have an internal mdio to access switch port. If this is not present, the legacy mapping is used and the internal mdio access is used. With the legacy mapping the reg corresponding to the internal mdio is the switch reg with an offset of -1. - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - - patternProperties: - "^(ethernet-)?phy@[0-4]$": - type: object - - allOf: - - $ref: "http://devicetree.org/schemas/net/mdio.yaml#" - - properties: - reg: - maxItems: 1 - - required: - - reg - patternProperties: "^(ethernet-)?ports$": type: object diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index b0933a8c295a..34c5463abcec 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -17,9 +17,8 @@ properties: description: Specifies the MAC address that was assigned to the network device. $ref: /schemas/types.yaml#/definitions/uint8-array - items: - - minItems: 6 - maxItems: 6 + minItems: 6 + maxItems: 6 mac-address: description: @@ -28,9 +27,8 @@ properties: to the device by the boot program is different from the local-mac-address property. $ref: /schemas/types.yaml#/definitions/uint8-array - items: - - minItems: 6 - maxItems: 6 + minItems: 6 + maxItems: 6 max-frame-size: $ref: /schemas/types.yaml#/definitions/uint32 @@ -69,6 +67,7 @@ properties: - rev-mii - rmii - rev-rmii + - moca # RX and TX delays are added by the MAC when required - rgmii @@ -163,33 +162,30 @@ properties: type: array then: deprecated: true - minItems: 1 - maxItems: 1 items: - items: - - minimum: 0 - maximum: 31 - description: - Emulated PHY ID, choose any but unique to the all - specified fixed-links + - minimum: 0 + maximum: 31 + description: + Emulated PHY ID, choose any but unique to the all + specified fixed-links - - enum: [0, 1] - description: - Duplex configuration. 0 for half duplex or 1 for - full duplex + - enum: [0, 1] + description: + Duplex configuration. 0 for half duplex or 1 for + full duplex - - enum: [10, 100, 1000] - description: - Link speed in Mbits/sec. + - enum: [10, 100, 1000, 2500, 10000] + description: + Link speed in Mbits/sec. - - enum: [0, 1] - description: - Pause configuration. 0 for no pause, 1 for pause + - enum: [0, 1] + description: + Pause configuration. 0 for no pause, 1 for pause - - enum: [0, 1] - description: - Asymmetric pause configuration. 0 for no asymmetric - pause, 1 for asymmetric pause + - enum: [0, 1] + description: + Asymmetric pause configuration. 0 for no asymmetric + pause, 1 for asymmetric pause - if: @@ -200,7 +196,7 @@ properties: description: Link speed. $ref: /schemas/types.yaml#/definitions/uint32 - enum: [10, 100, 1000] + enum: [10, 100, 1000, 2500, 10000] full-duplex: $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index eca41443fcce..fd8371e31867 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -165,7 +165,8 @@ properties: req_bit is the gpr bit offset for ENET stop request. mdio: - type: object + $ref: mdio.yaml# + unevaluatedProperties: false description: Specifies the mdio bus in the FEC, used as a container for phy nodes. diff --git a/Documentation/devicetree/bindings/net/fsl-fman.txt b/Documentation/devicetree/bindings/net/fsl-fman.txt index c00fb0d22c7b..020337f3c05f 100644 --- a/Documentation/devicetree/bindings/net/fsl-fman.txt +++ b/Documentation/devicetree/bindings/net/fsl-fman.txt @@ -410,6 +410,15 @@ PROPERTIES The settings and programming routines for internal/external MDIO are different. Must be included for internal MDIO. +- fsl,erratum-a009885 + Usage: optional + Value type: <boolean> + Definition: Indicates the presence of the A009885 + erratum describing that the contents of MDIO_DATA may + become corrupt unless it is read within 16 MDC cycles + of MDIO_CFG[BSY] being cleared, when performing an + MDIO read operation. + - fsl,erratum-a011043 Usage: optional Value type: <boolean> diff --git a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml index 08a3f1f6aea2..52a7fa4f49a4 100644 --- a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml +++ b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml @@ -117,7 +117,7 @@ examples: snps,mtl-tx-config = <&mtl_tx_setup>; snps,tso; - mdio0 { + mdio { #address-cells = <1>; #size-cells = <0>; compatible = "snps,dwmac-mdio"; diff --git a/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml index 378ed2d3b003..67eaf02dda80 100644 --- a/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml +++ b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml @@ -48,8 +48,8 @@ properties: and the instance to use in the second cell mdio: - type: object - $ref: "mdio.yaml#" + $ref: mdio.yaml# + unevaluatedProperties: false description: optional node for embedded MDIO controller required: diff --git a/Documentation/devicetree/bindings/net/lantiq,etop-xway.yaml b/Documentation/devicetree/bindings/net/lantiq,etop-xway.yaml index 437502c5ca96..3ce9f9a16baf 100644 --- a/Documentation/devicetree/bindings/net/lantiq,etop-xway.yaml +++ b/Documentation/devicetree/bindings/net/lantiq,etop-xway.yaml @@ -46,7 +46,6 @@ properties: required: - compatible - reg - - interrupt-parent - interrupts - interrupt-names - lantiq,tx-burst-length diff --git a/Documentation/devicetree/bindings/net/lantiq,xrx200-net.yaml b/Documentation/devicetree/bindings/net/lantiq,xrx200-net.yaml index 7bc074a42369..5bc1a21ca579 100644 --- a/Documentation/devicetree/bindings/net/lantiq,xrx200-net.yaml +++ b/Documentation/devicetree/bindings/net/lantiq,xrx200-net.yaml @@ -38,7 +38,6 @@ properties: required: - compatible - reg - - interrupt-parent - interrupts - interrupt-names - "#address-cells" diff --git a/Documentation/devicetree/bindings/net/litex,liteeth.yaml b/Documentation/devicetree/bindings/net/litex,liteeth.yaml index 76c164a8199a..ebf4e360f8dd 100644 --- a/Documentation/devicetree/bindings/net/litex,liteeth.yaml +++ b/Documentation/devicetree/bindings/net/litex,liteeth.yaml @@ -62,6 +62,7 @@ properties: mdio: $ref: mdio.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt deleted file mode 100644 index a1b06fd1962e..000000000000 --- a/Documentation/devicetree/bindings/net/macb.txt +++ /dev/null @@ -1,60 +0,0 @@ -* Cadence MACB/GEM Ethernet controller - -Required properties: -- compatible: Should be "cdns,[<chip>-]{macb|gem}" - Use "cdns,at91rm9200-emac" Atmel at91rm9200 SoC. - Use "cdns,at91sam9260-macb" for Atmel at91sam9 SoCs. - Use "cdns,sam9x60-macb" for Microchip sam9x60 SoC. - Use "cdns,np4-macb" for NP4 SoC devices. - Use "cdns,at32ap7000-macb" for other 10/100 usage or use the generic form: "cdns,macb". - Use "atmel,sama5d2-gem" for the GEM IP (10/100) available on Atmel sama5d2 SoCs. - Use "atmel,sama5d29-gem" for GEM XL IP (10/100) available on Atmel sama5d29 SoCs. - Use "atmel,sama5d3-macb" for the 10/100Mbit IP available on Atmel sama5d3 SoCs. - Use "atmel,sama5d3-gem" for the Gigabit IP available on Atmel sama5d3 SoCs. - Use "atmel,sama5d4-gem" for the GEM IP (10/100) available on Atmel sama5d4 SoCs. - Use "cdns,zynq-gem" Xilinx Zynq-7xxx SoC. - Use "cdns,zynqmp-gem" for Zynq Ultrascale+ MPSoC. - Use "sifive,fu540-c000-gem" for SiFive FU540-C000 SoC. - Use "microchip,sama7g5-emac" for Microchip SAMA7G5 ethernet interface. - Use "microchip,sama7g5-gem" for Microchip SAMA7G5 gigabit ethernet interface. - Or the generic form: "cdns,emac". -- reg: Address and length of the register set for the device - For "sifive,fu540-c000-gem", second range is required to specify the - address and length of the registers for GEMGXL Management block. -- interrupts: Should contain macb interrupt -- phy-mode: See ethernet.txt file in the same directory. -- clock-names: Tuple listing input clock names. - Required elements: 'pclk', 'hclk' - Optional elements: 'tx_clk' - Optional elements: 'rx_clk' applies to cdns,zynqmp-gem - Optional elements: 'tsu_clk' -- clocks: Phandles to input clocks. - -Optional properties: -- mdio: node containing PHY children. If this node is not present, then PHYs - will be direct children. - -The MAC address will be determined using the optional properties -defined in ethernet.txt. - -Optional properties for PHY child node: -- reset-gpios : Should specify the gpio for phy reset -- magic-packet : If present, indicates that the hardware supports waking - up via magic packet. -- phy-handle : see ethernet.txt file in the same directory - -Examples: - - macb0: ethernet@fffc4000 { - compatible = "cdns,at32ap7000-macb"; - reg = <0xfffc4000 0x4000>; - interrupts = <21>; - phy-mode = "rmii"; - local-mac-address = [3a 0e 03 04 05 06]; - clock-names = "pclk", "hclk", "tx_clk"; - clocks = <&clkc 30>, <&clkc 30>, <&clkc 13>; - ethernet-phy@1 { - reg = <0x1>; - reset-gpios = <&pioE 6 1>; - }; - }; diff --git a/Documentation/devicetree/bindings/net/mdio-mux.yaml b/Documentation/devicetree/bindings/net/mdio-mux.yaml index d169adf5d9f4..4321c87de86f 100644 --- a/Documentation/devicetree/bindings/net/mdio-mux.yaml +++ b/Documentation/devicetree/bindings/net/mdio-mux.yaml @@ -15,9 +15,6 @@ description: |+ bus multiplexer/switch will have one child node for each child bus. properties: - $nodename: - pattern: '^mdio-mux[\-@]?' - mdio-parent-bus: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -32,12 +29,12 @@ properties: patternProperties: '^mdio@[0-9a-f]+$': - type: object + $ref: mdio.yaml# + unevaluatedProperties: false properties: reg: maxItems: 1 - description: The sub-bus number. additionalProperties: true diff --git a/Documentation/devicetree/bindings/net/mdio.yaml b/Documentation/devicetree/bindings/net/mdio.yaml index 08e15fb1584f..b5706d4e7e38 100644 --- a/Documentation/devicetree/bindings/net/mdio.yaml +++ b/Documentation/devicetree/bindings/net/mdio.yaml @@ -59,7 +59,7 @@ properties: type: boolean patternProperties: - "^ethernet-phy@[0-9a-f]+$": + '@[0-9a-f]+$': type: object properties: @@ -76,12 +76,6 @@ patternProperties: the turn around line low at end of the control phase of the MDIO transaction. - resets: - maxItems: 1 - - reset-names: - const: phy - reset-gpios: maxItems: 1 description: diff --git a/Documentation/devicetree/bindings/net/mediatek,star-emac.yaml b/Documentation/devicetree/bindings/net/mediatek,star-emac.yaml index e6a5ff208253..def994c9cbb4 100644 --- a/Documentation/devicetree/bindings/net/mediatek,star-emac.yaml +++ b/Documentation/devicetree/bindings/net/mediatek,star-emac.yaml @@ -48,9 +48,8 @@ properties: to control the MII mode. mdio: - type: object - description: - Creates and registers an MDIO bus. + $ref: mdio.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/net/oxnas-dwmac.txt b/Documentation/devicetree/bindings/net/oxnas-dwmac.txt index d7117a22fd87..27db496f1ce8 100644 --- a/Documentation/devicetree/bindings/net/oxnas-dwmac.txt +++ b/Documentation/devicetree/bindings/net/oxnas-dwmac.txt @@ -9,6 +9,9 @@ Required properties on all platforms: - compatible: For the OX820 SoC, it should be : - "oxsemi,ox820-dwmac" to select glue - "snps,dwmac-3.512" to select IP version. + For the OX810SE SoC, it should be : + - "oxsemi,ox810se-dwmac" to select glue + - "snps,dwmac-3.512" to select IP version. - clocks: Should contain phandles to the following clocks - clock-names: Should contain the following: diff --git a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml index cf4d35edaa1b..1ebf9e8c8a1d 100644 --- a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml @@ -34,14 +34,6 @@ properties: interrupts: maxItems: 1 - '#address-cells': - description: number of address cells for the MDIO bus - const: 1 - - '#size-cells': - description: number of size cells on the MDIO bus - const: 0 - clocks: items: - description: MAC main clock @@ -62,6 +54,10 @@ properties: - const: mac - const: mdio + mdio: + $ref: mdio.yaml# + unevaluatedProperties: false + required: - compatible - reg @@ -85,7 +81,6 @@ examples: reset-names = "mac", "mdio"; clocks = <&pll 1>, <&pll 2>; clock-names = "eth", "mdio"; - qca,ethcfg = <ðcfg>; phy-mode = "mii"; phy-handle = <&phy_port4>; }; @@ -111,9 +106,6 @@ examples: #size-cells = <0>; switch10: switch@10 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "qca,ar9331-switch"; reg = <0x10>; resets = <&rst 8>; diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index b86edf67ce62..58ecc62adfaa 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -107,6 +107,10 @@ properties: - const: imem - const: config + qcom,qmp: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the AOSS side-channel message RAM + qcom,smem-states: $ref: /schemas/types.yaml#/definitions/phandle-array description: State bits used in by the AP to signal the modem. @@ -222,6 +226,8 @@ examples: "imem", "config"; + qcom,qmp = <&aoss_qmp>; + qcom,smem-states = <&ipa_smp2p_out 0>, <&ipa_smp2p_out 1>; qcom,smem-state-names = "ipa-clock-enabled-valid", diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 7ae70dc27f78..7eb43707e601 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -286,7 +286,8 @@ properties: MAC2MAC connection. mdio: - type: object + $ref: mdio.yaml# + unevaluatedProperties: false description: Creates and registers an MDIO bus. @@ -326,6 +327,9 @@ allOf: - ingenic,x1600-mac - ingenic,x1830-mac - ingenic,x2000-mac + - snps,dwmac-3.50a + - snps,dwmac-4.10a + - snps,dwmac-4.20a - snps,dwxgmac - snps,dwxgmac-2.10 - st,spear600-gmac diff --git a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.yaml b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.yaml index 6bc61c42418f..aad5a9f3f962 100644 --- a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.yaml +++ b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.yaml @@ -72,6 +72,7 @@ properties: mdio: $ref: mdio.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/net/stm32-dwmac.yaml b/Documentation/devicetree/bindings/net/stm32-dwmac.yaml index 577f4e284425..3d8a3b763ae6 100644 --- a/Documentation/devicetree/bindings/net/stm32-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/stm32-dwmac.yaml @@ -44,6 +44,12 @@ properties: - st,stm32-dwmac - const: snps,dwmac-3.50a + reg: true + + reg-names: + items: + - const: stmmaceth + clocks: minItems: 3 items: @@ -102,7 +108,7 @@ examples: compatible = "st,stm32mp1-dwmac", "snps,dwmac-4.20a"; reg = <0x5800a000 0x2000>; reg-names = "stmmaceth"; - interrupts = <&intc GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>; + interrupts = <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "macirq"; clock-names = "stmmaceth", "mac-clk-tx", @@ -121,6 +127,7 @@ examples: phy-mode = "rgmii"; }; + - | //Example 2 (MCU example) ethernet1: ethernet@40028000 { compatible = "st,stm32-dwmac", "snps,dwmac-3.50a"; @@ -136,6 +143,7 @@ examples: phy-mode = "mii"; }; + - | //Example 3 ethernet2: ethernet@40027000 { compatible = "st,stm32-dwmac", "snps,dwmac-4.10a"; diff --git a/Documentation/devicetree/bindings/net/ti,davinci-mdio.yaml b/Documentation/devicetree/bindings/net/ti,davinci-mdio.yaml index 5728fe23f530..dbfca5ee9139 100644 --- a/Documentation/devicetree/bindings/net/ti,davinci-mdio.yaml +++ b/Documentation/devicetree/bindings/net/ti,davinci-mdio.yaml @@ -37,6 +37,13 @@ properties: maximum: 2500000 description: MDIO Bus frequency + clocks: + maxItems: 1 + + clock-names: + items: + - const: fck + ti,hwmods: description: TI hwmod name deprecated: true diff --git a/Documentation/devicetree/bindings/net/ti,dp83869.yaml b/Documentation/devicetree/bindings/net/ti,dp83869.yaml index 70a1209cb13b..1b780dce61ab 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83869.yaml +++ b/Documentation/devicetree/bindings/net/ti,dp83869.yaml @@ -92,7 +92,7 @@ examples: tx-fifo-depth = <DP83869_PHYCR_FIFO_DEPTH_4_B_NIB>; rx-fifo-depth = <DP83869_PHYCR_FIFO_DEPTH_4_B_NIB>; ti,op-mode = <DP83869_RGMII_COPPER_ETHERNET>; - ti,max-output-impedance = "true"; + ti,max-output-impedance; ti,clk-output-sel = <DP83869_CLK_O_SEL_CHN_A_RCLK>; rx-internal-delay-ps = <2000>; tx-internal-delay-ps = <2000>; diff --git a/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml b/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml index 59724d18e6f3..b12bfe61c67a 100644 --- a/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml @@ -71,7 +71,7 @@ examples: phy-mode = "rgmii-id"; phy-handle = <&phy0>; - mdio0 { + mdio { #address-cells = <0x1>; #size-cells = <0x0>; compatible = "snps,dwmac-mdio"; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml index 1489d3c1cd6e..269cd63fb544 100644 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml @@ -191,9 +191,9 @@ examples: channels = <36 48>; rates-ofdm = /bits/ 8 <23 23 23 23 23 23 23 23>; rates-mcs = /bits/ 8 <1 23 23 23 23 23 23 23 23 23 23>, - <3 22 22 22 22 22 22 22 22 22 22>; + /bits/ 8 <3 22 22 22 22 22 22 22 22 22 22>; rates-ru = /bits/ 8 <3 22 22 22 22 22 22 22 22 22 22 22 22>, - <4 20 20 20 20 20 20 20 20 20 20 20 20>; + /bits/ 8 <4 20 20 20 20 20 20 20 20 20 20 20 20>; }; b1 { channels = <100 181>; diff --git a/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml index 58ff6b0bdb1a..8c3f0cd22821 100644 --- a/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml +++ b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml @@ -24,6 +24,9 @@ properties: compatible: const: brcm,nvram + reg: + maxItems: 1 + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt index b6791702bcfc..39d529599444 100644 --- a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt @@ -8,8 +8,10 @@ Required properties: "mediatek,mt7623-efuse", "mediatek,efuse": for MT7623 "mediatek,mt8173-efuse" or "mediatek,efuse": for MT8173 "mediatek,mt8192-efuse", "mediatek,efuse": for MT8192 + "mediatek,mt8195-efuse", "mediatek,efuse": for MT8195 "mediatek,mt8516-efuse", "mediatek,efuse": for MT8516 - reg: Should contain registers location and length +- bits: contain the bits range by offset and size = Data cells = Are child nodes of MTK-EFUSE, bindings of which as described in diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 456fb808100a..43ed7e32e5ac 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -50,16 +50,15 @@ patternProperties: Offset and size in bytes within the storage device. bits: - maxItems: 1 + $ref: /schemas/types.yaml#/definitions/uint32-array items: - items: - - minimum: 0 - maximum: 7 - description: - Offset in bit within the address range specified by reg. - - minimum: 1 - description: - Size in bit within the address range specified by reg. + - minimum: 0 + maximum: 7 + description: + Offset in bit within the address range specified by reg. + - minimum: 1 + description: + Size in bit within the address range specified by reg. required: - reg diff --git a/Documentation/devicetree/bindings/nvmem/rmem.yaml b/Documentation/devicetree/bindings/nvmem/rmem.yaml index 1d85a0a30846..a4a755dcfc43 100644 --- a/Documentation/devicetree/bindings/nvmem/rmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/rmem.yaml @@ -19,6 +19,9 @@ properties: - raspberrypi,bootloader-config - const: nvmem-rmem + reg: + maxItems: 1 + no-map: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml index a48c8fa56bce..448a2678dc62 100644 --- a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml +++ b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml @@ -24,6 +24,9 @@ properties: - st,stm32f4-otp - st,stm32mp15-bsec + reg: + maxItems: 1 + patternProperties: "^.*@[0-9a-f]+$": type: object diff --git a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt deleted file mode 100644 index df065aa53a83..000000000000 --- a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt +++ /dev/null @@ -1,133 +0,0 @@ -* Broadcom iProc PCIe controller with the platform bus interface - -Required properties: -- compatible: - "brcm,iproc-pcie" for the first generation of PAXB based controller, -used in SoCs including NSP, Cygnus, NS2, and Pegasus - "brcm,iproc-pcie-paxb-v2" for the second generation of PAXB-based -controllers, used in Stingray - "brcm,iproc-pcie-paxc" for the first generation of PAXC based -controller, used in NS2 - "brcm,iproc-pcie-paxc-v2" for the second generation of PAXC based -controller, used in Stingray - PAXB-based root complex is used for external endpoint devices. PAXC-based -root complex is connected to emulated endpoint devices internal to the ASIC -- reg: base address and length of the PCIe controller I/O register space -- #interrupt-cells: set to <1> -- interrupt-map-mask and interrupt-map, standard PCI properties to define the - mapping of the PCIe interface to interrupt numbers -- linux,pci-domain: PCI domain ID. Should be unique for each host controller -- bus-range: PCI bus numbers covered -- #address-cells: set to <3> -- #size-cells: set to <2> -- device_type: set to "pci" -- ranges: ranges for the PCI memory and I/O regions - -Optional properties: -- phys: phandle of the PCIe PHY device -- phy-names: must be "pcie-phy" -- dma-coherent: present if DMA operations are coherent -- dma-ranges: Some PAXB-based root complexes do not have inbound mapping done - by the ASIC after power on reset. In this case, SW is required to configure -the mapping, based on inbound memory regions specified by this property. - -- brcm,pcie-ob: Some iProc SoCs do not have the outbound address mapping done -by the ASIC after power on reset. In this case, SW needs to configure it - -If the brcm,pcie-ob property is present, the following properties become -effective: - -Required: -- brcm,pcie-ob-axi-offset: The offset from the AXI address to the internal -address used by the iProc PCIe core (not the PCIe address) - -MSI support (optional): - -For older platforms without MSI integrated in the GIC, iProc PCIe core provides -an event queue based MSI support. The iProc MSI uses host memories to store -MSI posted writes in the event queues - -On newer iProc platforms, gicv2m or gicv3-its based MSI support should be used - -- msi-map: Maps a Requester ID to an MSI controller and associated MSI -sideband data - -- msi-parent: Link to the device node of the MSI controller, used when no MSI -sideband data is passed between the iProc PCIe controller and the MSI -controller - -Refer to the following binding documents for more detailed description on -the use of 'msi-map' and 'msi-parent': - Documentation/devicetree/bindings/pci/pci-msi.txt - Documentation/devicetree/bindings/interrupt-controller/msi.txt - -When the iProc event queue based MSI is used, one needs to define the -following properties in the MSI device node: -- compatible: Must be "brcm,iproc-msi" -- msi-controller: claims itself as an MSI controller -- interrupts: List of interrupt IDs from its parent interrupt device - -Optional properties: -- brcm,pcie-msi-inten: Needs to be present for some older iProc platforms that -require the interrupt enable registers to be set explicitly to enable MSI - -Example: - pcie0: pcie@18012000 { - compatible = "brcm,iproc-pcie"; - reg = <0x18012000 0x1000>; - - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 100 IRQ_TYPE_NONE>; - - linux,pci-domain = <0>; - - bus-range = <0x00 0xff>; - - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x81000000 0 0 0x28000000 0 0x00010000 - 0x82000000 0 0x20000000 0x20000000 0 0x04000000>; - - phys = <&phy 0 5>; - phy-names = "pcie-phy"; - - brcm,pcie-ob; - brcm,pcie-ob-axi-offset = <0x00000000>; - - msi-parent = <&msi0>; - - /* iProc event queue based MSI */ - msi0: msi@18012000 { - compatible = "brcm,iproc-msi"; - msi-controller; - interrupt-parent = <&gic>; - interrupts = <GIC_SPI 96 IRQ_TYPE_NONE>, - <GIC_SPI 97 IRQ_TYPE_NONE>, - <GIC_SPI 98 IRQ_TYPE_NONE>, - <GIC_SPI 99 IRQ_TYPE_NONE>, - }; - }; - - pcie1: pcie@18013000 { - compatible = "brcm,iproc-pcie"; - reg = <0x18013000 0x1000>; - - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 106 IRQ_TYPE_NONE>; - - linux,pci-domain = <1>; - - bus-range = <0x00 0xff>; - - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x81000000 0 0 0x48000000 0 0x00010000 - 0x82000000 0 0x40000000 0x40000000 0 0x04000000>; - - phys = <&phy 1 6>; - phy-names = "pcie-phy"; - }; diff --git a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml new file mode 100644 index 000000000000..0972868735fc --- /dev/null +++ b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/brcm,iproc-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom iProc PCIe controller with the platform bus interface + +maintainers: + - Ray Jui <ray.jui@broadcom.com> + - Scott Branden <scott.branden@broadcom.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/interrupt-controller/msi-controller.yaml# + +properties: + compatible: + items: + - enum: + # for the first generation of PAXB based controller, used in SoCs + # including NSP, Cygnus, NS2, and Pegasus + - brcm,iproc-pcie + # for the second generation of PAXB-based controllers, used in + # Stingray + - brcm,iproc-pcie-paxb-v2 + # For the first generation of PAXC based controller, used in NS2 + - brcm,iproc-pcie-paxc + # For the second generation of PAXC based controller, used in Stingray + - brcm,iproc-pcie-paxc-v2 + + reg: + maxItems: 1 + description: > + Base address and length of the PCIe controller I/O register space + + interrupt-map: true + + interrupt-map-mask: true + + "#interrupt-cells": + const: 1 + + ranges: + minItems: 1 + maxItems: 2 + description: > + Ranges for the PCI memory and I/O regions + + phys: + maxItems: 1 + + phy-names: + items: + - const: pcie-phy + + bus-range: true + + dma-coherent: true + + "#address-cells": true + + "#size-cells": true + + device_type: true + + brcm,pcie-ob: + type: boolean + description: > + Some iProc SoCs do not have the outbound address mapping done by the + ASIC after power on reset. In this case, SW needs to configure it + + brcm,pcie-ob-axi-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + The offset from the AXI address to the internal address used by the + iProc PCIe core (not the PCIe address) + + msi: + type: object + properties: + compatible: + items: + - const: brcm,iproc-msi + + msi-parent: true + + msi-controller: true + + brcm,pcie-msi-inten: + type: boolean + description: > + Needs to be present for some older iProc platforms that require the + interrupt enable registers to be set explicitly to enable MSI + +dependencies: + brcm,pcie-ob-axi-offset: ["brcm,pcie-ob"] + brcm,pcie-msi-inten: [msi-controller] + +required: + - compatible + - reg + - ranges + +if: + properties: + compatible: + contains: + enum: + - brcm,iproc-pcie +then: + required: + - interrupt-map + - interrupt-map-mask + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bus { + #address-cells = <1>; + #size-cells = <1>; + pcie0: pcie@18012000 { + compatible = "brcm,iproc-pcie"; + reg = <0x18012000 0x1000>; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 100 IRQ_TYPE_NONE>; + + linux,pci-domain = <0>; + + bus-range = <0x00 0xff>; + + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x81000000 0 0 0x28000000 0 0x00010000>, + <0x82000000 0 0x20000000 0x20000000 0 0x04000000>; + + phys = <&phy 0 5>; + phy-names = "pcie-phy"; + + brcm,pcie-ob; + brcm,pcie-ob-axi-offset = <0x00000000>; + + msi-parent = <&msi0>; + + /* iProc event queue based MSI */ + msi0: msi { + compatible = "brcm,iproc-msi"; + msi-controller; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 96 IRQ_TYPE_NONE>, + <GIC_SPI 97 IRQ_TYPE_NONE>, + <GIC_SPI 98 IRQ_TYPE_NONE>, + <GIC_SPI 99 IRQ_TYPE_NONE>; + }; + }; + + pcie1: pcie@18013000 { + compatible = "brcm,iproc-pcie"; + reg = <0x18013000 0x1000>; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 106 IRQ_TYPE_NONE>; + + linux,pci-domain = <1>; + + bus-range = <0x00 0xff>; + + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x81000000 0 0 0x48000000 0 0x00010000>, + <0x82000000 0 0x40000000 0x40000000 0 0x04000000>; + + phys = <&phy 1 6>; + phy-names = "pcie-phy"; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml index 1fe102743f82..0f064e4222f3 100644 --- a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml @@ -19,6 +19,8 @@ properties: - brcm,bcm7278-pcie # Broadcom 7278 Arm - brcm,bcm7216-pcie # Broadcom 7216 Arm - brcm,bcm7445-pcie # Broadcom 7445 Arm + - brcm,bcm7425-pcie # Broadcom 7425 MIPs + - brcm,bcm7435-pcie # Broadcom 7435 MIPs reg: maxItems: 1 @@ -76,6 +78,7 @@ properties: maxItems: 3 required: + - compatible - reg - ranges - dma-ranges @@ -143,11 +146,15 @@ examples: #address-cells = <3>; #size-cells = <2>; #interrupt-cells = <1>; - interrupts = <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>, + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "pcie", "msi"; interrupt-map-mask = <0x0 0x0 0x0 0x7>; - interrupt-map = <0 0 0 1 &gicv2 GIC_SPI 143 IRQ_TYPE_LEVEL_HIGH>; + interrupt-map = <0 0 0 1 &gicv2 GIC_SPI 143 IRQ_TYPE_LEVEL_HIGH + 0 0 0 2 &gicv2 GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH + 0 0 0 3 &gicv2 GIC_SPI 145 IRQ_TYPE_LEVEL_HIGH + 0 0 0 4 &gicv2 GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>; + msi-parent = <&pcie0>; msi-controller; ranges = <0x02000000 0x0 0xf8000000 0x6 0x00000000 0x0 0x04000000>; @@ -155,5 +162,24 @@ examples: <0x42000000 0x1 0x80000000 0x3 0x00000000 0x0 0x80000000>; brcm,enable-ssc; brcm,scb-sizes = <0x0000000080000000 0x0000000080000000>; + + /* PCIe bridge, Root Port */ + pci@0,0 { + #address-cells = <3>; + #size-cells = <2>; + reg = <0x0 0x0 0x0 0x0 0x0>; + compatible = "pciclass,0604"; + device_type = "pci"; + vpcie3v3-supply = <&vreg7>; + ranges; + + /* PCIe endpoint */ + pci-ep@0,0 { + assigned-addresses = + <0x82010000 0x0 0xf8000000 0x6 0x00000000 0x0 0x2000>; + reg = <0x0 0x0 0x0 0x0 0x0>; + compatible = "pci14e4,1688"; + }; + }; }; }; diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.yaml index 651eee88989d..e6ef1012a580 100644 --- a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.yaml @@ -11,7 +11,6 @@ maintainers: allOf: - $ref: "cdns-pcie-ep.yaml#" - - $ref: "pci-ep.yaml#" properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml index 21e8a8849076..baeafda36ebe 100644 --- a/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: "cdns-pcie.yaml#" + - $ref: "pci-ep.yaml#" properties: cdns,max-outbound-regions: diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml index acea1cd444fd..643a6333b07b 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml @@ -127,6 +127,12 @@ properties: enum: [1, 2, 3, 4] default: 1 + phys: + maxItems: 1 + + phy-names: + const: pcie-phy + reset-gpio: description: Should specify the GPIO for controlling the PCI bus device reset signal. It's not polarity aware and defaults to active-low reset diff --git a/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml b/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml index cbee87802559..c9f04999c9cf 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml @@ -37,6 +37,19 @@ properties: minItems: 3 maxItems: 4 + clocks: true + + clock-names: + items: + - const: pcie_phy_ref + - const: pcie_aux + - const: pcie_apb_phy + - const: pcie_apb_sys + - const: pcie_aclk + + phys: + maxItems: 1 + hisilicon,clken-gpios: description: | Clock input enablement GPIOs from PCI devices like Ethernet, M.2 and diff --git a/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml b/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml index 044fa967bc8b..d60f43fd9c5a 100644 --- a/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml @@ -45,6 +45,9 @@ patternProperties: phys: maxItems: 1 + phy-names: + pattern: '^pcie-phy[0-2]$' + required: - "#interrupt-cells" - interrupt-map-mask diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml index 742206dbd965..0499b94627ae 100644 --- a/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml @@ -95,6 +95,10 @@ properties: phys: maxItems: 1 + phy-names: + items: + - const: pcie-phy + '#interrupt-cells': const: 1 diff --git a/Documentation/devicetree/bindings/pci/microchip,pcie-host.yaml b/Documentation/devicetree/bindings/pci/microchip,pcie-host.yaml index 7b0776457178..edb4f81253c8 100644 --- a/Documentation/devicetree/bindings/pci/microchip,pcie-host.yaml +++ b/Documentation/devicetree/bindings/pci/microchip,pcie-host.yaml @@ -46,6 +46,24 @@ properties: msi-parent: description: MSI controller the device is capable of using. + interrupt-controller: + type: object + properties: + '#address-cells': + const: 0 + + '#interrupt-cells': + const: 1 + + interrupt-controller: true + + required: + - '#address-cells' + - '#interrupt-cells' + - interrupt-controller + + additionalProperties: false + required: - reg - reg-names diff --git a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml index 2b9d1d6fc661..392f0ab488c2 100644 --- a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml @@ -32,6 +32,8 @@ properties: - const: config - const: mgmt + dma-coherent: true + num-lanes: const: 8 @@ -61,10 +63,8 @@ required: - num-lanes - interrupts - interrupt-names - - interrupt-parent - interrupt-map-mask - interrupt-map - - clock-names - clocks - resets - pwren-gpios @@ -104,7 +104,6 @@ examples: <0x0 0x0 0x0 0x2 &plic0 58>, <0x0 0x0 0x0 0x3 &plic0 59>, <0x0 0x0 0x0 0x4 &plic0 60>; - clock-names = "pcie_aux"; clocks = <&prci PRCI_CLK_PCIE_AUX>; resets = <&prci 4>; pwren-gpios = <&gpio 5 0>; diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml index b5935b1b153f..e59059ab5be0 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml @@ -64,16 +64,12 @@ properties: maxItems: 1 deprecated: true - max-functions: - $ref: /schemas/types.yaml#/definitions/uint32 - description: maximum number of functions that can be configured - required: - reg - reg-names - compatible -unevaluatedProperties: false +additionalProperties: true examples: - | diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml index 9ed0dfba7f89..a5345c494744 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml @@ -73,7 +73,7 @@ properties: does not specify it, the driver autodetects it. deprecated: true -unevaluatedProperties: false +additionalProperties: true required: - reg diff --git a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml index 144cbcd60a1c..179ab0858482 100644 --- a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml @@ -79,7 +79,7 @@ required: - resets - reset-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/pci/ti,am65-pci-ep.yaml b/Documentation/devicetree/bindings/pci/ti,am65-pci-ep.yaml index 78c217d362a7..74195c1f5292 100644 --- a/Documentation/devicetree/bindings/pci/ti,am65-pci-ep.yaml +++ b/Documentation/devicetree/bindings/pci/ti,am65-pci-ep.yaml @@ -32,8 +32,12 @@ properties: maxItems: 1 ti,syscon-pcie-mode: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: Phandle to the SYSCON entry + - description: pcie_ctrl register offset within SYSCON description: Phandle to the SYSCON entry required for configuring PCIe in RC or EP mode. - $ref: /schemas/types.yaml#/definitions/phandle interrupts: minItems: 1 @@ -65,9 +69,7 @@ examples: <0x5506000 0x1000>; reg-names = "app", "dbics", "addr_space", "atu"; power-domains = <&k3_pds 120 TI_SCI_PD_EXCLUSIVE>; - ti,syscon-pcie-mode = <&pcie0_mode>; - num-ib-windows = <16>; - num-ob-windows = <16>; + ti,syscon-pcie-mode = <&scm_conf 0x4060>; max-link-speed = <2>; dma-coherent; interrupts = <GIC_SPI 340 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/pci/ti,am65-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,am65-pci-host.yaml index 834dc1c1743c..a20dccbafd94 100644 --- a/Documentation/devicetree/bindings/pci/ti,am65-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/ti,am65-pci-host.yaml @@ -29,16 +29,27 @@ properties: - const: config - const: atu + interrupts: + maxItems: 1 + power-domains: maxItems: 1 ti,syscon-pcie-id: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: Phandle to the SYSCON entry + - description: pcie_device_id register offset within SYSCON description: Phandle to the SYSCON entry required for getting PCIe device/vendor ID - $ref: /schemas/types.yaml#/definitions/phandle ti,syscon-pcie-mode: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: Phandle to the SYSCON entry + - description: pcie_ctrl register offset within SYSCON description: Phandle to the SYSCON entry required for configuring PCIe in RC or EP mode. - $ref: /schemas/types.yaml#/definitions/phandle msi-map: true @@ -84,10 +95,9 @@ examples: #size-cells = <2>; ranges = <0x81000000 0 0 0x10020000 0 0x00010000>, <0x82000000 0 0x10030000 0x10030000 0 0x07FD0000>; - ti,syscon-pcie-id = <&pcie_devid>; - ti,syscon-pcie-mode = <&pcie0_mode>; + ti,syscon-pcie-id = <&scm_conf 0x0210>; + ti,syscon-pcie-mode = <&scm_conf 0x4060>; bus-range = <0x0 0xff>; - num-viewport = <16>; max-link-speed = <2>; dma-coherent; interrupts = <GIC_SPI 340 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml index cc900202df29..2115d5a3f0e1 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml @@ -60,6 +60,8 @@ properties: - const: fck - const: pcie_refclk + dma-coherent: true + vendor-id: const: 0x104c diff --git a/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml b/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml index a2bbc0eb7220..32f4641085bc 100644 --- a/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml +++ b/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml @@ -55,7 +55,6 @@ required: - reg-names - "#interrupt-cells" - interrupts - - interrupt-parent - interrupt-map - interrupt-map-mask - bus-range diff --git a/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml b/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml new file mode 100644 index 000000000000..aef63a542f34 --- /dev/null +++ b/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2021 Arm Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/arm,dsu-pmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM DynamIQ Shared Unit (DSU) Performance Monitor Unit (PMU) + +maintainers: + - Suzuki K Poulose <suzuki.poulose@arm.com> + - Robin Murphy <robin.murphy@arm.com> + +description: + ARM DynamIQ Shared Unit (DSU) integrates one or more CPU cores with a shared + L3 memory system, control logic and external interfaces to form a multicore + cluster. The PMU enables gathering various statistics on the operation of the + DSU. The PMU provides independent 32-bit counters that can count any of the + supported events, along with a 64-bit cycle counter. The PMU is accessed via + CPU system registers and has no MMIO component. + +properties: + compatible: + oneOf: + - const: arm,dsu-pmu + - items: + - const: arm,dsu-110-pmu + - const: arm,dsu-pmu + + interrupts: + items: + - description: nCLUSTERPMUIRQ interrupt + + cpus: + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 12 + description: List of phandles for the CPUs connected to this DSU instance. + +required: + - compatible + - interrupts + - cpus + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/perf/marvell-cn10k-ddr.yaml b/Documentation/devicetree/bindings/perf/marvell-cn10k-ddr.yaml new file mode 100644 index 000000000000..a18dd0a8c43a --- /dev/null +++ b/Documentation/devicetree/bindings/perf/marvell-cn10k-ddr.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/marvell-cn10k-ddr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell CN10K DDR performance monitor + +maintainers: + - Bharat Bhushan <bbhushan2@marvell.com> + +properties: + compatible: + items: + - enum: + - marvell,cn10k-ddr-pmu + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + pmu@87e1c0000000 { + compatible = "marvell,cn10k-ddr-pmu"; + reg = <0x87e1 0xc0000000 0x0 0x10000>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson8-hdmi-tx-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,meson8-hdmi-tx-phy.yaml new file mode 100644 index 000000000000..1f085cdd1c85 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/amlogic,meson8-hdmi-tx-phy.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/amlogic,meson8-hdmi-tx-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic Meson8, Meson8b and Meson8m2 HDMI TX PHY + +maintainers: + - Martin Blumenstingl <martin.blumenstingl@googlemail.com> + +description: |+ + The HDMI TX PHY node should be the child of a syscon node with the + required property: + + compatible = "amlogic,meson-hhi-sysctrl", "simple-mfd", "syscon" + + Refer to the bindings described in + Documentation/devicetree/bindings/mfd/syscon.yaml + +properties: + $nodename: + pattern: "^hdmi-phy@[0-9a-f]+$" + + compatible: + oneOf: + - items: + - enum: + - amlogic,meson8b-hdmi-tx-phy + - amlogic,meson8m2-hdmi-tx-phy + - const: amlogic,meson8-hdmi-tx-phy + - const: amlogic,meson8-hdmi-tx-phy + + reg: + maxItems: 1 + + clocks: + minItems: 1 + description: + HDMI TMDS clock + + "#phy-cells": + const: 0 + +required: + - compatible + - "#phy-cells" + +additionalProperties: false + +examples: + - | + hdmi-phy@3a0 { + compatible = "amlogic,meson8-hdmi-tx-phy"; + reg = <0x3a0 0xc>; + clocks = <&tmds_clock>; + #phy-cells = <0>; + }; + - | + hdmi-phy@3a0 { + compatible = "amlogic,meson8b-hdmi-tx-phy", "amlogic,meson8-hdmi-tx-phy"; + reg = <0x3a0 0xc>; + clocks = <&tmds_clock>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt b/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt deleted file mode 100644 index 10efff28b52b..000000000000 --- a/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt +++ /dev/null @@ -1,47 +0,0 @@ -Broadcom Cygnus PCIe PHY - -Required properties: -- compatible: must be "brcm,cygnus-pcie-phy" -- reg: base address and length of the PCIe PHY block -- #address-cells: must be 1 -- #size-cells: must be 0 - -Each PCIe PHY should be represented by a child node - -Required properties For the child node: -- reg: the PHY ID -0 - PCIe RC 0 -1 - PCIe RC 1 -- #phy-cells: must be 0 - -Example: - pcie_phy: phy@301d0a0 { - compatible = "brcm,cygnus-pcie-phy"; - reg = <0x0301d0a0 0x14>; - - pcie0_phy: phy@0 { - reg = <0>; - #phy-cells = <0>; - }; - - pcie1_phy: phy@1 { - reg = <1>; - #phy-cells = <0>; - }; - }; - - /* users of the PCIe phy */ - - pcie0: pcie@18012000 { - ... - ... - phys = <&pcie0_phy>; - phy-names = "pcie-phy"; - }; - - pcie1: pcie@18013000 { - ... - ... - phys = <pcie1_phy>; - phy-names = "pcie-phy"; - }; diff --git a/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.yaml new file mode 100644 index 000000000000..045699c65779 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/brcm,cygnus-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Cygnus PCIe PHY + +maintainers: + - Ray Jui <ray.jui@broadcom.com> + - Scott Branden <scott.branden@broadcom.com> + +properties: + $nodename: + pattern: "^pcie[-|_]phy(@.*)?$" + + compatible: + items: + - const: brcm,cygnus-pcie-phy + + reg: + maxItems: 1 + description: > + Base address and length of the PCIe PHY block + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^pcie-phy@[0-9]+$": + type: object + description: > + PCIe PHY child nodes + + properties: + reg: + maxItems: 1 + description: > + The PCIe PHY port number + + "#phy-cells": + const: 0 + + required: + - reg + - "#phy-cells" + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + pcie_phy: pcie_phy@301d0a0 { + compatible = "brcm,cygnus-pcie-phy"; + reg = <0x0301d0a0 0x14>; + #address-cells = <1>; + #size-cells = <0>; + + pcie0_phy: pcie-phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + pcie1_phy: pcie-phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,mdio-mux-bus-pci.txt b/Documentation/devicetree/bindings/phy/brcm,mdio-mux-bus-pci.txt deleted file mode 100644 index 5b51007c6f24..000000000000 --- a/Documentation/devicetree/bindings/phy/brcm,mdio-mux-bus-pci.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Broadcom NS2 PCIe PHY binding document - -Required bus properties: -- reg: MDIO Bus number for the MDIO interface -- #address-cells: must be 1 -- #size-cells: must be 0 - -Required PHY properties: -- compatible: should be "brcm,ns2-pcie-phy" -- reg: MDIO Phy ID for the MDIO interface -- #phy-cells: must be 0 - -This is a child bus node of "brcm,mdio-mux-iproc" node. - -Example: - -mdio@0 { - reg = <0x0>; - #address-cells = <1>; - #size-cells = <0>; - - pci_phy0: pci-phy@0 { - compatible = "brcm,ns2-pcie-phy"; - reg = <0x0>; - #phy-cells = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/phy/brcm,ns2-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,ns2-pcie-phy.yaml new file mode 100644 index 000000000000..70eb48b391c9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,ns2-pcie-phy.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/brcm,ns2-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom NS2 PCIe PHY binding document + +maintainers: + - Ray Jui <ray.jui@broadcom.com> + - Scott Branden <scott.branden@broadcom.com> + +properties: + compatible: + const: brcm,ns2-pcie-phy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - "#phy-cells" + +additionalProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + pci-phy@0 { + compatible = "brcm,ns2-pcie-phy"; + reg = <0x0>; + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/fsl,imx8-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/fsl,imx8-pcie-phy.yaml new file mode 100644 index 000000000000..b6421eedece3 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/fsl,imx8-pcie-phy.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/fsl,imx8-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX8 SoC series PCIe PHY Device Tree Bindings + +maintainers: + - Richard Zhu <hongxing.zhu@nxp.com> + +properties: + "#phy-cells": + const: 0 + + compatible: + enum: + - fsl,imx8mm-pcie-phy + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: ref + + resets: + maxItems: 1 + + reset-names: + items: + - const: pciephy + + fsl,refclk-pad-mode: + description: | + Specifies the mode of the refclk pad used. It can be UNUSED(PHY + refclock is derived from SoC internal source), INPUT(PHY refclock + is provided externally via the refclk pad) or OUTPUT(PHY refclock + is derived from SoC internal source and provided on the refclk pad). + Refer include/dt-bindings/phy/phy-imx8-pcie.h for the constants + to be used. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2 ] + + fsl,tx-deemph-gen1: + description: Gen1 De-emphasis value (optional). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + fsl,tx-deemph-gen2: + description: Gen2 De-emphasis value (optional). + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + fsl,clkreq-unsupported: + type: boolean + description: A boolean property indicating the CLKREQ# signal is + not supported in the board design (optional) + +required: + - "#phy-cells" + - compatible + - reg + - clocks + - clock-names + - fsl,refclk-pad-mode + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mm-clock.h> + #include <dt-bindings/phy/phy-imx8-pcie.h> + #include <dt-bindings/reset/imx8mq-reset.h> + + pcie_phy: pcie-phy@32f00000 { + compatible = "fsl,imx8mm-pcie-phy"; + reg = <0x32f00000 0x10000>; + clocks = <&clk IMX8MM_CLK_PCIE1_PHY>; + clock-names = "ref"; + assigned-clocks = <&clk IMX8MM_CLK_PCIE1_PHY>; + assigned-clock-rates = <100000000>; + assigned-clock-parents = <&clk IMX8MM_SYS_PLL2_100M>; + resets = <&src IMX8MQ_RESET_PCIEPHY>; + reset-names = "pciephy"; + fsl,refclk-pad-mode = <IMX8_PCIE_REFCLK_PAD_INPUT>; + #phy-cells = <0>; + }; +... diff --git a/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml b/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml new file mode 100644 index 000000000000..34bdb5c4cae8 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/intel,phy-thunderbay-emmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Thunder Bay eMMC PHY bindings + +maintainers: + - Srikandan Nandhini <nandhini.srikandan@intel.com> + +properties: + compatible: + const: intel,thunderbay-emmc-phy + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: emmcclk + +required: + - "#phy-cells" + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + mmc_phy@80440800 { + #phy-cells = <0x0>; + compatible = "intel,thunderbay-emmc-phy"; + status = "okay"; + reg = <0x80440800 0x100>; + clocks = <&emmc>; + clock-names = "emmcclk"; + }; diff --git a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml index 9e6c0f43f1c6..05ee274b4b71 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml @@ -160,6 +160,24 @@ patternProperties: - PHY_TYPE_PCIE - PHY_TYPE_SATA + nvmem-cells: + items: + - description: internal R efuse for U2 PHY or U3/PCIe PHY + - description: rx_imp_sel efuse for U3/PCIe PHY + - description: tx_imp_sel efuse for U3/PCIe PHY + description: | + Phandles to nvmem cell that contains the efuse data; + Available only for U2 PHY or U3/PCIe PHY of version 2/3, these + three items should be provided at the same time for U3/PCIe PHY, + when use software to load efuse; + If unspecified, will use hardware auto-load efuse. + + nvmem-cell-names: + items: + - const: intr + - const: rx_imp + - const: tx_imp + # The following optional vendor properties are only for debug or HQA test mediatek,eye-src: description: diff --git a/Documentation/devicetree/bindings/phy/microchip,lan966x-serdes.yaml b/Documentation/devicetree/bindings/phy/microchip,lan966x-serdes.yaml new file mode 100644 index 000000000000..6e914fbbac56 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/microchip,lan966x-serdes.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/microchip,lan966x-serdes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Lan966x Serdes controller + +maintainers: + - Horatiu Vultur <horatiu.vultur@microchip.com> + +description: | + Lan966x has 7 interfaces, consisting of 2 copper transceivers(CU), + 3 SERDES6G and 2 RGMII interfaces. Two of the SERDES6G support QSGMII. + Also it has 8 logical Ethernet ports which can be connected to these + interfaces. The Serdes controller will allow to configure these interfaces + and allows to "mux" the interfaces to different ports. + + For simple selection of the interface that is used with a port, the + following macros are defined CU(X), SERDES6G(X), RGMII(X). Where X is a + number that represents the index of that interface type. For example + CU(1) means use interface copper transceivers 1. SERDES6G(2) means use + interface SerDes 2. + +properties: + $nodename: + pattern: "^serdes@[0-9a-f]+$" + + compatible: + const: microchip,lan966x-serdes + + reg: + items: + - description: HSIO registers + - description: HW_STAT register + + '#phy-cells': + const: 2 + description: | + - Input port to use for a given macro. + - The macro to be used. The macros are defined in + dt-bindings/phy/phy-lan966x-serdes. + +required: + - compatible + - reg + - '#phy-cells' + +additionalProperties: false + +examples: + - | + serdes: serdes@e2004010 { + compatible = "microchip,lan966x-serdes"; + reg = <0xe202c000 0x9c>, <0xe2004010 0x4>; + #phy-cells = <2>; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml index e71b32c9c0d1..a9e227d8b076 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml @@ -113,6 +113,15 @@ patternProperties: minimum: 1 maximum: 16 + cdns,ssc-mode: + description: + Specifies the Spread Spectrum Clocking mode used. It can be NO_SSC, + EXTERNAL_SSC or INTERNAL_SSC. + Refer include/dt-bindings/phy/phy-cadence.h for the constants to be used. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + default: 1 + required: - reg - resets diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml index bd9ae11c9994..2fec9e54ad0e 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml @@ -202,7 +202,7 @@ examples: #phy-cells = <0>; cdns,phy-type = <PHY_TYPE_PCIE>; cdns,num-lanes = <2>; - cdns,ssc-mode = <TORRENT_SERDES_NO_SSC>; + cdns,ssc-mode = <CDNS_SERDES_NO_SSC>; }; phy@2 { @@ -211,7 +211,7 @@ examples: #phy-cells = <0>; cdns,phy-type = <PHY_TYPE_SGMII>; cdns,num-lanes = <1>; - cdns,ssc-mode = <TORRENT_SERDES_NO_SSC>; + cdns,ssc-mode = <CDNS_SERDES_NO_SSC>; }; }; }; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml index 5bebd86bf8b6..4b75289735eb 100644 --- a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml @@ -18,6 +18,7 @@ properties: - rockchip,rk3328-usb2phy - rockchip,rk3366-usb2phy - rockchip,rk3399-usb2phy + - rockchip,rk3568-usb2phy - rockchip,rv1108-usb2phy reg: @@ -50,6 +51,10 @@ properties: description: Phandle to the extcon device providing the cable state for the otg phy. + interrupts: + description: Muxed interrupt for both ports + maxItems: 1 + rockchip,usbgrf: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -67,6 +72,7 @@ properties: interrupts: description: host linestate interrupt + maxItems: 1 interrupt-names: const: linestate @@ -78,8 +84,6 @@ properties: required: - "#phy-cells" - - interrupts - - interrupt-names otg-port: type: object @@ -109,8 +113,6 @@ properties: required: - "#phy-cells" - - interrupts - - interrupt-names required: - compatible @@ -120,6 +122,40 @@ required: - host-port - otg-port +allOf: + - if: + properties: + compatible: + contains: + const: rockchip,rk3568-usb2phy + + then: + properties: + host-port: + properties: + interrupts: false + + otg-port: + properties: + interrupts: false + + required: + - interrupts + + else: + properties: + interrupts: false + + host-port: + required: + - interrupts + - interrupt-names + + otg-port: + required: + - interrupts + - interrupt-names + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt b/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt deleted file mode 100644 index d23ff90baad5..000000000000 --- a/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt +++ /dev/null @@ -1,28 +0,0 @@ -NVIDIA Tegra194 P2U binding - -Tegra194 has two PHY bricks namely HSIO (High Speed IO) and NVHS (NVIDIA High -Speed) each interfacing with 12 and 8 P2U instances respectively. -A P2U instance is a glue logic between Synopsys DesignWare Core PCIe IP's PIPE -interface and PHY of HSIO/NVHS bricks. Each P2U instance represents one PCIe -lane. - -Required properties: -- compatible: For Tegra19x, must contain "nvidia,tegra194-p2u". -- reg: Should be the physical address space and length of respective each P2U - instance. -- reg-names: Must include the entry "ctl". - -Required properties for PHY port node: -- #phy-cells: Defined by generic PHY bindings. Must be 0. - -Refer to phy/phy-bindings.txt for the generic PHY binding properties. - -Example: - -p2u_hsio_0: phy@3e10000 { - compatible = "nvidia,tegra194-p2u"; - reg = <0x03e10000 0x10000>; - reg-names = "ctl"; - - #phy-cells = <0>; -}; diff --git a/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.yaml b/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.yaml new file mode 100644 index 000000000000..9a89d05efbda --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/phy-tegra194-p2u.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra194 P2U binding + +maintainers: + - Thierry Reding <treding@nvidia.com> + +description: > + Tegra194 has two PHY bricks namely HSIO (High Speed IO) and NVHS (NVIDIA High + Speed) each interfacing with 12 and 8 P2U instances respectively. + A P2U instance is a glue logic between Synopsys DesignWare Core PCIe IP's PIPE + interface and PHY of HSIO/NVHS bricks. Each P2U instance represents one PCIe + lane. + +properties: + compatible: + const: nvidia,tegra194-p2u + + reg: + maxItems: 1 + description: Should be the physical address space and length of respective each P2U instance. + + reg-names: + items: + - const: ctl + + '#phy-cells': + const: 0 + +additionalProperties: false + +examples: + - | + p2u_hsio_0: phy@3e10000 { + compatible = "nvidia,tegra194-p2u"; + reg = <0x03e10000 0x10000>; + reg-names = "ctl"; + + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,edp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,edp-phy.yaml new file mode 100644 index 000000000000..9076e19b6417 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,edp-phy.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/qcom,edp-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm eDP PHY + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + The Qualcomm eDP PHY is found in a number of Qualcomm platform and provides + the physical interface for Embedded Display Port. + +properties: + compatible: + const: qcom,sc8180x-edp-phy + + reg: + items: + - description: PHY base register block + - description: tx0 register block + - description: tx1 register block + - description: PLL register block + + clocks: + maxItems: 2 + + clock-names: + items: + - const: aux + - const: cfg_ahb + + "#clock-cells": + const: 1 + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + - "#phy-cells" + +additionalProperties: false + +examples: + - | + phy@aec2a00 { + compatible = "qcom,sc8180x-edp-phy"; + reg = <0x0aec2a00 0x1c0>, + <0x0aec2200 0xa0>, + <0x0aec2600 0xa0>, + <0x0aec2000 0x19c>; + + clocks = <&dispcc 0>, <&dispcc 1>; + clock-names = "aux", "cfg_ahb"; + + #clock-cells = <1>; + #phy-cells = <0>; + }; +... diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index 630ceaf915e2..e417cd667997 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -50,6 +50,10 @@ properties: - qcom,sm8350-qmp-ufs-phy - qcom,sm8350-qmp-usb3-phy - qcom,sm8350-qmp-usb3-uni-phy + - qcom,sm8450-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen4x2-pcie-phy + - qcom,sm8450-qmp-ufs-phy + - qcom,sm8450-qmp-usb3-phy - qcom,sdx55-qmp-pcie-phy - qcom,sdx55-qmp-usb3-uni-phy @@ -332,6 +336,8 @@ allOf: - qcom,sm8250-qmp-gen3x1-pcie-phy - qcom,sm8250-qmp-gen3x2-pcie-phy - qcom,sm8250-qmp-modem-pcie-phy + - qcom,sm8450-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen4x2-pcie-phy then: properties: clocks: diff --git a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml index aa2e409a1a09..e651a63a4be3 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml @@ -30,6 +30,7 @@ properties: - enum: - qcom,sc7180-qusb2-phy - qcom,sdm845-qusb2-phy + - qcom,sm6350-qusb2-phy - const: qcom,qusb2-v2-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml index 20203a8a9e41..0dfe6914ec87 100644 --- a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml @@ -20,6 +20,7 @@ properties: - qcom,sm8150-usb-hs-phy - qcom,sm8250-usb-hs-phy - qcom,sm8350-usb-hs-phy + - qcom,sm8450-usb-hs-phy - qcom,usb-snps-femto-v2-phy reg: diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml index 745c525ce6b9..3b400a85b44a 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml @@ -16,6 +16,7 @@ maintainers: properties: compatible: enum: + - socionext,uniphier-pro4-ahci-phy - socionext,uniphier-pxs2-ahci-phy - socionext,uniphier-pxs3-ahci-phy @@ -26,23 +27,35 @@ properties: const: 0 clocks: + minItems: 1 maxItems: 2 clock-names: oneOf: - items: # for PXs2 - const: link + - items: # for Pro4 + - const: link + - const: gio - items: # for others - const: link - const: phy resets: - maxItems: 2 + minItems: 2 + maxItems: 5 reset-names: - items: - - const: link - - const: phy + oneOf: + - items: # for Pro4 + - const: link + - const: gio + - const: pm + - const: tx + - const: rx + - items: # for others + - const: link + - const: phy required: - compatible diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-pcie-phy.yaml index 3e0566899041..fbb71d6dd531 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-pcie-phy.yaml @@ -19,6 +19,7 @@ properties: - socionext,uniphier-pro5-pcie-phy - socionext,uniphier-ld20-pcie-phy - socionext,uniphier-pxs3-pcie-phy + - socionext,uniphier-nx1-pcie-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml index a681cbc3b4ef..33946efcac5e 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml @@ -22,6 +22,7 @@ properties: - socionext,uniphier-pxs2-usb3-hsphy - socionext,uniphier-ld20-usb3-hsphy - socionext,uniphier-pxs3-usb3-hsphy + - socionext,uniphier-nx1-usb3-hsphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml index 41c0dd68ee25..92d46eb913a3 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml @@ -23,6 +23,7 @@ properties: - socionext,uniphier-pxs2-usb3-ssphy - socionext,uniphier-ld20-usb3-ssphy - socionext,uniphier-pxs3-usb3-ssphy + - socionext,uniphier-nx1-usb3-ssphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml b/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml index cbbf5e8b1197..f78d3246fbdc 100644 --- a/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml +++ b/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml @@ -8,7 +8,7 @@ title: OMAP USB2 PHY maintainers: - Kishon Vijay Abraham I <kishon@ti.com> - - Roger Quadros <rogerq@ti.com> + - Roger Quadros <rogerq@kernel.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/phy/ti,tcan104x-can.yaml b/Documentation/devicetree/bindings/phy/ti,tcan104x-can.yaml index 6107880e5246..02b76f15e717 100644 --- a/Documentation/devicetree/bindings/phy/ti,tcan104x-can.yaml +++ b/Documentation/devicetree/bindings/phy/ti,tcan104x-can.yaml @@ -37,6 +37,12 @@ properties: max bit rate supported in bps minimum: 1 + mux-states: + description: + mux controller node to route the signals from controller to + transceiver. + maxItems: 1 + required: - compatible - '#phy-cells' @@ -53,4 +59,5 @@ examples: max-bitrate = <5000000>; standby-gpios = <&wakeup_gpio1 16 GPIO_ACTIVE_LOW>; enable-gpios = <&main_gpio1 67 GPIO_ACTIVE_HIGH>; + mux-states = <&mux0 1>; }; diff --git a/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml index 3f94f6944740..fb0f69ce9c16 100644 --- a/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml @@ -184,6 +184,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml index cce63c3cc463..bfce850c2035 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml @@ -147,6 +147,7 @@ allOf: # boards are defining it at the moment so it would generate a lot of # warnings. + - $ref: "pinctrl.yaml#" - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml index 572923d7023e..d3b11351ca45 100644 --- a/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml @@ -72,6 +72,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml index 100bb6dea3ec..c689bea7ce6e 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml @@ -50,6 +50,9 @@ patternProperties: TXD3, TXD4, UART6, USB11D1, USB11H2, USB2D1, USB2H1, USBCKI, VGABIOS_ROM, VGAHS, VGAVS, VPI18, VPI24, VPI30, VPO12, VPO24, WDTRST1, WDTRST2] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml index 904697bc9415..d316cc082107 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml @@ -62,6 +62,9 @@ patternProperties: USB11BHID, USB2AD, USB2AH, USB2BD, USB2BH, USBCKI, VGABIOSROM, VGAHS, VGAVS, VPI24, VPO, WDTRST1, WDTRST2] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - aspeed,external-nodes diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml index ad2866c99738..57b68d6c7c70 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml @@ -83,6 +83,9 @@ patternProperties: UART7, UART8, UART9, USBA, USBB, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml index 08995a4f854b..ab019a1998e8 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml @@ -37,6 +37,9 @@ patternProperties: enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio40 ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml index 58ffed44b3c4..8c9d4668c8c4 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml @@ -41,6 +41,9 @@ patternProperties: vdsl_phy_override_1_grp, vdsl_phy_override_2_grp, vdsl_phy_override_3_grp, dsl_gpio8, dsl_gpio9 ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml index 0fd24f40afb1..a8e22ec02215 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml @@ -36,6 +36,9 @@ patternProperties: gpio20, gpio25, gpio26, gpio27, gpio28, hsspi_cs1, usb_port1 ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml index 0c3ce256aa78..35867355a47a 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml @@ -34,6 +34,9 @@ patternProperties: enum: [ ebi_cs_grp, uart1_grp, serial_led_grp, legacy_led_grp, led_grp, spi_cs_grp, utopia_grp, pwm_syn_clk, sys_irq_grp ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml index 6f68fee373bd..b584d4b27223 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml @@ -41,6 +41,9 @@ patternProperties: gpio15, gpio16, gpio17, gpio18, gpio19, gpio20, gpio21, gpio22, gpio23, gpio24, gpio25, gpio26, gpio27, nand_grp ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml index f4168b9f4460..229323d9237d 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml @@ -42,6 +42,9 @@ patternProperties: gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, gpio31, uart1_grp ] +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,ns-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,ns-pinmux.yaml index fc39e3e9f71c..8d1e5b1cdd5f 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,ns-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,ns-pinmux.yaml @@ -53,6 +53,7 @@ patternProperties: additionalProperties: false allOf: + - $ref: "pinctrl.yaml#" - if: properties: compatible: @@ -77,7 +78,7 @@ additionalProperties: false examples: - | - pin-controller@1800c1c0 { + pinctrl@1800c1c0 { compatible = "brcm,bcm4708-pinmux"; reg = <0x1800c1c0 0x24>; reg-names = "cru_gpio_control"; diff --git a/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml b/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml index 46fbc73ab26b..a44691d9c57d 100644 --- a/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml +++ b/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml @@ -137,6 +137,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg @@ -151,9 +154,9 @@ examples: #include <dt-bindings/clock/k210-clk.h> #include <dt-bindings/reset/k210-rst.h> - fpioa: pinmux@502B0000 { + fpioa: pinmux@502b0000 { compatible = "canaan,k210-fpioa"; - reg = <0x502B0000 0x100>; + reg = <0x502b0000 0x100>; clocks = <&sysclk K210_CLK_FPIOA>, <&sysclk K210_CLK_APB0>; clock-names = "ref", "pclk"; diff --git a/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.yaml b/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.yaml index a07dd197176a..5cd512b7d5ba 100644 --- a/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.yaml +++ b/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.yaml @@ -51,15 +51,6 @@ properties: appropriate of the LOCHNAGARx_PIN_NUM_GPIOS define, see [3]. maxItems: 1 - pinctrl-0: - description: - A phandle to the default pinctrl state. - - pinctrl-names: - description: - A pinctrl state named "default" must be defined. - const: default - pin-settings: type: object patternProperties: @@ -181,6 +172,9 @@ properties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - gpio-controller diff --git a/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml b/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml index 4cb174bf31ff..8a90d8273767 100644 --- a/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml +++ b/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml @@ -30,16 +30,6 @@ description: | Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt properties: - pinctrl-0: - description: - A phandle to the node containing the subnodes containing default - configurations. - - pinctrl-names: - description: - A pinctrl state named "default" must be defined. - const: default - pin-settings: description: One subnode is required to contain the default settings. It diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml index 6d7d162e6171..6717f163390b 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml @@ -58,6 +58,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml index 7131cfd1fc45..b1cdbb56d4e4 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml @@ -58,6 +58,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml index d474bc1f393b..4eed3a4e153a 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml @@ -58,6 +58,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml index 0af2b6c95c17..d4a8ea5551a5 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml @@ -58,6 +58,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml index 86622c4f374b..693398d88223 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml @@ -56,6 +56,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml new file mode 100644 index 000000000000..1278f7293560 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/fsl,imxrt1050.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale IMXRT1050 IOMUX Controller + +maintainers: + - Giulio Benetti <giulio.benetti@benettiengineering.com> + - Jesse Taube <Mr.Bossman075@gmail.com> + +description: + Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory + for common binding part and usage. + +properties: + compatible: + const: fsl,imxrt1050-iomuxc + + reg: + maxItems: 1 + +# Client device subnode's properties +patternProperties: + 'grp$': + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + + properties: + fsl,pins: + description: + each entry consists of 6 integers and represents the mux and config + setting for one pin. The first 5 integers <mux_reg conf_reg input_reg + mux_val input_val> are specified using a PIN_FUNC_ID macro, which can + be found in <include/dt-bindings/pinctrl/pins-imxrt1050.h>. The last + integer CONFIG is the pad setting value like pull-up on this pin. Please + refer to i.MXRT1050 Reference Manual for detailed CONFIG settings. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: | + "mux_reg" indicates the offset of mux register. + - description: | + "conf_reg" indicates the offset of pad configuration register. + - description: | + "input_reg" indicates the offset of select input register. + - description: | + "mux_val" indicates the mux value to be applied. + - description: | + "input_val" indicates the select input value to be applied. + - description: | + "pad_setting" indicates the pad configuration value to be applied. + + required: + - fsl,pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + iomuxc: iomuxc@401f8000 { + compatible = "fsl,imxrt1050-iomuxc"; + reg = <0x401f8000 0x4000>; + + pinctrl_lpuart1: lpuart1grp { + fsl,pins = + <0x0EC 0x2DC 0x000 0x2 0x0 0xf1>, + <0x0F0 0x2E0 0x000 0x2 0x0 0xf1>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml index a12d0ceb7637..c2c370448b81 100644 --- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml @@ -28,9 +28,6 @@ maintainers: - Paul Cercueil <paul@crapouillou.net> properties: - nodename: - pattern: "^pinctrl@[0-9a-f]+$" - compatible: oneOf: - enum: @@ -121,6 +118,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg @@ -169,7 +169,7 @@ additionalProperties: examples: - | - pin-controller@10010000 { + pinctrl@10010000 { compatible = "ingenic,jz4770-pinctrl"; reg = <0x10010000 0x600>; diff --git a/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml b/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml index 2c0acb405e6c..b42548350188 100644 --- a/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml +++ b/Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml @@ -47,6 +47,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-thunderbay.yaml b/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-thunderbay.yaml new file mode 100644 index 000000000000..0ec476248f21 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/intel,pinctrl-thunderbay.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/intel,pinctrl-thunderbay.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Thunder Bay pin controller Device Tree Bindings + +maintainers: + - Lakshmi Sowjanya D <lakshmi.sowjanya.d@intel.com> + +description: | + Intel Thunder Bay SoC integrates a pin controller which enables control + of pin directions, input/output values and configuration + for a total of 67 pins. + +properties: + compatible: + const: intel,thunderbay-pinctrl + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + gpio-ranges: + maxItems: 1 + + interrupts: + description: + Specifies the interrupt lines to be used by the controller. + maxItems: 2 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + +patternProperties: + '^gpio@[0-9a-f]*$': + type: object + + description: + Child nodes can be specified to contain pin configuration information, + which can then be utilized by pinctrl client devices. + The following properties are supported. + + properties: + pins: + description: | + The name(s) of the pins to be configured in the child node. + Supported pin names are "GPIO0" up to "GPIO66". + + bias-disable: true + + bias-pull-down: true + + bias-pull-up: true + + drive-strength: + description: Drive strength for the pad. + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] + + bias-bus-hold: + type: boolean + + input-schmitt-enable: + type: boolean + + slew-rate: + description: GPIO slew rate control. + 0 - Slow + 1 - Fast + enum: [0, 1] + +additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - gpio-ranges + - interrupts + - interrupt-controller + - '#interrupt-cells' + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + // Example 1 + pinctrl0: gpio@0 { + compatible = "intel,thunderbay-pinctrl"; + reg = <0x600b0000 0x88>; + gpio-controller; + #gpio-cells = <0x2>; + gpio-ranges = <&pinctrl0 0 0 67>; + interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + // Example 2 + pinctrl1: gpio@1 { + compatible = "intel,thunderbay-pinctrl"; + reg = <0x600c0000 0x88>; + gpio-controller; + #gpio-cells = <0x2>; + gpio-ranges = <&pinctrl1 0 0 53>; + interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml index f8e6e138dc13..6953c958ff7c 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml @@ -64,6 +64,9 @@ required: - gpio-controller - "#gpio-cells" +allOf: + - $ref: "pinctrl.yaml#" + patternProperties: '-[0-9]+$': type: object diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml index 152c151c27ad..e7601c0f5a69 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml @@ -59,6 +59,9 @@ properties: "#interrupt-cells": const: 2 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml index 76a6df75ed9c..d42215f59afd 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml @@ -45,6 +45,9 @@ properties: "#interrupt-cells": const: 2 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml index 0feecd376c69..78a0175cecc7 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml @@ -42,6 +42,9 @@ properties: "#interrupt-cells": const: 2 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml index 7602b11e8bce..4eadea55df10 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml @@ -56,6 +56,9 @@ properties: "#interrupt-cells": const: 2 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml index cc1509e9b981..2d13a57b8961 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml @@ -56,6 +56,9 @@ properties: "#interrupt-cells": const: 2 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt index db99bd95d423..3bb76487669f 100644 --- a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt @@ -4,7 +4,8 @@ Microsemi Ocelot pin controller Device Tree Bindings Required properties: - compatible : Should be "mscc,ocelot-pinctrl", "mscc,jaguar2-pinctrl", "microchip,sparx5-pinctrl", - "mscc,luton-pinctrl" or "mscc,serval-pinctrl" + "mscc,luton-pinctrl", "mscc,serval-pinctrl" or + "microchip,lan966x-pinctrl" - reg : Address and length of the register set for the device - gpio-controller : Indicates this device is a GPIO controller - #gpio-cells : Must be 2. diff --git a/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml index 71ed0a9def84..4b22a9e3a447 100644 --- a/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml @@ -114,6 +114,9 @@ properties: description: enable output on a pin without actively driving it (such as enabling an output buffer) + output-impedance-ohms: + description: set the output impedance of a pin to at most X ohms + output-low: type: boolean description: set the pin to output mode with low level diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index 9dae60acf950..6904072d3944 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -97,47 +97,8 @@ For example: }; == Pin controller devices == -Required properties: See the pin controller driver specific documentation -Optional properties: -#pinctrl-cells: Number of pin control cells in addition to the index within the - pin controller device instance - -pinctrl-use-default: Boolean. Indicates that the OS can use the boot default - pin configuration. This allows using an OS that does not have a - driver for the pin controller. This property can be set either - globally for the pin controller or in child nodes for individual - pin group control. - -Pin controller devices should contain the pin configuration nodes that client -devices reference. - -For example: - - pincontroller { - ... /* Standard DT properties for the device itself elided */ - - state_0_node_a { - ... - }; - state_1_node_a { - ... - }; - state_1_node_b { - ... - }; - } - -The contents of each of those pin configuration child nodes is defined -entirely by the binding for the individual pin controller device. There -exists no common standard for this content. The pinctrl framework only -provides generic helper bindings that the pin controller driver can use. - -The pin configuration nodes need not be direct children of the pin controller -device; they may be grandchildren, for example. Whether this is legal, and -whether there is any interaction between the child and intermediate parent -nodes, is again defined entirely by the binding for the individual pin -controller device. +See pinctrl.yaml == Generic pin multiplexing node content == diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml index c4c071211611..3c84676a167d 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml @@ -108,6 +108,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml index 5e2bb2bf3a55..328ea59c5466 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml @@ -55,137 +55,162 @@ properties: Identifying i2c pins pull up/down type which is RSEL. It can support RSEL define or si unit value(ohm) to set different resistance. -#PIN CONFIGURATION NODES +# PIN CONFIGURATION NODES patternProperties: '-pins$': type: object - description: | - A pinctrl node should contain at least one subnodes representing the - pinctrl groups available on the machine. Each subnode will list the - pins it needs, and how they should be configured, with regard to muxer - configuration, pullups, drive strength, input enable/disable and - input schmitt. - An example of using macro: - pincontroller { - /* GPIO0 set as multifunction GPIO0 */ - gpio_pin { - pinmux = <PINMUX_GPIO0__FUNC_GPIO0>; - }; - /* GPIO8 set as multifunction SDA0 */ - i2c0_pin { - pinmux = <PINMUX_GPIO8__FUNC_SDA0>; - }; - }; - $ref: "pinmux-node.yaml" - - properties: - pinmux: - description: | - Integer array, represents gpio pin number and mux setting. - Supported pin number and mux varies for different SoCs, and are defined - as macros in dt-bindings/pinctrl/<soc>-pinfunc.h directly. - - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - - bias-pull-down: - description: | - For pull down type is normal, it don't need add RSEL & R1R0 define - and resistance value. - For pull down type is PUPD/R0/R1 type, it can add R1R0 define to - set different resistance. It can support "MTK_PUPD_SET_R1R0_00" & - "MTK_PUPD_SET_R1R0_01" & "MTK_PUPD_SET_R1R0_10" & "MTK_PUPD_SET_R1R0_11" - define in mt8195. - For pull down type is RSEL, it can add RSEL define & resistance value(ohm) - to set different resistance by identifying property "mediatek,rsel_resistance_in_si_unit". - It can support "MTK_PULL_SET_RSEL_000" & "MTK_PULL_SET_RSEL_001" - & "MTK_PULL_SET_RSEL_010" & "MTK_PULL_SET_RSEL_011" & "MTK_PULL_SET_RSEL_100" - & "MTK_PULL_SET_RSEL_101" & "MTK_PULL_SET_RSEL_110" & "MTK_PULL_SET_RSEL_111" - define in mt8195. It can also support resistance value(ohm) "75000" & "5000" in mt8195. - oneOf: - - enum: [100, 101, 102, 103] - - description: mt8195 pull down PUPD/R0/R1 type define value. - - enum: [200, 201, 202, 203, 204, 205, 206, 207] - - description: mt8195 pull down RSEL type define value. - - enum: [75000, 5000] - - description: mt8195 pull down RSEL type si unit value(ohm). - - An example of using RSEL define: - pincontroller { - i2c0_pin { - pinmux = <PINMUX_GPIO8__FUNC_SDA0>; - bias-pull-down = <MTK_PULL_SET_RSEL_001>; - }; - }; - An example of using si unit resistance value(ohm): - &pio { - mediatek,rsel_resistance_in_si_unit; - } - pincontroller { - i2c0_pin { - pinmux = <PINMUX_GPIO8__FUNC_SDA0>; - bias-pull-down = <75000>; - }; - }; - - bias-pull-up: + additionalProperties: false + patternProperties: + '^pins': + type: object + additionalProperties: false description: | - For pull up type is normal, it don't need add RSEL & R1R0 define - and resistance value. - For pull up type is PUPD/R0/R1 type, it can add R1R0 define to - set different resistance. It can support "MTK_PUPD_SET_R1R0_00" & - "MTK_PUPD_SET_R1R0_01" & "MTK_PUPD_SET_R1R0_10" & "MTK_PUPD_SET_R1R0_11" - define in mt8195. - For pull up type is RSEL, it can add RSEL define & resistance value(ohm) - to set different resistance by identifying property "mediatek,rsel_resistance_in_si_unit". - It can support "MTK_PULL_SET_RSEL_000" & "MTK_PULL_SET_RSEL_001" - & "MTK_PULL_SET_RSEL_010" & "MTK_PULL_SET_RSEL_011" & "MTK_PULL_SET_RSEL_100" - & "MTK_PULL_SET_RSEL_101" & "MTK_PULL_SET_RSEL_110" & "MTK_PULL_SET_RSEL_111" - define in mt8195. It can also support resistance value(ohm) - "1000" & "1500" & "2000" & "3000" & "4000" & "5000" & "10000" & "75000" in mt8195. - oneOf: - - enum: [100, 101, 102, 103] - - description: mt8195 pull up PUPD/R0/R1 type define value. - - enum: [200, 201, 202, 203, 204, 205, 206, 207] - - description: mt8195 pull up RSEL type define value. - - enum: [1000, 1500, 2000, 3000, 4000, 5000, 10000, 75000] - - description: mt8195 pull up RSEL type si unit value(ohm). - An example of using RSEL define: + A pinctrl node should contain at least one subnodes representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to muxer + configuration, pullups, drive strength, input enable/disable and + input schmitt. + An example of using macro: pincontroller { - i2c0_pin { - pinmux = <PINMUX_GPIO8__FUNC_SDA0>; - bias-pull-up = <MTK_PULL_SET_RSEL_001>; + /* GPIO0 set as multifunction GPIO0 */ + gpio-pins { + pins { + pinmux = <PINMUX_GPIO0__FUNC_GPIO0>; + } }; - }; - An example of using si unit resistance value(ohm): - &pio { - mediatek,rsel_resistance_in_si_unit; - } - pincontroller { - i2c0_pin { - pinmux = <PINMUX_GPIO8__FUNC_SDA0>; - bias-pull-up = <1000>; + /* GPIO8 set as multifunction SDA0 */ + i2c0-pins { + pins { + pinmux = <PINMUX_GPIO8__FUNC_SDA0>; + } }; }; - - bias-disable: true - - output-high: true - - output-low: true - - input-enable: true - - input-disable: true - - input-schmitt-enable: true - - input-schmitt-disable: true - - required: - - pinmux - - additionalProperties: false + $ref: "pinmux-node.yaml" + + properties: + pinmux: + description: | + Integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are + defined as macros in dt-bindings/pinctrl/<soc>-pinfunc.h + directly. + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + + bias-pull-down: + description: | + For pull down type is normal, it don't need add RSEL & R1R0 define + and resistance value. + For pull down type is PUPD/R0/R1 type, it can add R1R0 define to + set different resistance. It can support "MTK_PUPD_SET_R1R0_00" & + "MTK_PUPD_SET_R1R0_01" & "MTK_PUPD_SET_R1R0_10" & + "MTK_PUPD_SET_R1R0_11" define in mt8195. + For pull down type is RSEL, it can add RSEL define & resistance + value(ohm) to set different resistance by identifying property + "mediatek,rsel_resistance_in_si_unit". + It can support "MTK_PULL_SET_RSEL_000" & "MTK_PULL_SET_RSEL_001" + & "MTK_PULL_SET_RSEL_010" & "MTK_PULL_SET_RSEL_011" + & "MTK_PULL_SET_RSEL_100" & "MTK_PULL_SET_RSEL_101" + & "MTK_PULL_SET_RSEL_110" & "MTK_PULL_SET_RSEL_111" + define in mt8195. It can also support resistance value(ohm) + "75000" & "5000" in mt8195. + oneOf: + - enum: [100, 101, 102, 103] + - description: mt8195 pull down PUPD/R0/R1 type define value. + - enum: [200, 201, 202, 203, 204, 205, 206, 207] + - description: mt8195 pull down RSEL type define value. + - enum: [75000, 5000] + - description: mt8195 pull down RSEL type si unit value(ohm). + + An example of using RSEL define: + pincontroller { + i2c0_pin { + pins { + pinmux = <PINMUX_GPIO8__FUNC_SDA0>; + bias-pull-down = <MTK_PULL_SET_RSEL_001>; + } + }; + }; + An example of using si unit resistance value(ohm): + &pio { + mediatek,rsel_resistance_in_si_unit; + } + pincontroller { + i2c0_pin { + pins { + pinmux = <PINMUX_GPIO8__FUNC_SDA0>; + bias-pull-down = <75000>; + } + }; + }; + + bias-pull-up: + description: | + For pull up type is normal, it don't need add RSEL & R1R0 define + and resistance value. + For pull up type is PUPD/R0/R1 type, it can add R1R0 define to + set different resistance. It can support "MTK_PUPD_SET_R1R0_00" & + "MTK_PUPD_SET_R1R0_01" & "MTK_PUPD_SET_R1R0_10" & + "MTK_PUPD_SET_R1R0_11" define in mt8195. + For pull up type is RSEL, it can add RSEL define & resistance + value(ohm) to set different resistance by identifying property + "mediatek,rsel_resistance_in_si_unit". + It can support "MTK_PULL_SET_RSEL_000" & "MTK_PULL_SET_RSEL_001" + & "MTK_PULL_SET_RSEL_010" & "MTK_PULL_SET_RSEL_011" + & "MTK_PULL_SET_RSEL_100" & "MTK_PULL_SET_RSEL_101" + & "MTK_PULL_SET_RSEL_110" & "MTK_PULL_SET_RSEL_111" + define in mt8195. It can also support resistance value(ohm) + "1000" & "1500" & "2000" & "3000" & "4000" & "5000" & "10000" & + "75000" in mt8195. + oneOf: + - enum: [100, 101, 102, 103] + - description: mt8195 pull up PUPD/R0/R1 type define value. + - enum: [200, 201, 202, 203, 204, 205, 206, 207] + - description: mt8195 pull up RSEL type define value. + - enum: [1000, 1500, 2000, 3000, 4000, 5000, 10000, 75000] + - description: mt8195 pull up RSEL type si unit value(ohm). + An example of using RSEL define: + pincontroller { + i2c0-pins { + pins { + pinmux = <PINMUX_GPIO8__FUNC_SDA0>; + bias-pull-up = <MTK_PULL_SET_RSEL_001>; + } + }; + }; + An example of using si unit resistance value(ohm): + &pio { + mediatek,rsel_resistance_in_si_unit; + } + pincontroller { + i2c0-pins { + pins { + pinmux = <PINMUX_GPIO8__FUNC_SDA0>; + bias-pull-up = <1000>; + } + }; + }; + + bias-disable: true + + output-high: true + + output-low: true + + input-enable: true + + input-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + required: + - pinmux + +allOf: + - $ref: "pinctrl.yaml#" required: - compatible @@ -201,30 +226,46 @@ additionalProperties: false examples: - | - #include <dt-bindings/pinctrl/mt8195-pinfunc.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - pio: pinctrl@10005000 { - compatible = "mediatek,mt8195-pinctrl"; - reg = <0x10005000 0x1000>, - <0x11d10000 0x1000>, - <0x11d30000 0x1000>, - <0x11d40000 0x1000>, - <0x11e20000 0x1000>, - <0x11eb0000 0x1000>, - <0x11f40000 0x1000>, - <0x1000b000 0x1000>; - reg-names = "iocfg0", "iocfg_bm", "iocfg_bl", - "iocfg_br", "iocfg_lm", "iocfg_rb", - "iocfg_tl", "eint"; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&pio 0 0 144>; - interrupt-controller; - interrupts = <GIC_SPI 225 IRQ_TYPE_LEVEL_HIGH 0>; - #interrupt-cells = <2>; - - pio-pins { - pinmux = <PINMUX_GPIO0__FUNC_GPIO0>; - output-low; - }; - }; + #include <dt-bindings/pinctrl/mt8195-pinfunc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + # + pio: pinctrl@10005000 { + compatible = "mediatek,mt8195-pinctrl"; + reg = <0x10005000 0x1000>, + <0x11d10000 0x1000>, + <0x11d30000 0x1000>, + <0x11d40000 0x1000>, + <0x11e20000 0x1000>, + <0x11eb0000 0x1000>, + <0x11f40000 0x1000>, + <0x1000b000 0x1000>; + reg-names = "iocfg0", "iocfg_bm", "iocfg_bl", + "iocfg_br", "iocfg_lm", "iocfg_rb", + "iocfg_tl", "eint"; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pio 0 0 144>; + interrupt-controller; + interrupts = <GIC_SPI 225 IRQ_TYPE_LEVEL_HIGH 0>; + #interrupt-cells = <2>; + + pio-pins { + pins { + pinmux = <PINMUX_GPIO0__FUNC_GPIO0>; + output-low; + }; + }; + + spi0-pins { + pins-spi { + pinmux = <PINMUX_GPIO132__FUNC_SPIM0_CSB>, + <PINMUX_GPIO134__FUNC_SPIM0_MO>, + <PINMUX_GPIO133__FUNC_SPIM0_CLK>; + bias-disable; + }; + pins-spi-mi { + pinmux = <PINMUX_GPIO135__FUNC_SPIM0_MI>; + bias-pull-down; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml new file mode 100644 index 000000000000..d471563119a9 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pin controller device + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +description: | + Pin controller devices should contain the pin configuration nodes that client + devices reference. + + The contents of each of those pin configuration child nodes is defined + entirely by the binding for the individual pin controller device. There + exists no common standard for this content. The pinctrl framework only + provides generic helper bindings that the pin controller driver can use. + + The pin configuration nodes need not be direct children of the pin controller + device; they may be grandchildren, for example. Whether this is legal, and + whether there is any interaction between the child and intermediate parent + nodes, is again defined entirely by the binding for the individual pin + controller device. + +properties: + $nodename: + pattern: "^(pinctrl|pinmux)(@[0-9a-f]+)?$" + + "#pinctrl-cells": + description: > + Number of pin control cells in addition to the index within the pin + controller device instance. + + pinctrl-use-default: + type: boolean + description: > + Indicates that the OS can use the boot default pin configuration. This + allows using an OS that does not have a driver for the pin controller. + This property can be set either globally for the pin controller or in + child nodes for individual pin group control. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml index c64c93206817..b83c7f476e19 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml @@ -118,6 +118,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,lpass-lpi-pinctrl.yaml index e47ebf934daf..5c5542f1627c 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,lpass-lpi-pinctrl.yaml @@ -103,6 +103,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml index 3b02dc6626ed..f7bd4be1739e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml @@ -14,6 +14,7 @@ description: | MDM9607 platform. allOf: + - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml index 040d2ada3669..ab4a2b4cfda2 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml @@ -97,6 +97,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml index abe9f4c9b1e3..64c0a41ca0c3 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml @@ -133,6 +133,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml index 8952b4cc1262..9400b665a46f 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml @@ -17,6 +17,7 @@ properties: compatible: items: - enum: + - qcom,pm2250-gpio - qcom,pm660-gpio - qcom,pm660l-gpio - qcom,pm6150-gpio @@ -26,10 +27,12 @@ properties: - qcom,pm8005-gpio - qcom,pm8008-gpio - qcom,pm8018-gpio + - qcom,pm8019-gpio - qcom,pm8038-gpio - qcom,pm8058-gpio - qcom,pm8150-gpio - qcom,pm8150b-gpio + - qcom,pm8226-gpio - qcom,pm8350-gpio - qcom,pm8350b-gpio - qcom,pm8350c-gpio diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml index 13f338619d77..206f4f238736 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml @@ -118,6 +118,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml index 7d6a2ab10eec..6c7c3f6a140e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml @@ -123,6 +123,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml index a82dab898395..86509172603d 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml @@ -14,6 +14,7 @@ description: | SC8180X platform. allOf: + - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml index 112dd59ce7ed..a38090b14aab 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml @@ -118,6 +118,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-pinctrl.yaml new file mode 100644 index 000000000000..cdfcf29dffee --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-pinctrl.yaml @@ -0,0 +1,191 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sdx65-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SDX65 TLMM block + +maintainers: + - Vamsi krishna Lanka <quic_vamslank@quicinc.com> + +description: + This binding describes the Top Level Mode Multiplexer block found in the + SDX65 platform. + +properties: + compatible: + const: qcom,sdx65-tlmm + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + description: Specifies the PIN numbers and Flags, as defined in + include/dt-bindings/interrupt-controller/irq.h + const: 2 + + gpio-controller: true + + '#gpio-cells': + description: Specifying the pin number and flags, as defined in + include/dt-bindings/gpio/gpio.h + const: 2 + + gpio-ranges: + maxItems: 1 + + gpio-reserved-ranges: + maxItems: 1 + +#PIN CONFIGURATION NODES +patternProperties: + '-state$': + oneOf: + - $ref: "#/$defs/qcom-sdx65-tlmm-state" + - patternProperties: + ".*": + $ref: "#/$defs/qcom-sdx65-tlmm-state" +'$defs': + qcom-sdx65-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-7])$" + - enum: [ ufs_reset, sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data, sdc1_rclk ] + minItems: 1 + maxItems: 150 + + function: + description: + Specify the alternative function to be configured for the specified + pins. Functions are only valid for gpio pins. + enum: [ blsp_uart1, blsp_spi1, blsp_i2c1, blsp_uim1, atest_tsens, + bimc_dte1, dac_calib0, blsp_spi8, blsp_uart8, blsp_uim8, + qdss_cti_trig_out_b, bimc_dte0, dac_calib1, qdss_cti_trig_in_b, + dac_calib2, atest_tsens2, atest_usb1, blsp_spi10, blsp_uart10, + blsp_uim10, atest_bbrx1, atest_usb13, atest_bbrx0, atest_usb12, + mdp_vsync, edp_lcd, blsp_i2c10, atest_gpsadc1, atest_usb11, + atest_gpsadc0, edp_hot, atest_usb10, m_voc, dac_gpio, atest_char, + cam_mclk, pll_bypassnl, qdss_stm7, blsp_i2c8, qdss_tracedata_b, + pll_reset, qdss_stm6, qdss_stm5, qdss_stm4, atest_usb2, cci_i2c, + qdss_stm3, dac_calib3, atest_usb23, atest_char3, dac_calib4, + qdss_stm2, atest_usb22, atest_char2, qdss_stm1, dac_calib5, + atest_usb21, atest_char1, dbg_out, qdss_stm0, dac_calib6, + atest_usb20, atest_char0, dac_calib10, qdss_stm10, + qdss_cti_trig_in_a, cci_timer4, blsp_spi6, blsp_uart6, blsp_uim6, + blsp2_spi, qdss_stm9, qdss_cti_trig_out_a, dac_calib11, + qdss_stm8, cci_timer0, qdss_stm13, dac_calib7, cci_timer1, + qdss_stm12, dac_calib8, cci_timer2, blsp1_spi, qdss_stm11, + dac_calib9, cci_timer3, cci_async, dac_calib12, blsp_i2c6, + qdss_tracectl_a, dac_calib13, qdss_traceclk_a, dac_calib14, + dac_calib15, hdmi_rcv, dac_calib16, hdmi_cec, pwr_modem, + dac_calib17, hdmi_ddc, pwr_nav, dac_calib18, pwr_crypto, + dac_calib19, hdmi_hot, dac_calib20, dac_calib21, pci_e0, + dac_calib22, dac_calib23, dac_calib24, tsif1_sync, dac_calib25, + sd_write, tsif1_error, blsp_spi2, blsp_uart2, blsp_uim2, + qdss_cti, blsp_i2c2, blsp_spi3, blsp_uart3, blsp_uim3, blsp_i2c3, + uim3, blsp_spi9, blsp_uart9, blsp_uim9, blsp10_spi, blsp_i2c9, + blsp_spi7, blsp_uart7, blsp_uim7, qdss_tracedata_a, blsp_i2c7, + qua_mi2s, gcc_gp1_clk_a, ssc_irq, uim4, blsp_spi11, blsp_uart11, + blsp_uim11, gcc_gp2_clk_a, gcc_gp3_clk_a, blsp_i2c11, cri_trng0, + cri_trng1, cri_trng, qdss_stm18, pri_mi2s, qdss_stm17, blsp_spi4, + blsp_uart4, blsp_uim4, qdss_stm16, qdss_stm15, blsp_i2c4, + qdss_stm14, dac_calib26, spkr_i2s, audio_ref, lpass_slimbus, + isense_dbg, tsense_pwm1, tsense_pwm2, btfm_slimbus, ter_mi2s, + qdss_stm22, qdss_stm21, qdss_stm20, qdss_stm19, gcc_gp1_clk_b, + sec_mi2s, blsp_spi5, blsp_uart5, blsp_uim5, gcc_gp2_clk_b, + gcc_gp3_clk_b, blsp_i2c5, blsp_spi12, blsp_uart12, blsp_uim12, + qdss_stm25, qdss_stm31, blsp_i2c12, qdss_stm30, qdss_stm29, + tsif1_clk, qdss_stm28, tsif1_en, tsif1_data, sdc4_cmd, qdss_stm27, + qdss_traceclk_b, tsif2_error, sdc43, vfr_1, qdss_stm26, tsif2_clk, + sdc4_clk, qdss_stm24, tsif2_en, sdc42, qdss_stm23, qdss_tracectl_b, + sd_card, tsif2_data, sdc41, tsif2_sync, sdc40, mdp_vsync_p_b, + ldo_en, mdp_vsync_s_b, ldo_update, blsp11_uart_tx_b, blsp11_uart_rx_b, + blsp11_i2c_sda_b, prng_rosc, blsp11_i2c_scl_b, uim2, uim1, uim_batt, + pci_e2, pa_indicator, adsp_ext, ddr_bist, qdss_tracedata_11, + qdss_tracedata_12, modem_tsync, nav_dr, nav_pps, pci_e1, gsm_tx, + qspi_cs, ssbi2, ssbi1, mss_lte, qspi_clk, qspi0, qspi1, qspi2, qspi3, + gpio ] + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + default: 2 + description: + Selects the drive strength for the specified pins, in mA. + + bias-pull-down: true + + bias-pull-up: true + + bias-disable: true + + output-high: true + + output-low: true + + required: + - pins + - function + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + - gpio-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@f100000 { + compatible = "qcom,sdx65-tlmm"; + reg = <0x03000000 0xdc2000>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 109>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 212 IRQ_TYPE_LEVEL_HIGH>; + + gpio-wo-subnode-state { + pins = "gpio1"; + function = "gpio"; + }; + + uart-w-subnodes-state { + rx { + pins = "gpio4"; + function = "blsp_uart1"; + bias-pull-up; + }; + + tx { + pins = "gpio5"; + function = "blsp_uart1"; + bias-disable; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml index 8fc06f6a3ef4..cfcde405d30a 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml @@ -121,6 +121,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml index 5f7adaa81f83..c8eec845ade9 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml @@ -13,6 +13,7 @@ description: | in the SM6125 platform. allOf: + - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml index 554992a681f3..898608671c4b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml @@ -14,6 +14,7 @@ description: | in the SM6350 platform. allOf: + - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml index 8508c57522fd..cfa2c50fdb93 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml @@ -115,6 +115,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml index 4f2667ea2805..6b7789db2f75 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml @@ -14,6 +14,7 @@ description: | in the SM8350 platform. allOf: + - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-pinctrl.yaml new file mode 100644 index 000000000000..9c891246245b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-pinctrl.yaml @@ -0,0 +1,143 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8450-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SM8450 TLMM block + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +description: | + This binding describes the Top Level Mode Multiplexer (TLMM) block found + in the SM8450 platform. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,sm8450-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + '#interrupt-cells': true + gpio-controller: true + gpio-reserved-ranges: true + '#gpio-cells': true + gpio-ranges: true + wakeup-parent: true + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + '-state$': + oneOf: + - $ref: "#/$defs/qcom-sm8450-tlmm-state" + - patternProperties: + ".*": + $ref: "#/$defs/qcom-sm8450-tlmm-state" + +$defs: + qcom-sm8450-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-9])$" + - enum: [ ufs_reset, sdc2_clk, sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + enum: [ aon_cam, atest_char, atest_usb, audio_ref, cam_mclk, cci_async, + cci_i2c, cci_timer, cmu_rng, coex_uart1, coex_uart2, cri_trng, + cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, ddr_pxi1, + ddr_pxi2, ddr_pxi3, dp_hot, gcc_gp1, gcc_gp2, gcc_gp3, + gpio, ibi_i3c, jitter_bist, mdp_vsync, mdp_vsync0, mdp_vsync1, + mdp_vsync2, mdp_vsync3, mi2s0_data0, mi2s0_data1, mi2s0_sck, + mi2s0_ws, mi2s2_data0, mi2s2_data1, mi2s2_sck, mi2s2_ws, + mss_grfc0, mss_grfc1, mss_grfc10, mss_grfc11, mss_grfc12, + mss_grfc2, mss_grfc3, mss_grfc4, mss_grfc5, mss_grfc6, + mss_grfc7, mss_grfc8, mss_grfc9, nav, pcie0_clkreqn, + pcie1_clkreqn, phase_flag, pll_bist, pll_clk, pri_mi2s, + prng_rosc, qdss_cti, qdss_gpio, qlink0_enable, qlink0_request, + qlink0_wmss, qlink1_enable, qlink1_request, qlink1_wmss, + qlink2_enable, qlink2_request, qlink2_wmss, qspi0, qspi1, + qspi2, qspi3, qspi_clk, qspi_cs, qup0, qup1, qup10, qup11, + qup12, qup13, qup14, qup15, qup16, qup17, qup18, qup19, qup2, + qup20, qup21, qup3, qup4, qup5, qup6, qup7, qup8, qup9, qup_l4, + qup_l5, qup_l6, sd_write, sdc40, sdc41, sdc42, sdc43, sdc4_clk, + sdc4_cmd, sec_mi2s, tb_trig, tgu_ch0, tgu_ch1, tgu_ch2, + tgu_ch3, tmess_prng0, tmess_prng1, tmess_prng2, tmess_prng3, + tsense_pwm1, tsense_pwm2, uim0_clk, uim0_data, uim0_present, + uim0_reset, uim1_clk, uim1_data, uim1_present, uim1_reset, + usb2phy_ac, usb_phy, vfr_0, vfr_1, vsense_trigger ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + - function + + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + pinctrl@f100000 { + compatible = "qcom,sm8450-tlmm"; + reg = <0x0f100000 0x300000>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 211>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + + gpio-wo-subnode-state { + pins = "gpio1"; + function = "gpio"; + }; + + uart-w-subnodes-state { + rx { + pins = "gpio26"; + function = "qup7"; + bias-pull-up; + }; + + tx { + pins = "gpio27"; + function = "qup7"; + bias-disable; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml index 3b37cf102d41..be8cb0ead62f 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml @@ -51,6 +51,9 @@ properties: should not be accessed by the OS. Please see the ../gpio/gpio.txt for more information. +allOf: + - $ref: "pinctrl.yaml#" + required: - interrupts - interrupt-controller diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinmux.yaml index b32f2676cab5..f0c52feb24d7 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinmux.yaml @@ -44,6 +44,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml index ac4e068aa03f..8548e3639b75 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml @@ -70,6 +70,9 @@ properties: power-domains: maxItems: 1 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml index 7f80578dc229..8ed4b98a1628 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml @@ -31,6 +31,9 @@ properties: reg: maxItems: 1 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml index ce1f7343788f..d761fddc2206 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml @@ -72,6 +72,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml index ef68dabcf4dc..b749c82edebd 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -73,6 +73,8 @@ additionalProperties: pins: true drive-strength: enum: [ 2, 4, 8, 12 ] + output-impedance-ohms: + enum: [ 33, 50, 66, 100 ] power-source: enum: [ 1800, 2500, 3300 ] slew-rate: true @@ -90,6 +92,9 @@ additionalProperties: additionalProperties: $ref: "#/additionalProperties/anyOf/0" +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml index 4a43af0d6e02..70b1788ab594 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml @@ -31,6 +31,9 @@ properties: description: The bus clock, sometimes described as pclk, for register accesses. +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml index 07c0a98ef9c6..b0eae3a67ab1 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml @@ -67,6 +67,9 @@ properties: ranges: true +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - rockchip,grf diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index b8b475967ff9..9e70edceb21b 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -22,6 +22,7 @@ Required Properties: - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller. - "samsung,exynos5433-pinctrl": for Exynos5433 compatible pin-controller. - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller. + - "samsung,exynos7885-pinctrl": for Exynos7885 compatible pin-controller. - "samsung,exynos850-pinctrl": for Exynos850 compatible pin-controller. - "samsung,exynosautov9-pinctrl": for ExynosAutov9 compatible pin-controller. diff --git a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml index a804d9bc1602..14a8c0215cc6 100644 --- a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml @@ -10,9 +10,6 @@ maintainers: - Masahiro Yamada <yamada.masahiro@socionext.com> properties: - $nodename: - pattern: "pinctrl" - compatible: enum: - socionext,uniphier-ld4-pinctrl @@ -26,11 +23,48 @@ properties: - socionext,uniphier-pxs3-pinctrl - socionext,uniphier-nx1-pinctrl +additionalProperties: + type: object + + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + properties: + phandle: true + function: true + groups: true + pins: true + bias-pull-up: true + bias-pull-down: true + bias-pull-pin-default: true + drive-strength: true + + additionalProperties: + type: object + + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + properties: + phandle: true + function: true + groups: true + pins: true + bias-pull-up: true + bias-pull-down: true + bias-pull-pin-default: true + drive-strength: true + + unevaluatedProperties: false + +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible -additionalProperties: false - examples: - | // The UniPhier pinctrl should be a subnode of a "syscon" compatible node. diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index ac88e01ec430..83a18d0331b1 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -183,6 +183,9 @@ patternProperties: required: - pinmux +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - '#address-cells' diff --git a/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml index 9f1dab0c2430..306524885a2b 100644 --- a/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml @@ -20,6 +20,9 @@ properties: reg: maxItems: 1 +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg @@ -80,7 +83,7 @@ examples: #address-cells = <2>; #size-cells = <2>; - pmux: pmux@24190000 { + pmux: pinmux@24190000 { compatible = "toshiba,tmpv7708-pinctrl"; reg = <0 0x24190000 0 0x10000>; diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml index ac97dbf6998e..cfd0cc549a7b 100644 --- a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml @@ -167,6 +167,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: "pinctrl.yaml#" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml index 8ef0d07d35fe..2722dc7bb03d 100644 --- a/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml @@ -290,6 +290,9 @@ patternProperties: additionalProperties: false +allOf: + - $ref: pinctrl.yaml# + required: - compatible diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt deleted file mode 100644 index 3e56c1b34a4c..000000000000 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ /dev/null @@ -1,41 +0,0 @@ -Driver a GPIO line that can be used to turn the power off. - -The driver supports both level triggered and edge triggered power off. -At driver load time, the driver will request the given gpio line and -install a handler to power off the system. If the optional properties -'input' is not found, the GPIO line will be driven in the inactive -state. Otherwise its configured as an input. - -When the power-off handler is called, the gpio is configured as an -output, and drive active, so triggering a level triggered power off -condition. This will also cause an inactive->active edge condition, so -triggering positive edge triggered power off. After a delay of 100ms, -the GPIO is set to inactive, thus causing an active->inactive edge, -triggering negative edge triggered power off. After another 100ms -delay the GPIO is driver active again. If the power is still on and -the CPU still running after a 3000ms delay, a WARN_ON(1) is emitted. - -Required properties: -- compatible : should be "gpio-poweroff". -- gpios : The GPIO to set high/low, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be - low to power down the board set it to "Active Low", otherwise set - gpio to "Active High". - -Optional properties: -- input : Initially configure the GPIO line as an input. Only reconfigure - it to an output when the power-off handler is called. If this optional - property is not specified, the GPIO is initialized as an output in its - inactive state. -- active-delay-ms: Delay (default 100) to wait after driving gpio active -- inactive-delay-ms: Delay (default 100) to wait after driving gpio inactive -- timeout-ms: Time to wait before asserting a WARN_ON(1). If nothing is - specified, 3000 ms is used. - -Examples: - -gpio-poweroff { - compatible = "gpio-poweroff"; - gpios = <&gpio 4 0>; - timeout-ms = <3000>; -}; diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml new file mode 100644 index 000000000000..45d66c775115 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/gpio-poweroff.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled power off + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: > + System power off support via a GPIO line. When a shutdown is + executed the operating system is expected to switch the GPIO + from inactive to active. After a delay (active-delay-ms) it + is expected to be switched back to inactive. After another + delay (inactive-delay-ms) it is configured as active again. + Finally the operating system assumes the power off failed if + the system is still running after waiting some time (timeout-ms). + +properties: + compatible: + const: gpio-poweroff + + gpios: + maxItems: 1 + + input: + type: boolean + description: > + Initially configure the GPIO line as an input. Only reconfigure + it to an output when the power-off sequence is initiated. If this optional + property is not specified, the GPIO is initialized as an output in its inactive state. + + active-delay-ms: + default: 100 + description: Delay to wait after driving gpio active + + inactive-delay-ms: + default: 100 + description: Delay to wait after driving gpio inactive + + timeout-ms: + default: 3000 + description: Time to wait before assuming the power off sequence failed. + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + gpio-poweroff { + compatible = "gpio-poweroff"; + gpios = <&gpio 4 0>; + timeout-ms = <3000>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/gpio-restart.txt b/Documentation/devicetree/bindings/power/reset/gpio-restart.txt deleted file mode 100644 index af3701bc15c4..000000000000 --- a/Documentation/devicetree/bindings/power/reset/gpio-restart.txt +++ /dev/null @@ -1,54 +0,0 @@ -Drive a GPIO line that can be used to restart the system from a restart -handler. - -This binding supports level and edge triggered reset. At driver load -time, the driver will request the given gpio line and install a restart -handler. If the optional properties 'open-source' is not found, the GPIO line -will be driven in the inactive state. Otherwise its not driven until -the restart is initiated. - -When the system is restarted, the restart handler will be invoked in -priority order. The gpio is configured as an output, and driven active, -triggering a level triggered reset condition. This will also cause an -inactive->active edge condition, triggering positive edge triggered -reset. After a delay specified by active-delay, the GPIO is set to -inactive, thus causing an active->inactive edge, triggering negative edge -triggered reset. After a delay specified by inactive-delay, the GPIO -is driven active again. After a delay specified by wait-delay, the -restart handler completes allowing other restart handlers to be attempted. - -Required properties: -- compatible : should be "gpio-restart". -- gpios : The GPIO to set high/low, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be - low to reset the board set it to "Active Low", otherwise set - gpio to "Active High". - -Optional properties: -- open-source : Treat the GPIO as being open source and defer driving - it to when the restart is initiated. If this optional property is not - specified, the GPIO is initialized as an output in its inactive state. -- priority : A priority ranging from 0 to 255 (default 128) according to - the following guidelines: - 0: Restart handler of last resort, with limited restart - capabilities - 128: Default restart handler; use if no other restart handler is - expected to be available, and/or if restart functionality is - sufficient to restart the entire system - 255: Highest priority restart handler, will preempt all other - restart handlers -- active-delay: Delay (default 100) to wait after driving gpio active [ms] -- inactive-delay: Delay (default 100) to wait after driving gpio inactive [ms] -- wait-delay: Delay (default 3000) to wait after completing restart - sequence [ms] - -Examples: - -gpio-restart { - compatible = "gpio-restart"; - gpios = <&gpio 4 0>; - priority = <128>; - active-delay = <100>; - inactive-delay = <100>; - wait-delay = <3000>; -}; diff --git a/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml b/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml new file mode 100644 index 000000000000..a72d5c721516 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/gpio-restart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled reset + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: > + Drive a GPIO line that can be used to restart the system from a restart handler. + + This binding supports level and edge triggered reset. At driver load time, the driver will + request the given gpio line and install a restart handler. If the optional properties + 'open-source' is not found, the GPIO line will be driven in the inactive state. Otherwise its + not driven until the restart is initiated. + + When the system is restarted, the restart handler will be invoked in priority order. The GPIO + is configured as an output, and driven active, triggering a level triggered reset condition. + This will also cause an inactive->active edge condition, triggering positive edge triggered + reset. After a delay specified by active-delay, the GPIO is set to inactive, thus causing an + active->inactive edge, triggering negative edge triggered reset. After a delay specified by + inactive-delay, the GPIO is driven active again. After a delay specified by wait-delay, the + restart handler completes allowing other restart handlers to be attempted. + +properties: + compatible: + const: gpio-restart + + gpios: + description: The GPIO to set high/low, see "gpios property" in + Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be low to reset the board + set it to "Active Low", otherwise set GPIO to "Active High". + + open-source: + $ref: /schemas/types.yaml#/definitions/flag + description: Treat the GPIO as being open source and defer driving it to when the restart is + initiated. If this optional property is not specified, the GPIO is initialized as an output + in its inactive state. + + priority: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + A priority ranging from 0 to 255 (default 129) according to the following guidelines: + + 0: Restart handler of last resort, with limited restart capabilities. + 128: Default restart handler; use if no other restart handler is expected to be available, + and/or if restart functionality is sufficient to restart the entire system. + 255: Highest priority restart handler, will preempt all other restart handlers. + minimum: 0 + maximum: 255 + default: 129 + + active-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Delay (default 100) to wait after driving gpio active [ms] + default: 100 + + inactive-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Delay (default 100) to wait after driving gpio inactive [ms] + default: 100 + + wait-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Delay (default 3000) to wait after completing restart sequence [ms] + default: 100 + +additionalProperties: false + +required: + - compatible + - gpios + +examples: + - | + gpio-restart { + compatible = "gpio-restart"; + gpios = <&gpio 4 0>; + priority = <128>; + active-delay = <100>; + inactive-delay = <100>; + wait-delay = <3000>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max14577.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max14577.yaml new file mode 100644 index 000000000000..3978b48299de --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max14577.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/maxim,max14577.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX14577/MAX77836 MicroUSB and Companion Power Management IC Charger + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX14577/MAX77836 MicroUSB + Integrated Circuit (MUIC). + + See also Documentation/devicetree/bindings/mfd/maxim,max14577.yaml for + additional information and example. + +properties: + compatible: + enum: + - maxim,max14577-charger + - maxim,max77836-charger + + maxim,constant-uvolt: + description: + Battery Constant Voltage in uV + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 4000000 + maximum: 4350000 + + maxim,eoc-uamp: + description: | + Current in uA for End-Of-Charge mode. + MAX14577: 50000-20000 + MAX77836: 5000-100000 + $ref: /schemas/types.yaml#/definitions/uint32 + + maxim,fast-charge-uamp: + description: | + Current in uA for Fast Charge + MAX14577: 90000-950000 + MAX77836: 45000-475000 + $ref: /schemas/types.yaml#/definitions/uint32 + + maxim,ovp-uvolt: + description: + OverVoltage Protection Threshold in uV; In an overvoltage condition, INT + asserts and charging stops. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [6000000, 6500000, 7000000, 7500000] + +required: + - compatible + - maxim,constant-uvolt + - maxim,eoc-uamp + - maxim,fast-charge-uamp + - maxim,ovp-uvolt + +allOf: + - if: + properties: + compatible: + contains: + const: maxim,max14577-charger + then: + properties: + maxim,eoc-uamp: + minimum: 50000 + maximum: 200000 + maxim,fast-charge-uamp: + minimum: 90000 + maximum: 950000 + else: + # max77836 + properties: + maxim,eoc-uamp: + minimum: 5000 + maximum: 100000 + maxim,fast-charge-uamp: + minimum: 45000 + maximum: 475000 + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml index ffb344987a7b..6b4588a3253b 100644 --- a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml @@ -44,7 +44,9 @@ properties: SoC == State of Charge == Capacity. maxim,rcomp: - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 1 + maxItems: 2 description: | A value to compensate readings for various battery chemistries and operating temperatures. max17040,41 have 2 byte rcomp, default to 0x97 0x00. diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml new file mode 100644 index 000000000000..675b9b26d233 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/maxim,max77976.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX77976 Battery charger + +maintainers: + - Luca Ceresoli <luca@lucaceresoli.net> + +description: | + The Maxim MAX77976 is a 19Vin / 5.5A, 1-Cell Li+ battery charger + configured via I2C. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,max77976 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@6b { + compatible = "maxim,max77976"; + reg = <0x6b>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml index bc8904872d1b..caeff68c66d5 100644 --- a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: qcom,pm8941-charger + enum: + - qcom,pm8226-charger + - qcom,pm8941-charger reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt deleted file mode 100644 index 0e662d7f6bd1..000000000000 --- a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt +++ /dev/null @@ -1,20 +0,0 @@ -Broadcom BCM7038 PWM controller (BCM7xxx Set Top Box PWM controller) - -Required properties: - -- compatible: must be "brcm,bcm7038-pwm" -- reg: physical base address and length for this controller -- #pwm-cells: should be 2. See pwm.yaml in this directory for a description - of the cells format -- clocks: a phandle to the reference clock for this block which is fed through - its internal variable clock frequency generator - - -Example: - - pwm: pwm@f0408000 { - compatible = "brcm,bcm7038-pwm"; - reg = <0xf0408000 0x28>; - #pwm-cells = <2>; - clocks = <&upg_fixed>; - }; diff --git a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml new file mode 100644 index 000000000000..4080e098f746 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/brcm,bcm7038-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM7038 PWM controller (BCM7xxx Set Top Box PWM controller) + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + const: brcm,bcm7038-pwm + + reg: + maxItems: 1 + + "#pwm-cells": + const: 2 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - "#pwm-cells" + - clocks + +additionalProperties: false + +examples: + - | + pwm: pwm@f0408000 { + compatible = "brcm,bcm7038-pwm"; + reg = <0xf0408000 0x28>; + #pwm-cells = <2>; + clocks = <&upg_fixed>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml index 84e66913d042..db41cd7bf150 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml @@ -8,7 +8,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SiFive PWM controller maintainers: - - Yash Shah <yash.shah@sifive.com> - Sagar Kadam <sagar.kadam@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> diff --git a/Documentation/devicetree/bindings/pwm/pwm.yaml b/Documentation/devicetree/bindings/pwm/pwm.yaml index 2effe6c0de6b..3c01f85029e5 100644 --- a/Documentation/devicetree/bindings/pwm/pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm.yaml @@ -9,6 +9,8 @@ title: PWM controllers (providers) maintainers: - Thierry Reding <thierry.reding@gmail.com> +select: false + properties: $nodename: pattern: "^pwm(@.*|-[0-9a-f])*$" diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml index 228018c87bea..24ace6e1e5ec 100644 --- a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml +++ b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml @@ -17,27 +17,39 @@ description: | Dialog Semiconductor DA9130 Single-channel 10A double-phase buck converter Dialog Semiconductor DA9131 Double-channel 5A single-phase buck converter Dialog Semiconductor DA9132 Double-channel 3A single-phase buck converter - - Current limits - - This is PER PHASE, and the current limit setting in the devices reflect - that with a maximum 10A limit. Allowing for transients at/near double - the rated current, this translates across the device range to per - channel figures as so... - - | DA9121 DA9122 DA9220 DA9217 DA9140 - | /DA9130 /DA9131 /DA9132 - ----------------------------------------------------------------------------- - Output current / channel | 10000000 5000000 3000000 6000000 40000000 - Output current / phase | 5000000 5000000 3000000 3000000 9500000 - ----------------------------------------------------------------------------- - Min regulator-min-microvolt| 300000 300000 300000 300000 500000 - Max regulator-max-microvolt| 1900000 1900000 1900000 1900000 1000000 - Device hardware default | 1000000 1000000 1000000 1000000 1000000 - ----------------------------------------------------------------------------- - Min regulator-min-microamp | 7000000 3500000 3500000 7000000 26000000 - Max regulator-max-microamp | 20000000 10000000 6000000 12000000 78000000 - Device hardware default | 15000000 7500000 5500000 11000000 58000000 + Dialog Semiconductor DA9141 Single-channel 40A quad-phase buck converter + Dialog Semiconductor DA9142 Single-channel 20A double-phase buck converter + + Device parameter ranges + + The current limits can be set to at/near double the rated current per channel + to allow for transient peaks. + Current limit changes when the output is enabled are not supported, as a + precaution against undefined behaviour. + + |----------------------------------------------| + | | range & reset default value | + | Device |------------------------------| + | | microvolt | microamp | + |----------------------------------------------| + | DA9121/DA9130 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 20000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 10000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 6000000 | + |----------------------------------------------| + | DA9217 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 12000000 | + |----------------------------------------------| + | DA9141 | Min: 300000 | Min: 26000000 | + | | Max: 1300000 | Max: 78000000 | + |----------------------------------------------| + | DA9142 | Min: 300000 | Min: 13000000 | + | | Max: 1300000 | Max: 39000000 | + |----------------------------------------------| properties: $nodename: @@ -51,7 +63,8 @@ properties: - dlg,da9130 - dlg,da9131 - dlg,da9132 - - dlg,da9140 + - dlg,da9141 + - dlg,da9142 reg: maxItems: 1 @@ -70,26 +83,24 @@ properties: regulators: type: object - $ref: regulator.yaml# description: | - This node defines the settings for the BUCK. The content of the - sub-node is defined by the standard binding for regulators; see regulator.yaml. - The DA9121 regulator is bound using their names listed below - buck1 - BUCK1 - buck2 - BUCK2 //DA9122, DA9220, DA9131, DA9132 only + List of regulators provided by the device patternProperties: "^buck([1-2])$": type: object $ref: regulator.yaml# + description: | + Properties for a single BUCK regulator properties: - regulator-mode: - maxItems: 1 - description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h + regulator-name: + pattern: "^BUCK([1-2])$" + description: | + BUCK2 present in DA9122, DA9220, DA9131, DA9132 only regulator-initial-mode: - maxItems: 1 + enum: [ 0, 1, 2, 3 ] description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h enable-gpios: @@ -98,6 +109,7 @@ properties: dlg,ripple-cancel: $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 1, 2, 3 ] description: | Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h Only present on multi-channel devices (DA9122, DA9220, DA9131, DA9132) diff --git a/Documentation/devicetree/bindings/regulator/max77686.txt b/Documentation/devicetree/bindings/regulator/max77686.txt deleted file mode 100644 index ff3d2dec8c4b..000000000000 --- a/Documentation/devicetree/bindings/regulator/max77686.txt +++ /dev/null @@ -1,71 +0,0 @@ -Binding for Maxim MAX77686 regulators - -This is a part of the device tree bindings of MAX77686 multi-function device. -More information can be found in ../mfd/max77686.txt file. - -The MAX77686 PMIC has 9 high-efficiency Buck and 26 Low-DropOut (LDO) -regulators that can be controlled over I2C. - -Following properties should be present in main device node of the MFD chip. - -Optional node: -- voltage-regulators : The regulators of max77686 have to be instantiated - under subnode named "voltage-regulators" using the following format. - - regulator_name { - regulator-compatible = LDOn/BUCKn - standard regulator constraints.... - }; - refer Documentation/devicetree/bindings/regulator/regulator.txt - - The regulator node's name should be initialized with a string -to get matched with their hardware counterparts as follow: - - -LDOn : for LDOs, where n can lie in range 1 to 26. - example: LDO1, LDO2, LDO26. - -BUCKn : for BUCKs, where n can lie in range 1 to 9. - example: BUCK1, BUCK5, BUCK9. - - Regulators which can be turned off during system suspend: - -LDOn : 2, 6-8, 10-12, 14-16, - -BUCKn : 1-4. - Use standard regulator bindings for it ('regulator-off-in-suspend'). - - LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable - control. To turn this feature on this property must be added to the regulator - sub-node: - - maxim,ena-gpios : one GPIO specifier enable control (the gpio - flags are actually ignored and always - ACTIVE_HIGH is used) - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - - voltage-regulators { - ldo11_reg: LDO11 { - regulator-name = "vdd_ldo11"; - regulator-min-microvolt = <1900000>; - regulator-max-microvolt = <1900000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - regulator-boot-on; - }; - - buck9_reg: BUCK9 { - regulator-name = "CAM_ISP_CORE_1.2V"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1200000>; - maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/max77802.txt b/Documentation/devicetree/bindings/regulator/max77802.txt deleted file mode 100644 index b82943d83677..000000000000 --- a/Documentation/devicetree/bindings/regulator/max77802.txt +++ /dev/null @@ -1,111 +0,0 @@ -Binding for Maxim MAX77802 regulators - -This is a part of device tree bindings of MAX77802 multi-function device. -More information can be found in bindings/mfd/max77802.txt file. - -The MAX77802 PMIC has 10 high-efficiency Buck and 32 Low-dropout (LDO) -regulators that can be controlled over I2C. - -Following properties should be present in main device node of the MFD chip. - -Optional properties: -- inb1-supply: The input supply for BUCK1 -- inb2-supply: The input supply for BUCK2 -- inb3-supply: The input supply for BUCK3 -- inb4-supply: The input supply for BUCK4 -- inb5-supply: The input supply for BUCK5 -- inb6-supply: The input supply for BUCK6 -- inb7-supply: The input supply for BUCK7 -- inb8-supply: The input supply for BUCK8 -- inb9-supply: The input supply for BUCK9 -- inb10-supply: The input supply for BUCK10 -- inl1-supply: The input supply for LDO8 and LDO15 -- inl2-supply: The input supply for LDO17, LDO27, LDO30 and LDO35 -- inl3-supply: The input supply for LDO3, LDO5, LDO6 and LDO7 -- inl4-supply: The input supply for LDO10, LDO11, LDO13 and LDO14 -- inl5-supply: The input supply for LDO9 and LDO19 -- inl6-supply: The input supply for LDO4, LDO21, LDO24 and LDO33 -- inl7-supply: The input supply for LDO18, LDO20, LDO28 and LDO29 -- inl9-supply: The input supply for LDO12, LDO23, LDO25, LDO26, LDO32 and LDO34 -- inl10-supply: The input supply for LDO1 and LDO2 - -Optional nodes: -- regulators : The regulators of max77802 have to be instantiated - under subnode named "regulators" using the following format. - - regulator-name { - standard regulator constraints.... - }; - refer Documentation/devicetree/bindings/regulator/regulator.txt - -The regulator node name should be initialized with a string to get matched -with their hardware counterparts as follow. The valid names are: - - -LDOn : for LDOs, where n can lie in ranges 1-15, 17-21, 23-30 - and 32-35. - example: LDO1, LDO2, LDO35. - -BUCKn : for BUCKs, where n can lie in range 1 to 10. - example: BUCK1, BUCK5, BUCK10. - -The max77802 regulator supports two different operating modes: Normal and Low -Power Mode. Some regulators support the modes to be changed at startup or by -the consumers during normal operation while others only support to change the -mode during system suspend. The standard regulator suspend states binding can -be used to configure the regulator operating mode. - -The regulators that support the standard "regulator-initial-mode" property, -changing their mode during normal operation are: LDOs 1, 3, 20 and 21. - -The possible values for "regulator-initial-mode" and "regulator-mode" are: - 1: Normal regulator voltage output mode. - 3: Low Power which reduces the quiescent current down to only 1uA - -The valid modes list is defined in the dt-bindings/regulator/maxim,max77802.h -header and can be included by device tree source files. - -The standard "regulator-mode" property can only be used for regulators that -support changing their mode to Low Power Mode during suspend. These regulators -are: BUCKs 2-4 and LDOs 1-35. Also, it only takes effect if the regulator has -been enabled for the given suspend state using "regulator-on-in-suspend" and -has not been disabled for that state using "regulator-off-in-suspend". - -Example: - - max77802@9 { - compatible = "maxim,max77802"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 0>; - reg = <0x09>; - #address-cells = <1>; - #size-cells = <0>; - - inb1-supply = <&parent_reg>; - - regulators { - ldo1_reg: LDO1 { - regulator-name = "vdd_1v0"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1000000>; - regulator-always-on; - regulator-initial-mode = <MAX77802_OPMODE_LP>; - }; - - ldo11_reg: LDO11 { - regulator-name = "vdd_ldo11"; - regulator-min-microvolt = <1900000>; - regulator-max-microvolt = <1900000>; - regulator-always-on; - regulator-state-mem { - regulator-on-in-suspend; - regulator-mode = <MAX77802_OPMODE_LP>; - }; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - regulator-boot-on; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/maxim,max14577.yaml b/Documentation/devicetree/bindings/regulator/maxim,max14577.yaml new file mode 100644 index 000000000000..16f01886a601 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max14577.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max14577.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX14577/MAX77836 MicroUSB and Companion Power Management IC regulators + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX14577/MAX77836 MicroUSB + Integrated Circuit (MUIC). + + See also Documentation/devicetree/bindings/mfd/maxim,max14577.yaml for + additional information and example. + +properties: + compatible: + enum: + - maxim,max14577-regulator + - maxim,max77836-regulator + + CHARGER: + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Current regulator. + + properties: + regulator-min-microvolt: false + regulator-max-microvolt: false + + SAFEOUT: + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Safeout LDO regulator (fixed voltage). + + properties: + regulator-min-microamp: false + regulator-max-microamp: false + regulator-min-microvolt: + const: 4900000 + regulator-max-microvolt: + const: 4900000 + +patternProperties: + "^LDO[12]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Current regulator. + + properties: + regulator-min-microamp: false + regulator-max-microamp: false + regulator-min-microvolt: + minimum: 800000 + regulator-max-microvolt: + maximum: 3950000 + +allOf: + - if: + properties: + compatible: + contains: + const: maxim,max14577-regulator + then: + properties: + LDO1: false + LDO2: false + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml new file mode 100644 index 000000000000..05f72391185e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max20086.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX20086-MAX20089 Camera Power Protector + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: | + The MAX20086-MAX20089 are dual/quad camera power protectors, designed to + deliver power over coax for radar and camera modules. They support + software-configurable output switching and monitoring. The output voltage and + current limit are fixed by the hardware design. + +properties: + compatible: + enum: + - maxim,max20086 + - maxim,max20087 + - maxim,max20088 + - maxim,max20089 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + description: GPIO connected to the EN pin, active high + + in-supply: + description: Input supply for the camera outputs (IN pin, 3.0V to 15.0V) + + vdd-supply: + description: Input supply for the device (VDD pin, 3.0V to 5.5V) + + regulators: + type: object + + patternProperties: + "^OUT[1-4]$": + type: object + $ref: regulator.yaml# + + additionalProperties: false + +required: + - compatible + - reg + - in-supply + - vdd-supply + - regulators + +allOf: + - if: + properties: + compatible: + contains: + enum: + - maxim,max20088 + - maxim,max20089 + then: + properties: + regulators: + properties: + OUT3: false + OUT4: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@28 { + compatible = "maxim,max20087"; + reg = <0x28>; + + in-supply = <®_12v0>; + vdd-supply = <®_3v3>; + + enable-gpios = <&gpio 108 GPIO_ACTIVE_HIGH>; + + regulators { + OUT1 { + regulator-name = "VOUT1"; + }; + OUT2 { + regulator-name = "VOUT2"; + }; + OUT3 { + regulator-name = "VOUT3"; + }; + OUT4 { + regulator-name = "VOUT4"; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml new file mode 100644 index 000000000000..bb64b679f765 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC regulators + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 provides high-efficiency Buck and 26 Low-DropOut (LDO) + regulators. + + See also Documentation/devicetree/bindings/mfd/maxim,max77686.yaml for + additional information and example. + +patternProperties: + # 26 LDOs + "^LDO([1-9]|1[0-9]|2[3-6])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + Regulators which can be turned off during system suspend: + LDO2, LDO6-8, LDO10-12, LDO14-16 + + required: + - regulator-name + + # LDO20-LDO22 with maxim,ena-gpios + "^LDO2[0-2]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + + # 9 bucks + "^BUCK[1-7]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + Regulators which can be turned off during system suspend: + BUCK[1-4] + + required: + - regulator-name + + "^BUCK[89]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml new file mode 100644 index 000000000000..f2b4dd15a0f3 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max77802.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77802 Power Management IC regulators + +maintainers: + - Javier Martinez Canillas <javier@dowhile0.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77802 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 provides 10 high-efficiency Buck and 32 Low-DropOut (LDO) + regulators. + + See also Documentation/devicetree/bindings/mfd/maxim,max77802.yaml for + additional information and example. + + Certain regulators support "regulator-initial-mode" and "regulator-mode". + The valid modes list is defined in the dt-bindings/regulator/maxim,max77802.h + and their meaning is:: + 1 - Normal regulator voltage output mode. + 3 - Low Power which reduces the quiescent current down to only 1uA + + The standard "regulator-mode" property can only be used for regulators that + support changing their mode to Low Power Mode during suspend. These + regulators are:: bucks 2-4 and LDOs 1-35. Also, it only takes effect if the + regulator has been enabled for the given suspend state using + "regulator-on-in-suspend" and has not been disabled for that state using + "regulator-off-in-suspend". + +patternProperties: + # LDO1, LDO3, LDO20, LDO21 + "^LDO([13]|2[01])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + LDOs supporting the regulator-initial-mode property and changing their + mode during normal operation. + + # LDO2, LDO4-15, LDO17-19, LDO23-30, LDO32-35 + "^LDO([24-9]|1[0-5789]|2[3-9]|3[02345])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + LDOs supporting the regulator-mode property (changing mode to Low Power + Mode during suspend). + + properties: + regulator-initial-mode: false + + # buck2-4 + "^BUCK[2-4]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + bucks supporting the regulator-mode property (changing mode to Low Power + Mode during suspend). + + properties: + regulator-initial-mode: false + + # buck1, buck5-10 + "^BUCK([15-9]|10)$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + + properties: + regulator-initial-mode: false + + patternProperties: + regulator-state-(standby|mem|disk): + type: object + properties: + regulator-mode: false + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77843.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77843.yaml new file mode 100644 index 000000000000..a963025e96c1 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max77843.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max77843.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77843 MicroUSB and Companion Power Management IC regulators + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77843 MicroUSB Integrated + Circuit (MUIC). + + See also Documentation/devicetree/bindings/mfd/maxim,max77843.yaml for + additional information and example. + +properties: + compatible: + const: maxim,max77843-regulator + + CHARGER: + type: object + $ref: regulator.yaml# + additionalProperties: false + description: | + Current regulator. + + properties: + regulator-name: true + regulator-always-on: true + regulator-boot-on: true + regulator-min-microamp: + minimum: 100000 + regulator-max-microamp: + maximum: 3150000 + + required: + - regulator-name + +patternProperties: + "^SAFEOUT[12]$": + type: object + $ref: regulator.yaml# + additionalProperties: false + description: | + Safeout LDO regulator. + + properties: + regulator-name: true + regulator-always-on: true + regulator-boot-on: true + regulator-min-microvolt: + minimum: 3300000 + regulator-max-microvolt: + maximum: 4950000 + + required: + - regulator-name + +required: + - compatible + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml index 54522827265b..5898dcf10f06 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml @@ -86,6 +86,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + required: - compatible - reg @@ -110,7 +113,7 @@ examples: }; - | - #include <dt-bindings/gpio/tegra-gpio.h> + #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> i2c { @@ -120,8 +123,7 @@ examples: regulator@1b { compatible = "maxim,max77621"; reg = <0x1b>; - interrupt-parent = <&gpio>; - interrupts = <TEGRA_GPIO(Y, 1) IRQ_TYPE_LEVEL_LOW>; + interrupts = <1 IRQ_TYPE_LEVEL_LOW>; regulator-always-on; regulator-boot-on; diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.yaml b/Documentation/devicetree/bindings/regulator/pfuze100.yaml index f578e72778a7..a26bbd68b729 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.yaml +++ b/Documentation/devicetree/bindings/regulator/pfuze100.yaml @@ -70,7 +70,11 @@ properties: $ref: "regulator.yaml#" type: object - "^(vsnvs|vref|vrefddr|swbst|coin)$": + "^vldo[1-4]$": + $ref: "regulator.yaml#" + type: object + + "^(vsnvs|vref|vrefddr|swbst|coin|v33|vccsd)$": $ref: "regulator.yaml#" type: object diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index b959504e0ea4..e28ee9e46788 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -43,10 +43,12 @@ description: | For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb For PM8350, smps1 - smps12, ldo1 - ldo10 For PM8350C, smps1 - smps10, ldo1 - ldo13, bob + For PM8450, smps1 - smps6, ldo1 - ldo4 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob For PMR735A, smps1 - smps3, ldo1 - ldo7 For PMX55, smps1 - smps7, ldo1 - ldo16 + For PMX65, smps1 - smps8, ldo1 - ldo21 properties: compatible: @@ -62,11 +64,14 @@ properties: - qcom,pm8150l-rpmh-regulators - qcom,pm8350-rpmh-regulators - qcom,pm8350c-rpmh-regulators + - qcom,pm8450-rpmh-regulators - qcom,pm8998-rpmh-regulators + - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators - qcom,pmm8155au-rpmh-regulators - qcom,pmr735a-rpmh-regulators - qcom,pmx55-rpmh-regulators + - qcom,pmx65-rpmh-regulators qcom,pmic-id: description: | diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt index 2b544059e029..c2a39b121b1b 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt @@ -6,6 +6,7 @@ Qualcomm SPMI Regulators Definition: must be one of: "qcom,pm8004-regulators" "qcom,pm8005-regulators" + "qcom,pm8226-regulators" "qcom,pm8841-regulators" "qcom,pm8916-regulators" "qcom,pm8941-regulators" diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index a6ae9ecae5cc..ed560ee8714e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -218,7 +218,7 @@ properties: description: Array of maximum spread between voltages of coupled regulators in microvolts, each value in the array relates to the corresponding couple specified by the regulator-coupled-with property. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: "/schemas/types.yaml#/definitions/uint32-array" regulator-max-step-microvolt: description: Maximum difference between current and target voltages diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml new file mode 100644 index 000000000000..28725c5467fc --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/richtek,rt5190a-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RT5190A PMIC Regulator + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: | + The RT5190A integrates 1 channel buck controller, 3 channels high efficiency + synchronous buck converters, 1 LDO, I2C control interface and peripherial + logical control. + + It also supports mute AC OFF depop sound and quick setting storage while + input power is removed. + +properties: + compatible: + enum: + - richtek,rt5190a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vin2-supply: + description: phandle to buck2 input voltage. + + vin3-supply: + description: phandle to buck3 input voltage. + + vin4-supply: + description: phandle to buck4 input voltage. + + vinldo-supply: + description: phandle to ldo input voltage + + richtek,mute-enable: + description: | + The mute function uses 'mutein', 'muteout', and 'vdet' pins as the control + signal. When enabled, The normal behavior is to bypass the 'mutein' signal + 'muteout'. But if the power source removal is detected from 'vdet', + whatever the 'mutein' signal is, it will pull down the 'muteout' to force + speakers mute. this function is commonly used to prevent the speaker pop + noise during AC power turned off in the modern TV system design. + type: boolean + + regulators: + type: object + + patternProperties: + "^buck[1-4]$|^ldo$": + type: object + $ref: regulator.yaml# + description: | + regulator description for buck1 and buck4. + + properties: + regulator-allowed-modes: + description: | + buck operating mode, only buck1/4 support mode operating. + 0: auto mode + 1: force pwm mode + items: + enum: [0, 1] + + richtek,latchup-enable: + type: boolean + description: | + If specified, undervolt protection mode changes from the default + hiccup to latchup. + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/regulator/richtek,rt5190a-regulator.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@64 { + compatible = "richtek,rt5190a"; + reg = <0x64>; + interrupts-extended = <&gpio26 0 IRQ_TYPE_LEVEL_LOW>; + vin2-supply = <&rt5190_buck1>; + vin3-supply = <&rt5190_buck1>; + vin4-supply = <&rt5190_buck1>; + + regulators { + rt5190_buck1: buck1 { + regulator-name = "rt5190a-buck1"; + regulator-min-microvolt = <5090000>; + regulator-max-microvolt = <5090000>; + regulator-allowed-modes = <RT5190A_OPMODE_AUTO RT5190A_OPMODE_FPWM>; + regulator-boot-on; + }; + buck2 { + regulator-name = "rt5190a-buck2"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1400000>; + regulator-boot-on; + }; + buck3 { + regulator-name = "rt5190a-buck3"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1400000>; + regulator-boot-on; + }; + buck4 { + regulator-name = "rt5190a-buck4"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <850000>; + regulator-allowed-modes = <RT5190A_OPMODE_AUTO RT5190A_OPMODE_FPWM>; + regulator-boot-on; + }; + ldo { + regulator-name = "rt5190a-ldo"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-boot-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt b/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt deleted file mode 100644 index 698cfc3bc3dd..000000000000 --- a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt +++ /dev/null @@ -1,68 +0,0 @@ -ROHM BD70528 Power Management Integrated Circuit regulator bindings - -Required properties: - - regulator-name: should be "buck1", "buck2", "buck3", "ldo1", "ldo2", "ldo3", - "led_ldo1", "led_ldo2" - -List of regulators provided by this controller. BD70528 regulators node -should be sub node of the BD70528 MFD node. See BD70528 MFD bindings at -Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt - -The valid names for BD70528 regulator nodes are: -BUCK1, BUCK2, BUCK3, LDO1, LDO2, LDO3, LED_LDO1, LED_LDO2 - -Optional properties: -- Any optional property defined in bindings/regulator/regulator.txt - -Example: -regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml index c98929a213e9..3c1617b66861 100644 --- a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml +++ b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml @@ -67,8 +67,9 @@ patternProperties: required: - regulator-name +properties: # 9 buck - "^BUCK9$": + BUCK9: type: object $ref: regulator.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/regulator/ti,tps62360.yaml b/Documentation/devicetree/bindings/regulator/ti,tps62360.yaml new file mode 100644 index 000000000000..12aeddedde05 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ti,tps62360.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/ti,tps62360.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TPS6236x Voltage Regulators + +maintainers: + - Laxman Dewangan <ldewangan@nvidia.com> + +description: | + The TPS6236x are a family of step down dc-dc converter with + an input voltage range of 2.5V to 5.5V. The devices provide + up to 3A peak load current, and an output voltage range of + 0.77V to 1.4V (TPS62360/62) and 0.5V to 1.77V (TPS62361B/63). + + Datasheet is available at: + https://www.ti.com/lit/gpn/tps62360 + +allOf: + - $ref: "regulator.yaml#" + +properties: + compatible: + enum: + - ti,tps62360 + - ti,tps62361 + - ti,tps62362 + - ti,tps62363 + + reg: + maxItems: 1 + + ti,vsel0-gpio: + description: | + GPIO for controlling VSEL0 line. If this property + is missing, then assume that there is no GPIO for + VSEL0 control. + maxItems: 1 + + ti,vsel1-gpio: + description: | + GPIO for controlling VSEL1 line. If this property + is missing, then assume that there is no GPIO for + VSEL1 control. + maxItems: 1 + + ti,enable-vout-discharge: + description: Enable output discharge. + type: boolean + + ti,enable-pull-down: + description: Enable pull down. + type: boolean + + ti,vsel0-state-high: + description: | + Initial state of VSEL0 input is high. If this property + is missing, then assume the state as low. + type: boolean + + ti,vsel1-state-high: + description: | + Initial state of VSEL1 input is high. If this property + is missing, then assume the state as low. + type: boolean + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@60 { + compatible = "ti,tps62361"; + reg = <0x60>; + regulator-name = "tps62361-vout"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + ti,vsel0-gpio = <&gpio1 16 GPIO_ACTIVE_HIGH>; + ti,vsel1-gpio = <&gpio1 17 GPIO_ACTIVE_HIGH>; + ti,vsel0-state-high; + ti,vsel1-state-high; + ti,enable-pull-down; + ti,enable-vout-discharge; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/regulator/ti,tps62864.yaml b/Documentation/devicetree/bindings/regulator/ti,tps62864.yaml new file mode 100644 index 000000000000..0f29c75f42ea --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ti,tps62864.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/ti,tps62864.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI TPS62864/TPS6286/TPS62868/TPS62869 voltage regulator + +maintainers: + - Vincent Whitchurch <vincent.whitchurch@axis.com> + +properties: + compatible: + enum: + - ti,tps62864 + - ti,tps62866 + - ti,tps62868 + - ti,tps62869 + + reg: + maxItems: 1 + + regulators: + type: object + + properties: + "SW": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/regulator/ti,tps62864.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@48 { + compatible = "ti,tps62864"; + reg = <0x48>; + + regulators { + SW { + regulator-name = "+0.85V"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <890000>; + regulator-initial-mode = <TPS62864_MODE_FPWM>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/regulator/tps62360-regulator.txt b/Documentation/devicetree/bindings/regulator/tps62360-regulator.txt deleted file mode 100644 index 1b20c3dbcdb8..000000000000 --- a/Documentation/devicetree/bindings/regulator/tps62360-regulator.txt +++ /dev/null @@ -1,44 +0,0 @@ -TPS62360 Voltage regulators - -Required properties: -- compatible: Must be one of the following. - "ti,tps62360" - "ti,tps62361", - "ti,tps62362", - "ti,tps62363", -- reg: I2C slave address - -Optional properties: -- ti,enable-vout-discharge: Enable output discharge. This is boolean value. -- ti,enable-pull-down: Enable pull down. This is boolean value. -- ti,vsel0-gpio: GPIO for controlling VSEL0 line. - If this property is missing, then assume that there is no GPIO - for vsel0 control. -- ti,vsel1-gpio: Gpio for controlling VSEL1 line. - If this property is missing, then assume that there is no GPIO - for vsel1 control. -- ti,vsel0-state-high: Initial state of vsel0 input is high. - If this property is missing, then assume the state as low (0). -- ti,vsel1-state-high: Initial state of vsel1 input is high. - If this property is missing, then assume the state as low (0). - -Any property defined as part of the core regulator binding, defined in -regulator.txt, can also be used. - -Example: - - abc: tps62360 { - compatible = "ti,tps62361"; - reg = <0x60>; - regulator-name = "tps62361-vout"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1500000>; - regulator-boot-on - ti,vsel0-gpio = <&gpio1 16 0>; - ti,vsel1-gpio = <&gpio1 17 0>; - ti,vsel0-state-high; - ti,vsel1-state-high; - ti,enable-pull-down; - ti,enable-force-pwm; - ti,enable-vout-discharge; - }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml index 63e06d93bca3..c635c181d2c2 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml @@ -33,6 +33,9 @@ properties: - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas - qcom,sdx55-mpss-pas + - qcom,sm6350-adsp-pas + - qcom,sm6350-cdsp-pas + - qcom,sm6350-mpss-pas - qcom,sm8150-adsp-pas - qcom,sm8150-cdsp-pas - qcom,sm8150-mpss-pas @@ -158,6 +161,9 @@ allOf: - qcom,sc8180x-mpss-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas + - qcom,sm6350-adsp-pas + - qcom,sm6350-cdsp-pas + - qcom,sm6350-mpss-pas - qcom,sm8150-adsp-pas - qcom,sm8150-cdsp-pas - qcom,sm8150-mpss-pas @@ -266,6 +272,8 @@ allOf: - qcom,sc8180x-cdsp-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas + - qcom,sm6350-adsp-pas + - qcom,sm6350-cdsp-pas - qcom,sm8150-adsp-pas - qcom,sm8150-cdsp-pas - qcom,sm8150-slpi-pas @@ -301,6 +309,7 @@ allOf: - qcom,sc7280-mpss-pas - qcom,sc8180x-mpss-pas - qcom,sdx55-mpss-pas + - qcom,sm6350-mpss-pas - qcom,sm8150-mpss-pas - qcom,sm8350-mpss-pas then: @@ -390,6 +399,23 @@ allOf: compatible: contains: enum: + - qcom,sm6350-cdsp-pas + then: + properties: + power-domains: + items: + - description: CX power domain + - description: MX power domain + power-domain-names: + items: + - const: cx + - const: mx + + - if: + properties: + compatible: + contains: + enum: - qcom,sm8150-adsp-pas - qcom,sm8150-cdsp-pas then: @@ -405,6 +431,7 @@ allOf: enum: - qcom,sc7280-mpss-pas - qcom,sdx55-mpss-pas + - qcom,sm6350-mpss-pas - qcom,sm8150-mpss-pas - qcom,sm8350-mpss-pas then: @@ -425,6 +452,7 @@ allOf: enum: - qcom,sc8180x-adsp-pas - qcom,sc8180x-cdsp-pas + - qcom,sm6350-adsp-pas - qcom,sm8150-slpi-pas - qcom,sm8250-adsp-pas - qcom,sm8250-slpi-pas diff --git a/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml new file mode 100644 index 000000000000..a7d25fa920e5 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/remoteproc/renesas,rcar-rproc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Renesas R-Car remote processor controller bindings + +maintainers: + - Julien Massot <julien.massot@iot.bzh> + +description: | + This document defines the bindings for the remoteproc component that loads and + boots firmwares on the Renesas R-Car family chipset. + R-Car gen3 family may have a realtime processor, this processor shares peripheral + and RAM with the host processor with the same address map. + +properties: + compatible: + const: renesas,rcar-cr7 + + resets: + maxItems: 1 + + power-domains: + maxItems: 1 + + memory-region: + description: + List of phandles to the reserved memory regions associated with the + remoteproc device. This is variable and describes the memories shared with + the remote processor (e.g. remoteproc firmware and carveouts, rpmsg + vrings, ...). + (see ../reserved-memory/reserved-memory.yaml) + +required: + - compatible + - resets + - memory-region + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/power/r8a7795-sysc.h> + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + + cr7_ram: cr7_ram@40040000 { + no-map; + reg = <0x0 0x40040000 0x0 0x1fc0000>; + }; + }; + + cr7_rproc: cr7 { + compatible = "renesas,rcar-cr7"; + memory-region = <&cr7_ram>; + power-domains = <&sysc R8A7795_PD_CR7>; + resets = <&cpg 222>; + }; + +... diff --git a/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml index 5ec6505ac408..7b56497eec4d 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml @@ -33,9 +33,11 @@ properties: enum: - ti,j721e-c66-dsp - ti,j721e-c71-dsp + - ti,j721s2-c71-dsp description: Use "ti,j721e-c66-dsp" for C66x DSPs on K3 J721E SoCs Use "ti,j721e-c71-dsp" for C71x DSPs on K3 J721E SoCs + Use "ti,j721s2-c71-dsp" for C71x DSPs on K3 J721S2 SoCs resets: description: | @@ -106,6 +108,7 @@ else: compatible: enum: - ti,j721e-c71-dsp + - ti,j721s2-c71-dsp then: properties: reg: diff --git a/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml index eeef255c4045..d9c7e8c2b268 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml @@ -38,6 +38,7 @@ properties: - ti,j721e-r5fss - ti,j7200-r5fss - ti,am64-r5fss + - ti,j721s2-r5fss power-domains: description: | @@ -64,9 +65,9 @@ properties: description: | Configuration Mode for the Dual R5F cores within the R5F cluster. Should be either a value of 1 (LockStep mode) or 0 (Split mode) on - most SoCs (AM65x, J721E, J7200), default is LockStep mode if omitted; - and should be either a value of 0 (Split mode) or 2 (Single-CPU mode) - on AM64x SoCs, default is Split mode if omitted. + most SoCs (AM65x, J721E, J7200, J721s2), default is LockStep mode if + omitted; and should be either a value of 0 (Split mode) or 2 + (Single-CPU mode) on AM64x SoCs, default is Split mode if omitted. # R5F Processor Child Nodes: # ========================== @@ -104,6 +105,7 @@ patternProperties: - ti,j721e-r5f - ti,j7200-r5f - ti,am64-r5f + - ti,j721s2-r5f reg: items: diff --git a/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra210-emc-table.yaml b/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra210-emc-table.yaml new file mode 100644 index 000000000000..035a50fe3ee4 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra210-emc-table.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reserved-memory/nvidia,tegra210-emc-table.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra210 EMC Frequency Table Device Tree Bindings + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: On Tegra210, firmware passes a binary representation of the + EMC frequency table via a reserved memory region. + +allOf: + - $ref: "reserved-memory.yaml" + +properties: + compatible: + const: nvidia,tegra210-emc-table + + reg: + description: region of memory reserved by firmware to pass the EMC + frequency table + +unevaluatedProperties: false + +required: + - compatible + - reg diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.txt b/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.txt deleted file mode 100644 index 68395530c0a5..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.txt +++ /dev/null @@ -1,37 +0,0 @@ -Command DB ---------- - -Command DB is a database that provides a mapping between resource key and the -resource address for a system resource managed by a remote processor. The data -is stored in a shared memory region and is loaded by the remote processor. - -Some of the Qualcomm Technologies Inc SoC's have hardware accelerators for -controlling shared resources. Depending on the board configuration the shared -resource properties may change. These properties are dynamically probed by the -remote processor and made available in the shared memory. - -The bindings for Command DB is specified in the reserved-memory section in -devicetree. The devicetree representation of the command DB driver should be: - -Properties: -- compatible: - Usage: required - Value type: <string> - Definition: Should be "qcom,cmd-db" - -- reg: - Usage: required - Value type: <prop encoded array> - Definition: The register address that points to the actual location of - the Command DB in memory. - -Example: - - reserved-memory { - [...] - reserved-memory@85fe0000 { - reg = <0x0 0x85fe0000 0x0 0x20000>; - compatible = "qcom,cmd-db"; - no-map; - }; - }; diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.yaml b/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.yaml new file mode 100644 index 000000000000..df1b5e0ed3f4 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/reserved-memory/qcom,cmd-db.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Command DB + +description: | + Command DB is a database that provides a mapping between resource key and the + resource address for a system resource managed by a remote processor. The data + is stored in a shared memory region and is loaded by the remote processor. + + Some of the Qualcomm Technologies Inc SoC's have hardware accelerators for + controlling shared resources. Depending on the board configuration the shared + resource properties may change. These properties are dynamically probed by the + remote processor and made available in the shared memory. + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +allOf: + - $ref: "reserved-memory.yaml" + +properties: + compatible: + const: qcom,cmd-db + +required: + - reg + +unevaluatedProperties: false + +examples: + - | + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + reserved-memory@85fe0000 { + reg = <0x85fe0000 0x20000>; + compatible = "qcom,cmd-db"; + no-map; + }; + }; diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.txt b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.txt deleted file mode 100644 index 8562ba1dce69..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.txt +++ /dev/null @@ -1,51 +0,0 @@ -Qualcomm Remote File System Memory binding - -This binding describes the Qualcomm remote filesystem memory, which serves the -purpose of describing the shared memory region used for remote processors to -access block device data using the Remote Filesystem protocol. - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be: - "qcom,rmtfs-mem" - -- reg: - Usage: required for static allocation - Value type: <prop-encoded-array> - Definition: must specify base address and size of the memory region, - as described in reserved-memory.txt - -- size: - Usage: required for dynamic allocation - Value type: <prop-encoded-array> - Definition: must specify a size of the memory region, as described in - reserved-memory.txt - -- qcom,client-id: - Usage: required - Value type: <u32> - Definition: identifier of the client to use this region for buffers. - -- qcom,vmid: - Usage: optional - Value type: <u32> - Definition: vmid of the remote processor, to set up memory protection. - -= EXAMPLE -The following example shows the remote filesystem memory setup for APQ8016, -with the rmtfs region for the Hexagon DSP (id #1) located at 0x86700000. - - reserved-memory { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - rmtfs@86700000 { - compatible = "qcom,rmtfs-mem"; - reg = <0x0 0x86700000 0x0 0xe0000>; - no-map; - - qcom,client-id = <1>; - }; - }; diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml new file mode 100644 index 000000000000..2998f1c8f0db --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/reserved-memory/qcom,rmtfs-mem.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Remote File System Memory + +description: | + This binding describes the Qualcomm remote filesystem memory, which serves the + purpose of describing the shared memory region used for remote processors to + access block device data using the Remote Filesystem protocol. + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +allOf: + - $ref: "reserved-memory.yaml" + +properties: + compatible: + const: qcom,rmtfs-mem + + qcom,client-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + identifier of the client to use this region for buffers + + qcom,vmid: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + vmid of the remote processor, to set up memory protection + +required: + - qcom,client-id + +unevaluatedProperties: false + +examples: + - | + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + rmtfs@86700000 { + compatible = "qcom,rmtfs-mem"; + reg = <0x86700000 0xe0000>; + no-map; + + qcom,client-id = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt b/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt deleted file mode 100644 index ee59409640f2..000000000000 --- a/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt +++ /dev/null @@ -1,27 +0,0 @@ -Broadcom STB SW_INIT-style reset controller -=========================================== - -Broadcom STB SoCs have a SW_INIT-style reset controller with separate -SET/CLEAR/STATUS registers and possibly multiple banks, each of 32 bit -reset lines. - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: should be brcm,brcmstb-reset -- reg: register base and length -- #reset-cells: must be set to 1 - -Example: - - reset: reset-controller@8404318 { - compatible = "brcm,brcmstb-reset"; - reg = <0x8404318 0x30>; - #reset-cells = <1>; - }; - - ðernet_switch { - resets = <&reset 26>; - reset-names = "switch"; - }; diff --git a/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.yaml b/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.yaml new file mode 100644 index 000000000000..e00efa88a198 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/reset/brcm,brcmstb-reset.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Broadcom STB SW_INIT-style reset controller + +description: + Broadcom STB SoCs have a SW_INIT-style reset controller with separate + SET/CLEAR/STATUS registers and possibly multiple banks, each of 32 bit + reset lines. + + Please also refer to reset.txt in this directory for common reset + controller binding usage. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + const: brcm,brcmstb-reset + + reg: + maxItems: 1 + + "#reset-cells": + const: 1 + +required: + - compatible + - reg + - "#reset-cells" + +additionalProperties: false + +examples: + - | + reset: reset-controller@8404318 { + compatible = "brcm,brcmstb-reset"; + reg = <0x8404318 0x30>; + #reset-cells = <1>; + }; + + ethernet_switch { + resets = <&reset 26>; + reset-names = "switch"; + }; diff --git a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml index 2b1f91603897..e2d330bd4608 100644 --- a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml @@ -9,7 +9,6 @@ title: SiFive L2 Cache Controller maintainers: - Sagar Kadam <sagar.kadam@sifive.com> - - Yash Shah <yash.shah@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> description: diff --git a/Documentation/devicetree/bindings/rng/apm,rng.txt b/Documentation/devicetree/bindings/rng/apm,rng.txt deleted file mode 100644 index 4dde4b06cdd9..000000000000 --- a/Documentation/devicetree/bindings/rng/apm,rng.txt +++ /dev/null @@ -1,17 +0,0 @@ -APM X-Gene SoC random number generator. - -Required properties: - -- compatible : should be "apm,xgene-rng" -- reg : specifies base physical address and size of the registers map -- clocks : phandle to clock-controller plus clock-specifier pair -- interrupts : specify the fault interrupt for the RNG device - -Example: - - rng: rng@10520000 { - compatible = "apm,xgene-rng"; - reg = <0x0 0x10520000 0x0 0x100>; - interrupts = <0x0 0x41 0x4>; - clocks = <&rngpkaclk 0>; - }; diff --git a/Documentation/devicetree/bindings/rng/apm,x-gene-rng.yaml b/Documentation/devicetree/bindings/rng/apm,x-gene-rng.yaml new file mode 100644 index 000000000000..02be143cc829 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/apm,x-gene-rng.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/apm,x-gene-rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: APM X-Gene SoC Random Number Generator + +maintainers: + - Khuong Dinh <khuong@os.amperecomputing.com> + +properties: + compatible: + const: apm,xgene-rng + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - interrupts + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + rng@10520000 { + compatible = "apm,xgene-rng"; + reg = <0x0 0x10520000 0x0 0x100>; + interrupts = <GIC_SPI 65 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rngpkaclk 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/rng/atmel,at91-trng.yaml b/Documentation/devicetree/bindings/rng/atmel,at91-trng.yaml new file mode 100644 index 000000000000..c1527637eb74 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/atmel,at91-trng.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/atmel,at91-trng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91 True Random Number Generator + +maintainers: + - Nicolas Ferre <nicolas.ferre@microchip.com> + - Alexandre Belloni <alexandre.belloni@bootlin.com> + - Ludovic Desroches <ludovic.desroches@microchip.com> + +properties: + compatible: + oneOf: + - enum: + - atmel,at91sam9g45-trng + - microchip,sam9x60-trng + - items: + - enum: + - microchip,sama7g5-trng + - const: atmel,at91sam9g45-trng + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - interrupts + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + rng@fffcc000 { + compatible = "atmel,at91sam9g45-trng"; + reg = <0xfffcc000 0x4000>; + interrupts = <6 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&trng_clk>; + }; diff --git a/Documentation/devicetree/bindings/rng/atmel-trng.txt b/Documentation/devicetree/bindings/rng/atmel-trng.txt deleted file mode 100644 index 3900ee4f3532..000000000000 --- a/Documentation/devicetree/bindings/rng/atmel-trng.txt +++ /dev/null @@ -1,16 +0,0 @@ -Atmel TRNG (True Random Number Generator) block - -Required properties: -- compatible : Should be "atmel,at91sam9g45-trng" or "microchip,sam9x60-trng" -- reg : Offset and length of the register set of this block -- interrupts : the interrupt number for the TRNG block -- clocks: should contain the TRNG clk source - -Example: - -trng@fffcc000 { - compatible = "atmel,at91sam9g45-trng"; - reg = <0xfffcc000 0x4000>; - interrupts = <6 IRQ_TYPE_LEVEL_HIGH 0>; - clocks = <&trng_clk>; -}; diff --git a/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt deleted file mode 100644 index 802523196ee5..000000000000 --- a/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt +++ /dev/null @@ -1,16 +0,0 @@ -HWRNG support for the iproc-rng200 driver - -Required properties: -- compatible : Must be one of: - "brcm,bcm2711-rng200" - "brcm,bcm7211-rng200" - "brcm,bcm7278-rng200" - "brcm,iproc-rng200" -- reg : base address and size of control register block - -Example: - -rng { - compatible = "brcm,iproc-rng200"; - reg = <0x18032000 0x28>; -}; diff --git a/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.yaml b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.yaml new file mode 100644 index 000000000000..a00e9bc8b609 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.yaml @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/rng/brcm,iproc-rng200.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: HWRNG support for the iproc-rng200 driver + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + enum: + - brcm,bcm2711-rng200 + - brcm,bcm7211-rng200 + - brcm,bcm7278-rng200 + - brcm,iproc-rng200 + + reg: + maxItems: 1 + +additionalProperties: false + +examples: + - | + rng@18032000 { + compatible = "brcm,iproc-rng200"; + reg = <0x18032000 0x28>; + }; diff --git a/Documentation/devicetree/bindings/rng/ks-sa-rng.txt b/Documentation/devicetree/bindings/rng/ks-sa-rng.txt deleted file mode 100644 index b7a65b487901..000000000000 --- a/Documentation/devicetree/bindings/rng/ks-sa-rng.txt +++ /dev/null @@ -1,21 +0,0 @@ -Keystone SoC Hardware Random Number Generator(HWRNG) Module - -On Keystone SoCs HWRNG module is a submodule of the Security Accelerator. - -- compatible: should be "ti,keystone-rng" -- ti,syscon-sa-cfg: phandle to syscon node of the SA configuration registers. - This registers are shared between hwrng and crypto drivers. -- clocks: phandle to the reference clocks for the subsystem -- clock-names: functional clock name. Should be set to "fck" -- reg: HWRNG module register space - -Example: -/* K2HK */ - -rng@24000 { - compatible = "ti,keystone-rng"; - ti,syscon-sa-cfg = <&sa_config>; - clocks = <&clksa>; - clock-names = "fck"; - reg = <0x24000 0x1000>; -}; diff --git a/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.txt b/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.txt deleted file mode 100644 index 65c04172fc8c..000000000000 --- a/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.txt +++ /dev/null @@ -1,12 +0,0 @@ -NPCM SoC Random Number Generator - -Required properties: -- compatible : "nuvoton,npcm750-rng" for the NPCM7XX BMC. -- reg : Specifies physical base address and size of the registers. - -Example: - -rng: rng@f000b000 { - compatible = "nuvoton,npcm750-rng"; - reg = <0xf000b000 0x8>; -}; diff --git a/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml b/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml new file mode 100644 index 000000000000..abd134c9d400 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/nuvoton,npcm-rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM SoC Random Number Generator + +maintainers: + - Avi Fishman <avifishman70@gmail.com> + - Tomer Maimon <tmaimon77@gmail.com> + - Tali Perry <tali.perry1@gmail.com> + - Patrick Venture <venture@google.com> + - Nancy Yuen <yuenn@google.com> + - Benjamin Fair <benjaminfair@google.com> + +properties: + compatible: + const: nuvoton,npcm750-rng + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + rng@f000b000 { + compatible = "nuvoton,npcm750-rng"; + reg = <0xf000b000 0x8>; + }; diff --git a/Documentation/devicetree/bindings/rng/omap3_rom_rng.txt b/Documentation/devicetree/bindings/rng/omap3_rom_rng.txt deleted file mode 100644 index f315c9723bd2..000000000000 --- a/Documentation/devicetree/bindings/rng/omap3_rom_rng.txt +++ /dev/null @@ -1,27 +0,0 @@ -OMAP ROM RNG driver binding - -Secure SoCs may provide RNG via secure ROM calls like Nokia N900 does. The -implementation can depend on the SoC secure ROM used. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "nokia,n900-rom-rng" - -- clocks: - Usage: required - Value type: <prop-encoded-array> - Definition: reference to the the RNG interface clock - -- clock-names: - Usage: required - Value type: <stringlist> - Definition: must be "ick" - -Example: - - rom_rng: rng { - compatible = "nokia,n900-rom-rng"; - clocks = <&rng_ick>; - clock-names = "ick"; - }; diff --git a/Documentation/devicetree/bindings/rng/st,rng.txt b/Documentation/devicetree/bindings/rng/st,rng.txt deleted file mode 100644 index 35734bc282e9..000000000000 --- a/Documentation/devicetree/bindings/rng/st,rng.txt +++ /dev/null @@ -1,15 +0,0 @@ -STMicroelectronics HW Random Number Generator ----------------------------------------------- - -Required parameters: -compatible : Should be "st,rng" -reg : Base address and size of IP's register map. -clocks : Phandle to device's clock (See: ../clocks/clock-bindings.txt) - -Example: - -rng@fee80000 { - compatible = "st,rng"; - reg = <0xfee80000 0x1000>; - clocks = <&clk_sysin>; -} diff --git a/Documentation/devicetree/bindings/rng/st,rng.yaml b/Documentation/devicetree/bindings/rng/st,rng.yaml new file mode 100644 index 000000000000..ff1211ef9046 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/st,rng.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/st,rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics Hardware Random Number Generator + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +properties: + compatible: + const: st,rng + + clocks: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - reg + +additionalProperties: false + +examples: + - | + rng@fee80000 { + compatible = "st,rng"; + reg = <0xfee80000 0x1000>; + clocks = <&clk_sysin>; + }; diff --git a/Documentation/devicetree/bindings/rng/ti,keystone-rng.yaml b/Documentation/devicetree/bindings/rng/ti,keystone-rng.yaml new file mode 100644 index 000000000000..e749818fc193 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/ti,keystone-rng.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/ti,keystone-rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Keystone SoC Hardware Random Number Generator + +maintainers: + - Nishanth Menon <nm@ti.com> + - Santosh Shilimkar <ssantosh@kernel.org> + +properties: + compatible: + const: ti,keystone-rng + + clocks: + maxItems: 1 + + clock-names: + items: + - const: fck + + reg: + maxItems: 1 + + ti,syscon-sa-cfg: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: | + Phandle to syscon node of the SA configuration registers. These + registers are shared between HWRNG and crypto drivers. + +required: + - compatible + - clocks + - clock-names + - reg + - ti,syscon-sa-cfg + +additionalProperties: false + +examples: + - | + rng@24000 { + compatible = "ti,keystone-rng"; + ti,syscon-sa-cfg = <&sa_config>; + clocks = <&clksa>; + clock-names = "fck"; + reg = <0x24000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/rng/ti,omap-rom-rng.yaml b/Documentation/devicetree/bindings/rng/ti,omap-rom-rng.yaml new file mode 100644 index 000000000000..9a58440b1ab1 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/ti,omap-rom-rng.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/ti,omap-rom-rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OMAP ROM Random Number Generator + +maintainers: + - Pali Rohár <pali@kernel.org> + - Tony Lindgren <tony@atomide.com> + +description: + Secure SoCs may provide RNG via secure ROM calls like Nokia N900 does. + The implementation can depend on the SoC secure ROM used. + +properties: + compatible: + const: nokia,n900-rom-rng + + clocks: + maxItems: 1 + + clock-names: + items: + - const: ick + +required: + - compatible + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + rng { + compatible = "nokia,n900-rom-rng"; + clocks = <&rng_ick>; + clock-names = "ick"; + }; diff --git a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt deleted file mode 100644 index fb4846160047..000000000000 --- a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt +++ /dev/null @@ -1,25 +0,0 @@ -HWRNG support for the timeriomem_rng driver - -Required properties: -- compatible : "timeriomem_rng" -- reg : base address to sample from -- period : wait time in microseconds to use between samples - -Optional properties: -- quality : estimated number of bits of true entropy per 1024 bits read from the - rng. Defaults to zero which causes the kernel's default quality to - be used instead. Note that the default quality is usually zero - which disables using this rng to automatically fill the kernel's - entropy pool. - -N.B. currently 'reg' must be at least four bytes wide and 32-bit aligned - -Example: - -hwrng@44 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "timeriomem_rng"; - reg = <0x44 0x04>; - period = <1000000>; -}; diff --git a/Documentation/devicetree/bindings/rng/timeriomem_rng.yaml b/Documentation/devicetree/bindings/rng/timeriomem_rng.yaml new file mode 100644 index 000000000000..84bf518a5549 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/timeriomem_rng.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/timeriomem_rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TimerIO Random Number Generator + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +properties: + compatible: + const: timeriomem_rng + + period: + $ref: /schemas/types.yaml#/definitions/uint32 + description: wait time in microseconds to use between samples + + quality: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + description: + Estimated number of bits of true entropy per 1024 bits read from the rng. + Defaults to zero which causes the kernel's default quality to be used + instead. Note that the default quality is usually zero which disables + using this rng to automatically fill the kernel's entropy pool. + + reg: + maxItems: 1 + description: + Base address to sample from. Currently 'reg' must be at least four bytes + wide and 32-bit aligned. + +required: + - compatible + - period + - reg + +additionalProperties: false + +examples: + - | + rng@44 { + compatible = "timeriomem_rng"; + reg = <0x44 0x04>; + period = <1000000>; + }; diff --git a/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt b/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt deleted file mode 100644 index d946f28502b3..000000000000 --- a/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt +++ /dev/null @@ -1,20 +0,0 @@ -Broadcom STB wake-up Timer - -The Broadcom STB wake-up timer provides a 27Mhz resolution timer, with the -ability to wake up the system from low-power suspend/standby modes. - -Required properties: -- compatible : should contain "brcm,brcmstb-waketimer" -- reg : the register start and length for the WKTMR block -- interrupts : The TIMER interrupt -- clocks : The phandle to the UPG fixed clock (27Mhz domain) - -Example: - -waketimer@f0411580 { - compatible = "brcm,brcmstb-waketimer"; - reg = <0xf0411580 0x14>; - interrupts = <0x3>; - interrupt-parent = <&aon_pm_l2_intc>; - clocks = <&upg_fixed>; -}; diff --git a/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.yaml b/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.yaml new file mode 100644 index 000000000000..9fe079917a98 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/brcm,brcmstb-waketimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom STB wake-up Timer + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +description: + The Broadcom STB wake-up timer provides a 27Mhz resolution timer, with the + ability to wake up the system from low-power suspend/standby modes. + +allOf: + - $ref: "rtc.yaml#" + +properties: + compatible: + const: brcm,brcmstb-waketimer + + reg: + maxItems: 1 + + interrupts: + description: the TIMER interrupt + maxItems: 1 + + clocks: + description: clock reference in the 27MHz domain + maxItems: 1 + +additionalProperties: false + +examples: + - | + rtc@f0411580 { + compatible = "brcm,brcmstb-waketimer"; + reg = <0xf0411580 0x14>; + interrupts = <0x3>; + interrupt-parent = <&aon_pm_l2_intc>; + clocks = <&upg_fixed>; + }; diff --git a/Documentation/devicetree/bindings/rtc/epson,rx8900.yaml b/Documentation/devicetree/bindings/rtc/epson,rx8900.yaml index 29fe39bb08ad..d12855e7ffd7 100644 --- a/Documentation/devicetree/bindings/rtc/epson,rx8900.yaml +++ b/Documentation/devicetree/bindings/rtc/epson,rx8900.yaml @@ -15,6 +15,7 @@ allOf: properties: compatible: enum: + - epson,rx8804 - epson,rx8900 - microcrystal,rv8803 diff --git a/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml index 4fba6dba16f3..6fa7d9fc2dc7 100644 --- a/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml @@ -19,7 +19,14 @@ properties: - qcom,pmk8350-rtc reg: - maxItems: 1 + minItems: 1 + maxItems: 2 + + reg-names: + minItems: 1 + items: + - const: rtc + - const: alarm interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml index 2359f541b770..764717ce1873 100644 --- a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml @@ -127,6 +127,7 @@ examples: st,syscfg = <&pwrcfg 0x00 0x100>; }; + - | #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/stm32mp1-clks.h> rtc@5c004000 { diff --git a/Documentation/devicetree/bindings/rtc/sunplus,sp7021-rtc.yaml b/Documentation/devicetree/bindings/rtc/sunplus,sp7021-rtc.yaml new file mode 100644 index 000000000000..fd1b3e71ff2c --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/sunplus,sp7021-rtc.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/sunplus,sp7021-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus SP7021 Real Time Clock controller + +maintainers: + - Vincent Shih <vincent.sunplus@gmail.com> + +properties: + compatible: + const: sunplus,sp7021-rtc + + reg: + maxItems: 1 + + reg-names: + items: + - const: rtc + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - reg-names + - clocks + - resets + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + rtc: serial@9c003a00 { + compatible = "sunplus,sp7021-rtc"; + reg = <0x9c003a00 0x80>; + reg-names = "rtc"; + clocks = <&clkc 0x12>; + resets = <&rstc 0x02>; + interrupt-parent = <&intc>; + interrupts = <163 IRQ_TYPE_EDGE_RISING>; + }; +... diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml index 7487aa6ef849..72e8868db3e0 100644 --- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml +++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml @@ -29,6 +29,7 @@ properties: - amlogic,meson8-uart - amlogic,meson8b-uart - amlogic,meson-gx-uart + - amlogic,meson-s4-uart - const: amlogic,meson-ao-uart - description: Everything-Else power domain UART controller enum: @@ -36,6 +37,7 @@ properties: - amlogic,meson8-uart - amlogic,meson8b-uart - amlogic,meson-gx-uart + - amlogic,meson-s4-uart reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index a90c971b4f1f..6e04e3848261 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -21,9 +21,15 @@ properties: - fsl,ls1028a-lpuart - fsl,imx7ulp-lpuart - fsl,imx8qm-lpuart + - fsl,imxrt1050-lpuart - items: - - const: fsl,imx8qxp-lpuart + - enum: + - fsl,imx8qxp-lpuart + - fsl,imx8ulp-lpuart - const: fsl,imx7ulp-lpuart + - items: + - const: fsl,imx8qm-lpuart + - const: fsl,imx8qxp-lpuart reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/serial/pl011.yaml b/Documentation/devicetree/bindings/serial/pl011.yaml index 5ea00f8a283d..d8aed84abcd3 100644 --- a/Documentation/devicetree/bindings/serial/pl011.yaml +++ b/Documentation/devicetree/bindings/serial/pl011.yaml @@ -91,6 +91,9 @@ properties: 3000ms. default: 3000 + resets: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/serial/renesas,sci.yaml b/Documentation/devicetree/bindings/serial/renesas,sci.yaml index 22ed2f0b1dc3..8dda4e10e09d 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,sci.yaml @@ -14,7 +14,15 @@ allOf: properties: compatible: - const: renesas,sci + oneOf: + - items: + - enum: + - renesas,r9a07g044-sci # RZ/G2{L,LC} + - renesas,r9a07g054-sci # RZ/V2L + - const: renesas,sci # generic SCI compatible UART + + - items: + - const: renesas,sci # generic SCI compatible UART reg: maxItems: 1 @@ -54,18 +62,46 @@ required: - clocks - clock-names +if: + properties: + compatible: + contains: + enum: + - renesas,r9a07g044-sci + - renesas,r9a07g054-sci +then: + properties: + resets: + maxItems: 1 + + power-domains: + maxItems: 1 + + required: + - resets + - power-domains + unevaluatedProperties: false examples: - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + aliases { serial0 = &sci0; }; - sci0: serial@ffff78 { - compatible = "renesas,sci"; - reg = <0xffff78 8>; - interrupts = <88 0>, <89 0>, <90 0>, <91 0>; - clocks = <&fclk>; + sci0: serial@1004d000 { + compatible = "renesas,r9a07g044-sci", "renesas,sci"; + reg = <0x1004d000 0x400>; + interrupts = <GIC_SPI 405 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 406 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 407 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 408 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "eri", "rxi", "txi", "tei"; + clocks = <&cpg CPG_MOD R9A07G044_SCI0_CLKP>; clock-names = "fck"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_SCI0_RST>; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,scif.yaml b/Documentation/devicetree/bindings/serial/renesas,scif.yaml index 6b8731f7f2fb..ba5d3e0acc63 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scif.yaml @@ -66,7 +66,19 @@ properties: - items: - enum: + - renesas,scif-r8a779f0 # R-Car S4-8 + - const: renesas,rcar-gen4-scif # R-Car Gen4 + - const: renesas,scif # generic SCIF compatible UART + + - items: + - enum: - renesas,scif-r9a07g044 # RZ/G2{L,LC} + - renesas,scif-r9a07g054 # RZ/V2L + + - items: + - enum: + - renesas,scif-r9a07g054 # RZ/V2L + - const: renesas,scif-r9a07g044 # RZ/G2{L,LC} fallback for RZ/V2L reg: maxItems: 1 @@ -153,6 +165,9 @@ if: enum: - renesas,rcar-gen2-scif - renesas,rcar-gen3-scif + - renesas,rcar-gen4-scif + - renesas,scif-r9a07g044 + - renesas,scif-r9a07g054 then: required: - resets diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml index 273f2d95a043..e72b6a3fae99 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml @@ -22,7 +22,7 @@ description: | [1] Documentation/devicetree/bindings/serial/samsung_uart.yaml [2] Documentation/devicetree/bindings/i2c/i2c-exynos5.txt - [3] Documentation/devicetree/bindings/spi/spi-samsung.txt + [3] Documentation/devicetree/bindings/spi/samsung,spi.yaml properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/ak4375.yaml b/Documentation/devicetree/bindings/sound/ak4375.yaml new file mode 100644 index 000000000000..f1d5074a024d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4375.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ak4375.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AK4375 DAC and headphones amplifier Device Tree Bindings + +maintainers: + - Vincent Knecht <vincent.knecht@mailoo.org> + +properties: + compatible: + const: asahi-kasei,ak4375 + + reg: + maxItems: 1 + + '#sound-dai-cells': + const: 0 + + avdd-supply: + description: regulator phandle for the AVDD power supply. + + tvdd-supply: + description: regulator phandle for the TVDD power supply. + + pdn-gpios: + description: optional GPIO to set the PDN pin. + +required: + - compatible + - reg + - '#sound-dai-cells' + - avdd-supply + - tvdd-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + headphones: audio-codec@10 { + compatible = "asahi-kasei,ak4375"; + reg = <0x10>; + avdd-supply = <®_headphones_avdd>; + tvdd-supply = <&pm8916_l6>; + pdn-gpios = <&msmgpio 114 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&headphones_pdn_default>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml b/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml index f50558ed914f..0705f91199a0 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml @@ -9,6 +9,9 @@ title: Amlogic AIU audio output controller maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: name-prefix.yaml# + properties: $nodename: pattern: "^audio-controller@.*" @@ -65,6 +68,8 @@ properties: resets: maxItems: 1 + sound-name-prefix: true + required: - "#sound-dai-cells" - compatible diff --git a/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml b/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml index 3c3891d17238..77469a45bb7a 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml @@ -9,6 +9,9 @@ title: Amlogic G12a Internal DAC Control Glue maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: name-prefix.yaml# + properties: $nodename: pattern: "^audio-controller@.*" @@ -31,6 +34,8 @@ properties: resets: maxItems: 1 + sound-name-prefix: true + required: - "#sound-dai-cells" - compatible diff --git a/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml b/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml index db7b04da0b39..580a3d040abc 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml @@ -9,6 +9,9 @@ title: Amlogic T9015 Internal Audio DAC maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: name-prefix.yaml# + properties: $nodename: pattern: "^audio-controller@.*" @@ -38,6 +41,8 @@ properties: description: Analogue power supply. + sound-name-prefix: true + required: - "#sound-dai-cells" - compatible diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index 43e7f86e3b23..476dcb49ece6 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -42,10 +42,15 @@ patternProperties: $ref: /schemas/types.yaml#/definitions/flag frame-master: description: Indicates dai-link frame master. - $ref: /schemas/types.yaml#/definitions/phandle + oneOf: + - $ref: /schemas/types.yaml#/definitions/flag + - $ref: /schemas/types.yaml#/definitions/phandle bitclock-master: description: Indicates dai-link bit clock master - $ref: /schemas/types.yaml#/definitions/phandle + oneOf: + - $ref: /schemas/types.yaml#/definitions/flag + - $ref: /schemas/types.yaml#/definitions/phandle + dai-format: description: audio format. items: diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml new file mode 100644 index 000000000000..31800f70e9d9 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml @@ -0,0 +1,225 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/cirrus,cs42l42.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus Logic CS42L42 audio CODEC + +maintainers: + - patches@opensource.cirrus.com + +description: + The CS42L42 is a low-power audio codec designed for portable applications. + It provides a high-dynamic range, stereo DAC for audio playback and a mono + high-dynamic-range ADC for audio capture. There is an integrated headset + detection block. + +properties: + compatible: + enum: + - cirrus,cs42l42 + + reg: + description: + The I2C address of the CS42L42. + maxItems: 1 + + VP-supply: + description: + VP power supply. + + VCP-supply: + description: + Charge pump power supply. + + VD_FILT-supply: + description: + FILT+ power supply. + + VL-supply: + description: + Logic power supply. + + VA-supply: + description: + Analog power supply. + + reset-gpios: + description: + This pin will be asserted and then deasserted to reset the + CS42L42 before communication starts. + maxItems: 1 + + interrupts: + description: + Interrupt for CS42L42 IRQ line. + maxItems: 1 + + cirrus,ts-inv: + description: | + Sets the behaviour of the jack plug detect switch. + + 0 - (Default) Shorted to tip when unplugged, open when plugged. + This is "inverted tip sense (ITS)" in the datasheet. + + 1 - Open when unplugged, shorted to tip when plugged. + This is "normal tip sense (TS)" in the datasheet. + + The CS42L42_TS_INV_* defines are available for this. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1 + + cirrus,ts-dbnc-rise: + description: | + Debounce the rising edge of TIP_SENSE_PLUG. With no + debounce, the tip sense pin might be noisy on a plug event. + + 0 - 0ms + 1 - 125ms + 2 - 250ms + 3 - 500ms + 4 - 750ms + 5 - 1s (Default) + 6 - 1.25s + 7 - 1.5s + + The CS42L42_TS_DBNCE_* defines are available for this. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 7 + + cirrus,ts-dbnc-fall: + description: | + Debounce the falling edge of TIP_SENSE_UNPLUG. With no + debounce, the tip sense pin might be noisy on an unplug event. + + 0 - 0ms + 1 - 125ms + 2 - 250ms + 3 - 500ms + 4 - 750ms + 5 - 1s (Default) + 6 - 1.25s + 7 - 1.5s + + The CS42L42_TS_DBNCE_* defines are available for this. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 7 + + cirrus,btn-det-init-dbnce: + description: | + This sets how long to wait after enabling button detection + interrupts before servicing button interrupts, to allow the + HS bias time to settle. Value is in milliseconds. + There may be erroneous button interrupts if this debounce time + is too short. + + 0ms - 200ms, + Default = 100ms + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 200 + + cirrus,btn-det-event-dbnce: + description: | + This sets how long to wait after receiving a button press + interrupt before processing it. Allows time for the button + press to make a clean connection with the bias resistors. + Value is in milliseconds. + + 0ms - 20ms, + Default = 10ms + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 20 + + cirrus,bias-lvls: + description: | + For a level-detect headset button scheme, each button will bias + the mic pin to a certain voltage. To determine which button was + pressed, the voltage is compared to sequential, decreasing + voltages, until the compared voltage < bias voltage. + For different hardware setups, a designer might want to tweak this. + This is an array of descending values for the comparator voltage, + given as percent of the HSBIAS voltage. + + Array of 4 values, each 0-63 + < x1 x2 x3 x4 > + Default = < 15 8 4 1 > + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 4 + maxItems: 4 + items: + minimum: 0 + maximum: 63 + + cirrus,hs-bias-ramp-rate: + description: | + If present this sets the rate that the HS bias should rise and fall. + The actual rise and fall times depend on external hardware (the + datasheet gives several rise and fall time examples). + + 0 - Fast rise time; slow, load-dependent fall time + 1 - Fast + 2 - Slow (default) + 3 - Slowest + + The CS42L42_HSBIAS_RAMP_* defines are available for this. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 3 + + cirrus,hs-bias-sense-disable: + description: | + If present the HSBIAS sense is disabled. Configures HSBIAS output + current sense through the external 2.21-k resistor. HSBIAS_SENSE + is a hardware feature to reduce the potential pop noise when the + headset plug is removed slowly. But on some platforms ESD voltage + will affect it causing plug detection to fail, especially with CTIA + headset type. For different hardware setups, a designer might want + to tweak default behavior. + type: boolean + +required: + - compatible + - reg + - VP-supply + - VCP-supply + - VD_FILT-supply + - VL-supply + - VA-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/sound/cs42l42.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cs42l42: cs42l42@48 { + compatible = "cirrus,cs42l42"; + reg = <0x48>; + VA-supply = <&dummy_vreg>; + VP-supply = <&dummy_vreg>; + VCP-supply = <&dummy_vreg>; + VD_FILT-supply = <&dummy_vreg>; + VL-supply = <&dummy_vreg>; + + reset-gpios = <&axi_gpio_0 1 0>; + interrupt-parent = <&gpio0>; + interrupts = <55 8>; + + cirrus,ts-inv = <CS42L42_TS_INV_DIS>; + cirrus,ts-dbnc-rise = <CS42L42_TS_DBNCE_1000>; + cirrus,ts-dbnc-fall = <CS42L42_TS_DBNCE_0>; + cirrus,btn-det-init-dbnce = <100>; + cirrus,btn-det-event-dbnce = <10>; + cirrus,bias-lvls = <0x0F 0x08 0x04 0x01>; + cirrus,hs-bias-ramp-rate = <CS42L42_HSBIAS_RAMP_SLOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/cs42l42.txt b/Documentation/devicetree/bindings/sound/cs42l42.txt deleted file mode 100644 index 3b7705623980..000000000000 --- a/Documentation/devicetree/bindings/sound/cs42l42.txt +++ /dev/null @@ -1,115 +0,0 @@ -CS42L42 audio CODEC - -Required properties: - - - compatible : "cirrus,cs42l42" - - - reg : the I2C address of the device for I2C. - - - VP-supply, VCP-supply, VD_FILT-supply, VL-supply, VA-supply : - power supplies for the device, as covered in - Documentation/devicetree/bindings/regulator/regulator.txt. - -Optional properties: - - - reset-gpios : a GPIO spec for the reset pin. If specified, it will be - deasserted before communication to the codec starts. - - - interrupts : IRQ line info CS42L42. - (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - for further information relating to interrupt properties) - - - cirrus,ts-inv : Boolean property. Sets the behaviour of the jack plug - detect switch. - - 0 = (Default) Shorted to tip when unplugged, open when plugged. - This is "inverted tip sense (ITS)" in the datasheet. - - 1 = Open when unplugged, shorted to tip when plugged. - This is "normal tip sense (TS)" in the datasheet. - - - cirrus,ts-dbnc-rise : Debounce the rising edge of TIP_SENSE_PLUG. With no - debounce, the tip sense pin might be noisy on a plug event. - - 0 - 0ms, - 1 - 125ms, - 2 - 250ms, - 3 - 500ms, - 4 - 750ms, - 5 - (Default) 1s, - 6 - 1.25s, - 7 - 1.5s, - - - cirrus,ts-dbnc-fall : Debounce the falling edge of TIP_SENSE_UNPLUG. - With no debounce, the tip sense pin might be noisy on an unplug event. - - 0 - 0ms, - 1 - 125ms, - 2 - 250ms, - 3 - 500ms, - 4 - 750ms, - 5 - (Default) 1s, - 6 - 1.25s, - 7 - 1.5s, - - - cirrus,btn-det-init-dbnce : This sets how long the driver sleeps after - enabling button detection interrupts. After auto-detection and before - servicing button interrupts, the HS bias needs time to settle. If you - don't wait, there is possibility for erroneous button interrupt. - - 0ms - 200ms, - Default = 100ms - - - cirrus,btn-det-event-dbnce : This sets how long the driver delays after - receiving a button press interrupt. With level detect interrupts, you want - to wait a small amount of time to make sure the button press is making a - clean connection with the bias resistors. - - 0ms - 20ms, - Default = 10ms - - - cirrus,bias-lvls : For a level-detect headset button scheme, each button - will bias the mic pin to a certain voltage. To determine which button was - pressed, the driver will compare this biased voltage to sequential, - decreasing voltages and will stop when a comparator is tripped, - indicating a comparator voltage < bias voltage. This value represents a - percentage of the internally generated HS bias voltage. For different - hardware setups, a designer might want to tweak this. This is an array of - descending values for the comparator voltage. - - Array of 4 values - Each 0-63 - < x1 x2 x3 x4 > - Default = < 15 8 4 1> - - - cirrus,hs-bias-sense-disable: This is boolean property. If present the - HSBIAS sense is disabled. Configures HSBIAS output current sense through - the external 2.21-k resistor. HSBIAS_SENSE is hardware feature to reduce - the potential pop noise during the headset plug out slowly. But on some - platforms ESD voltage will affect it causing test to fail, especially - with CTIA headset type. For different hardware setups, a designer might - want to tweak default behavior. - -Example: - -cs42l42: cs42l42@48 { - compatible = "cirrus,cs42l42"; - reg = <0x48>; - VA-supply = <&dummy_vreg>; - VP-supply = <&dummy_vreg>; - VCP-supply = <&dummy_vreg>; - VD_FILT-supply = <&dummy_vreg>; - VL-supply = <&dummy_vreg>; - - reset-gpios = <&axi_gpio_0 1 0>; - interrupt-parent = <&gpio0>; - interrupts = <55 8> - - cirrus,ts-inv = <0x00>; - cirrus,ts-dbnc-rise = <0x05>; - cirrus,ts-dbnc-fall = <0x00>; - cirrus,btn-det-init-dbnce = <100>; - cirrus,btn-det-event-dbnce = <10>; - cirrus,bias-lvls = <0x0F 0x08 0x04 0x01>; - cirrus,hs-bias-ramp-rate = <0x02>; -}; diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml index 77adbebed824..c3e9f3485449 100644 --- a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml +++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml @@ -8,6 +8,7 @@ title: Audio codec controlled by ChromeOS EC maintainers: - Cheng-Yi Chiang <cychiang@chromium.org> + - Tzung-Bi Shih <tzungbi@google.com> description: | Google's ChromeOS EC codec is a digital mic codec provided by the diff --git a/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml b/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml index c6b070e1d014..a4f9257e313d 100644 --- a/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml +++ b/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml @@ -9,6 +9,9 @@ title: Dummy SPDIF Transmitter Device Tree Bindings maintainers: - Mark Brown <broonie@kernel.org> +allOf: + - $ref: name-prefix.yaml# + properties: compatible: const: linux,spdif-dit @@ -16,6 +19,8 @@ properties: "#sound-dai-cells": const: 0 + sound-name-prefix: true + required: - "#sound-dai-cells" - compatible diff --git a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml index dcf790b053d2..6d0975b33d15 100644 --- a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml +++ b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml @@ -19,6 +19,12 @@ properties: interrupts: maxItems: 1 + memory-region: + maxItems: 1 + description: | + Shared memory region for AFE memif. A "shared-dma-pool". + See ../reserved-memory/reserved-memory.txt for details. + mediatek,topckgen: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of the mediatek topckgen controller @@ -125,6 +131,7 @@ required: - power-domains - clocks - clock-names + - memory-region additionalProperties: false @@ -139,6 +146,7 @@ examples: interrupts = <GIC_SPI 822 IRQ_TYPE_LEVEL_HIGH 0>; mediatek,topckgen = <&topckgen>; power-domains = <&spm 7>; //MT8195_POWER_DOMAIN_AUDIO + memory-region = <&snd_dma_mem_reserved>; clocks = <&clk26m>, <&topckgen 163>, //CLK_TOP_APLL1 <&topckgen 166>, //CLK_TOP_APLL2 diff --git a/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1011-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1011-rt5682.yaml index d354c30d3377..cf6ad7933e23 100644 --- a/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1011-rt5682.yaml +++ b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1011-rt5682.yaml @@ -16,6 +16,10 @@ properties: compatible: const: mediatek,mt8195_mt6359_rt1011_rt5682 + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + mediatek,platform: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of MT8195 ASoC platform. diff --git a/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml index 20bc0ffd0e34..8f177e02ad35 100644 --- a/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml +++ b/Documentation/devicetree/bindings/sound/mt8195-mt6359-rt1019-rt5682.yaml @@ -16,6 +16,10 @@ properties: compatible: const: mediatek,mt8195_mt6359_rt1019_rt5682 + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + mediatek,platform: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of MT8195 ASoC platform. @@ -28,6 +32,16 @@ properties: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of MT8195 HDMI codec node. + mediatek,adsp: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of MT8195 ADSP platform. + + mediatek,dai-link: + $ref: /schemas/types.yaml#/definitions/string-array + description: + A list of the desired dai-links in the sound card. Each entry is a + name defined in the machine driver. + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.txt deleted file mode 100644 index 57f40f93453e..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.txt +++ /dev/null @@ -1,48 +0,0 @@ -NVIDIA Tegra audio complex - -Required properties: -- compatible : "nvidia,tegra-audio-alc5632" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the ALC5632's pins as documented in the binding for the device - and: - - * Headset Stereophone - * Int Spk - * Headset Mic - * Digital Mic - -- nvidia,i2s-controller : The phandle of the Tegra I2S controller -- nvidia,audio-codec : The phandle of the ALC5632 audio codec - -Example: - -sound { - compatible = "nvidia,tegra-audio-alc5632-paz00", - "nvidia,tegra-audio-alc5632"; - - nvidia,model = "Compal PAZ00"; - - nvidia,audio-routing = - "Int Spk", "SPK_OUTP", - "Int Spk", "SPK_OUTN", - "Headset Mic","MICBIAS1", - "MIC1_N", "Headset Mic", - "MIC1_P", "Headset Mic", - "Headset Stereophone", "HP_OUT_R", - "Headset Stereophone", "HP_OUT_L"; - - nvidia,i2s-controller = <&tegra_i2s1>; - nvidia,audio-codec = <&alc5632>; - - clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml new file mode 100644 index 000000000000..7ef774910e5c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-alc5632.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with ALC5632 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-alc5632(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-alc5632 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headset Stereophone" + - "Int Spk" + - "Headset Mic" + - "Digital Mic" + + # CODEC Pins + - SPKOUT + - SPKOUTN + - MICBIAS1 + - MIC1 + - HPR + - HPL + - DMICDAT + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-alc5632-paz00", + "nvidia,tegra-audio-alc5632"; + + nvidia,model = "Compal PAZ00"; + + nvidia,audio-routing = "Int Spk", "SPKOUT", + "Int Spk", "SPKOUTN", + "Headset Mic", "MICBIAS1", + "MIC1", "Headset Mic", + "Headset Stereophone", "HPR", + "Headset Stereophone", "HPL", + "DMICDAT", "Digital Mic"; + + nvidia,i2s-controller = <&i2s>; + nvidia,audio-codec = <&codec>; + + clocks = <&clk 112>, <&clk 113>, <&clk 93>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml new file mode 100644 index 000000000000..82801b4f46dd --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/sound/nvidia,tegra-audio-common.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Common properties for NVIDIA Tegra audio complexes + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +properties: + clocks: + items: + - description: PLL A clock + - description: PLL A OUT0 clock + - description: The Tegra cdev1/extern1 clock, which feeds the card's mclk + + clock-names: + items: + - const: pll_a + - const: pll_a_out0 + - const: mclk + + nvidia,model: + $ref: /schemas/types.yaml#/definitions/string + description: The user-visible name of this sound complex. + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + + nvidia,ac97-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the AC97 controller + + nvidia,i2s-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the Tegra I2S controller + + nvidia,audio-codec: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of audio codec + + nvidia,spkr-en-gpios: + maxItems: 1 + description: The GPIO that enables the speakers + + nvidia,hp-mute-gpios: + maxItems: 1 + description: The GPIO that mutes the headphones + + nvidia,hp-det-gpios: + maxItems: 1 + description: The GPIO that detect headphones are plugged in + + nvidia,mic-det-gpios: + maxItems: 1 + description: The GPIO that detect microphone is plugged in + + nvidia,ear-sel-gpios: + maxItems: 1 + description: The GPIO that switch between the microphones + + nvidia,int-mic-en-gpios: + maxItems: 1 + description: The GPIO that enables the internal microphone + + nvidia,ext-mic-en-gpios: + maxItems: 1 + description: The GPIO that enables the external microphone + + nvidia,headset: + type: boolean + description: The Mic Jack represents state of the headset microphone pin + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml index 5bdd30a8a404..b4bee466d67a 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml @@ -44,6 +44,16 @@ properties: minItems: 1 maxItems: 3 + interconnects: + items: + - description: APE read memory client + - description: APE write memory client + + interconnect-names: + items: + - const: dma-mem # read + - const: write + iommus: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt deleted file mode 100644 index c3495beba358..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt +++ /dev/null @@ -1,53 +0,0 @@ -NVIDIA Tegra audio complex, with MAX98090 CODEC - -Required properties: -- compatible : "nvidia,tegra-audio-max98090" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the MAX98090's pins (as documented in its binding), and the jacks - on the board: - - * Headphones - * Speakers - * Mic Jack - * Int Mic - -- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's - connected to the CODEC. -- nvidia,audio-codec : The phandle of the MAX98090 audio codec. - -Optional properties: -- nvidia,hp-det-gpios : The GPIO that detect headphones are plugged in -- nvidia,mic-det-gpios : The GPIO that detect microphones are plugged in - -Example: - -sound { - compatible = "nvidia,tegra-audio-max98090-venice2", - "nvidia,tegra-audio-max98090"; - nvidia,model = "NVIDIA Tegra Venice2"; - - nvidia,audio-routing = - "Headphones", "HPR", - "Headphones", "HPL", - "Speakers", "SPKR", - "Speakers", "SPKL", - "Mic Jack", "MICBIAS", - "IN34", "Mic Jack"; - - nvidia,i2s-controller = <&tegra_i2s1>; - nvidia,audio-codec = <&acodec>; - - clocks = <&tegra_car TEGRA124_CLK_PLL_A>, - <&tegra_car TEGRA124_CLK_PLL_A_OUT0>, - <&tegra_car TEGRA124_CLK_EXTERN1>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml new file mode 100644 index 000000000000..ccc2ee77ca30 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-max98090.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with MAX98090 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + oneOf: + - items: + - pattern: '^[a-z0-9]+,tegra-audio-max98090(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-max98090 + - items: + - enum: + - nvidia,tegra-audio-max98090-nyan-big + - nvidia,tegra-audio-max98090-nyan-blaze + - const: nvidia,tegra-audio-max98090-nyan + - const: nvidia,tegra-audio-max98090 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphones" + - "Speakers" + - "Mic Jack" + - "Int Mic" + + # CODEC Pins + - MIC1 + - MIC2 + - DMICL + - DMICR + - IN1 + - IN2 + - IN3 + - IN4 + - IN5 + - IN6 + - IN12 + - IN34 + - IN56 + - HPL + - HPR + - SPKL + - SPKR + - RCVL + - RCVR + - MICBIAS + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra124-car.h> + + sound { + compatible = "nvidia,tegra-audio-max98090-venice2", + "nvidia,tegra-audio-max98090"; + nvidia,model = "NVIDIA Tegra Venice2"; + + nvidia,audio-routing = + "Headphones", "HPR", + "Headphones", "HPL", + "Speakers", "SPKR", + "Speakers", "SPKL", + "Mic Jack", "MICBIAS", + "IN34", "Mic Jack"; + + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&acodec>; + + clocks = <&tegra_car TEGRA124_CLK_PLL_A>, + <&tegra_car TEGRA124_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA124_CLK_EXTERN1>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.txt deleted file mode 100644 index 7788808dcd0b..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.txt +++ /dev/null @@ -1,52 +0,0 @@ -NVIDIA Tegra audio complex, with RT5640 CODEC - -Required properties: -- compatible : "nvidia,tegra-audio-rt5640" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the RT5640's pins (as documented in its binding), and the jacks - on the board: - - * Headphones - * Speakers - * Mic Jack - -- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's - connected to the CODEC. -- nvidia,audio-codec : The phandle of the RT5640 audio codec. This binding - assumes that AIF1 on the CODEC is connected to Tegra. - -Optional properties: -- nvidia,hp-det-gpios : The GPIO that detects headphones are plugged in - -Example: - -sound { - compatible = "nvidia,tegra-audio-rt5640-dalmore", - "nvidia,tegra-audio-rt5640"; - nvidia,model = "NVIDIA Tegra Dalmore"; - - nvidia,audio-routing = - "Headphones", "HPOR", - "Headphones", "HPOL", - "Speakers", "SPORP", - "Speakers", "SPORN", - "Speakers", "SPOLP", - "Speakers", "SPOLN"; - - nvidia,i2s-controller = <&tegra_i2s1>; - nvidia,audio-codec = <&rt5640>; - - nvidia,hp-det-gpios = <&gpio 143 0>; /* GPIO PR7 */ - - clocks = <&tegra_car 216>, <&tegra_car 217>, <&tegra_car 120>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml new file mode 100644 index 000000000000..e768fb0e9a59 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-rt5640.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with RT5639 or RT5640 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-rt56(39|40)(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-rt5640 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphones" + - "Speakers" + - "Mic Jack" + + # CODEC Pins + - DMIC1 + - DMIC2 + - MICBIAS1 + - IN1P + - IN1R + - IN2P + - IN2R + - HPOL + - HPOR + - LOUTL + - LOUTR + - MONOP + - MONON + - SPOLP + - SPOLN + - SPORP + - SPORN + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-rt5640-dalmore", + "nvidia,tegra-audio-rt5640"; + nvidia,model = "NVIDIA Tegra Dalmore"; + + nvidia,audio-routing = + "Headphones", "HPOR", + "Headphones", "HPOL", + "Speakers", "SPORP", + "Speakers", "SPORN", + "Speakers", "SPOLP", + "Speakers", "SPOLN"; + + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&rt5640>; + + nvidia,hp-det-gpios = <&gpio 143 0>; + + clocks = <&clk 216>, <&clk 217>, <&clk 120>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; + diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt deleted file mode 100644 index a4589cda214e..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt +++ /dev/null @@ -1,67 +0,0 @@ -NVIDIA Tegra audio complex, with RT5677 CODEC - -Required properties: -- compatible : "nvidia,tegra-audio-rt5677" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the RT5677's pins (as documented in its binding), and the jacks - on the board: - - * Headphone - * Speaker - * Headset Mic - * Internal Mic 1 - * Internal Mic 2 - -- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's - connected to the CODEC. -- nvidia,audio-codec : The phandle of the RT5677 audio codec. This binding - assumes that AIF1 on the CODEC is connected to Tegra. - -Optional properties: -- nvidia,hp-det-gpios : The GPIO that detects headphones are plugged in -- nvidia,hp-en-gpios : The GPIO that enables headphone amplifier -- nvidia,mic-present-gpios: The GPIO that mic jack is plugged in -- nvidia,dmic-clk-en-gpios : The GPIO that gates DMIC clock signal - -Example: - -sound { - compatible = "nvidia,tegra-audio-rt5677-ryu", - "nvidia,tegra-audio-rt5677"; - nvidia,model = "NVIDIA Tegra Ryu"; - - nvidia,audio-routing = - "Headphone", "LOUT2", - "Headphone", "LOUT1", - "Headset Mic", "MICBIAS1", - "IN1P", "Headset Mic", - "IN1N", "Headset Mic", - "DMIC L1", "Internal Mic 1", - "DMIC R1", "Internal Mic 1", - "DMIC L2", "Internal Mic 2", - "DMIC R2", "Internal Mic 2", - "Speaker", "PDM1L", - "Speaker", "PDM1R"; - - nvidia,i2s-controller = <&tegra_i2s1>; - nvidia,audio-codec = <&rt5677>; - - nvidia,hp-det-gpios = <&gpio TEGRA_GPIO(R, 7) GPIO_ACTIVE_HIGH>; - nvidia,mic-present-gpios = <&gpio TEGRA_GPIO(O, 5) GPIO_ACTIVE_LOW>; - nvidia,hp-en-gpios = <&rt5677 1 GPIO_ACTIVE_HIGH>; - nvidia,dmic-clk-en-gpios = <&rt5677 2 GPIO_ACTIVE_HIGH>; - - clocks = <&tegra_car TEGRA124_CLK_PLL_A>, - <&tegra_car TEGRA124_CLK_PLL_A_OUT0>, - <&tegra_car TEGRA124_CLK_EXTERN1>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml new file mode 100644 index 000000000000..a49997d6028b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-rt5677.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with RT5677 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-rt5677(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-rt5677 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphone" + - "Speaker" + - "Headset Mic" + - "Internal Mic 1" + - "Internal Mic 2" + + # CODEC Pins + - IN1P + - IN1N + - IN2P + - IN2N + - MICBIAS1 + - DMIC1 + - DMIC2 + - DMIC3 + - DMIC4 + - "DMIC L1" + - "DMIC L2" + - "DMIC L3" + - "DMIC L4" + - "DMIC R1" + - "DMIC R2" + - "DMIC R3" + - "DMIC R4" + - LOUT1 + - LOUT2 + - LOUT3 + - PDM1L + - PDM1R + - PDM2L + - PDM2R + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-rt5677-ryu", + "nvidia,tegra-audio-rt5677"; + nvidia,model = "NVIDIA Tegra Ryu"; + + nvidia,audio-routing = + "Headphone", "LOUT2", + "Headphone", "LOUT1", + "Headset Mic", "MICBIAS1", + "IN1P", "Headset Mic", + "IN1N", "Headset Mic", + "DMIC L1", "Internal Mic 1", + "DMIC R1", "Internal Mic 1", + "DMIC L2", "Internal Mic 2", + "DMIC R2", "Internal Mic 2", + "Speaker", "PDM1L", + "Speaker", "PDM1R"; + + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&rt5677>; + + nvidia,hp-det-gpios = <&gpio 143 0>; + + clocks = <&clk 216>, + <&clk 217>, + <&clk 121>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt deleted file mode 100644 index 5da7da4ea07a..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt +++ /dev/null @@ -1,42 +0,0 @@ -NVIDIA Tegra audio complex, with SGTL5000 CODEC - -Required properties: -- compatible : "nvidia,tegra-audio-sgtl5000" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the SGTL5000's pins (as documented in its binding), and the jacks - on the board: - - * Headphone Jack - * Line In Jack - * Mic Jack - -- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's - connected to the CODEC. -- nvidia,audio-codec : The phandle of the SGTL5000 audio codec. - -Example: - -sound { - compatible = "toradex,tegra-audio-sgtl5000-apalis_t30", - "nvidia,tegra-audio-sgtl5000"; - nvidia,model = "Toradex Apalis T30"; - nvidia,audio-routing = - "Headphone Jack", "HP_OUT", - "LINE_IN", "Line In Jack", - "MIC_IN", "Mic Jack"; - nvidia,i2s-controller = <&tegra_i2s2>; - nvidia,audio-codec = <&sgtl5000>; - clocks = <&tegra_car TEGRA30_CLK_PLL_A>, - <&tegra_car TEGRA30_CLK_PLL_A_OUT0>, - <&tegra_car TEGRA30_CLK_EXTERN1>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml new file mode 100644 index 000000000000..943e7c01741c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-sgtl5000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with SGTL5000 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-sgtl5000([-_][a-z0-9]+)+$' + - const: nvidia,tegra-audio-sgtl5000 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphone Jack" + - "Line In Jack" + - "Mic Jack" + + # CODEC Pins + - HP_OUT + - LINE_OUT + - LINE_IN + - MIC_IN + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra30-car.h> + + sound { + compatible = "toradex,tegra-audio-sgtl5000-apalis_t30", + "nvidia,tegra-audio-sgtl5000"; + nvidia,model = "Toradex Apalis T30 SGTL5000"; + nvidia,audio-routing = + "Headphone Jack", "HP_OUT", + "LINE_IN", "Line In Jack", + "MIC_IN", "Mic Jack"; + nvidia,i2s-controller = <&tegra_i2s2>; + nvidia,audio-codec = <&codec>; + clocks = <&tegra_car TEGRA30_CLK_PLL_A>, + <&tegra_car TEGRA30_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA30_CLK_EXTERN1>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.txt deleted file mode 100644 index ef1fe7358279..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.txt +++ /dev/null @@ -1,21 +0,0 @@ -NVIDIA Tegra audio complex for TrimSlice - -Required properties: -- compatible : "nvidia,tegra-audio-trimslice" -- clocks : Must contain an entry for each entry in clock-names. -- clock-names : Must include the following entries: - "pll_a" (The Tegra clock of that name), - "pll_a_out0" (The Tegra clock of that name), - "mclk" (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,i2s-controller : The phandle of the Tegra I2S1 controller -- nvidia,audio-codec : The phandle of the WM8903 audio codec - -Example: - -sound { - compatible = "nvidia,tegra-audio-trimslice"; - nvidia,i2s-controller = <&tegra_i2s1>; - nvidia,audio-codec = <&codec>; - clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.yaml new file mode 100644 index 000000000000..8c87cd166238 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-trimslice.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with TrimSlice CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + const: nvidia,tegra-audio-trimslice + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-trimslice"; + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&codec>; + clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.txt deleted file mode 100644 index 96f6a57dd6b4..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra audio complex - -Required properties: -- compatible : "nvidia,tegra-audio-wm8753" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the WM8753's pins as documented in the binding for the WM8753, - and the jacks on the board: - - * Headphone Jack - * Mic Jack - -- nvidia,i2s-controller : The phandle of the Tegra I2S1 controller -- nvidia,audio-codec : The phandle of the WM8753 audio codec -Example: - -sound { - compatible = "nvidia,tegra-audio-wm8753-whistler", - "nvidia,tegra-audio-wm8753" - nvidia,model = "tegra-wm8753-harmony"; - - nvidia,audio-routing = - "Headphone Jack", "LOUT1", - "Headphone Jack", "ROUT1"; - - nvidia,i2s-controller = <&i2s1>; - nvidia,audio-codec = <&wm8753>; - - clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; - diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml new file mode 100644 index 000000000000..a5b431d7d0c2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-wm8753.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with WM8753 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-wm8753(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-wm8753 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphone Jack" + - "Mic Jack" + + # CODEC Pins + - LOUT1 + - LOUT2 + - ROUT1 + - ROUT2 + - MONO1 + - MONO2 + - OUT3 + - OUT4 + - LINE1 + - LINE2 + - RXP + - RXN + - ACIN + - ACOP + - MIC1N + - MIC1 + - MIC2N + - MIC2 + - "Mic Bias" + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-wm8753-whistler", + "nvidia,tegra-audio-wm8753"; + nvidia,model = "tegra-wm8753-harmony"; + + nvidia,audio-routing = + "Headphone Jack", "LOUT1", + "Headphone Jack", "ROUT1"; + + nvidia,i2s-controller = <&i2s1>; + nvidia,audio-codec = <&wm8753>; + + clocks = <&clk 112>, <&clk 113>, <&clk 93>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.txt deleted file mode 100644 index bbd581a8c5bc..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.txt +++ /dev/null @@ -1,62 +0,0 @@ -NVIDIA Tegra audio complex - -Required properties: -- compatible : "nvidia,tegra-audio-wm8903" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the WM8903's pins (documented in the WM8903 binding document), - and the jacks on the board: - - * Headphone Jack - * Int Spk - * Mic Jack - * Int Mic - -- nvidia,i2s-controller : The phandle of the Tegra I2S1 controller -- nvidia,audio-codec : The phandle of the WM8903 audio codec - -Optional properties: -- nvidia,spkr-en-gpios : The GPIO that enables the speakers -- nvidia,hp-mute-gpios : The GPIO that mutes the headphones -- nvidia,hp-det-gpios : The GPIO that detect headphones are plugged in -- nvidia,int-mic-en-gpios : The GPIO that enables the internal microphone -- nvidia,ext-mic-en-gpios : The GPIO that enables the external microphone -- nvidia,headset : The Mic Jack represents state of the headset microphone pin - -Example: - -sound { - compatible = "nvidia,tegra-audio-wm8903-harmony", - "nvidia,tegra-audio-wm8903" - nvidia,model = "tegra-wm8903-harmony"; - - nvidia,audio-routing = - "Headphone Jack", "HPOUTR", - "Headphone Jack", "HPOUTL", - "Int Spk", "ROP", - "Int Spk", "RON", - "Int Spk", "LOP", - "Int Spk", "LON", - "Mic Jack", "MICBIAS", - "IN1L", "Mic Jack"; - - nvidia,i2s-controller = <&i2s1>; - nvidia,audio-codec = <&wm8903>; - - nvidia,spkr-en-gpios = <&codec 2 0>; - nvidia,hp-det-gpios = <&gpio 178 0>; /* gpio PW2 */ - nvidia,int-mic-en-gpios = <&gpio 184 0>; /*gpio PX0 */ - nvidia,ext-mic-en-gpios = <&gpio 185 0>; /* gpio PX1 */ - - clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; - diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml new file mode 100644 index 000000000000..1b836acab980 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-wm8903.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with WM8903 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + oneOf: + - items: + - pattern: '^[a-z0-9]+,tegra-audio-wm8903(-[a-z0-9]+)+$' + - const: nvidia,tegra-audio-wm8903 + - items: + - pattern: ad,tegra-audio-plutux + - const: nvidia,tegra-audio-wm8903 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphone Jack" + - "Int Spk" + - "Mic Jack" + - "Int Mic" + + # CODEC Pins + - IN1L + - IN1R + - IN2L + - IN2R + - IN3L + - IN3R + - DMICDAT + - HPOUTL + - HPOUTR + - LINEOUTL + - LINEOUTR + - LOP + - LON + - ROP + - RON + - MICBIAS + +required: + - nvidia,i2s-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-wm8903-harmony", + "nvidia,tegra-audio-wm8903"; + nvidia,model = "tegra-wm8903-harmony"; + + nvidia,audio-routing = + "Headphone Jack", "HPOUTR", + "Headphone Jack", "HPOUTL", + "Int Spk", "ROP", + "Int Spk", "RON", + "Int Spk", "LOP", + "Int Spk", "LON", + "Mic Jack", "MICBIAS", + "IN1L", "Mic Jack"; + + nvidia,i2s-controller = <&i2s1>; + nvidia,audio-codec = <&wm8903>; + + nvidia,spkr-en-gpios = <&codec 2 0>; + nvidia,hp-det-gpios = <&gpio 178 0>; + nvidia,int-mic-en-gpios = <&gpio 184 0>; + nvidia,ext-mic-en-gpios = <&gpio 185 0>; + + clocks = <&clk 112>, <&clk 113>, <&clk 93>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.txt deleted file mode 100644 index 436f6cd9d07c..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.txt +++ /dev/null @@ -1,60 +0,0 @@ -NVIDIA Tegra audio complex - -Required properties: -- compatible : "nvidia,tegra-audio-wm9712" -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - pll_a - - pll_a_out0 - - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) -- nvidia,model : The user-visible name of this sound complex. -- nvidia,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the WM9712's pins, and the jacks on the board: - - WM9712 pins: - - * MONOOUT - * HPOUTL - * HPOUTR - * LOUT2 - * ROUT2 - * OUT3 - * LINEINL - * LINEINR - * PHONE - * PCBEEP - * MIC1 - * MIC2 - * Mic Bias - - Board connectors: - - * Headphone - * LineIn - * Mic - -- nvidia,ac97-controller : The phandle of the Tegra AC97 controller - - -Example: - -sound { - compatible = "nvidia,tegra-audio-wm9712-colibri_t20", - "nvidia,tegra-audio-wm9712"; - nvidia,model = "Toradex Colibri T20"; - - nvidia,audio-routing = - "Headphone", "HPOUTL", - "Headphone", "HPOUTR", - "LineIn", "LINEINL", - "LineIn", "LINEINR", - "Mic", "MIC1"; - - nvidia,ac97-controller = <&ac97>; - - clocks = <&tegra_car 112>, <&tegra_car 113>, <&tegra_car 93>; - clock-names = "pll_a", "pll_a_out0", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml new file mode 100644 index 000000000000..a1448283344b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-wm9712.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra audio complex with WM9712 CODEC + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +allOf: + - $ref: nvidia,tegra-audio-common.yaml# + +properties: + compatible: + items: + - pattern: '^[a-z0-9]+,tegra-audio-wm9712([-_][a-z0-9]+)+$' + - const: nvidia,tegra-audio-wm9712 + + nvidia,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the pins (documented in the binding document), + and the jacks on the board. + minItems: 2 + items: + enum: + # Board Connectors + - "Headphone" + - "LineIn" + - "Mic" + + # CODEC Pins + - MONOOUT + - HPOUTL + - HPOUTR + - LOUT2 + - ROUT2 + - OUT3 + - LINEINL + - LINEINR + - PHONE + - PCBEEP + - MIC1 + - MIC2 + - "Mic Bias" + +required: + - nvidia,ac97-controller + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "nvidia,tegra-audio-wm9712-colibri_t20", + "nvidia,tegra-audio-wm9712"; + nvidia,model = "Toradex Colibri T20"; + + nvidia,audio-routing = + "Headphone", "HPOUTL", + "Headphone", "HPOUTR", + "LineIn", "LINEINL", + "LineIn", "LINEINR", + "Mic", "MIC1"; + + nvidia,ac97-controller = <&ac97>; + + clocks = <&clk 112>, <&clk 113>, <&clk 93>; + clock-names = "pll_a", "pll_a_out0", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.txt deleted file mode 100644 index dc30c6bfbe95..000000000000 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.txt +++ /dev/null @@ -1,30 +0,0 @@ -NVIDIA Tegra 20 I2S controller - -Required properties: -- compatible : "nvidia,tegra20-i2s" -- reg : Should contain I2S registers location and length -- interrupts : Should contain I2S interrupt -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - i2s -- dmas : Must contain an entry for each entry in clock-names. - See ../dma/dma.txt for details. -- dma-names : Must include the following entries: - - rx - - tx -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. - -Example: - -i2s@70002800 { - compatible = "nvidia,tegra20-i2s"; - reg = <0x70002800 0x200>; - interrupts = < 45 >; - clocks = <&tegra_car 11>; - resets = <&tegra_car 11>; - reset-names = "i2s"; - dmas = <&apbdma 21>, <&apbdma 21>; - dma-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.yaml new file mode 100644 index 000000000000..68ae124eaf80 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra20-i2s.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 I2S Controller + +description: | + The I2S Controller streams synchronous serial audio data between system + memory and an external audio device. The controller supports the I2S Left + Justified Mode, Right Justified Mode, and DSP mode formats. + +maintainers: + - Thierry Reding <treding@nvidia.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra20-i2s + + reg: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + const: i2s + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + + dmas: + minItems: 2 + + dma-names: + items: + - const: rx + - const: tx + + nvidia,fixed-parent-rate: + description: | + Specifies whether board prefers parent clock to stay at a fixed rate. + This allows multiple Tegra20 audio components work simultaneously by + limiting number of supportable audio rates. + type: boolean + +required: + - compatible + - reg + - resets + - reset-names + - interrupts + - clocks + - dmas + - dma-names + +additionalProperties: false + +examples: + - | + i2s@70002800 { + compatible = "nvidia,tegra20-i2s"; + reg = <0x70002800 0x200>; + interrupts = <45>; + clocks = <&tegra_car 11>; + resets = <&tegra_car 11>; + reset-names = "i2s"; + dmas = <&apbdma 21>, <&apbdma 21>; + dma-names = "rx", "tx"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml new file mode 100644 index 000000000000..60a368a132b8 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra20-spdif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 S/PDIF Controller + +description: | + The S/PDIF controller supports both input and output in serial audio + digital interface format. The input controller can digitally recover + a clock from the received stream. The S/PDIF controller is also used + to generate the embedded audio for HDMI output channel. + +maintainers: + - Thierry Reding <treding@nvidia.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra20-spdif + + reg: + maxItems: 1 + + resets: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + + clock-names: + items: + - const: out + - const: in + + dmas: + minItems: 2 + + dma-names: + items: + - const: rx + - const: tx + + "#sound-dai-cells": + const: 0 + + nvidia,fixed-parent-rate: + description: | + Specifies whether board prefers parent clock to stay at a fixed rate. + This allows multiple Tegra20 audio components work simultaneously by + limiting number of supportable audio rates. + type: boolean + +required: + - compatible + - reg + - resets + - interrupts + - clocks + - clock-names + - dmas + - dma-names + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + spdif@70002400 { + compatible = "nvidia,tegra20-spdif"; + reg = <0x70002400 0x200>; + interrupts = <77>; + clocks = <&clk 99>, <&clk 98>; + clock-names = "out", "in"; + resets = <&rst 10>; + dmas = <&apbdma 3>, <&apbdma 3>; + dma-names = "rx", "tx"; + #sound-dai-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.yaml index b55775e21de6..2c913aa44fee 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.yaml @@ -50,9 +50,11 @@ properties: - const: hda2codec_2x resets: + minItems: 2 maxItems: 3 reset-names: + minItems: 2 items: - const: hda - const: hda2hdmi diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml index 7667471be1e4..b9b1dba40856 100644 --- a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml +++ b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml @@ -24,11 +24,23 @@ properties: '#sound-dai-cells': const: 0 + rcv-gpios: + description: optional GPIO to be asserted when receiver mode is enabled. + sound-name-prefix: true vddd-supply: description: regulator phandle for the VDDD power supply. +if: + not: + properties: + compatible: + const: nxp,tfa9897 +then: + properties: + rcv-gpios: false + required: - compatible - reg @@ -55,3 +67,32 @@ examples: #sound-dai-cells = <0>; }; }; + + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + speaker_codec_top: audio-codec@34 { + compatible = "nxp,tfa9897"; + reg = <0x34>; + vddd-supply = <&pm8916_l6>; + rcv-gpios = <&msmgpio 50 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&speaker_top_default>; + sound-name-prefix = "Speaker Top"; + #sound-dai-cells = <0>; + }; + + speaker_codec_bottom: audio-codec@36 { + compatible = "nxp,tfa9897"; + reg = <0x36>; + vddd-supply = <&pm8916_l6>; + rcv-gpios = <&msmgpio 111 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&speaker_bottom_default>; + sound-name-prefix = "Speaker Bottom"; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt b/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt deleted file mode 100644 index 23998262a0a7..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt +++ /dev/null @@ -1,96 +0,0 @@ -* Qualcomm Technologies APQ8016 SBC ASoC machine driver - -This node models the Qualcomm Technologies APQ8016 SBC ASoC machine driver - -Required properties: - -- compatible : "qcom,apq8016-sbc-sndcard" - -- pinctrl-N : One property must exist for each entry in - pinctrl-names. See ../pinctrl/pinctrl-bindings.txt - for details of the property values. -- pinctrl-names : Must contain a "default" entry. -- reg : Must contain an address for each entry in reg-names. -- reg-names : A list which must include the following entries: - * "mic-iomux" - * "spkr-iomux" -- qcom,model : Name of the sound card. - -- qcom,audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the - connection's sink, the second being the connection's - source. Valid names could be power supplies, MicBias - of msm8x16_wcd codec and the jacks on the board: - - Power supplies: - * MIC BIAS External1 - * MIC BIAS External2 - * MIC BIAS Internal1 - * MIC BIAS Internal2 - - Board connectors: - * Headset Mic - * Secondary Mic - * DMIC - * Ext Spk - -Optional properties: - -- aux-devs : A list of phandles for auxiliary devices (e.g. analog - amplifiers) that do not appear directly within the DAI - links. Should be connected to another audio component - using "qcom,audio-routing". - -Dai-link subnode properties and subnodes: - -Required dai-link subnodes: - -- cpu : CPU sub-node -- codec : CODEC sub-node - -Required CPU/CODEC subnodes properties: - --link-name : Name of the dai link. --sound-dai : phandle/s and port of CPU/CODEC - -Example: - -sound: sound { - compatible = "qcom,apq8016-sbc-sndcard"; - reg = <0x07702000 0x4>, <0x07702004 0x4>; - reg-names = "mic-iomux", "spkr-iomux"; - qcom,model = "DB410c"; - - qcom,audio-routing = - "MIC BIAS External1", "Handset Mic", - "MIC BIAS Internal2", "Headset Mic", - "MIC BIAS External1", "Secondary Mic", - "AMIC1", "MIC BIAS External1", - "AMIC2", "MIC BIAS Internal2", - "AMIC3", "MIC BIAS External1", - "DMIC1", "MIC BIAS Internal1", - "MIC BIAS Internal1", "Digital Mic1", - "DMIC2", "MIC BIAS Internal1", - "MIC BIAS Internal1", "Digital Mic2"; - - /* I2S - Internal codec */ - internal-dai-link@0 { - cpu { /* PRIMARY */ - sound-dai = <&lpass MI2S_PRIMARY>; - }; - codec { - sound-dai = <&lpass_codec 0>, <&wcd_codec 0>; - }; - }; - - /* External Primary or External Secondary -ADV7533 HDMI */ - external-dai-link@0 { - link-name = "ADV7533"; - cpu { /* QUAT */ - sound-dai = <&lpass MI2S_QUATERNARY>; - }; - codec { - sound-dai = <&adv_bridge 0>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 7d57eb91657a..4bfda04b4608 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -4,18 +4,20 @@ $id: http://devicetree.org/schemas/sound/qcom,sm8250.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Technologies Inc. SM8250 ASoC sound card driver +title: Qualcomm Technologies Inc. ASoC sound card drivers maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> description: - This bindings describes SC8250 SoC based sound cards + This bindings describes Qualcomm SoC based sound cards which uses LPASS internal codec for audio. properties: compatible: enum: + - qcom,apq8016-sbc-sndcard + - qcom,msm8916-qdsp6-sndcard - qcom,sm8250-sndcard - qcom,qrb5165-rb5-sndcard @@ -27,10 +29,28 @@ properties: being the connection's source. Valid names could be power supplies, MicBias of codec and the jacks on the board. + aux-devs: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: | + List of phandles pointing to auxiliary devices, such + as amplifiers, to be added to the sound card. + model: $ref: /schemas/types.yaml#/definitions/string description: User visible long sound card name + pin-switches: + description: List of widget names for which pin switches should be created. + $ref: /schemas/types.yaml#/definitions/string-array + + widgets: + description: User specified audio sound widgets. + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + + # Only valid for some compatibles (see allOf if below) + reg: true + reg-names: true + patternProperties: ".*-dai-link$": description: @@ -73,6 +93,34 @@ required: - compatible - model +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,apq8016-sbc-sndcard + - qcom,msm8916-qdsp6-sndcard + then: + properties: + reg: + items: + - description: Microphone I/O mux register address + - description: Speaker I/O mux register address + reg-names: + items: + - const: mic-iomux + - const: spkr-iomux + required: + - compatible + - model + - reg + - reg-names + else: + properties: + reg: false + reg-names: false + additionalProperties: false examples: @@ -86,10 +134,7 @@ examples: audio-routing = "SpkrLeft IN", "WSA_SPK1 OUT", "SpkrRight IN", "WSA_SPK2 OUT", "VA DMIC0", "vdd-micb", - "VA DMIC1", "vdd-micb", - "MM_DL1", "MultiMedia1 Playback", - "MM_DL2", "MultiMedia2 Playback", - "MultiMedia3 Capture", "MM_UL3"; + "VA DMIC1", "vdd-micb"; mm1-dai-link { link-name = "MultiMedia0"; @@ -157,3 +202,98 @@ examples: }; }; }; + + - | + #include <dt-bindings/sound/qcom,lpass.h> + sound@7702000 { + compatible = "qcom,apq8016-sbc-sndcard"; + reg = <0x07702000 0x4>, <0x07702004 0x4>; + reg-names = "mic-iomux", "spkr-iomux"; + + model = "DB410c"; + audio-routing = + "AMIC2", "MIC BIAS Internal2", + "AMIC3", "MIC BIAS External1"; + + pinctrl-0 = <&cdc_pdm_lines_act &ext_sec_tlmm_lines_act &ext_mclk_tlmm_lines_act>; + pinctrl-1 = <&cdc_pdm_lines_sus &ext_sec_tlmm_lines_sus &ext_mclk_tlmm_lines_sus>; + pinctrl-names = "default", "sleep"; + + quaternary-dai-link { + link-name = "ADV7533"; + cpu { + sound-dai = <&lpass MI2S_QUATERNARY>; + }; + codec { + sound-dai = <&adv_bridge 0>; + }; + }; + + primary-dai-link { + link-name = "WCD"; + cpu { + sound-dai = <&lpass MI2S_PRIMARY>; + }; + codec { + sound-dai = <&lpass_codec 0>, <&wcd_codec 0>; + }; + }; + + tertiary-dai-link { + link-name = "WCD-Capture"; + cpu { + sound-dai = <&lpass MI2S_TERTIARY>; + }; + codec { + sound-dai = <&lpass_codec 1>, <&wcd_codec 1>; + }; + }; + }; + + - | + #include <dt-bindings/sound/qcom,q6afe.h> + #include <dt-bindings/sound/qcom,q6asm.h> + sound@7702000 { + compatible = "qcom,msm8916-qdsp6-sndcard"; + reg = <0x07702000 0x4>, <0x07702004 0x4>; + reg-names = "mic-iomux", "spkr-iomux"; + + model = "msm8916"; + widgets = + "Speaker", "Speaker", + "Headphone", "Headphones"; + pin-switches = "Speaker"; + audio-routing = + "Speaker", "Speaker Amp OUT", + "Speaker Amp IN", "HPH_R", + "Headphones", "HPH_L", + "Headphones", "HPH_R", + "AMIC1", "MIC BIAS Internal1", + "AMIC2", "MIC BIAS Internal2", + "AMIC3", "MIC BIAS Internal3"; + aux-devs = <&speaker_amp>; + + pinctrl-names = "default", "sleep"; + pinctrl-0 = <&cdc_pdm_lines_act>; + pinctrl-1 = <&cdc_pdm_lines_sus>; + + mm1-dai-link { + link-name = "MultiMedia1"; + cpu { + sound-dai = <&q6asmdai MSM_FRONTEND_DAI_MULTIMEDIA1>; + }; + }; + + primary-dai-link { + link-name = "Primary MI2S"; + cpu { + sound-dai = <&q6afedai PRIMARY_MI2S_RX>; + }; + platform { + sound-dai = <&q6routing>; + }; + codec { + sound-dai = <&lpass_codec 0>, <&wcd_codec 0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml b/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml index 2b8b7b51fe55..d65c0ed5060c 100644 --- a/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml @@ -61,6 +61,10 @@ properties: description: | Set the delay time (ms) for the requirement of the particular DMIC. + realtek,amic-delay-ms: + description: | + Set the delay time (ms) for the requirement of the particular platform or AMIC. + realtek,dmic-clk-driving-high: type: boolean description: | diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml index 2e3628ef48df..84c4d6cba521 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml @@ -110,12 +110,6 @@ properties: Internal DMA register base address of the audio subsystem (used in secondary sound source). - pinctrl-0: - description: Should specify pin control groups used for this controller. - - pinctrl-names: - const: default - power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml b/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml index 26379377a7ac..8327846356d3 100644 --- a/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml +++ b/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml @@ -9,6 +9,9 @@ title: Simple Audio Amplifier Device Tree Bindings maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: name-prefix.yaml# + properties: compatible: enum: @@ -22,10 +25,7 @@ properties: description: > power supply for the device - sound-name-prefix: - $ref: /schemas/types.yaml#/definitions/string - description: > - See ./name-prefix.txt + sound-name-prefix: true required: - compatible diff --git a/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml b/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml new file mode 100644 index 000000000000..83936f594d1a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,tlv320adc3xxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TLV320ADC3001/TLV320ADC3101 Stereo ADC + +maintainers: + - Ricard Wanderlof <ricardw@axis.com> + +description: | + Texas Instruments TLV320ADC3001 and TLV320ADC3101 Stereo ADC + https://www.ti.com/product/TLV320ADC3001 + https://www.ti.com/product/TLV320ADC3101 + +properties: + compatible: + enum: + - ti,tlv320adc3001 + - ti,tlv320adc3101 + + reg: + maxItems: 1 + description: I2C address + + '#sound-dai-cells': + const: 0 + + '#gpio-cells': + const: 2 + + gpio-controller: true + + reset-gpios: + maxItems: 1 + description: GPIO pin used for codec reset (RESET pin) + + clocks: + maxItems: 1 + description: Master clock (MCLK) + + ti,dmdin-gpio1: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # ADC3XXX_GPIO_DISABLED - I/O buffers powered down and not used + - 1 # ADC3XXX_GPIO_INPUT - Various non-GPIO input functions + - 2 # ADC3XXX_GPIO_GPI - General purpose input + - 3 # ADC3XXX_GPIO_GPO - General purpose output + - 4 # ADC3XXX_GPIO_CLKOUT - Clock source set in CLKOUT_MUX reg + - 5 # ADC3XXX_GPIO_INT1 - INT1 output + - 6 # ADC3XXX_GPIO_SECONDARY_BCLK - Codec interface secondary BCLK + - 7 # ADC3XXX_GPIO_SECONDARY_WCLK - Codec interface secondary WCLK + default: 0 + description: | + Configuration for DMDIN/GPIO1 pin. + + When ADC3XXX_GPIO_GPO is configured, this causes corresponding the + ALSA control "GPIOx Output" to appear, as a switch control. + + ti,dmclk-gpio2: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # ADC3XXX_GPIO_DISABLED - I/O buffers powered down and not used + - 1 # ADC3XXX_GPIO_INPUT - Various non-GPIO input functions + - 2 # ADC3XXX_GPIO_GPI - General purpose input + - 3 # ADC3XXX_GPIO_GPO - General purpose output + - 4 # ADC3XXX_GPIO_CLKOUT - Clock source set in CLKOUT_MUX reg + - 5 # ADC3XXX_GPIO_INT1 - INT1 output + - 6 # ADC3XXX_GPIO_SECONDARY_BCLK - Codec interface secondary BCLK + - 7 # ADC3XXX_GPIO_SECONDARY_WCLK - Codec interface secondary WCLK + default: 0 + description: | + Configuration for DMCLK/GPIO2 pin. + + When ADC3XXX_GPIO_GPO is configured, this causes corresponding the + ALSA control "GPIOx Output" to appear, as a switch control. + + Note that there is currently no support for reading the GPIO pins as + inputs. + + ti,micbias1-vg: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # ADC3XXX_MICBIAS_OFF - Mic bias is powered down + - 1 # ADC3XXX_MICBIAS_2_0V - Mic bias is set to 2.0V + - 2 # ADC3XXX_MICBIAS_2_5V - Mic bias is set to 2.5V + - 3 # ADC3XXX_MICBIAS_AVDD - Mic bias is same as AVDD supply + default: 0 + description: | + Mic bias voltage output on MICBIAS1 pin + + ti,micbias2-vg: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # ADC3XXX_MICBIAS_OFF - Mic bias is powered down + - 1 # ADC3XXX_MICBIAS_2_0V - Mic bias is set to 2.0V + - 2 # ADC3XXX_MICBIAS_2_5V - Mic bias is set to 2.5V + - 3 # ADC3XXX_MICBIAS_AVDD - Mic bias is same as AVDD supply + default: 0 + description: | + Mic bias voltage output on MICBIAS2 pin + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/sound/tlv320adc3xxx.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + tlv320adc3101: audio-codec@18 { + compatible = "ti,tlv320adc3101"; + reg = <0x18>; + reset-gpios = <&gpio_pc 3 GPIO_ACTIVE_LOW>; + clocks = <&audio_mclk>; + gpio-controller; + #gpio-cells = <2>; + ti,dmdin-gpio1 = <ADC3XXX_GPIO_GPO>; + ti,micbias1-vg = <ADC3XXX_MICBIAS_AVDD>; + }; + }; + + audio_mclk: clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <24576000>; + }; +... diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8903.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8903.yaml new file mode 100644 index 000000000000..7105ed5fd6c7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wlf,wm8903.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/sound/wlf,wm8903.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: WM8903 audio codec + +description: | + This device supports I2C only. + Pins on the device (for linking into audio routes): + * IN1L + * IN1R + * IN2L + * IN2R + * IN3L + * IN3R + * DMICDAT + * HPOUTL + * HPOUTR + * LINEOUTL + * LINEOUTR + * LOP + * LON + * ROP + * RON + * MICBIAS + +maintainers: + - patches@opensource.cirrus.com + +properties: + compatible: + const: wlf,wm8903 + + reg: + maxItems: 1 + + gpio-controller: true + '#gpio-cells': + const: 2 + + interrupts: + maxItems: 1 + + micdet-cfg: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + description: Default register value for R6 (Mic Bias). + + micdet-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 100 + description: The debounce delay for microphone detection in mS. + + gpio-cfg: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + minItems: 5 + maxItems: 5 + A list of GPIO configuration register values. + If absent, no configuration of these registers is performed. + If any entry has the value 0xffffffff, that GPIO's + configuration will not be modified. + + AVDD-supply: + description: Analog power supply regulator on the AVDD pin. + + CPVDD-supply: + description: Charge pump supply regulator on the CPVDD pin. + + DBVDD-supply: + description: Digital buffer supply regulator for the DBVDD pin. + + DCVDD-supply: + description: Digital core supply regulator for the DCVDD pin. + + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + wm8903: codec@1a { + compatible = "wlf,wm8903"; + reg = <0x1a>; + interrupts = <347>; + + AVDD-supply = <&fooreg_a>; + CPVDD-supply = <&fooreg_b>; + DBVDD-supply = <&fooreg_c>; + DCVDD-supply = <&fooreg_d>; + + gpio-controller; + #gpio-cells = <2>; + + micdet-cfg = <0>; + micdet-delay = <100>; + gpio-cfg = < + 0x0600 /* DMIC_LR, output */ + 0x0680 /* DMIC_DAT, input */ + 0x0000 /* GPIO, output, low */ + 0x0200 /* Interrupt, output */ + 0x01a0 /* BCLK, input, active high */ + >; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wm8903.txt b/Documentation/devicetree/bindings/sound/wm8903.txt deleted file mode 100644 index 6371c2434afe..000000000000 --- a/Documentation/devicetree/bindings/sound/wm8903.txt +++ /dev/null @@ -1,82 +0,0 @@ -WM8903 audio CODEC - -This device supports I2C only. - -Required properties: - - - compatible : "wlf,wm8903" - - - reg : the I2C address of the device. - - - gpio-controller : Indicates this device is a GPIO controller. - - - #gpio-cells : Should be two. The first cell is the pin number and the - second cell is used to specify optional parameters (currently unused). - -Optional properties: - - - interrupts : The interrupt line the codec is connected to. - - - micdet-cfg : Default register value for R6 (Mic Bias). If absent, the - default is 0. - - - micdet-delay : The debounce delay for microphone detection in mS. If - absent, the default is 100. - - - gpio-cfg : A list of GPIO configuration register values. The list must - be 5 entries long. If absent, no configuration of these registers is - performed. If any entry has the value 0xffffffff, that GPIO's - configuration will not be modified. - - - AVDD-supply : Analog power supply regulator on the AVDD pin. - - - CPVDD-supply : Charge pump supply regulator on the CPVDD pin. - - - DBVDD-supply : Digital buffer supply regulator for the DBVDD pin. - - - DCVDD-supply : Digital core supply regulator for the DCVDD pin. - -Pins on the device (for linking into audio routes): - - * IN1L - * IN1R - * IN2L - * IN2R - * IN3L - * IN3R - * DMICDAT - * HPOUTL - * HPOUTR - * LINEOUTL - * LINEOUTR - * LOP - * LON - * ROP - * RON - * MICBIAS - -Example: - -wm8903: codec@1a { - compatible = "wlf,wm8903"; - reg = <0x1a>; - interrupts = < 347 >; - - AVDD-supply = <&fooreg_a>; - CPVDD-supply = <&fooreg_b>; - DBVDD-supply = <&fooreg_c>; - DCVDC-supply = <&fooreg_d>; - - gpio-controller; - #gpio-cells = <2>; - - micdet-cfg = <0>; - micdet-delay = <100>; - gpio-cfg = < - 0x0600 /* DMIC_LR, output */ - 0x0680 /* DMIC_DAT, input */ - 0x0000 /* GPIO, output, low */ - 0x0200 /* Interrupt, output */ - 0x01a0 /* BCLK, input, active high */ - >; -}; diff --git a/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml new file mode 100644 index 000000000000..1d493add4053 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/atmel,quadspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel Quad Serial Peripheral Interface (QSPI) + +maintainers: + - Tudor Ambarus <tudor.ambarus@microchip.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + enum: + - atmel,sama5d2-qspi + - microchip,sam9x60-qspi + - microchip,sama7g5-qspi + - microchip,sama7g5-ospi + + reg: + items: + - description: base registers + - description: mapped memory + + reg-names: + items: + - const: qspi_base + - const: qspi_mmap + + clocks: + minItems: 1 + items: + - description: peripheral clock + - description: system clock or generic clock, if available + + clock-names: + minItems: 1 + items: + - const: pclk + - enum: [ qspick, gclk ] + + interrupts: + maxItems: 1 + + dmas: + items: + - description: tx DMA channel + - description: rx DMA channel + + dma-names: + items: + - const: tx + - const: rx + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/at91.h> + spi@f0020000 { + compatible = "atmel,sama5d2-qspi"; + reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; + reg-names = "qspi_base", "qspi_mmap"; + interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; + clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; + clock-names = "pclk"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_spi0_default>; + + flash@0 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-rx-bus-width = <4>; + spi-tx-bus-width = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt b/Documentation/devicetree/bindings/spi/atmel-quadspi.txt deleted file mode 100644 index 7c40ea694352..000000000000 --- a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt +++ /dev/null @@ -1,37 +0,0 @@ -* Atmel Quad Serial Peripheral Interface (QSPI) - -Required properties: -- compatible: Should be one of the following: - - "atmel,sama5d2-qspi" - - "microchip,sam9x60-qspi" -- reg: Should contain the locations and lengths of the base registers - and the mapped memory. -- reg-names: Should contain the resource reg names: - - qspi_base: configuration register address space - - qspi_mmap: memory mapped address space -- interrupts: Should contain the interrupt for the device. -- clocks: Should reference the peripheral clock and the QSPI system - clock if available. -- clock-names: Should contain "pclk" for the peripheral clock and "qspick" - for the system clock when available. -- #address-cells: Should be <1>. -- #size-cells: Should be <0>. - -Example: - -spi@f0020000 { - compatible = "atmel,sama5d2-qspi"; - reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; - reg-names = "qspi_base", "qspi_mmap"; - interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; - clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; - clock-names = "pclk"; - #address-cells = <1>; - #size-cells = <0>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_spi0_default>; - - m25p80@0 { - ... - }; -}; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml new file mode 100644 index 000000000000..553601a441a7 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/cdns,qspi-nor-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for the Cadence QSPI controller. + +description: + See spi-peripheral-props.yaml for more info. + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +properties: + # cdns,qspi-nor.yaml + cdns,read-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Delay for read capture logic, in clock cycles. + + cdns,tshsl-ns: + description: + Delay in nanoseconds for the length that the master mode chip select + outputs are de-asserted between transactions. + + cdns,tsd2d-ns: + description: + Delay in nanoseconds between one chip select being de-activated + and the activation of another. + + cdns,tchsh-ns: + description: + Delay in nanoseconds between last bit of current transaction and + deasserting the device chip select (qspi_n_ss_out). + + cdns,tslch-ns: + description: + Delay in nanoseconds between setting qspi_n_ss_out low and + first bit transfer. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index 037f41f58503..0a537fa3a641 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -87,39 +87,6 @@ properties: items: enum: [ qspi, qspi-ocp ] -# subnode's properties -patternProperties: - "@[0-9a-f]+$": - type: object - description: - Flash device uses the below defined properties in the subnode. - - properties: - cdns,read-delay: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Delay for read capture logic, in clock cycles. - - cdns,tshsl-ns: - description: - Delay in nanoseconds for the length that the master mode chip select - outputs are de-asserted between transactions. - - cdns,tsd2d-ns: - description: - Delay in nanoseconds between one chip select being de-activated - and the activation of another. - - cdns,tchsh-ns: - description: - Delay in nanoseconds between last bit of current transaction and - deasserting the device chip select (qspi_n_ss_out). - - cdns,tslch-ns: - description: - Delay in nanoseconds between setting qspi_n_ss_out low and - first bit transfer. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml new file mode 100644 index 000000000000..818130b11bb9 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/mediatek,spi-mt65xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SPI Bus controller for MediaTek ARM SoCs + +maintainers: + - Leilk Liu <leilk.liu@mediatek.com> + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + oneOf: + - items: + - enum: + - mediatek,mt7629-spi + - const: mediatek,mt7622-spi + - items: + - enum: + - mediatek,mt8516-spi + - const: mediatek,mt2712-spi + - items: + - enum: + - mediatek,mt6779-spi + - mediatek,mt8186-spi + - mediatek,mt8192-spi + - mediatek,mt8195-spi + - const: mediatek,mt6765-spi + - items: + - enum: + - mediatek,mt7986-spi-ipm + - const: mediatek,spi-ipm + - items: + - enum: + - mediatek,mt2701-spi + - mediatek,mt2712-spi + - mediatek,mt6589-spi + - mediatek,mt6765-spi + - mediatek,mt6893-spi + - mediatek,mt7622-spi + - mediatek,mt8135-spi + - mediatek,mt8173-spi + - mediatek,mt8183-spi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: clock used for the parent clock + - description: clock used for the muxes clock + - description: clock used for the clock gate + + clock-names: + items: + - const: parent-clk + - const: sel-clk + - const: spi-clk + + mediatek,pad-select: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + items: + enum: [0, 1, 2, 3] + description: + specify which pins group(ck/mi/mo/cs) spi controller used. + This is an array. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + spi@1100a000 { + compatible = "mediatek,mt8173-spi"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x1100a000 0x1000>; + interrupts = <GIC_SPI 110 IRQ_TYPE_LEVEL_LOW>; + clocks = <&topckgen CLK_TOP_SYSPLL3_D2>, + <&topckgen CLK_TOP_SPI_SEL>, + <&pericfg CLK_PERI_SPI0>; + clock-names = "parent-clk", "sel-clk", "spi-clk"; + cs-gpios = <&pio 105 GPIO_ACTIVE_LOW>, <&pio 72 GPIO_ACTIVE_LOW>; + mediatek,pad-select = <1>, <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 7393f30535df..be3cc7faed53 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -30,6 +30,7 @@ properties: - mediatek,mt7622-nor - mediatek,mt7623-nor - mediatek,mt7629-nor + - mediatek,mt8186-nor - mediatek,mt8192-nor - mediatek,mt8195-nor - enum: @@ -43,14 +44,22 @@ properties: maxItems: 1 clocks: + minItems: 2 items: - description: clock used for spi bus - description: clock used for controller + - description: clock used for nor dma bus. this depends on hardware + design, so this is optional. + - description: clock used for controller axi slave bus. + this depends on hardware design, so it is optional. clock-names: + minItems: 2 items: - const: spi - const: sf + - const: axi + - const: axi_s required: - compatible @@ -72,7 +81,7 @@ examples: nor_flash: spi@1100d000 { compatible = "mediatek,mt8173-nor"; reg = <0 0x1100d000 0 0xe0>; - interrupts = <&spi_flash_irq>; + interrupts = <1>; clocks = <&pericfg CLK_PERI_SPI>, <&topckgen CLK_TOP_SPINFI_IFR_SEL>; clock-names = "spi", "sf"; #address-cells = <1>; @@ -84,4 +93,3 @@ examples: }; }; }; - diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml new file mode 100644 index 000000000000..7977799a8ee1 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/mediatek,spi-slave-mt27xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SPI Slave controller for MediaTek ARM SoCs + +maintainers: + - Leilk Liu <leilk.liu@mediatek.com> + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + enum: + - mediatek,mt2712-spi-slave + - mediatek,mt8195-spi-slave + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: spi + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/mt2712-clk.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + spi@10013000 { + compatible = "mediatek,mt2712-spi-slave"; + reg = <0x10013000 0x100>; + interrupts = <GIC_SPI 283 IRQ_TYPE_LEVEL_LOW>; + clocks = <&infracfg CLK_INFRA_AO_SPI1>; + clock-names = "spi"; + assigned-clocks = <&topckgen CLK_TOP_SPISLV_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_UNIVPLL1_D2>; + }; diff --git a/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml new file mode 100644 index 000000000000..ece261b8e963 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/microchip,mpfs-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip MPFS {Q,}SPI Controller Device Tree Bindings + +maintainers: + - Conor Dooley <conor.dooley@microchip.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + enum: + - microchip,mpfs-spi + - microchip,mpfs-qspi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-names: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + #include "dt-bindings/clock/microchip,mpfs-clock.h" + spi@20108000 { + compatible = "microchip,mpfs-spi"; + reg = <0x20108000 0x1000>; + clocks = <&clkcfg CLK_SPI0>; + interrupt-parent = <&plic>; + interrupts = <54>; + spi-max-frequency = <25000000>; + }; +... diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 35a8045b2c70..0296edd1de22 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -19,6 +19,7 @@ properties: - nvidia,tegra210-qspi - nvidia,tegra186-qspi - nvidia,tegra194-qspi + - nvidia,tegra234-qspi reg: maxItems: 1 @@ -106,7 +107,7 @@ examples: dma-names = "rx", "tx"; flash@0 { - compatible = "spi-nor"; + compatible = "jedec,spi-nor"; reg = <0>; spi-max-frequency = <104000000>; spi-tx-bus-width = <2>; diff --git a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml index 8397f60d80a2..2c3c6bd6ec45 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml @@ -21,7 +21,9 @@ properties: - enum: - renesas,rspi-r7s72100 # RZ/A1H - renesas,rspi-r7s9210 # RZ/A2 - - const: renesas,rspi-rz # RZ/A + - renesas,r9a07g044-rspi # RZ/G2{L,LC} + - renesas,r9a07g054-rspi # RZ/V2L + - const: renesas,rspi-rz - items: - enum: @@ -122,6 +124,8 @@ allOf: contains: enum: - renesas,qspi + - renesas,r9a07g044-rspi + - renesas,r9a07g054-rspi then: required: - resets diff --git a/Documentation/devicetree/bindings/spi/samsung,spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/samsung,spi-peripheral-props.yaml new file mode 100644 index 000000000000..f0db3fb3d688 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/samsung,spi-peripheral-props.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/samsung,spi-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for Samsung S3C/S5P/Exynos SoC SPI controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: + See spi-peripheral-props.yaml for more info. + +properties: + controller-data: + type: object + additionalProperties: false + + properties: + samsung,spi-feedback-delay: + description: | + The sampling phase shift to be applied on the miso line (to account + for any lag in the miso line). Valid values: + - 0: No phase shift. + - 1: 90 degree phase shift sampling. + - 2: 180 degree phase shift sampling. + - 3: 270 degree phase shift sampling. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/samsung,spi.yaml b/Documentation/devicetree/bindings/spi/samsung,spi.yaml new file mode 100644 index 000000000000..bf9a76d931d2 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/samsung,spi.yaml @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/samsung,spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S3C/S5P/Exynos SoC SPI controller + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: + All the SPI controller nodes should be represented in the aliases node using + the following format 'spi{n}' where n is a unique number for the alias. + +properties: + compatible: + oneOf: + - enum: + - samsung,s3c2443-spi # for S3C2443, S3C2416 and S3C2450 + - samsung,s3c6410-spi + - samsung,s5pv210-spi # for S5PV210 and S5PC110 + - samsung,exynos5433-spi + - tesla,fsd-spi + - const: samsung,exynos7-spi + deprecated: true + + clocks: + minItems: 2 + maxItems: 3 + + clock-names: + minItems: 2 + maxItems: 3 + + cs-gpios: true + + dmas: + minItems: 2 + maxItems: 2 + + dma-names: + items: + - const: tx + - const: rx + + interrupts: + maxItems: 1 + + no-cs-readback: + description: + The CS line is disconnected, therefore the device should not operate + based on CS signalling. + type: boolean + + num-cs: + minimum: 1 + maximum: 4 + default: 1 + + samsung,spi-src-clk: + description: + If the spi controller includes a internal clock mux to select the clock + source for the spi bus clock, this property can be used to indicate the + clock to be used for driving the spi bus clock. If not specified, the + clock number 0 is used as default. + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - dmas + - dma-names + - interrupts + - reg + +allOf: + - $ref: spi-controller.yaml# + - if: + properties: + compatible: + contains: + const: samsung,exynos5433-spi + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: spi + - enum: + - spi_busclk0 + - spi_busclk1 + - spi_busclk2 + - spi_busclk3 + - const: spi_ioclk + else: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: spi + - enum: + - spi_busclk0 + - spi_busclk1 + - spi_busclk2 + - spi_busclk3 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos5433.h> + #include <dt-bindings/clock/samsung,s2mps11.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/gpio/gpio.h> + + spi@14d30000 { + compatible = "samsung,exynos5433-spi"; + reg = <0x14d30000 0x100>; + interrupts = <GIC_SPI 433 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&pdma0 11>, <&pdma0 10>; + dma-names = "tx", "rx"; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cmu_peric CLK_PCLK_SPI1>, + <&cmu_peric CLK_SCLK_SPI1>, + <&cmu_peric CLK_SCLK_IOCLK_SPI1>; + clock-names = "spi", + "spi_busclk0", + "spi_ioclk"; + samsung,spi-src-clk = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&spi1_bus>; + num-cs = <1>; + + cs-gpios = <&gpd6 3 GPIO_ACTIVE_HIGH>; + + audio-codec@0 { + compatible = "wlf,wm5110"; + reg = <0x0>; + spi-max-frequency = <20000000>; + interrupt-parent = <&gpa0>; + interrupts = <4 IRQ_TYPE_NONE>; + clocks = <&pmu_system_controller 0>, + <&s2mps13_osc S2MPS11_CLK_BT>; + clock-names = "mclk1", "mclk2"; + + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + wlf,micd-detect-debounce = <300>; + wlf,micd-bias-start-time = <0x1>; + wlf,micd-rate = <0x7>; + wlf,micd-dbtime = <0x2>; + wlf,micd-force-micbias; + wlf,micd-configs = <0x0 1 0>; + wlf,hpdet-channel = <1>; + wlf,gpsw = <0x1>; + wlf,inmode = <2 0 2 0>; + + wlf,reset = <&gpc0 7 GPIO_ACTIVE_HIGH>; + wlf,ldoena = <&gpf0 0 GPIO_ACTIVE_HIGH>; + + /* core supplies */ + AVDD-supply = <&ldo18_reg>; + DBVDD1-supply = <&ldo18_reg>; + CPVDD-supply = <&ldo18_reg>; + DBVDD2-supply = <&ldo18_reg>; + DBVDD3-supply = <&ldo18_reg>; + SPKVDDL-supply = <&ldo18_reg>; + SPKVDDR-supply = <&ldo18_reg>; + + controller-data { + samsung,spi-feedback-delay = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 8246891602e7..0f4d40218400 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -94,73 +94,8 @@ patternProperties: "^.*@[0-9a-f]+$": type: object - properties: - compatible: - description: - Compatible of the SPI device. - - reg: - minItems: 1 - maxItems: 256 - items: - minimum: 0 - maximum: 256 - description: - Chip select used by the device. - - spi-3wire: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires 3-wire mode. - - spi-cpha: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires shifted clock phase (CPHA) mode. - - spi-cpol: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires inverse clock polarity (CPOL) mode. - - spi-cs-high: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the chip select active high. - - spi-lsb-first: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the LSB first mode. - - spi-max-frequency: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Maximum SPI clocking speed of the device in Hz. - - spi-rx-bus-width: - description: - Bus width to the SPI bus used for read transfers. - If 0 is provided, then no RX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-rx-delay-us: - description: - Delay, in microseconds, after a read transfer. - - spi-tx-bus-width: - description: - Bus width to the SPI bus used for write transfers. - If 0 is provided, then no TX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-tx-delay-us: - description: - Delay, in microseconds, after a write transfer. + allOf: + - $ref: spi-peripheral-props.yaml required: - compatible @@ -204,4 +139,11 @@ examples: spi-max-frequency = <100000>; reg = <1>; }; + + flash@2 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <2>, <3>; + stacked-memories = /bits/ 64 <0x10000000 0x10000000>; + }; }; diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 312d8fee9dbb..1d46877fe46a 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -14,10 +14,13 @@ allOf: properties: compatible: - enum: - - fsl,imx7ulp-spi - - fsl,imx8qxp-spi - + oneOf: + - enum: + - fsl,imx7ulp-spi + - fsl,imx8qxp-spi + - items: + - const: fsl,imx8ulp-spi + - const: fsl,imx7ulp-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt deleted file mode 100644 index 2a24969159cc..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ /dev/null @@ -1,68 +0,0 @@ -Binding for MTK SPI controller - -Required properties: -- compatible: should be one of the following. - - mediatek,mt2701-spi: for mt2701 platforms - - mediatek,mt2712-spi: for mt2712 platforms - - mediatek,mt6589-spi: for mt6589 platforms - - mediatek,mt6765-spi: for mt6765 platforms - - mediatek,mt7622-spi: for mt7622 platforms - - "mediatek,mt7629-spi", "mediatek,mt7622-spi": for mt7629 platforms - - mediatek,mt8135-spi: for mt8135 platforms - - mediatek,mt8173-spi: for mt8173 platforms - - mediatek,mt8183-spi: for mt8183 platforms - - mediatek,mt6893-spi: for mt6893 platforms - - "mediatek,mt8192-spi", "mediatek,mt6765-spi": for mt8192 platforms - - "mediatek,mt8195-spi", "mediatek,mt6765-spi": for mt8195 platforms - - "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms - - "mediatek,mt6779-spi", "mediatek,mt6765-spi": for mt6779 platforms - -- #address-cells: should be 1. - -- #size-cells: should be 0. - -- reg: Address and length of the register set for the device - -- interrupts: Should contain spi interrupt - -- clocks: phandles to input clocks. - The first should be one of the following. It's PLL. - - <&clk26m>: specify parent clock 26MHZ. - - <&topckgen CLK_TOP_SYSPLL3_D2>: specify parent clock 109MHZ. - It's the default one. - - <&topckgen CLK_TOP_SYSPLL4_D2>: specify parent clock 78MHZ. - - <&topckgen CLK_TOP_UNIVPLL2_D4>: specify parent clock 104MHZ. - - <&topckgen CLK_TOP_UNIVPLL1_D8>: specify parent clock 78MHZ. - The second should be <&topckgen CLK_TOP_SPI_SEL>. It's clock mux. - The third is <&pericfg CLK_PERI_SPI0>. It's clock gate. - -- clock-names: shall be "parent-clk" for the parent clock, "sel-clk" for the - muxes clock, and "spi-clk" for the clock gate. - -Optional properties: --cs-gpios: see spi-bus.txt. - -- mediatek,pad-select: specify which pins group(ck/mi/mo/cs) spi - controller used. This is an array, the element value should be 0~3, - only required for MT8173. - 0: specify GPIO69,70,71,72 for spi pins. - 1: specify GPIO102,103,104,105 for spi pins. - 2: specify GPIO128,129,130,131 for spi pins. - 3: specify GPIO5,6,7,8 for spi pins. - -Example: - -- SoC Specific Portion: -spi: spi@1100a000 { - compatible = "mediatek,mt8173-spi"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0 0x1100a000 0 0x1000>; - interrupts = <GIC_SPI 110 IRQ_TYPE_LEVEL_LOW>; - clocks = <&topckgen CLK_TOP_SYSPLL3_D2>, - <&topckgen CLK_TOP_SPI_SEL>, - <&pericfg CLK_PERI_SPI0>; - clock-names = "parent-clk", "sel-clk", "spi-clk"; - cs-gpios = <&pio 105 GPIO_ACTIVE_LOW>, <&pio 72 GPIO_ACTIVE_LOW>; - mediatek,pad-select = <1>, <0>; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml index 51c7622dc20b..7ea79f6d33f3 100644 --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml @@ -31,6 +31,7 @@ description: | allOf: - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: "/schemas/spi/spi-peripheral-props.yaml#" maintainers: - Chris Packham <chris.packham@alliedtelesis.co.nz> diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml index 283815d59e85..1b552c298277 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: NXP Flex Serial Peripheral Interface (FSPI) maintainers: - - Kuldeep Singh <kuldeep.singh@nxp.com> + - Han Xu <han.xu@nxp.com> + - Kuldeep Singh <singh.kuldeep87k@gmail.com> allOf: - $ref: "spi-controller.yaml#" diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml new file mode 100644 index 000000000000..5e32928c4fc3 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/spi-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for a SPI bus. + +description: + Many SPI controllers need to add properties to peripheral devices. They could + be common properties like spi-max-frequency, spi-cpha, etc. or they could be + controller specific like delay in clock or data lines, etc. These properties + need to be defined in the peripheral node because they are per-peripheral and + there can be multiple peripherals attached to a controller. All those + properties are listed here. The controller specific properties should go in + their own separate schema that should be referenced from here. + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +properties: + reg: + minItems: 1 + maxItems: 256 + items: + items: + - minimum: 0 + maximum: 256 + description: + Chip select used by the device. + + spi-3wire: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires 3-wire mode. + + spi-cpha: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires shifted clock phase (CPHA) mode. + + spi-cpol: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires inverse clock polarity (CPOL) mode. + + spi-cs-high: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the chip select active high. + + spi-lsb-first: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the LSB first mode. + + spi-max-frequency: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Maximum SPI clocking speed of the device in Hz. + + spi-rx-bus-width: + description: + Bus width to the SPI bus used for read transfers. + If 0 is provided, then no RX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-rx-delay-us: + description: + Delay, in microseconds, after a read transfer. + + spi-tx-bus-width: + description: + Bus width to the SPI bus used for write transfers. + If 0 is provided, then no TX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-tx-delay-us: + description: + Delay, in microseconds, after a write transfer. + + stacked-memories: + description: Several SPI memories can be wired in stacked mode. + This basically means that either a device features several chip + selects, or that different devices must be seen as a single + bigger chip. This basically doubles (or more) the total address + space with only a single additional wire, while still needing + to repeat the commands when crossing a chip boundary. The size of + each chip should be provided as members of the array. + $ref: /schemas/types.yaml#/definitions/uint64-array + minItems: 2 + maxItems: 4 + + parallel-memories: + description: Several SPI memories can be wired in parallel mode. + The devices are physically on a different buses but will always + act synchronously as each data word is spread across the + different memories (eg. even bits are stored in one memory, odd + bits in the other). This basically doubles the address space and + the throughput while greatly complexifying the wiring because as + many busses as devices must be wired. The size of each chip should + be provided as members of the array. + $ref: /schemas/types.yaml#/definitions/uint64-array + minItems: 2 + maxItems: 4 + +# The controller specific properties go here. +allOf: + - $ref: cdns,qspi-nor-peripheral-props.yaml# + - $ref: samsung,spi-peripheral-props.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index a91d868e40c5..bda45ff3d294 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -38,9 +38,7 @@ properties: clock-names: items: - - enum: - - SSPCLK - - sspclk + - const: sspclk - const: apb_pclk pl022,autosuspend-delay: @@ -72,6 +70,9 @@ properties: - const: rx - const: tx + resets: + maxItems: 1 + patternProperties: "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": type: object diff --git a/Documentation/devicetree/bindings/spi/spi-samsung.txt b/Documentation/devicetree/bindings/spi/spi-samsung.txt deleted file mode 100644 index 49028a4f5df1..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-samsung.txt +++ /dev/null @@ -1,122 +0,0 @@ -* Samsung SPI Controller - -The Samsung SPI controller is used to interface with various devices such as flash -and display controllers using the SPI communication interface. - -Required SoC Specific Properties: - -- compatible: should be one of the following. - - samsung,s3c2443-spi: for s3c2443, s3c2416 and s3c2450 platforms - - samsung,s3c6410-spi: for s3c6410 platforms - - samsung,s5pv210-spi: for s5pv210 and s5pc110 platforms - - samsung,exynos5433-spi: for exynos5433 compatible controllers - - samsung,exynos7-spi: for exynos7 platforms <DEPRECATED> - -- reg: physical base address of the controller and length of memory mapped - region. - -- interrupts: The interrupt number to the cpu. The interrupt specifier format - depends on the interrupt controller. - -- dmas : Two or more DMA channel specifiers following the convention outlined - in bindings/dma/dma.txt - -- dma-names: Names for the dma channels. There must be at least one channel - named "tx" for transmit and named "rx" for receive. - -- clocks: specifies the clock IDs provided to the SPI controller; they are - required for interacting with the controller itself, for synchronizing the bus - and as I/O clock (the latter is required by exynos5433 and exynos7). - -- clock-names: string names of the clocks in the 'clocks' property; for all the - the devices the names must be "spi", "spi_busclkN" (where N is determined by - "samsung,spi-src-clk"), while Exynos5433 should specify a third clock - "spi_ioclk" for the I/O clock. - -Required Board Specific Properties: - -- #address-cells: should be 1. -- #size-cells: should be 0. - -Optional Board Specific Properties: - -- samsung,spi-src-clk: If the spi controller includes a internal clock mux to - select the clock source for the spi bus clock, this property can be used to - indicate the clock to be used for driving the spi bus clock. If not specified, - the clock number 0 is used as default. - -- num-cs: Specifies the number of chip select lines supported. If - not specified, the default number of chip select lines is set to 1. - -- cs-gpios: should specify GPIOs used for chipselects (see spi-bus.txt) - -- no-cs-readback: the CS line is disconnected, therefore the device should not - operate based on CS signalling. - -SPI Controller specific data in SPI slave nodes: - -- The spi slave nodes should provide the following information which is required - by the spi controller. - - - samsung,spi-feedback-delay: The sampling phase shift to be applied on the - miso line (to account for any lag in the miso line). The following are the - valid values. - - - 0: No phase shift. - - 1: 90 degree phase shift sampling. - - 2: 180 degree phase shift sampling. - - 3: 270 degree phase shift sampling. - -Aliases: - -- All the SPI controller nodes should be represented in the aliases node using - the following format 'spi{n}' where n is a unique number for the alias. - - -Example: - -- SoC Specific Portion: - - spi_0: spi@12d20000 { - compatible = "samsung,exynos4210-spi"; - reg = <0x12d20000 0x100>; - interrupts = <0 66 0>; - dmas = <&pdma0 5 - &pdma0 4>; - dma-names = "tx", "rx"; - #address-cells = <1>; - #size-cells = <0>; - }; - -- Board Specific Portion: - - spi_0: spi@12d20000 { - #address-cells = <1>; - #size-cells = <0>; - pinctrl-names = "default"; - pinctrl-0 = <&spi0_bus>; - cs-gpios = <&gpa2 5 0>; - - w25q80bw@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "w25x80"; - reg = <0>; - spi-max-frequency = <10000>; - - controller-data { - samsung,spi-feedback-delay = <0>; - }; - - partition@0 { - label = "U-Boot"; - reg = <0x0 0x40000>; - read-only; - }; - - partition@40000 { - label = "Kernel"; - reg = <0x40000 0xc0000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt b/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt deleted file mode 100644 index 9192724540fd..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt +++ /dev/null @@ -1,33 +0,0 @@ -Binding for MTK SPI Slave controller - -Required properties: -- compatible: should be one of the following. - - mediatek,mt2712-spi-slave: for mt2712 platforms - - mediatek,mt8195-spi-slave: for mt8195 platforms -- reg: Address and length of the register set for the device. -- interrupts: Should contain spi interrupt. -- clocks: phandles to input clocks. - It's clock gate, and should be <&infracfg CLK_INFRA_AO_SPI1>. -- clock-names: should be "spi" for the clock gate. - -Optional properties: -- assigned-clocks: it's mux clock, should be <&topckgen CLK_TOP_SPISLV_SEL>. -- assigned-clock-parents: parent of mux clock. - It's PLL, and should be one of the following. - - <&topckgen CLK_TOP_UNIVPLL1_D2>: specify parent clock 312MHZ. - It's the default one. - - <&topckgen CLK_TOP_UNIVPLL1_D4>: specify parent clock 156MHZ. - - <&topckgen CLK_TOP_UNIVPLL2_D4>: specify parent clock 104MHZ. - - <&topckgen CLK_TOP_UNIVPLL1_D8>: specify parent clock 78MHZ. - -Example: -- SoC Specific Portion: -spis1: spi@10013000 { - compatible = "mediatek,mt2712-spi-slave"; - reg = <0 0x10013000 0 0x100>; - interrupts = <GIC_SPI 283 IRQ_TYPE_LEVEL_LOW>; - clocks = <&infracfg CLK_INFRA_AO_SPI1>; - clock-names = "spi"; - assigned-clocks = <&topckgen CLK_TOP_SPISLV_SEL>; - assigned-clock-parents = <&topckgen CLK_TOP_UNIVPLL1_D2>; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml b/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml new file mode 100644 index 000000000000..3a58cf0f1ec8 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/spi-sunplus-sp7021.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus sp7021 SPI controller + +allOf: + - $ref: "spi-controller.yaml" + +maintainers: + - Li-hao Kuo <lhjeff911@gmail.com> + +properties: + compatible: + enum: + - sunplus,sp7021-spi + + reg: + items: + - description: the SPI master registers + - description: the SPI slave registers + + reg-names: + items: + - const: master + - const: slave + + interrupt-names: + items: + - const: dma_w + - const: master_risc + - const: slave_risc + + interrupts: + minItems: 3 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - resets + - pinctrl-names + - pinctrl-0 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi@9C002D80 { + compatible = "sunplus,sp7021-spi"; + reg = <0x9C002D80 0x80>, <0x9C002E00 0x80>; + reg-names = "master", "slave"; + interrupt-parent = <&intc>; + interrupt-names = "dma_w", + "master_risc", + "slave_risc"; + interrupts = <144 IRQ_TYPE_LEVEL_HIGH>, + <146 IRQ_TYPE_LEVEL_HIGH>, + <145 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clkc 0x32>; + resets = <&rstc 0x22>; + pinctrl-names = "default"; + pinctrl-0 = <&pins_spi0>; + }; +... diff --git a/Documentation/devicetree/bindings/spmi/mtk,spmi-mtk-pmif.yaml b/Documentation/devicetree/bindings/spmi/mtk,spmi-mtk-pmif.yaml new file mode 100644 index 000000000000..2445c5e0b0ef --- /dev/null +++ b/Documentation/devicetree/bindings/spmi/mtk,spmi-mtk-pmif.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spmi/mtk,spmi-mtk-pmif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek SPMI Controller Device Tree Bindings + +maintainers: + - Hsin-Hsiung Wang <hsin-hsiung.wang@mediatek.com> + +description: |+ + On MediaTek SoCs the PMIC is connected via SPMI and the controller allows + for multiple SoCs to control a single SPMI master. + +allOf: + - $ref: "spmi.yaml" + +properties: + compatible: + enum: + - mediatek,mt6873-spmi + - mediatek,mt8195-spmi + + reg: + maxItems: 2 + + reg-names: + items: + - const: pmif + - const: spmimst + + clocks: + minItems: 3 + maxItems: 3 + + clock-names: + items: + - const: pmif_sys_ck + - const: pmif_tmr_ck + - const: spmimst_clk_mux + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8192-clk.h> + + spmi: spmi@10027000 { + compatible = "mediatek,mt6873-spmi"; + reg = <0x10027000 0xe00>, + <0x10029000 0x100>; + reg-names = "pmif", "spmimst"; + clocks = <&infracfg CLK_INFRA_PMIC_AP>, + <&infracfg CLK_INFRA_PMIC_TMR>, + <&topckgen CLK_TOP_SPMI_MST_SEL>; + clock-names = "pmif_sys_ck", + "pmif_tmr_ck", + "spmimst_clk_mux"; + assigned-clocks = <&topckgen CLK_TOP_PWRAP_ULPOSC_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_OSC_D10>; + }; +... diff --git a/Documentation/devicetree/bindings/spmi/spmi.yaml b/Documentation/devicetree/bindings/spmi/spmi.yaml index 1d243faef2f8..c1b06fa5c631 100644 --- a/Documentation/devicetree/bindings/spmi/spmi.yaml +++ b/Documentation/devicetree/bindings/spmi/spmi.yaml @@ -24,9 +24,6 @@ properties: $nodename: pattern: "^spmi@.*" - reg: - maxItems: 1 - "#address-cells": const: 2 diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt b/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt deleted file mode 100644 index 74a9ef09db8b..000000000000 --- a/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.txt +++ /dev/null @@ -1,23 +0,0 @@ -* Broadcom STB thermal management - -Thermal management core, provided by the AVS TMON hardware block. - -Required properties: -- compatible: must be one of: - "brcm,avs-tmon-bcm7216" - "brcm,avs-tmon-bcm7445" - "brcm,avs-tmon" -- reg: address range for the AVS TMON registers -- interrupts: temperature monitor interrupt, for high/low threshold triggers, - required except for "brcm,avs-tmon-bcm7216" -- interrupt-names: should be "tmon" - -Example: - - thermal@f04d1500 { - compatible = "brcm,avs-tmon-bcm7445", "brcm,avs-tmon"; - reg = <0xf04d1500 0x28>; - interrupts = <0x6>; - interrupt-names = "tmon"; - interrupt-parent = <&avs_host_l2_intc>; - }; diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.yaml b/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.yaml new file mode 100644 index 000000000000..267a0f423504 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/brcm,avs-tmon.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/brcm,avs-tmon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom STB thermal management + +description: Thermal management core, provided by the AVS TMON hardware block. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + items: + - enum: + - brcm,avs-tmon-bcm7216 + - brcm,avs-tmon-bcm7445 + - const: brcm,avs-tmon + + reg: + maxItems: 1 + description: > + Address range for the AVS TMON registers + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: tmon + + "#thermal-sensor-cells": + const: 0 + +additionalProperties: false + +required: + - compatible + - reg + - "#thermal-sensor-cells" + +examples: + - | + thermal@f04d1500 { + compatible = "brcm,avs-tmon-bcm7445", "brcm,avs-tmon"; + reg = <0xf04d1500 0x28>; + interrupts = <0x6>; + interrupt-names = "tmon"; + interrupt-parent = <&avs_host_l2_intc>; + #thermal-sensor-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt deleted file mode 100644 index 33004ce7e5df..000000000000 --- a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt +++ /dev/null @@ -1,106 +0,0 @@ -* Exynos Thermal Management Unit (TMU) - -** Required properties: - -- compatible : One of the following: - "samsung,exynos3250-tmu" - "samsung,exynos4412-tmu" - "samsung,exynos4210-tmu" - "samsung,exynos5250-tmu" - "samsung,exynos5260-tmu" - "samsung,exynos5420-tmu" for TMU channel 0, 1 on Exynos5420 - "samsung,exynos5420-tmu-ext-triminfo" for TMU channels 2, 3 and 4 - Exynos5420 (Must pass triminfo base and triminfo clock) - "samsung,exynos5433-tmu" - "samsung,exynos7-tmu" -- reg : Address range of the thermal registers. For soc's which has multiple - instances of TMU and some registers are shared across all TMU's like - interrupt related then 2 set of register has to supplied. First set - belongs to register set of TMU instance and second set belongs to - registers shared with the TMU instance. - - NOTE: On Exynos5420, the TRIMINFO register is misplaced for TMU - channels 2, 3 and 4 - Use "samsung,exynos5420-tmu-ext-triminfo" in cases, there is a misplaced - register, also provide clock to access that base. - - TRIMINFO at 0x1006c000 contains data for TMU channel 3 - TRIMINFO at 0x100a0000 contains data for TMU channel 4 - TRIMINFO at 0x10068000 contains data for TMU channel 2 - -- interrupts : Should contain interrupt for thermal system -- clocks : The main clocks for TMU device - -- 1. operational clock for TMU channel - -- 2. optional clock to access the shared registers of TMU channel - -- 3. optional special clock for functional operation -- clock-names : Thermal system clock name - -- "tmu_apbif" operational clock for current TMU channel - -- "tmu_triminfo_apbif" clock to access the shared triminfo register - for current TMU channel - -- "tmu_sclk" clock for functional operation of the current TMU - channel - -The Exynos TMU supports generating interrupts when reaching given -temperature thresholds. Number of supported thermal trip points depends -on the SoC (only first trip points defined in DT will be configured): - - most of SoC: 4 - - samsung,exynos5433-tmu: 8 - - samsung,exynos7-tmu: 8 - -** Optional properties: - -- vtmu-supply: This entry is optional and provides the regulator node supplying - voltage to TMU. If needed this entry can be placed inside - board/platform specific dts file. - -Example 1): - - tmu@100c0000 { - compatible = "samsung,exynos4412-tmu"; - interrupt-parent = <&combiner>; - reg = <0x100C0000 0x100>; - interrupts = <2 4>; - clocks = <&clock 383>; - clock-names = "tmu_apbif"; - vtmu-supply = <&tmu_regulator_node>; - #thermal-sensor-cells = <0>; - }; - -Example 2): (In case of Exynos5420 "with misplaced TRIMINFO register") - tmu_cpu2: tmu@10068000 { - compatible = "samsung,exynos5420-tmu-ext-triminfo"; - reg = <0x10068000 0x100>, <0x1006c000 0x4>; - interrupts = <0 184 0>; - clocks = <&clock 318>, <&clock 318>; - clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #thermal-sensor-cells = <0>; - }; - - tmu_cpu3: tmu@1006c000 { - compatible = "samsung,exynos5420-tmu-ext-triminfo"; - reg = <0x1006c000 0x100>, <0x100a0000 0x4>; - interrupts = <0 185 0>; - clocks = <&clock 318>, <&clock 319>; - clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #thermal-sensor-cells = <0>; - }; - - tmu_gpu: tmu@100a0000 { - compatible = "samsung,exynos5420-tmu-ext-triminfo"; - reg = <0x100a0000 0x100>, <0x10068000 0x4>; - interrupts = <0 215 0>; - clocks = <&clock 319>, <&clock 318>; - clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #thermal-sensor-cells = <0>; - }; - -Note: For multi-instance tmu each instance should have an alias correctly -numbered in "aliases" node. - -Example: - -aliases { - tmuctrl0 = &tmuctrl_0; - tmuctrl1 = &tmuctrl_1; - tmuctrl2 = &tmuctrl_2; -}; diff --git a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml index 289e9a845600..a9b7388ca9ac 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml @@ -19,6 +19,7 @@ properties: compatible: enum: - qcom,sdm845-lmh + - qcom,sm8150-lmh reg: items: diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index d3b9e9b600a2..b6406bcc683f 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -43,6 +43,7 @@ properties: - description: v2 of TSENS items: - enum: + - qcom,msm8953-tsens - qcom,msm8996-tsens - qcom,msm8998-tsens - qcom,sc7180-tsens diff --git a/Documentation/devicetree/bindings/thermal/samsung,exynos-thermal.yaml b/Documentation/devicetree/bindings/thermal/samsung,exynos-thermal.yaml new file mode 100644 index 000000000000..17129f75d962 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/samsung,exynos-thermal.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/samsung,exynos-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC Thermal Management Unit (TMU) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + For multi-instance tmu each instance should have an alias correctly numbered + in "aliases" node. + +properties: + compatible: + enum: + - samsung,exynos3250-tmu + - samsung,exynos4412-tmu + - samsung,exynos4210-tmu + - samsung,exynos5250-tmu + - samsung,exynos5260-tmu + # For TMU channel 0, 1 on Exynos5420: + - samsung,exynos5420-tmu + # For TMU channels 2, 3 and 4 of Exynos5420: + - samsung,exynos5420-tmu-ext-triminfo + - samsung,exynos5433-tmu + - samsung,exynos7-tmu + + clocks: + minItems: 1 + maxItems: 3 + + clock-names: + minItems: 1 + maxItems: 3 + + interrupts: + description: | + The Exynos TMU supports generating interrupts when reaching given + temperature thresholds. Number of supported thermal trip points depends + on the SoC (only first trip points defined in DT will be configured):: + - most of SoC: 4 + - samsung,exynos5433-tmu: 8 + - samsung,exynos7-tmu: 8 + maxItems: 1 + + reg: + items: + - description: TMU instance registers. + - description: | + Shared TMU registers. + + Note:: On Exynos5420, the TRIMINFO register is misplaced for TMU + channels 2, 3 and 4 Use "samsung,exynos5420-tmu-ext-triminfo" in + cases, there is a misplaced register, also provide clock to access + that base. + TRIMINFO at 0x1006c000 contains data for TMU channel 3 + TRIMINFO at 0x100a0000 contains data for TMU channel 4 + TRIMINFO at 0x10068000 contains data for TMU channel 2 + minItems: 1 + + '#thermal-sensor-cells': true + + vtmu-supply: + description: The regulator node supplying voltage to TMU. + +required: + - compatible + - clocks + - clock-names + - interrupts + - reg + +allOf: + - $ref: /schemas/thermal/thermal-sensor.yaml + - if: + properties: + compatible: + contains: + const: samsung,exynos5420-tmu-ext-triminfo + then: + properties: + clocks: + items: + - description: + Operational clock for TMU channel. + - description: + Optional clock to access the shared registers (e.g. TRIMINFO) of TMU + channel. + clock-names: + items: + - const: tmu_apbif + - const: tmu_triminfo_apbif + reg: + minItems: 2 + maxItems: 2 + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos5433-tmu + - samsung,exynos7-tmu + then: + properties: + clocks: + items: + - description: + Operational clock for TMU channel. + - description: + Optional special clock for functional operation of TMU channel. + clock-names: + items: + - const: tmu_apbif + - const: tmu_sclk + reg: + minItems: 1 + maxItems: 1 + + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos3250-tmu + - samsung,exynos4412-tmu + - samsung,exynos4210-tmu + - samsung,exynos5250-tmu + - samsung,exynos5260-tmu + - samsung,exynos5420-tmu + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + reg: + minItems: 1 + maxItems: 1 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos4.h> + + tmu@100c0000 { + compatible = "samsung,exynos4412-tmu"; + reg = <0x100C0000 0x100>; + interrupt-parent = <&combiner>; + interrupts = <2 4>; + #thermal-sensor-cells = <0>; + clocks = <&clock CLK_TMU_APBIF>; + clock-names = "tmu_apbif"; + vtmu-supply = <&ldo10_reg>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tmu@10068000 { + compatible = "samsung,exynos5420-tmu-ext-triminfo"; + reg = <0x10068000 0x100>, <0x1006c000 0x4>; + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + #thermal-sensor-cells = <0>; + clocks = <&clock 318>, <&clock 318>; /* CLK_TMU */ + clock-names = "tmu_apbif", "tmu_triminfo_apbif"; + vtmu-supply = <&ldo7_reg>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tmu@10060000 { + compatible = "samsung,exynos5433-tmu"; + reg = <0x10060000 0x200>; + interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + #thermal-sensor-cells = <0>; + clocks = <&cmu_peris 3>, /* CLK_PCLK_TMU0_APBIF */ + <&cmu_peris 35>; /* CLK_SCLK_TMU0 */ + clock-names = "tmu_apbif", "tmu_sclk"; + vtmu-supply = <&ldo3_reg>; + }; diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index a07de5ed0ca6..2d34f3ccb257 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -199,12 +199,11 @@ patternProperties: contribution: $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 100 description: - The percentage contribution of the cooling devices at the - specific trip temperature referenced in this map - to this thermal zone + The cooling contribution to the thermal zone of the referred + cooling device at the referred trip point. The contribution is + a ratio of the sum of all cooling contributions within a + thermal zone. required: - trip diff --git a/Documentation/devicetree/bindings/timer/cdns,ttc.yaml b/Documentation/devicetree/bindings/timer/cdns,ttc.yaml index 8615353f69b4..c3386076a98c 100644 --- a/Documentation/devicetree/bindings/timer/cdns,ttc.yaml +++ b/Documentation/devicetree/bindings/timer/cdns,ttc.yaml @@ -25,6 +25,9 @@ properties: clocks: maxItems: 1 + power-domains: + maxItems: 1 + timer-width: $ref: "/schemas/types.yaml#/definitions/uint32" description: | diff --git a/Documentation/devicetree/bindings/timer/mstar,msc313e-timer.yaml b/Documentation/devicetree/bindings/timer/mstar,msc313e-timer.yaml new file mode 100644 index 000000000000..03d5dba5d5b3 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/mstar,msc313e-timer.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/mstar,msc313e-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mstar MSC313e Timer Device Tree Bindings + +maintainers: + - Daniel Palmer <daniel@0x0f.com> + - Romain Perier <romain.perier@gmail.com> + +properties: + compatible: + enum: + - mstar,msc313e-timer + - sstar,ssd20xd-timer + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + timer@6040 { + compatible = "mstar,msc313e-timer"; + reg = <0x6040 0x40>; + clocks = <&xtal_div2>; + interrupts-extended = <&intc_fiq GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra-timer.yaml b/Documentation/devicetree/bindings/timer/nvidia,tegra-timer.yaml new file mode 100644 index 000000000000..b78209cd0f28 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/nvidia,tegra-timer.yaml @@ -0,0 +1,150 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/timer/nvidia,tegra-timer.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra timer + +maintainers: + - Stephen Warren <swarren@nvidia.com> + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-timer + then: + properties: + interrupts: + # Either a single combined interrupt or up to 14 individual interrupts + minItems: 1 + maxItems: 14 + description: > + A list of 14 interrupts; one per each timer channels 0 through 13 + + - if: + properties: + compatible: + oneOf: + - items: + - enum: + - nvidia,tegra114-timer + - nvidia,tegra124-timer + - nvidia,tegra132-timer + - const: nvidia,tegra30-timer + - items: + - const: nvidia,tegra30-timer + - const: nvidia,tegra20-timer + then: + properties: + interrupts: + # Either a single combined interrupt or up to 6 individual interrupts + minItems: 1 + maxItems: 6 + description: > + A list of 6 interrupts; one per each of timer channels 1 through 5, + and one for the shared interrupt for the remaining channels. + + - if: + properties: + compatible: + const: nvidia,tegra20-timer + then: + properties: + interrupts: + # Either a single combined interrupt or up to 4 individual interrupts + minItems: 1 + maxItems: 4 + description: | + A list of 4 interrupts; one per timer channel. + +properties: + compatible: + oneOf: + - const: nvidia,tegra210-timer + description: > + The Tegra210 timer provides fourteen 29-bit timer counters and one 32-bit + timestamp counter. The TMRs run at either a fixed 1 MHz clock rate derived + from the oscillator clock (TMR0-TMR9) or directly at the oscillator clock + (TMR10-TMR13). Each TMR can be programmed to generate one-shot, periodic, + or watchdog interrupts. + - items: + - enum: + - nvidia,tegra114-timer + - nvidia,tegra124-timer + - nvidia,tegra132-timer + - const: nvidia,tegra30-timer + - items: + - const: nvidia,tegra30-timer + - const: nvidia,tegra20-timer + description: > + The Tegra30 timer provides ten 29-bit timer channels, a single 32-bit free + running counter, and 5 watchdog modules. The first two channels may also + trigger a legacy watchdog reset. + - const: nvidia,tegra20-timer + description: > + The Tegra20 timer provides four 29-bit timer channels and a single 32-bit free + running counter. The first two channels may also trigger a watchdog reset. + + reg: + maxItems: 1 + + interrupts: true + + clocks: + maxItems: 1 + + clock-names: + items: + - const: timer + + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + timer@60005000 { + compatible = "nvidia,tegra30-timer", "nvidia,tegra20-timer"; + reg = <0x60005000 0x400>; + interrupts = <0 0 IRQ_TYPE_LEVEL_HIGH>, + <0 1 IRQ_TYPE_LEVEL_HIGH>, + <0 41 IRQ_TYPE_LEVEL_HIGH>, + <0 42 IRQ_TYPE_LEVEL_HIGH>, + <0 121 IRQ_TYPE_LEVEL_HIGH>, + <0 122 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car 214>; + }; + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + timer@60005000 { + compatible = "nvidia,tegra210-timer"; + reg = <0x60005000 0x400>; + interrupts = <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 153 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 154 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 179 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA210_CLK_TIMER>; + clock-names = "timer"; + }; diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra20-timer.txt b/Documentation/devicetree/bindings/timer/nvidia,tegra20-timer.txt deleted file mode 100644 index 4a864bd10d3d..000000000000 --- a/Documentation/devicetree/bindings/timer/nvidia,tegra20-timer.txt +++ /dev/null @@ -1,24 +0,0 @@ -NVIDIA Tegra20 timer - -The Tegra20 timer provides four 29-bit timer channels and a single 32-bit free -running counter. The first two channels may also trigger a watchdog reset. - -Required properties: - -- compatible : should be "nvidia,tegra20-timer". -- reg : Specifies base physical address and size of the registers. -- interrupts : A list of 4 interrupts; one per timer channel. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. - -Example: - -timer { - compatible = "nvidia,tegra20-timer"; - reg = <0x60005000 0x60>; - interrupts = <0 0 0x04 - 0 1 0x04 - 0 41 0x04 - 0 42 0x04>; - clocks = <&tegra_car 132>; -}; diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt b/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt deleted file mode 100644 index 032cda96fe0d..000000000000 --- a/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt +++ /dev/null @@ -1,36 +0,0 @@ -NVIDIA Tegra210 timer - -The Tegra210 timer provides fourteen 29-bit timer counters and one 32-bit -timestamp counter. The TMRs run at either a fixed 1 MHz clock rate derived -from the oscillator clock (TMR0-TMR9) or directly at the oscillator clock -(TMR10-TMR13). Each TMR can be programmed to generate one-shot, periodic, -or watchdog interrupts. - -Required properties: -- compatible : "nvidia,tegra210-timer". -- reg : Specifies base physical address and size of the registers. -- interrupts : A list of 14 interrupts; one per each timer channels 0 through - 13. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. - -timer@60005000 { - compatible = "nvidia,tegra210-timer"; - reg = <0x0 0x60005000 0x0 0x400>; - interrupts = <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 153 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 154 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 179 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&tegra_car TEGRA210_CLK_TIMER>; - clock-names = "timer"; -}; diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt b/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt deleted file mode 100644 index 1761f53ee36f..000000000000 --- a/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt +++ /dev/null @@ -1,28 +0,0 @@ -NVIDIA Tegra30 timer - -The Tegra30 timer provides ten 29-bit timer channels, a single 32-bit free -running counter, and 5 watchdog modules. The first two channels may also -trigger a legacy watchdog reset. - -Required properties: - -- compatible : For Tegra30, must contain "nvidia,tegra30-timer". Otherwise, - must contain '"nvidia,<chip>-timer", "nvidia,tegra30-timer"' where - <chip> is tegra124 or tegra132. -- reg : Specifies base physical address and size of the registers. -- interrupts : A list of 6 interrupts; one per each of timer channels 1 - through 5, and one for the shared interrupt for the remaining channels. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. - -timer { - compatible = "nvidia,tegra30-timer", "nvidia,tegra20-timer"; - reg = <0x60005000 0x400>; - interrupts = <0 0 0x04 - 0 1 0x04 - 0 41 0x04 - 0 42 0x04 - 0 121 0x04 - 0 122 0x04>; - clocks = <&tegra_car 214>; -}; diff --git a/Documentation/devicetree/bindings/timer/nxp,tpm-timer.yaml b/Documentation/devicetree/bindings/timer/nxp,tpm-timer.yaml index edd9585f6726..f69773a8e4b9 100644 --- a/Documentation/devicetree/bindings/timer/nxp,tpm-timer.yaml +++ b/Documentation/devicetree/bindings/timer/nxp,tpm-timer.yaml @@ -19,7 +19,11 @@ description: | properties: compatible: - const: fsl,imx7ulp-tpm + oneOf: + - const: fsl,imx7ulp-tpm + - items: + - const: fsl,imx8ulp-tpm + - const: fsl,imx7ulp-tpm reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/timer/renesas,ostm.yaml b/Documentation/devicetree/bindings/timer/renesas,ostm.yaml index 600d47ab7d58..7fa7f977b44c 100644 --- a/Documentation/devicetree/bindings/timer/renesas,ostm.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,ostm.yaml @@ -21,9 +21,10 @@ properties: compatible: items: - enum: - - renesas,r7s72100-ostm # RZ/A1H - - renesas,r7s9210-ostm # RZ/A2M - - const: renesas,ostm # Generic + - renesas,r7s72100-ostm # RZ/A1H + - renesas,r7s9210-ostm # RZ/A2M + - renesas,r9a07g044-ostm # RZ/G2{L,LC} + - const: renesas,ostm # Generic reg: maxItems: 1 @@ -37,6 +38,9 @@ properties: power-domains: maxItems: 1 + resets: + maxItems: 1 + required: - compatible - reg @@ -44,6 +48,16 @@ required: - clocks - power-domains +if: + properties: + compatible: + contains: + enum: + - renesas,r9a07g044-ostm +then: + required: + - resets + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml index e26ecb5893ae..5d157d87dad5 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml @@ -18,7 +18,6 @@ properties: - enum: - rockchip,rv1108-timer - rockchip,rk3036-timer - - rockchip,rk3066-timer - rockchip,rk3188-timer - rockchip,rk3228-timer - rockchip,rk3229-timer diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 791079021f1b..da929cb08463 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -31,7 +31,7 @@ properties: - enum: # SMBus/I2C Digital Temperature Sensor in 6-Pin SOT with SMBus Alert and Over Temperature Pin - ad,ad7414 - # ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems + # ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems - ad,adm9240 # AD5110 - Nonvolatile Digital Potentiometer - adi,ad5110 @@ -43,7 +43,7 @@ properties: - adi,adp5589 # AMS iAQ-Core VOC Sensor - ams,iaq-core - # i2c serial eeprom (24cxx) + # i2c serial eeprom (24cxx) - at,24c08 # i2c trusted platform module (TPM) - atmel,at97sc3204t @@ -73,6 +73,8 @@ properties: - dallas,ds4510 # Digital Thermometer and Thermostat - dallas,ds75 + # Delta AHE-50DC Open19 power shelf fan control module + - delta,ahe50dc-fan # Delta Electronics DPS-650-AB power supply - delta,dps650ab # Delta Electronics DPS920AB 920W 54V Power Supply @@ -121,14 +123,22 @@ properties: - ibm,cffps2 # Infineon IR36021 digital POL buck controller - infineon,ir36021 + # Infineon IR38060 Voltage Regulator + - infineon,ir38060 # Infineon IR38064 Voltage Regulator - infineon,ir38064 + # Infineon IR38164 Voltage Regulator + - infineon,ir38164 + # Infineon IR38263 Voltage Regulator + - infineon,ir38263 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) - infineon,slb9635tt # Infineon SLB9645 I2C TPM (new protocol, max 400khz) - infineon,slb9645tt # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor - infineon,tlv493d-a1b6 + # Infineon Multi-phase Digital VR Controller xdpe11280 + - infineon,xdpe11280 # Infineon Multi-phase Digital VR Controller xdpe12254 - infineon,xdpe12254 # Infineon Multi-phase Digital VR Controller xdpe12284 @@ -281,6 +291,8 @@ properties: - sensirion,sgp30 # Sensirion gas sensor with I2C interface - sensirion,sgp40 + # Sensirion temperature & humidity sensor with I2C interface + - sensirion,sht4x # Sensortek 3 axis accelerometer - sensortek,stk8312 # Sensortek 3 axis accelerometer @@ -293,9 +305,9 @@ properties: - skyworks,sky81452 # Socionext SynQuacer TPM MMIO module - socionext,synquacer-tpm-mmio - # i2c serial eeprom (24cxx) - - sparkfun,qwiic-joystick # SparkFun Qwiic Joystick (COM-15168) with i2c interface + - sparkfun,qwiic-joystick + # i2c serial eeprom (24cxx) - st,24c256 # Ambient Light Sensor with SMBUS/Two Wire Serial Interface - taos,tsl2550 @@ -327,16 +339,26 @@ properties: # Thermometer with SPI interface - ti,tmp121 - ti,tmp122 + - ti,tmp125 # Digital Temperature Sensor - ti,tmp275 + # TI DC-DC converter on PMBus + - ti,tps40400 # TI Dual channel DCAP+ multiphase controller TPS53676 with AVSBus - ti,tps53676 # TI Dual channel DCAP+ multiphase controller TPS53679 - ti,tps53679 # TI Dual channel DCAP+ multiphase controller TPS53688 - ti,tps53688 + # TI DC-DC converters on PMBus + - ti,tps544b20 + - ti,tps544b25 + - ti,tps544c20 + - ti,tps544c25 # Winbond/Nuvoton H/W Monitor - winbond,w83793 + # Vicor Corporation Digital Supervisor + - vicor,pli1209bc # i2c trusted platform module (TPM) - winbond,wpct301 diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index d8fd4df81743..d0fee78e6203 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -16,6 +16,7 @@ Required properties: "qcom,sm8150-ufshc", "qcom,ufshc", "jedec,ufs-2.0" "qcom,sm8250-ufshc", "qcom,ufshc", "jedec,ufs-2.0" "qcom,sm8350-ufshc", "qcom,ufshc", "jedec,ufs-2.0" + "qcom,sm8450-ufshc", "qcom,ufshc", "jedec,ufs-2.0" - interrupts : <interrupt mapping for UFS host controller IRQ> - reg : <registers mapping> diff --git a/Documentation/devicetree/bindings/usb/brcm,bdc.txt b/Documentation/devicetree/bindings/usb/brcm,bdc.txt deleted file mode 100644 index c9f52b97cef1..000000000000 --- a/Documentation/devicetree/bindings/usb/brcm,bdc.txt +++ /dev/null @@ -1,29 +0,0 @@ -Broadcom USB Device Controller (BDC) -==================================== - -Required properties: - -- compatible: must be one of: - "brcm,bdc-udc-v2" - "brcm,bdc" -- reg: the base register address and length -- interrupts: the interrupt line for this controller - -Optional properties: - -On Broadcom STB platforms, these properties are required: - -- phys: phandle to one or two USB PHY blocks - NOTE: Some SoC's have a single phy and some have - USB 2.0 and USB 3.0 phys -- clocks: phandle to the functional clock of this block - -Example: - - bdc@f0b02000 { - compatible = "brcm,bdc-udc-v2"; - reg = <0xf0b02000 0xfc4>; - interrupts = <0x0 0x60 0x0>; - phys = <&usbphy_0 0x0>; - clocks = <&sw_usbd>; - }; diff --git a/Documentation/devicetree/bindings/usb/brcm,bdc.yaml b/Documentation/devicetree/bindings/usb/brcm,bdc.yaml new file mode 100644 index 000000000000..9e561fee98f1 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/brcm,bdc.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/brcm,bdc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom USB Device Controller (BDC) + +maintainers: + - Al Cooper <alcooperx@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + items: + - enum: + - brcm,bdc-udc-v2 + - brcm,bdc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + phys: + minItems: 1 + items: + - description: USB 2.0 or 3.0 PHY + - description: USB 3.0 PHY if there is a dedicated 2.0 PHY + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + usb@f0b02000 { + compatible = "brcm,bdc-udc-v2"; + reg = <0xf0b02000 0xfc4>; + interrupts = <0x0 0x60 0x0>; + phys = <&usbphy_0 0x0>; + clocks = <&sw_usbd>; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.yaml b/Documentation/devicetree/bindings/usb/dwc2.yaml index 56a818478cd7..481aaa09f3f2 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.yaml +++ b/Documentation/devicetree/bindings/usb/dwc2.yaml @@ -53,6 +53,7 @@ properties: - const: st,stm32mp15-hsotg - const: snps,dwc2 - const: samsung,s3c6400-hsotg + - const: intel,socfpga-agilex-hsotg reg: maxItems: 1 @@ -114,6 +115,8 @@ properties: usb-role-switch: true + role-switch-default-mode: true + g-rx-fifo-size: $ref: /schemas/types.yaml#/definitions/uint32 description: size of rx fifo size in gadget mode. @@ -136,6 +139,17 @@ properties: description: If present indicates that we need to reset the PHY when we detect a wakeup. This is due to a hardware errata. + port: + description: + Any connector to the data bus of this controller should be modelled + using the OF graph bindings specified, if the "usb-role-switch" + property is used. + $ref: /schemas/graph.yaml#/properties/port + +dependencies: + port: [ usb-role-switch ] + role-switch-default-mode: [ usb-role-switch ] + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt deleted file mode 100644 index 04813a46e5d0..000000000000 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt +++ /dev/null @@ -1,56 +0,0 @@ -Xilinx SuperSpeed DWC3 USB SoC controller - -Required properties: -- compatible: May contain "xlnx,zynqmp-dwc3" or "xlnx,versal-dwc3" -- reg: Base address and length of the register control block -- clocks: A list of phandles for the clocks listed in clock-names -- clock-names: Should contain the following: - "bus_clk" Master/Core clock, have to be >= 125 MHz for SS - operation and >= 60MHz for HS operation - - "ref_clk" Clock source to core during PHY power down -- resets: A list of phandles for resets listed in reset-names -- reset-names: - "usb_crst" USB core reset - "usb_hibrst" USB hibernation reset - "usb_apbrst" USB APB reset - -Required child node: -A child node must exist to represent the core DWC3 IP block. The name of -the node is not important. The content of the node is defined in dwc3.txt. - -Optional properties for snps,dwc3: -- dma-coherent: Enable this flag if CCI is enabled in design. Adding this - flag configures Global SoC bus Configuration Register and - Xilinx USB 3.0 IP - USB coherency register to enable CCI. -- interrupt-names: Should contain the following: - "dwc_usb3" USB gadget mode interrupts - "otg" USB OTG mode interrupts - "hiber" USB hibernation interrupts - -Example device node: - - usb@0 { - #address-cells = <0x2>; - #size-cells = <0x1>; - compatible = "xlnx,zynqmp-dwc3"; - reg = <0x0 0xff9d0000 0x0 0x100>; - clock-names = "bus_clk", "ref_clk"; - clocks = <&clk125>, <&clk125>; - resets = <&zynqmp_reset ZYNQMP_RESET_USB1_CORERESET>, - <&zynqmp_reset ZYNQMP_RESET_USB1_HIBERRESET>, - <&zynqmp_reset ZYNQMP_RESET_USB1_APB>; - reset-names = "usb_crst", "usb_hibrst", "usb_apbrst"; - ranges; - - dwc3@fe200000 { - compatible = "snps,dwc3"; - reg = <0x0 0xfe200000 0x40000>; - interrupt-names = "dwc_usb3", "otg", "hiber"; - interrupts = <0 65 4>, <0 69 4>, <0 75 4>; - phys = <&psgtr 2 PHY_TYPE_USB3 0 2>; - phy-names = "usb3-phy"; - dr_mode = "host"; - dma-coherent; - }; - }; diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml b/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml new file mode 100644 index 000000000000..f77c16e203d5 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml @@ -0,0 +1,131 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/dwc3-xilinx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx SuperSpeed DWC3 USB SoC controller + +maintainers: + - Manish Narani <manish.narani@xilinx.com> + +properties: + compatible: + items: + - enum: + - xlnx,zynqmp-dwc3 + - xlnx,versal-dwc3 + reg: + maxItems: 1 + + "#address-cells": + enum: [ 1, 2 ] + + "#size-cells": + enum: [ 1, 2 ] + + ranges: true + + power-domains: + description: specifies a phandle to PM domain provider node + maxItems: 1 + + clocks: + description: + A list of phandle and clock-specifier pairs for the clocks + listed in clock-names. + items: + - description: Master/Core clock, has to be >= 125 MHz + for SS operation and >= 60MHz for HS operation. + - description: Clock source to core during PHY power down. + + clock-names: + items: + - const: bus_clk + - const: ref_clk + + resets: + description: + A list of phandles for resets listed in reset-names. + + items: + - description: USB core reset + - description: USB hibernation reset + - description: USB APB reset + + reset-names: + items: + - const: usb_crst + - const: usb_hibrst + - const: usb_apbrst + + phys: + minItems: 1 + maxItems: 2 + + phy-names: + minItems: 1 + maxItems: 2 + items: + enum: + - usb2-phy + - usb3-phy + +# Required child node: + +patternProperties: + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - ranges + - power-domains + - clocks + - clock-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/dma/xlnx-zynqmp-dpdma.h> + #include <dt-bindings/power/xlnx-zynqmp-power.h> + #include <dt-bindings/reset/xlnx-zynqmp-resets.h> + #include <dt-bindings/clock/xlnx-zynqmp-clk.h> + #include <dt-bindings/reset/xlnx-zynqmp-resets.h> + #include <dt-bindings/phy/phy.h> + axi { + #address-cells = <2>; + #size-cells = <2>; + + usb@0 { + #address-cells = <0x2>; + #size-cells = <0x2>; + compatible = "xlnx,zynqmp-dwc3"; + reg = <0x0 0xff9d0000 0x0 0x100>; + clocks = <&zynqmp_clk USB0_BUS_REF>, <&zynqmp_clk USB3_DUAL_REF>; + clock-names = "bus_clk", "ref_clk"; + power-domains = <&zynqmp_firmware PD_USB_0>; + resets = <&zynqmp_reset ZYNQMP_RESET_USB1_CORERESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_HIBERRESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_APB>; + reset-names = "usb_crst", "usb_hibrst", "usb_apbrst"; + phys = <&psgtr 2 PHY_TYPE_USB3 0 2>; + phy-names = "usb3-phy"; + ranges; + + usb@fe200000 { + compatible = "snps,dwc3"; + reg = <0x0 0xfe200000 0x0 0x40000>; + interrupt-names = "host", "otg"; + interrupts = <0 65 4>, <0 69 4>; + dr_mode = "host"; + dma-coherent; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml b/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml index 43b91ab62004..d3511f48cd55 100644 --- a/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml @@ -13,6 +13,9 @@ properties: compatible: const: intel,keembay-dwc3 + reg: + maxItems: 1 + clocks: maxItems: 4 diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index 2bdaba023c01..2d23a4ff702f 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -13,7 +13,9 @@ properties: compatible: items: - enum: + - qcom,ipq4019-dwc3 - qcom,ipq6018-dwc3 + - qcom,ipq8064-dwc3 - qcom,msm8996-dwc3 - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 @@ -23,9 +25,11 @@ properties: - qcom,sdx55-dwc3 - qcom,sm4250-dwc3 - qcom,sm6115-dwc3 + - qcom,sm6350-dwc3 - qcom,sm8150-dwc3 - qcom,sm8250-dwc3 - qcom,sm8350-dwc3 + - qcom,sm8450-dwc3 - const: qcom,dwc3 reg: diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 25ac2c93dc6c..d29ffcd27472 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -36,6 +36,9 @@ properties: - const: synopsys,dwc3 deprecated: true + reg: + maxItems: 1 + interrupts: description: It's either a single common DWC3 interrupt (dwc_usb3) or individual @@ -65,6 +68,9 @@ properties: - enum: [bus_early, ref, suspend] - true + iommus: + maxItems: 1 + usb-phy: minItems: 1 items: diff --git a/Documentation/devicetree/bindings/usb/ti,j721e-usb.yaml b/Documentation/devicetree/bindings/usb/ti,j721e-usb.yaml index a634774c537c..eedde385d299 100644 --- a/Documentation/devicetree/bindings/usb/ti,j721e-usb.yaml +++ b/Documentation/devicetree/bindings/usb/ti,j721e-usb.yaml @@ -7,7 +7,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Bindings for the TI wrapper module for the Cadence USBSS-DRD controller maintainers: - - Roger Quadros <rogerq@ti.com> + - Roger Quadros <rogerq@kernel.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml index f6e91a5fd8fe..4f7a212fddd3 100644 --- a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: TI Keystone Soc USB Controller maintainers: - - Roger Quadros <rogerq@ti.com> + - Roger Quadros <rogerq@kernel.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index ae2aaaba620a..047a83a089ce 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -25,6 +25,8 @@ patternProperties: # Keep list in alphabetical order. "^70mai,.*": description: 70mai Co., Ltd. + "^8dev,.*": + description: 8devices, UAB "^abb,.*": description: ABB "^abilis,.*": @@ -441,6 +443,8 @@ patternProperties: description: Freescale Semiconductor "^fujitsu,.*": description: Fujitsu Ltd. + "^fxtec,.*": + description: FX Technology Ltd. "^gardena,.*": description: GARDENA GmbH "^gateworks,.*": @@ -515,6 +519,8 @@ patternProperties: description: HannStar Display Co. "^holtek,.*": description: Holtek Semiconductor, Inc. + "^huawei,.*": + description: Huawei Technologies Co., Ltd. "^hugsun,.*": description: Shenzhen Hugsun Technology Co. Ltd. "^hwacom,.*": @@ -858,6 +864,8 @@ patternProperties: description: OLIMEX Ltd. "^olpc,.*": description: One Laptop Per Child + "^oneplus,.*": + description: OnePlus Technology (Shenzhen) Co., Ltd. "^onion,.*": description: Onion Corporation "^onnn,.*": @@ -1159,6 +1167,8 @@ patternProperties: description: Summit microelectronics "^sunchip,.*": description: Shenzhen Sunchip Technology Co., Ltd + "^sunplus,.*": + description: Sunplus Technology Co., Ltd. "^SUNW,.*": description: Sun Microsystems, Inc "^supermicro,.*": @@ -1197,10 +1207,14 @@ patternProperties: description: Terasic Inc. "^tfc,.*": description: Three Five Corp + "^thead,.*": + description: T-Head Semiconductor Co., Ltd. "^thine,.*": description: THine Electronics, Inc. "^thingyjp,.*": description: thingy.jp + "^thundercomm,.*": + description: Thundercomm Technology Co., Ltd. "^ti,.*": description: Texas Instruments "^tianma,.*": @@ -1284,6 +1298,8 @@ patternProperties: description: Vertexcom Technologies, Inc. "^via,.*": description: VIA Technologies, Inc. + "^vicor,.*": + description: Vicor Corporation "^videostrong,.*": description: Videostrong Technology Co., Ltd. "^virtio,.*": @@ -1328,6 +1344,8 @@ patternProperties: description: Wiligear, Ltd. "^winbond,.*": description: Winbond Electronics corp. + "^wingtech,.*": + description: Wingtech Technology Co., Ltd. "^winlink,.*": description: WinLink Co., Ltd "^winstar,.*": diff --git a/Documentation/devicetree/bindings/watchdog/atmel,sama5d4-wdt.yaml b/Documentation/devicetree/bindings/watchdog/atmel,sama5d4-wdt.yaml index 9856cd76c28d..a9635c03761c 100644 --- a/Documentation/devicetree/bindings/watchdog/atmel,sama5d4-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/atmel,sama5d4-wdt.yaml @@ -22,6 +22,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + atmel,watchdog-type: $ref: /schemas/types.yaml#/definitions/string description: should be hardware or software. diff --git a/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt b/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt deleted file mode 100644 index 84122270be8f..000000000000 --- a/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt +++ /dev/null @@ -1,19 +0,0 @@ -BCM7038 Watchdog timer - -Required properties: - -- compatible : should be "brcm,bcm7038-wdt" -- reg : Specifies base physical address and size of the registers. - -Optional properties: - -- clocks: The clock running the watchdog. If no clock is found the - driver will default to 27000000 Hz. - -Example: - -watchdog@f040a7e8 { - compatible = "brcm,bcm7038-wdt"; - clocks = <&upg_fixed>; - reg = <0xf040a7e8 0x16>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.yaml b/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.yaml new file mode 100644 index 000000000000..a926809352b8 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/brcm,bcm7038-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BCM63xx and BCM7038 watchdog timer + +allOf: + - $ref: "watchdog.yaml#" + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + - Justin Chen <justinpopo6@gmail.com> + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +properties: + compatible: + enum: + - brcm,bcm6345-wdt + - brcm,bcm7038-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + description: > + The clock running the watchdog. If no clock is found the driver will + default to 27000000 Hz. + +unevaluatedProperties: false + +required: + - reg + +examples: + - | + watchdog@f040a7e8 { + compatible = "brcm,bcm7038-wdt"; + reg = <0xf040a7e8 0x16>; + clocks = <&upg_fixed>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.yaml b/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.yaml index 51d6d482bbc2..fb603a20e396 100644 --- a/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.yaml @@ -14,8 +14,11 @@ allOf: properties: compatible: - enum: - - fsl,imx7ulp-wdt + oneOf: + - const: fsl,imx7ulp-wdt + - items: + - const: fsl,imx8ulp-wdt + - const: fsl,imx7ulp-wdt reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml index ba60bdf1fecc..16c6f82a13ca 100644 --- a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml @@ -20,7 +20,9 @@ properties: - qcom,apss-wdt-sc7280 - qcom,apss-wdt-sdm845 - qcom,apss-wdt-sdx55 + - qcom,apss-wdt-sm6350 - qcom,apss-wdt-sm8150 + - qcom,apss-wdt-sm8250 - qcom,kpss-timer - qcom,kpss-wdt - qcom,kpss-wdt-apq8064 diff --git a/Documentation/devicetree/bindings/watchdog/realtek,otto-wdt.yaml b/Documentation/devicetree/bindings/watchdog/realtek,otto-wdt.yaml new file mode 100644 index 000000000000..11b220a5e0f6 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/realtek,otto-wdt.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/realtek,otto-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek Otto watchdog timer + +maintainers: + - Sander Vanheule <sander@svanheule.net> + +description: | + The timer has two timeout phases. Both phases have a maximum duration of 32 + prescaled clock ticks, which is ca. 43s with a bus clock of 200MHz. The + minimum duration of each phase is one tick. Each phase can trigger an + interrupt, although the phase 2 interrupt will occur with the system reset. + - Phase 1: During this phase, the WDT can be pinged to reset the timeout. + - Phase 2: Starts after phase 1 has timed out, and only serves to give the + system some time to clean up, or notify others that it's going to reset. + During this phase, pinging the WDT has no effect, and a reset is + unavoidable, unless the WDT is disabled. + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + enum: + - realtek,rtl8380-wdt + - realtek,rtl8390-wdt + - realtek,rtl9300-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + items: + - description: interrupt specifier for pretimeout + - description: interrupt specifier for timeout + + interrupt-names: + items: + - const: phase1 + - const: phase2 + + realtek,reset-mode: + $ref: /schemas/types.yaml#/definitions/string + description: | + Specify how the system is reset after a timeout. Defaults to "cpu" if + left unspecified. + oneOf: + - description: Reset the entire chip + const: soc + - description: | + Reset the CPU and IPsec engine, but leave other peripherals untouched + const: cpu + - description: | + Reset the execution pointer, but don't actually reset any hardware + const: software + +required: + - compatible + - reg + - clocks + - interrupts + +unevaluatedProperties: false + +dependencies: + interrupts: [ interrupt-names ] + +examples: + - | + watchdog: watchdog@3150 { + compatible = "realtek,rtl8380-wdt"; + reg = <0x3150 0xc>; + + realtek,reset-mode = "soc"; + + clocks = <&lxbus_clock>; + timeout-sec = <20>; + + interrupt-parent = <&rtlintc>; + interrupt-names = "phase1", "phase2"; + interrupts = <19>, <18>; + }; + +... diff --git a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml index ab66d3f0c476..91a98ccd4226 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml @@ -10,9 +10,6 @@ maintainers: - Wolfram Sang <wsa+renesas@sang-engineering.com> - Geert Uytterhoeven <geert+renesas@glider.be> -allOf: - - $ref: "watchdog.yaml#" - properties: compatible: oneOf: @@ -24,6 +21,11 @@ properties: - items: - enum: + - renesas,r9a07g044-wdt # RZ/G2{L,LC} + - const: renesas,rzg2l-wdt # RZ/G2L + + - items: + - enum: - renesas,r8a7742-wdt # RZ/G1H - renesas,r8a7743-wdt # RZ/G1M - renesas,r8a7744-wdt # RZ/G1N @@ -56,11 +58,13 @@ properties: reg: maxItems: 1 - interrupts: - maxItems: 1 + interrupts: true - clocks: - maxItems: 1 + interrupt-names: true + + clocks: true + + clock-names: true power-domains: maxItems: 1 @@ -75,17 +79,52 @@ required: - reg - clocks -if: - not: - properties: - compatible: - contains: - enum: - - renesas,rza-wdt -then: - required: - - power-domains - - resets +allOf: + - $ref: "watchdog.yaml#" + + - if: + not: + properties: + compatible: + contains: + enum: + - renesas,rza-wdt + then: + required: + - power-domains + - resets + + - if: + properties: + compatible: + contains: + enum: + - renesas,rzg2l-wdt + then: + properties: + interrupts: + maxItems: 2 + interrupt-names: + items: + - const: wdt + - const: perrout + clocks: + items: + - description: Register access clock + - description: Main clock + clock-names: + items: + - const: pclk + - const: oscclk + required: + - clock-names + - interrupt-names + else: + properties: + interrupts: + maxItems: 1 + clocks: + maxItems: 1 additionalProperties: false diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml b/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml index 76cb9586ee00..b08373336b16 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml @@ -22,25 +22,32 @@ properties: - samsung,exynos5250-wdt # for Exynos5250 - samsung,exynos5420-wdt # for Exynos5420 - samsung,exynos7-wdt # for Exynos7 + - samsung,exynos850-wdt # for Exynos850 reg: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + maxItems: 2 clock-names: - items: - - const: watchdog + minItems: 1 + maxItems: 2 interrupts: maxItems: 1 + samsung,cluster-index: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Index of CPU cluster on which watchdog is running (in case of Exynos850) + samsung,syscon-phandle: $ref: /schemas/types.yaml#/definitions/phandle description: - Phandle to the PMU system controller node (in case of Exynos5250 - and Exynos5420). + Phandle to the PMU system controller node (in case of Exynos5250, + Exynos5420, Exynos7 and Exynos850). required: - compatible @@ -58,9 +65,40 @@ allOf: enum: - samsung,exynos5250-wdt - samsung,exynos5420-wdt + - samsung,exynos7-wdt + - samsung,exynos850-wdt then: required: - samsung,syscon-phandle + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos850-wdt + then: + properties: + clocks: + items: + - description: Bus clock, used for register interface + - description: Source clock (driving watchdog counter) + clock-names: + items: + - const: watchdog + - const: watchdog_src + samsung,cluster-index: + enum: [0, 1] + required: + - samsung,cluster-index + else: + properties: + clocks: + items: + - description: Bus clock, which is also a source clock + clock-names: + items: + - const: watchdog + samsung,cluster-index: false unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml b/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml index 054584d7543a..2f33635876ff 100644 --- a/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml @@ -34,12 +34,6 @@ properties: power-domains: maxItems: 1 - assigned-clocks: - maxItems: 1 - - assigned-clocks-parents: - maxItems: 1 - required: - compatible - reg diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index e445cb146efe..bb36f18ae9ac 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -138,6 +138,17 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose output. +It is also possible to pass an extra DOCS_CSS overlay file, in order to customize +the html layout, by using the ``DOCS_CSS`` make variable. + +By default, the build will try to use the Read the Docs sphinx theme: + + https://github.com/readthedocs/sphinx_rtd_theme + +If the theme is not available, it will fall-back to the classic one. + +The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. + To remove the generated documentation, run ``make cleandocs``. Writing Documentation @@ -250,12 +261,11 @@ please feel free to remove it. list tables ----------- -We recommend the use of *list table* formats. The *list table* formats are -double-stage lists. Compared to the ASCII-art they might not be as -comfortable for -readers of the text files. Their advantage is that they are easy to -create or modify and that the diff of a modification is much more meaningful, -because it is limited to the modified content. +The list-table formats can be useful for tables that are not easily laid +out in the usual Sphinx ASCII-art formats. These formats are nearly +impossible for readers of the plain-text documents to understand, though, +and should be avoided in the absence of a strong justification for their +use. The ``flat-table`` is a double-stage list similar to the ``list-table`` with some additional features: diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index ef902daf0d68..cec84908fbc0 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -6,231 +6,45 @@ Auxiliary Bus ============= -In some subsystems, the functionality of the core device (PCI/ACPI/other) is -too complex for a single device to be managed by a monolithic driver -(e.g. Sound Open Firmware), multiple devices might implement a common -intersection of functionality (e.g. NICs + RDMA), or a driver may want to -export an interface for another subsystem to drive (e.g. SIOV Physical Function -export Virtual Function management). A split of the functionality into child- -devices representing sub-domains of functionality makes it possible to -compartmentalize, layer, and distribute domain-specific concerns via a Linux -device-driver model. - -An example for this kind of requirement is the audio subsystem where a single -IP is handling multiple entities such as HDMI, Soundwire, local devices such as -mics/speakers etc. The split for the core's functionality can be arbitrary or -be defined by the DSP firmware topology and include hooks for test/debug. This -allows for the audio core device to be minimal and focused on hardware-specific -control and communication. - -Each auxiliary_device represents a part of its parent functionality. The -generic behavior can be extended and specialized as needed by encapsulating an -auxiliary_device within other domain-specific structures and the use of .ops -callbacks. Devices on the auxiliary bus do not share any structures and the use -of a communication channel with the parent is domain-specific. - -Note that ops are intended as a way to augment instance behavior within a class -of auxiliary devices, it is not the mechanism for exporting common -infrastructure from the parent. Consider EXPORT_SYMBOL_NS() to convey -infrastructure from the parent module to the auxiliary module(s). - +.. kernel-doc:: drivers/base/auxiliary.c + :doc: PURPOSE When Should the Auxiliary Bus Be Used ===================================== -The auxiliary bus is to be used when a driver and one or more kernel modules, -who share a common header file with the driver, need a mechanism to connect and -provide access to a shared object allocated by the auxiliary_device's -registering driver. The registering driver for the auxiliary_device(s) and the -kernel module(s) registering auxiliary_drivers can be from the same subsystem, -or from multiple subsystems. - -The emphasis here is on a common generic interface that keeps subsystem -customization out of the bus infrastructure. - -One example is a PCI network device that is RDMA-capable and exports a child -device to be driven by an auxiliary_driver in the RDMA subsystem. The PCI -driver allocates and registers an auxiliary_device for each physical -function on the NIC. The RDMA driver registers an auxiliary_driver that claims -each of these auxiliary_devices. This conveys data/ops published by the parent -PCI device/driver to the RDMA auxiliary_driver. - -Another use case is for the PCI device to be split out into multiple sub -functions. For each sub function an auxiliary_device is created. A PCI sub -function driver binds to such devices that creates its own one or more class -devices. A PCI sub function auxiliary device is likely to be contained in a -struct with additional attributes such as user defined sub function number and -optional attributes such as resources and a link to the parent device. These -attributes could be used by systemd/udev; and hence should be initialized -before a driver binds to an auxiliary_device. - -A key requirement for utilizing the auxiliary bus is that there is no -dependency on a physical bus, device, register accesses or regmap support. -These individual devices split from the core cannot live on the platform bus as -they are not physical devices that are controlled by DT/ACPI. The same -argument applies for not using MFD in this scenario as MFD relies on individual -function devices being physical devices. - -Auxiliary Device -================ - -An auxiliary_device represents a part of its parent device's functionality. It -is given a name that, combined with the registering drivers KBUILD_MODNAME, -creates a match_name that is used for driver binding, and an id that combined -with the match_name provide a unique name to register with the bus subsystem. - -Registering an auxiliary_device is a two-step process. First call -auxiliary_device_init(), which checks several aspects of the auxiliary_device -struct and performs a device_initialize(). After this step completes, any -error state must have a call to auxiliary_device_uninit() in its resolution path. -The second step in registering an auxiliary_device is to perform a call to -auxiliary_device_add(), which sets the name of the device and add the device to -the bus. - -Unregistering an auxiliary_device is also a two-step process to mirror the -register process. First call auxiliary_device_delete(), then call -auxiliary_device_uninit(). - -.. code-block:: c - - struct auxiliary_device { - struct device dev; - const char *name; - u32 id; - }; - -If two auxiliary_devices both with a match_name "mod.foo" are registered onto -the bus, they must have unique id values (e.g. "x" and "y") so that the -registered devices names are "mod.foo.x" and "mod.foo.y". If match_name + id -are not unique, then the device_add fails and generates an error message. - -The auxiliary_device.dev.type.release or auxiliary_device.dev.release must be -populated with a non-NULL pointer to successfully register the auxiliary_device. - -The auxiliary_device.dev.parent must also be populated. +.. kernel-doc:: drivers/base/auxiliary.c + :doc: USAGE + + +Auxiliary Device Creation +========================= + +.. kernel-doc:: include/linux/auxiliary_bus.h + :identifiers: auxiliary_device + +.. kernel-doc:: drivers/base/auxiliary.c + :identifiers: auxiliary_device_init __auxiliary_device_add + auxiliary_find_device Auxiliary Device Memory Model and Lifespan ------------------------------------------ -The registering driver is the entity that allocates memory for the -auxiliary_device and register it on the auxiliary bus. It is important to note -that, as opposed to the platform bus, the registering driver is wholly -responsible for the management for the memory used for the driver object. - -A parent object, defined in the shared header file, contains the -auxiliary_device. It also contains a pointer to the shared object(s), which -also is defined in the shared header. Both the parent object and the shared -object(s) are allocated by the registering driver. This layout allows the -auxiliary_driver's registering module to perform a container_of() call to go -from the pointer to the auxiliary_device, that is passed during the call to the -auxiliary_driver's probe function, up to the parent object, and then have -access to the shared object(s). - -The memory for the auxiliary_device is freed only in its release() callback -flow as defined by its registering driver. - -The memory for the shared object(s) must have a lifespan equal to, or greater -than, the lifespan of the memory for the auxiliary_device. The auxiliary_driver -should only consider that this shared object is valid as long as the -auxiliary_device is still registered on the auxiliary bus. It is up to the -registering driver to manage (e.g. free or keep available) the memory for the -shared object beyond the life of the auxiliary_device. - -The registering driver must unregister all auxiliary devices before its own -driver.remove() is completed. +.. kernel-doc:: include/linux/auxiliary_bus.h + :doc: DEVICE_LIFESPAN + Auxiliary Drivers ================= -Auxiliary drivers follow the standard driver model convention, where -discovery/enumeration is handled by the core, and drivers -provide probe() and remove() methods. They support power management -and shutdown notifications using the standard conventions. - -.. code-block:: c +.. kernel-doc:: include/linux/auxiliary_bus.h + :identifiers: auxiliary_driver module_auxiliary_driver - struct auxiliary_driver { - int (*probe)(struct auxiliary_device *, - const struct auxiliary_device_id *id); - void (*remove)(struct auxiliary_device *); - void (*shutdown)(struct auxiliary_device *); - int (*suspend)(struct auxiliary_device *, pm_message_t); - int (*resume)(struct auxiliary_device *); - struct device_driver driver; - const struct auxiliary_device_id *id_table; - }; - -Auxiliary drivers register themselves with the bus by calling -auxiliary_driver_register(). The id_table contains the match_names of auxiliary -devices that a driver can bind with. +.. kernel-doc:: drivers/base/auxiliary.c + :identifiers: __auxiliary_driver_register auxiliary_driver_unregister Example Usage ============= -Auxiliary devices are created and registered by a subsystem-level core device -that needs to break up its functionality into smaller fragments. One way to -extend the scope of an auxiliary_device is to encapsulate it within a domain- -pecific structure defined by the parent device. This structure contains the -auxiliary_device and any associated shared data/callbacks needed to establish -the connection with the parent. - -An example is: - -.. code-block:: c - - struct foo { - struct auxiliary_device auxdev; - void (*connect)(struct auxiliary_device *auxdev); - void (*disconnect)(struct auxiliary_device *auxdev); - void *data; - }; - -The parent device then registers the auxiliary_device by calling -auxiliary_device_init(), and then auxiliary_device_add(), with the pointer to -the auxdev member of the above structure. The parent provides a name for the -auxiliary_device that, combined with the parent's KBUILD_MODNAME, creates a -match_name that is be used for matching and binding with a driver. - -Whenever an auxiliary_driver is registered, based on the match_name, the -auxiliary_driver's probe() is invoked for the matching devices. The -auxiliary_driver can also be encapsulated inside custom drivers that make the -core device's functionality extensible by adding additional domain-specific ops -as follows: - -.. code-block:: c - - struct my_ops { - void (*send)(struct auxiliary_device *auxdev); - void (*receive)(struct auxiliary_device *auxdev); - }; - - - struct my_driver { - struct auxiliary_driver auxiliary_drv; - const struct my_ops ops; - }; - -An example of this type of usage is: - -.. code-block:: c - - const struct auxiliary_device_id my_auxiliary_id_table[] = { - { .name = "foo_mod.foo_dev" }, - { }, - }; - - const struct my_ops my_custom_ops = { - .send = my_tx, - .receive = my_rx, - }; - - const struct my_driver my_drv = { - .auxiliary_drv = { - .name = "myauxiliarydrv", - .id_table = my_auxiliary_id_table, - .probe = my_probe, - .remove = my_remove, - .shutdown = my_shutdown, - }, - .ops = my_custom_ops, - }; +.. kernel-doc:: drivers/base/auxiliary.c + :doc: EXAMPLE + diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index ee268d445d38..cf9859cd0b43 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -6,6 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com> This small document introduces how to test DMA drivers using dmatest module. +The dmatest module tests DMA memcpy, memset, XOR and RAID6 P+Q operations using +various lengths and various offsets into the source and destination buffers. It +will initialize both buffers with a repeatable pattern and verify that the DMA +engine copies the requested region and nothing more. It will also verify that +the bytes aren't swapped around, and that the source buffer isn't modified. + +The dmatest module can be configured to test a specific channel. It can also +test multiple channels at the same time, and it can start multiple threads +competing for the same channel. + .. note:: The test suite works only on the channels that have at least one capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET @@ -143,13 +153,14 @@ Part 5 - Handling channel allocation Allocating Channels ------------------- -Channels are required to be configured prior to starting the test run. -Attempting to run the test without configuring the channels will fail. +Channels do not need to be configured prior to starting a test run. Attempting +to run the test without configuring the channels will result in testing any +channels that are available. Example:: % echo 1 > /sys/module/dmatest/parameters/run - dmatest: Could not start test, no channels configured + dmatest: No channels configured, continue with any Channels are registered using the "channel" parameter. Channels can be requested by their name, once requested, the channel is registered and a pending thread is added to the test list. diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index ddb0a81a796c..0072c9c7efd3 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -162,6 +162,29 @@ Currently, the types available are: - The device is able to do memory to memory copies +- - DMA_MEMCPY_SG + + - The device supports memory to memory scatter-gather transfers. + + - Even though a plain memcpy can look like a particular case of a + scatter-gather transfer, with a single chunk to copy, it's a distinct + transaction type in the mem2mem transfer case. This is because some very + simple devices might be able to do contiguous single-chunk memory copies, + but have no support for more complex SG transfers. + + - No matter what the overall size of the combined chunks for source and + destination is, only as many bytes as the smallest of the two will be + transmitted. That means the number and size of the scatter-gather buffers in + both lists need not be the same, and that the operation functionally is + equivalent to a ``strncpy`` where the ``count`` argument equals the smallest + total size of the two scatter-gather list buffers. + + - It's usually used for copying pixel data between host memory and + memory-mapped GPU device memory, such as found on modern PCI video graphics + cards. The most immediate example is the OpenGL API function + ``glReadPielx()``, which might require a verbatim copy of a huge framebuffer + from local device memory onto host memory. + - DMA_XOR - The device is able to perform XOR operations on memory areas diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst index 94a2d7f01d99..d3cfa73cbb2b 100644 --- a/Documentation/driver-api/firewire.rst +++ b/Documentation/driver-api/firewire.rst @@ -19,7 +19,7 @@ of kernel interfaces is available via exported symbols in `firewire-core` module Firewire char device data structures ==================================== -.. include:: /ABI/stable/firewire-cdev +.. include:: ../ABI/stable/firewire-cdev :literal: .. kernel-doc:: include/uapi/linux/firewire-cdev.h @@ -28,7 +28,7 @@ Firewire char device data structures Firewire device probing and sysfs interfaces ============================================ -.. include:: /ABI/stable/sysfs-bus-firewire +.. include:: ../ABI/stable/sysfs-bus-firewire :literal: .. kernel-doc:: drivers/firewire/core-device.c diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst index 8d650b4e2ce6..604208534095 100644 --- a/Documentation/driver-api/fpga/fpga-bridge.rst +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -6,8 +6,7 @@ API to implement a new FPGA bridge * struct fpga_bridge - The FPGA Bridge structure * struct fpga_bridge_ops - Low level Bridge driver ops -* devm_fpga_bridge_create() - Allocate and init a bridge struct -* fpga_bridge_register() - Register a bridge +* fpga_bridge_register() - Create and register a bridge * fpga_bridge_unregister() - Unregister a bridge .. kernel-doc:: include/linux/fpga/fpga-bridge.h @@ -17,9 +16,6 @@ API to implement a new FPGA bridge :functions: fpga_bridge_ops .. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: devm_fpga_bridge_create - -.. kernel-doc:: drivers/fpga/fpga-bridge.c :functions: fpga_bridge_register .. kernel-doc:: drivers/fpga/fpga-bridge.c diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index 4d926b452cb3..42c01f396dce 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -24,7 +24,7 @@ How to support a new FPGA device -------------------------------- To add another FPGA manager, write a driver that implements a set of ops. The -probe function calls fpga_mgr_register(), such as:: +probe function calls fpga_mgr_register() or fpga_mgr_register_full(), such as:: static const struct fpga_manager_ops socfpga_fpga_ops = { .write_init = socfpga_fpga_ops_configure_init, @@ -49,14 +49,14 @@ probe function calls fpga_mgr_register(), such as:: * them in priv */ - mgr = devm_fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager", - &socfpga_fpga_ops, priv); - if (!mgr) - return -ENOMEM; + mgr = fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); + if (IS_ERR(mgr)) + return PTR_ERR(mgr); platform_set_drvdata(pdev, mgr); - return fpga_mgr_register(mgr); + return 0; } static int socfpga_fpga_remove(struct platform_device *pdev) @@ -68,6 +68,11 @@ probe function calls fpga_mgr_register(), such as:: return 0; } +Alternatively, the probe function could call one of the resource managed +register functions, devm_fpga_mgr_register() or devm_fpga_mgr_register_full(). +When these functions are used, the parameter syntax is the same, but the call +to fpga_mgr_unregister() should be removed. In the above example, the +socfpga_fpga_remove() function would not be required. The ops will implement whatever device specific register writes are needed to do the programming sequence for this particular FPGA. These ops return 0 for @@ -104,8 +109,14 @@ API for implementing a new FPGA Manager driver * ``fpga_mgr_states`` - Values for :c:expr:`fpga_manager->state`. * struct fpga_manager - the FPGA manager struct * struct fpga_manager_ops - Low level FPGA manager driver ops -* devm_fpga_mgr_create() - Allocate and init a manager struct -* fpga_mgr_register() - Register an FPGA manager +* struct fpga_manager_info - Parameter structure for fpga_mgr_register_full() +* fpga_mgr_register_full() - Create and register an FPGA manager using the + fpga_mgr_info structure to provide the full flexibility of options +* fpga_mgr_register() - Create and register an FPGA manager using standard + arguments +* devm_fpga_mgr_register_full() - Resource managed version of + fpga_mgr_register_full() +* devm_fpga_mgr_register() - Resource managed version of fpga_mgr_register() * fpga_mgr_unregister() - Unregister an FPGA manager .. kernel-doc:: include/linux/fpga/fpga-mgr.h @@ -117,11 +128,20 @@ API for implementing a new FPGA Manager driver .. kernel-doc:: include/linux/fpga/fpga-mgr.h :functions: fpga_manager_ops +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_manager_info + .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: devm_fpga_mgr_create + :functions: fpga_mgr_register_full .. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: devm_fpga_mgr_register_full + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: devm_fpga_mgr_register + +.. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_unregister diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst index 2636a27c11b2..dc55d60a0b4a 100644 --- a/Documentation/driver-api/fpga/fpga-region.rst +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -46,8 +46,11 @@ API to add a new FPGA region ---------------------------- * struct fpga_region - The FPGA region struct -* devm_fpga_region_create() - Allocate and init a region struct -* fpga_region_register() - Register an FPGA region +* struct fpga_region_info - Parameter structure for fpga_region_register_full() +* fpga_region_register_full() - Create and register an FPGA region using the + fpga_region_info structure to provide the full flexibility of options +* fpga_region_register() - Create and register an FPGA region using standard + arguments * fpga_region_unregister() - Unregister an FPGA region The FPGA region's probe function will need to get a reference to the FPGA @@ -75,8 +78,11 @@ following APIs to handle building or tearing down that list. .. kernel-doc:: include/linux/fpga/fpga-region.h :functions: fpga_region +.. kernel-doc:: include/linux/fpga/fpga-region.h + :functions: fpga_region_info + .. kernel-doc:: drivers/fpga/fpga-region.c - :functions: devm_fpga_region_create + :functions: fpga_region_register_full .. kernel-doc:: drivers/fpga/fpga-region.c :functions: fpga_region_register diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst index 1b487a331467..71ccc30e586b 100644 --- a/Documentation/driver-api/generic-counter.rst +++ b/Documentation/driver-api/generic-counter.rst @@ -262,11 +262,11 @@ order to communicate with the device: to read and write various Signals and Counts, and to set and get the "action mode" and "function mode" for various Synapses and Counts respectively. -A defined counter_device structure may be registered to the system by -passing it to the counter_register function, and unregistered by passing -it to the counter_unregister function. Similarly, the -devm_counter_register function may be used if device memory-managed -registration is desired. +A counter_device structure is allocated using counter_alloc() and then +registered to the system by passing it to the counter_add() function, and +unregistered by passing it to the counter_unregister function. There are +device managed variants of these functions: devm_counter_alloc() and +devm_counter_add(). The struct counter_comp structure is used to define counter extensions for Signals, Synapses, and Counts. diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index 191fa867826a..4e3adf31c8d1 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -71,14 +71,14 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:: Device (FOO) { Name (_CRS, ResourceTemplate () { - GpioIo (Exclusive, ..., IoRestrictionOutputOnly, - "\\_SB.GPI0") {15} // red - GpioIo (Exclusive, ..., IoRestrictionOutputOnly, - "\\_SB.GPI0") {16} // green - GpioIo (Exclusive, ..., IoRestrictionOutputOnly, - "\\_SB.GPI0") {17} // blue - GpioIo (Exclusive, ..., IoRestrictionOutputOnly, - "\\_SB.GPI0") {1} // power + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, + "\\_SB.GPI0", 0, ResourceConsumer) { 15 } // red + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, + "\\_SB.GPI0", 0, ResourceConsumer) { 16 } // green + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, + "\\_SB.GPI0", 0, ResourceConsumer) { 17 } // blue + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly, + "\\_SB.GPI0", 0, ResourceConsumer) { 1 } // power }) Name (_DSD, Package () { @@ -92,10 +92,7 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:: ^FOO, 2, 0, 1, } }, - Package () { - "power-gpios", - Package () {^FOO, 3, 0, 0}, - }, + Package () { "power-gpios", Package () { ^FOO, 3, 0, 0 } }, } }) } diff --git a/Documentation/driver-api/mtd/index.rst b/Documentation/driver-api/mtd/index.rst index 436ba5a851d7..6a4278f409d7 100644 --- a/Documentation/driver-api/mtd/index.rst +++ b/Documentation/driver-api/mtd/index.rst @@ -7,6 +7,6 @@ Memory Technology Device (MTD) .. toctree:: :maxdepth: 1 - intel-spi + spi-intel nand_ecc spi-nor diff --git a/Documentation/driver-api/mtd/intel-spi.rst b/Documentation/driver-api/mtd/spi-intel.rst index 0465f6879262..df854f20ead1 100644 --- a/Documentation/driver-api/mtd/intel-spi.rst +++ b/Documentation/driver-api/mtd/spi-intel.rst @@ -1,5 +1,5 @@ ============================== -Upgrading BIOS using intel-spi +Upgrading BIOS using spi-intel ============================== Many Intel CPUs like Baytrail and Braswell include SPI serial flash host @@ -11,12 +11,12 @@ avoid accidental (or on purpose) overwrite of the content. Not all manufacturers protect the SPI serial flash, mainly because it allows upgrading the BIOS image directly from an OS. -The intel-spi driver makes it possible to read and write the SPI serial +The spi-intel driver makes it possible to read and write the SPI serial flash, if certain protection bits are not set and locked. If it finds any of them set, the whole MTD device is made read-only to prevent partial overwrites. By default the driver exposes SPI serial flash contents as read-only but it can be changed from kernel command line, -passing "intel-spi.writeable=1". +passing "spi_intel.writeable=1". Please keep in mind that overwriting the BIOS image on SPI serial flash might render the machine unbootable and requires special equipment like @@ -32,7 +32,7 @@ Linux. serial flash. Distros like Debian and Fedora have this prepackaged with name "mtd-utils". - 3) Add "intel-spi.writeable=1" to the kernel command line and reboot + 3) Add "spi_intel.writeable=1" to the kernel command line and reboot the board (you can also reload the driver passing "writeable=1" as module parameter to modprobe). diff --git a/Documentation/driver-api/pci/pci.rst b/Documentation/driver-api/pci/pci.rst index ca85e5e78b2c..4843cfad4f60 100644 --- a/Documentation/driver-api/pci/pci.rst +++ b/Documentation/driver-api/pci/pci.rst @@ -13,7 +13,7 @@ PCI Support Library .. kernel-doc:: drivers/pci/search.c :export: -.. kernel-doc:: drivers/pci/msi.c +.. kernel-doc:: drivers/pci/msi/msi.c :export: .. kernel-doc:: drivers/pci/bus.c diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 31bd4e16fb1f..06ec04ba086f 100644 --- a/Documentation/driver-api/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -311,7 +311,7 @@ hardware. This call must not sleep set_ldisc(port,termios) - Notifier for discipline change. See Documentation/driver-api/serial/tty.rst. + Notifier for discipline change. See Documentation/tty/tty_ldisc.rst. Locking: caller holds tty_port->mutex diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst index 8f7d7af3b90b..7eb21a695fc3 100644 --- a/Documentation/driver-api/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -9,7 +9,6 @@ Support for Serial devices driver - tty Serial drivers ============== diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst index 8fe723ab9c67..49956509ad73 100644 --- a/Documentation/driver-api/serial/n_gsm.rst +++ b/Documentation/driver-api/serial/n_gsm.rst @@ -18,9 +18,12 @@ How to use it 1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through its serial port. Depending on the modem used, you can pass more or less parameters to this command. + 1.2 switch the serial line to using the n_gsm line discipline by using TIOCSETD ioctl. + 1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. + 1.4 obtain base gsmtty number for the used serial port. Major parts of the initialization program : @@ -95,10 +98,13 @@ Major parts of the initialization program : 2.1 receive string "AT+CMUX= command" through its serial port,initialize mux mode config + 2.2 switch the serial line to using the n_gsm line discipline by using TIOCSETD ioctl. + 2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. -2.4 obtain base gsmtty number for the used serial port, + +2.4 obtain base gsmtty number for the used serial port:: #include <stdio.h> #include <stdint.h> diff --git a/Documentation/driver-api/serial/tty.rst b/Documentation/driver-api/serial/tty.rst deleted file mode 100644 index 4b709f392713..000000000000 --- a/Documentation/driver-api/serial/tty.rst +++ /dev/null @@ -1,328 +0,0 @@ -================= -The Lockronomicon -================= - -Your guide to the ancient and twisted locking policies of the tty layer and -the warped logic behind them. Beware all ye who read on. - - -Line Discipline ---------------- - -Line disciplines are registered with tty_register_ldisc() passing the -discipline number and the ldisc structure. At the point of registration the -discipline must be ready to use and it is possible it will get used before -the call returns success. If the call returns an error then it won't get -called. Do not re-use ldisc numbers as they are part of the userspace ABI -and writing over an existing ldisc will cause demons to eat your computer. -After the return the ldisc data has been copied so you may free your own -copy of the structure. You must not re-register over the top of the line -discipline even with the same data or your computer again will be eaten by -demons. - -In order to remove a line discipline call tty_unregister_ldisc(). -In ancient times this always worked. In modern times the function will -return -EBUSY if the ldisc is currently in use. Since the ldisc referencing -code manages the module counts this should not usually be a concern. - -Heed this warning: the reference count field of the registered copies of the -tty_ldisc structure in the ldisc table counts the number of lines using this -discipline. The reference count of the tty_ldisc structure within a tty -counts the number of active users of the ldisc at this instant. In effect it -counts the number of threads of execution within an ldisc method (plus those -about to enter and exit although this detail matters not). - -Line Discipline Methods ------------------------ - -TTY side interfaces -^^^^^^^^^^^^^^^^^^^ - -======================= ======================================================= -open() Called when the line discipline is attached to - the terminal. No other call into the line - discipline for this tty will occur until it - completes successfully. Should initialize any - state needed by the ldisc, and set receive_room - in the tty_struct to the maximum amount of data - the line discipline is willing to accept from the - driver with a single call to receive_buf(). - Returning an error will prevent the ldisc from - being attached. Can sleep. - -close() This is called on a terminal when the line - discipline is being unplugged. At the point of - execution no further users will enter the - ldisc code for this tty. Can sleep. - -hangup() Called when the tty line is hung up. - The line discipline should cease I/O to the tty. - No further calls into the ldisc code will occur. - Can sleep. - -read() (optional) A process requests reading data from - the line. Multiple read calls may occur in parallel - and the ldisc must deal with serialization issues. - If not defined, the process will receive an EIO - error. May sleep. - -write() (optional) A process requests writing data to the - line. Multiple write calls are serialized by the - tty layer for the ldisc. If not defined, the - process will receive an EIO error. May sleep. - -flush_buffer() (optional) May be called at any point between - open and close, and instructs the line discipline - to empty its input buffer. - -set_termios() (optional) Called on termios structure changes. - The caller passes the old termios data and the - current data is in the tty. Called under the - termios semaphore so allowed to sleep. Serialized - against itself only. - -poll() (optional) Check the status for the poll/select - calls. Multiple poll calls may occur in parallel. - May sleep. - -ioctl() (optional) Called when an ioctl is handed to the - tty layer that might be for the ldisc. Multiple - ioctl calls may occur in parallel. May sleep. - -compat_ioctl() (optional) Called when a 32 bit ioctl is handed - to the tty layer that might be for the ldisc. - Multiple ioctl calls may occur in parallel. - May sleep. -======================= ======================================================= - -Driver Side Interfaces -^^^^^^^^^^^^^^^^^^^^^^ - -======================= ======================================================= -receive_buf() (optional) Called by the low-level driver to hand - a buffer of received bytes to the ldisc for - processing. The number of bytes is guaranteed not - to exceed the current value of tty->receive_room. - All bytes must be processed. - -receive_buf2() (optional) Called by the low-level driver to hand - a buffer of received bytes to the ldisc for - processing. Returns the number of bytes processed. - - If both receive_buf() and receive_buf2() are - defined, receive_buf2() should be preferred. - -write_wakeup() May be called at any point between open and close. - The TTY_DO_WRITE_WAKEUP flag indicates if a call - is needed but always races versus calls. Thus the - ldisc must be careful about setting order and to - handle unexpected calls. Must not sleep. - - The driver is forbidden from calling this directly - from the ->write call from the ldisc as the ldisc - is permitted to call the driver write method from - this function. In such a situation defer it. - -dcd_change() Report to the tty line the current DCD pin status - changes and the relative timestamp. The timestamp - cannot be NULL. -======================= ======================================================= - - -Driver Access -^^^^^^^^^^^^^ - -Line discipline methods can call the following methods of the underlying -hardware driver through the function pointers within the tty->driver -structure: - -======================= ======================================================= -write() Write a block of characters to the tty device. - Returns the number of characters accepted. The - character buffer passed to this method is already - in kernel space. - -put_char() Queues a character for writing to the tty device. - If there is no room in the queue, the character is - ignored. - -flush_chars() (Optional) If defined, must be called after - queueing characters with put_char() in order to - start transmission. - -write_room() Returns the numbers of characters the tty driver - will accept for queueing to be written. - -ioctl() Invoke device specific ioctl. - Expects data pointers to refer to userspace. - Returns ENOIOCTLCMD for unrecognized ioctl numbers. - -set_termios() Notify the tty driver that the device's termios - settings have changed. New settings are in - tty->termios. Previous settings should be passed in - the "old" argument. - - The API is defined such that the driver should return - the actual modes selected. This means that the - driver function is responsible for modifying any - bits in the request it cannot fulfill to indicate - the actual modes being used. A device with no - hardware capability for change (e.g. a USB dongle or - virtual port) can provide NULL for this method. - -throttle() Notify the tty driver that input buffers for the - line discipline are close to full, and it should - somehow signal that no more characters should be - sent to the tty. - -unthrottle() Notify the tty driver that characters can now be - sent to the tty without fear of overrunning the - input buffers of the line disciplines. - -stop() Ask the tty driver to stop outputting characters - to the tty device. - -start() Ask the tty driver to resume sending characters - to the tty device. - -hangup() Ask the tty driver to hang up the tty device. - -break_ctl() (Optional) Ask the tty driver to turn on or off - BREAK status on the RS-232 port. If state is -1, - then the BREAK status should be turned on; if - state is 0, then BREAK should be turned off. - If this routine is not implemented, use ioctls - TIOCSBRK / TIOCCBRK instead. - -wait_until_sent() Waits until the device has written out all of the - characters in its transmitter FIFO. - -send_xchar() Send a high-priority XON/XOFF character to the device. -======================= ======================================================= - - -Flags -^^^^^ - -Line discipline methods have access to tty->flags field containing the -following interesting flags: - -======================= ======================================================= -TTY_THROTTLED Driver input is throttled. The ldisc should call - tty->driver->unthrottle() in order to resume - reception when it is ready to process more data. - -TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's - write_wakeup() method in order to resume - transmission when it can accept more data - to transmit. - -TTY_IO_ERROR If set, causes all subsequent userspace read/write - calls on the tty to fail, returning -EIO. - -TTY_OTHER_CLOSED Device is a pty and the other side has closed. - -TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into - smaller chunks. -======================= ======================================================= - - -Locking -^^^^^^^ - -Callers to the line discipline functions from the tty layer are required to -take line discipline locks. The same is true of calls from the driver side -but not yet enforced. - -Three calls are now provided:: - - ldisc = tty_ldisc_ref(tty); - -takes a handle to the line discipline in the tty and returns it. If no ldisc -is currently attached or the ldisc is being closed and re-opened at this -point then NULL is returned. While this handle is held the ldisc will not -change or go away:: - - tty_ldisc_deref(ldisc) - -Returns the ldisc reference and allows the ldisc to be closed. Returning the -reference takes away your right to call the ldisc functions until you take -a new reference:: - - ldisc = tty_ldisc_ref_wait(tty); - -Performs the same function as tty_ldisc_ref except that it will wait for an -ldisc change to complete and then return a reference to the new ldisc. - -While these functions are slightly slower than the old code they should have -minimal impact as most receive logic uses the flip buffers and they only -need to take a reference when they push bits up through the driver. - -A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc -functions are called with the ldisc unavailable. Thus tty_ldisc_ref will -fail in this situation if used within these functions. Ldisc and driver -code calling its own functions must be careful in this case. - - -Driver Interface ----------------- - -======================= ======================================================= -open() Called when a device is opened. May sleep - -close() Called when a device is closed. At the point of - return from this call the driver must make no - further ldisc calls of any kind. May sleep - -write() Called to write bytes to the device. May not - sleep. May occur in parallel in special cases. - Because this includes panic paths drivers generally - shouldn't try and do clever locking here. - -put_char() Stuff a single character onto the queue. The - driver is guaranteed following up calls to - flush_chars. - -flush_chars() Ask the kernel to write put_char queue - -write_room() Return the number of characters that can be stuffed - into the port buffers without overflow (or less). - The ldisc is responsible for being intelligent - about multi-threading of write_room/write calls - -ioctl() Called when an ioctl may be for the driver - -set_termios() Called on termios change, serialized against - itself by a semaphore. May sleep. - -set_ldisc() Notifier for discipline change. At the point this - is done the discipline is not yet usable. Can now - sleep (I think) - -throttle() Called by the ldisc to ask the driver to do flow - control. Serialization including with unthrottle - is the job of the ldisc layer. - -unthrottle() Called by the ldisc to ask the driver to stop flow - control. - -stop() Ldisc notifier to the driver to stop output. As with - throttle the serializations with start() are down - to the ldisc layer. - -start() Ldisc notifier to the driver to start output. - -hangup() Ask the tty driver to cause a hangup initiated - from the host side. [Can sleep ??] - -break_ctl() Send RS232 break. Can sleep. Can get called in - parallel, driver must serialize (for now), and - with write calls. - -wait_until_sent() Wait for characters to exit the hardware queue - of the driver. Can sleep - -send_xchar() Send XON/XOFF and if possible jump the queue with - it in order to get fast flow control responses. - Cannot sleep ?? -======================= ======================================================= diff --git a/Documentation/driver-api/thermal/index.rst b/Documentation/driver-api/thermal/index.rst index 4cb0b9b6bfb8..030306ffa408 100644 --- a/Documentation/driver-api/thermal/index.rst +++ b/Documentation/driver-api/thermal/index.rst @@ -17,3 +17,4 @@ Thermal intel_powerclamp nouveau_thermal x86_pkg_temperature_thermal + intel_dptf diff --git a/Documentation/driver-api/thermal/intel_dptf.rst b/Documentation/driver-api/thermal/intel_dptf.rst new file mode 100644 index 000000000000..96668dca753a --- /dev/null +++ b/Documentation/driver-api/thermal/intel_dptf.rst @@ -0,0 +1,272 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================================== +Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface +=============================================================== + +:Copyright: |copy| 2022 Intel Corporation + +:Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> + +Introduction +------------ + +Intel(R) Dynamic Platform and Thermal Framework (DPTF) is a platform +level hardware/software solution for power and thermal management. + +As a container for multiple power/thermal technologies, DPTF provides +a coordinated approach for different policies to effect the hardware +state of a system. + +Since it is a platform level framework, this has several components. +Some parts of the technology is implemented in the firmware and uses +ACPI and PCI devices to expose various features for monitoring and +control. Linux has a set of kernel drivers exposing hardware interface +to user space. This allows user space thermal solutions like +"Linux Thermal Daemon" to read platform specific thermal and power +tables to deliver adequate performance while keeping the system under +thermal limits. + +DPTF ACPI Drivers interface +---------------------------- + +:file:`/sys/bus/platform/devices/<N>/uuids`, where <N> +=INT3400|INTC1040|INTC1041|INTC10A0 + +``available_uuids`` (RO) + A set of UUIDs strings presenting available policies + which should be notified to the firmware when the + user space can support those policies. + + UUID strings: + + "42A441D6-AE6A-462b-A84B-4A8CE79027D3" : Passive 1 + + "3A95C389-E4B8-4629-A526-C52C88626BAE" : Active + + "97C68AE7-15FA-499c-B8C9-5DA81D606E0A" : Critical + + "63BE270F-1C11-48FD-A6F7-3AF253FF3E2D" : Adaptive performance + + "5349962F-71E6-431D-9AE8-0A635B710AEE" : Emergency call + + "9E04115A-AE87-4D1C-9500-0F3E340BFE75" : Passive 2 + + "F5A35014-C209-46A4-993A-EB56DE7530A1" : Power Boss + + "6ED722A7-9240-48A5-B479-31EEF723D7CF" : Virtual Sensor + + "16CAF1B7-DD38-40ED-B1C1-1B8A1913D531" : Cooling mode + + "BE84BABF-C4D4-403D-B495-3128FD44dAC1" : HDC + +``current_uuid`` (RW) + User space can write strings from available UUIDs, one at a + time. + +:file:`/sys/bus/platform/devices/<N>/`, where <N> +=INT3400|INTC1040|INTC1041|INTC10A0 + +``imok`` (WO) + User space daemon write 1 to respond to firmware event + for sending keep alive notification. User space receives + THERMAL_EVENT_KEEP_ALIVE kobject uevent notification when + firmware calls for user space to respond with imok ACPI + method. + +``odvp*`` (RO) + Firmware thermal status variable values. Thermal tables + calls for different processing based on these variable + values. + +``data_vault`` (RO) + Binary thermal table. Refer to + https:/github.com/intel/thermal_daemon for decoding + thermal table. + + +ACPI Thermal Relationship table interface +------------------------------------------ + +:file:`/dev/acpi_thermal_rel` + + This device provides IOCTL interface to read standard ACPI + thermal relationship tables via ACPI methods _TRT and _ART. + These IOCTLs are defined in + drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h + + IOCTLs: + + ACPI_THERMAL_GET_TRT_LEN: Get length of TRT table + + ACPI_THERMAL_GET_ART_LEN: Get length of ART table + + ACPI_THERMAL_GET_TRT_COUNT: Number of records in TRT table + + ACPI_THERMAL_GET_ART_COUNT: Number of records in ART table + + ACPI_THERMAL_GET_TRT: Read binary TRT table, length to read is + provided via argument to ioctl(). + + ACPI_THERMAL_GET_ART: Read binary ART table, length to read is + provided via argument to ioctl(). + +DPTF ACPI Sensor drivers +------------------------- + +DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone. + + +DPTF ACPI Cooling drivers +-------------------------- + +DPTF cooling drivers are presented as standard thermal sysfs cooling_device. + + +DPTF Processor thermal PCI Driver interface +-------------------------------------------- + +:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/` + +Refer to Documentation/power/powercap/powercap.rst for powercap +ABI. + +``power_limit_0_max_uw`` (RO) + Maximum powercap sysfs constraint_0_power_limit_uw for Intel RAPL + +``power_limit_0_step_uw`` (RO) + Power limit increment/decrements for Intel RAPL constraint 0 power limit + +``power_limit_0_min_uw`` (RO) + Minimum powercap sysfs constraint_0_power_limit_uw for Intel RAPL + +``power_limit_0_tmin_us`` (RO) + Minimum powercap sysfs constraint_0_time_window_us for Intel RAPL + +``power_limit_0_tmax_us`` (RO) + Maximum powercap sysfs constraint_0_time_window_us for Intel RAPL + +``power_limit_1_max_uw`` (RO) + Maximum powercap sysfs constraint_1_power_limit_uw for Intel RAPL + +``power_limit_1_step_uw`` (RO) + Power limit increment/decrements for Intel RAPL constraint 1 power limit + +``power_limit_1_min_uw`` (RO) + Minimum powercap sysfs constraint_1_power_limit_uw for Intel RAPL + +``power_limit_1_tmin_us`` (RO) + Minimum powercap sysfs constraint_1_time_window_us for Intel RAPL + +``power_limit_1_tmax_us`` (RO) + Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL + +:file:`/sys/bus/pci/devices/0000\:00\:04.0/` + +``tcc_offset_degree_celsius`` (RW) + TCC offset from the critical temperature where hardware will throttle + CPU. + +:file:`/sys/bus/pci/devices/0000\:00\:04.0/workload_request` + +``workload_available_types`` (RO) + Available workload types. User space can specify one of the workload type + it is currently executing via workload_type. For example: idle, bursty, + sustained etc. + +``workload_type`` (RW) + User space can specify any one of the available workload type using + this interface. + +DPTF Processor thermal RFIM interface +-------------------------------------------- + +RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator) +and DDR (Double Data Rate)frequencies to avoid RF interference with WiFi and 5G. + +Switching voltage regulators (VR) generate radiated EMI or RFI at the +fundamental frequency and its harmonics. Some harmonics may interfere +with very sensitive wireless receivers such as Wi-Fi and cellular that +are integrated into host systems like notebook PCs. One of mitigation +methods is requesting SOC integrated VR (IVR) switching frequency to a +small % and shift away the switching noise harmonic interference from +radio channels. OEM or ODMs can use the driver to control SOC IVR +operation within the range where it does not impact IVR performance. + +DRAM devices of DDR IO interface and their power plane can generate EMI +at the data rates. Similar to IVR control mechanism, Intel offers a +mechanism by which DDR data rates can be changed if several conditions +are met: there is strong RFI interference because of DDR; CPU power +management has no other restriction in changing DDR data rates; +PC ODMs enable this feature (real time DDR RFI Mitigation referred to as +DDR-RFIM) for Wi-Fi from BIOS. + + +FIVR attributes + +:file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/` + +``vco_ref_code_lo`` (RW) + The VCO reference code is an 11-bit field and controls the FIVR + switching frequency. This is the 3-bit LSB field. + +``vco_ref_code_hi`` (RW) + The VCO reference code is an 11-bit field and controls the FIVR + switching frequency. This is the 8-bit MSB field. + +``spread_spectrum_pct`` (RW) + Set the FIVR spread spectrum clocking percentage + +``spread_spectrum_clk_enable`` (RW) + Enable/disable of the FIVR spread spectrum clocking feature + +``rfi_vco_ref_code`` (RW) + This field is a read only status register which reflects the + current FIVR switching frequency + +``fivr_fffc_rev`` (RW) + This field indicated the revision of the FIVR HW. + + +DVFS attributes + +:file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/` + +``rfi_restriction_run_busy`` (RW) + Request the restriction of specific DDR data rate and set this + value 1. Self reset to 0 after operation. + +``rfi_restriction_err_code`` (RW) + 0 :Request is accepted, 1:Feature disabled, + 2: the request restricts more points than it is allowed + +``rfi_restriction_data_rate_Delta`` (RW) + Restricted DDR data rate for RFI protection: Lower Limit + +``rfi_restriction_data_rate_Base`` (RW) + Restricted DDR data rate for RFI protection: Upper Limit + +``ddr_data_rate_point_0`` (RO) + DDR data rate selection 1st point + +``ddr_data_rate_point_1`` (RO) + DDR data rate selection 2nd point + +``ddr_data_rate_point_2`` (RO) + DDR data rate selection 3rd point + +``ddr_data_rate_point_3`` (RO) + DDR data rate selection 4th point + +``rfi_disable (RW)`` + Disable DDR rate change feature + +DPTF Power supply and Battery Interface +---------------------------------------- + +Refer to Documentation/ABI/testing/sysfs-platform-dptf + +DPTF Fan Control +---------------------------------------- + +Refer to Documentation/admin-guide/acpi/fan_performance_states.rst diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index b43e1ce49f0e..95c4f5d14052 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -94,8 +94,8 @@ usually in the driver's init function, as shown here:: /* register this driver with the USB subsystem */ result = usb_register(&skel_driver); if (result < 0) { - err("usb_register failed for the "__FILE__ "driver." - "Error number %d", result); + pr_err("usb_register failed for the %s driver. Error number %d\n", + skel_driver.name, result); return -1; } @@ -170,8 +170,8 @@ structure. This is done so that future calls to file operations will enable the driver to determine which device the user is addressing. All of this is done with the following code:: - /* increment our usage count for the module */ - ++skel->open_count; + /* increment our usage count for the device */ + kref_get(&dev->kref); /* save our object in the file's private structure */ file->private_data = dev; @@ -188,24 +188,26 @@ space, points the urb to the data and submits the urb to the USB subsystem. This can be seen in the following code:: /* we can only write as much as 1 urb will hold */ - bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; + size_t writesize = min_t(size_t, count, MAX_TRANSFER); /* copy the data from user space into our urb */ - copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); + copy_from_user(buf, user_buffer, writesize); /* set up our urb */ - usb_fill_bulk_urb(skel->write_urb, - skel->dev, - usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), - skel->write_urb->transfer_buffer, - bytes_written, + usb_fill_bulk_urb(urb, + dev->udev, + usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr), + buf, + writesize, skel_write_bulk_callback, - skel); + dev); /* send the data out the bulk port */ - result = usb_submit_urb(skel->write_urb); - if (result) { - err("Failed submitting write urb, error %d", result); + retval = usb_submit_urb(urb, GFP_KERNEL); + if (retval) { + dev_err(&dev->interface->dev, + "%s - failed submitting write urb, error %d\n", + __func__, retval); } diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 3361e86b0958..bc74d8beea72 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -8,7 +8,7 @@ ----------------------- | alpha: | TODO | | arc: | TODO | - | arm: | TODO | + | arm: | ok | | arm64: | ok | | csky: | TODO | | h8300: | TODO | diff --git a/Documentation/filesystems/caching/backend-api.rst b/Documentation/filesystems/caching/backend-api.rst index 19fbf6b9aa36..be793c49a772 100644 --- a/Documentation/filesystems/caching/backend-api.rst +++ b/Documentation/filesystems/caching/backend-api.rst @@ -1,727 +1,479 @@ .. SPDX-License-Identifier: GPL-2.0 -========================== -FS-Cache Cache backend API -========================== +================= +Cache Backend API +================= The FS-Cache system provides an API by which actual caches can be supplied to FS-Cache for it to then serve out to network filesystems and other interested -parties. +parties. This API is used by:: -This API is declared in <linux/fscache-cache.h>. + #include <linux/fscache-cache.h>. -Initialising and Registering a Cache -==================================== - -To start off, a cache definition must be initialised and registered for each -cache the backend wants to make available. For instance, CacheFS does this in -the fill_super() operation on mounting. - -The cache definition (struct fscache_cache) should be initialised by calling:: - - void fscache_init_cache(struct fscache_cache *cache, - struct fscache_cache_ops *ops, - const char *idfmt, - ...); - -Where: - - * "cache" is a pointer to the cache definition; - - * "ops" is a pointer to the table of operations that the backend supports on - this cache; and - - * "idfmt" is a format and printf-style arguments for constructing a label - for the cache. - - -The cache should then be registered with FS-Cache by passing a pointer to the -previously initialised cache definition to:: - - int fscache_add_cache(struct fscache_cache *cache, - struct fscache_object *fsdef, - const char *tagname); - -Two extra arguments should also be supplied: - - * "fsdef" which should point to the object representation for the FS-Cache - master index in this cache. Netfs primary index entries will be created - here. FS-Cache keeps the caller's reference to the index object if - successful and will release it upon withdrawal of the cache. - - * "tagname" which, if given, should be a text string naming this cache. If - this is NULL, the identifier will be used instead. For CacheFS, the - identifier is set to name the underlying block device and the tag can be - supplied by mount. - -This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag -is already in use. 0 will be returned on success. - - -Unregistering a Cache -===================== - -A cache can be withdrawn from the system by calling this function with a -pointer to the cache definition:: - - void fscache_withdraw_cache(struct fscache_cache *cache); - -In CacheFS's case, this is called by put_super(). - - -Security +Overview ======== -The cache methods are executed one of two contexts: - - (1) that of the userspace process that issued the netfs operation that caused - the cache method to be invoked, or - - (2) that of one of the processes in the FS-Cache thread pool. - -In either case, this may not be an appropriate context in which to access the -cache. - -The calling process's fsuid, fsgid and SELinux security identities may need to -be masqueraded for the duration of the cache driver's access to the cache. -This is left to the cache to handle; FS-Cache makes no effort in this regard. - +Interaction with the API is handled on three levels: cache, volume and data +storage, and each level has its own type of cookie object: -Control and Statistics Presentation -=================================== + ======================= ======================= + COOKIE C TYPE + ======================= ======================= + Cache cookie struct fscache_cache + Volume cookie struct fscache_volume + Data storage cookie struct fscache_cookie + ======================= ======================= -The cache may present data to the outside world through FS-Cache's interfaces -in sysfs and procfs - the former for control and the latter for statistics. +Cookies are used to provide some filesystem data to the cache, manage state and +pin the cache during access in addition to acting as reference points for the +API functions. Each cookie has a debugging ID that is included in trace points +to make it easier to correlate traces. Note, though, that debugging IDs are +simply allocated from incrementing counters and will eventually wrap. -A sysfs directory called /sys/fs/fscache/<cachetag>/ is created if CONFIG_SYSFS -is enabled. This is accessible through the kobject struct fscache_cache::kobj -and is for use by the cache as it sees fit. +The cache backend and the network filesystem can both ask for cache cookies - +and if they ask for one of the same name, they'll get the same cookie. Volume +and data cookies, however, are created at the behest of the filesystem only. -Relevant Data Structures -======================== +Cache Cookies +============= - * Index/Data file FS-Cache representation cookie:: +Caches are represented in the API by cache cookies. These are objects of +type:: - struct fscache_cookie { - struct fscache_object_def *def; - struct fscache_netfs *netfs; - void *netfs_data; - ... - }; - - The fields that might be of use to the backend describe the object - definition, the netfs definition and the netfs's data for this cookie. - The object definition contain functions supplied by the netfs for loading - and matching index entries; these are required to provide some of the - cache operations. - - - * In-cache object representation:: - - struct fscache_object { - int debug_id; - enum { - FSCACHE_OBJECT_RECYCLING, - ... - } state; - spinlock_t lock - struct fscache_cache *cache; - struct fscache_cookie *cookie; + struct fscache_cache { + void *cache_priv; + unsigned int debug_id; + char *name; ... }; - Structures of this type should be allocated by the cache backend and - passed to FS-Cache when requested by the appropriate cache operation. In - the case of CacheFS, they're embedded in CacheFS's internal object - structures. +There are a few fields that the cache backend might be interested in. The +``debug_id`` can be used in tracing to match lines referring to the same cache +and ``name`` is the name the cache was registered with. The ``cache_priv`` +member is private data provided by the cache when it is brought online. The +other fields are for internal use. - The debug_id is a simple integer that can be used in debugging messages - that refer to a particular object. In such a case it should be printed - using "OBJ%x" to be consistent with FS-Cache. - Each object contains a pointer to the cookie that represents the object it - is backing. An object should retired when put_object() is called if it is - in state FSCACHE_OBJECT_RECYCLING. The fscache_object struct should be - initialised by calling fscache_object_init(object). +Registering a Cache +=================== +When a cache backend wants to bring a cache online, it should first register +the cache name and that will get it a cache cookie. This is done with:: - * FS-Cache operation record:: + struct fscache_cache *fscache_acquire_cache(const char *name); - struct fscache_operation { - atomic_t usage; - struct fscache_object *object; - unsigned long flags; - #define FSCACHE_OP_EXCLUSIVE - void (*processor)(struct fscache_operation *op); - void (*release)(struct fscache_operation *op); - ... - }; +This will look up and potentially create a cache cookie. The cache cookie may +have already been created by a network filesystem looking for it, in which case +that cache cookie will be used. If the cache cookie is not in use by another +cache, it will be moved into the preparing state, otherwise it will return +busy. - FS-Cache has a pool of threads that it uses to give CPU time to the - various asynchronous operations that need to be done as part of driving - the cache. These are represented by the above structure. The processor - method is called to give the op CPU time, and the release method to get - rid of it when its usage count reaches 0. +If successful, the cache backend can then start setting up the cache. In the +event that the initialisation fails, the cache backend should call:: - An operation can be made exclusive upon an object by setting the - appropriate flag before enqueuing it with fscache_enqueue_operation(). If - an operation needs more processing time, it should be enqueued again. + void fscache_relinquish_cookie(struct fscache_cache *cache); +to reset and discard the cookie. - * FS-Cache retrieval operation record:: - struct fscache_retrieval { - struct fscache_operation op; - struct address_space *mapping; - struct list_head *to_do; - ... - }; +Bringing a Cache Online +======================= - A structure of this type is allocated by FS-Cache to record retrieval and - allocation requests made by the netfs. This struct is then passed to the - backend to do the operation. The backend may get extra refs to it by - calling fscache_get_retrieval() and refs may be discarded by calling - fscache_put_retrieval(). +Once the cache is set up, it can be brought online by calling:: - A retrieval operation can be used by the backend to do retrieval work. To - do this, the retrieval->op.processor method pointer should be set - appropriately by the backend and fscache_enqueue_retrieval() called to - submit it to the thread pool. CacheFiles, for example, uses this to queue - page examination when it detects PG_lock being cleared. + int fscache_add_cache(struct fscache_cache *cache, + const struct fscache_cache_ops *ops, + void *cache_priv); - The to_do field is an empty list available for the cache backend to use as - it sees fit. +This stores the cache operations table pointer and cache private data into the +cache cookie and moves the cache to the active state, thereby allowing accesses +to take place. - * FS-Cache storage operation record:: +Withdrawing a Cache From Service +================================ - struct fscache_storage { - struct fscache_operation op; - pgoff_t store_limit; - ... - }; +The cache backend can withdraw a cache from service by calling this function:: - A structure of this type is allocated by FS-Cache to record outstanding - writes to be made. FS-Cache itself enqueues this operation and invokes - the write_page() method on the object at appropriate times to effect - storage. + void fscache_withdraw_cache(struct fscache_cache *cache); +This moves the cache to the withdrawn state to prevent new cache- and +volume-level accesses from starting and then waits for outstanding cache-level +accesses to complete. -Cache Operations -================ +The cache must then go through the data storage objects it has and tell fscache +to withdraw them, calling:: -The cache backend provides FS-Cache with a table of operations that can be -performed on the denizens of the cache. These are held in a structure of type: + void fscache_withdraw_cookie(struct fscache_cookie *cookie); - :: +on the cookie that each object belongs to. This schedules the specified cookie +for withdrawal. This gets offloaded to a workqueue. The cache backend can +test for completion by calling:: - struct fscache_cache_ops + bool fscache_are_objects_withdrawn(struct fscache_cookie *cache); - * Name of cache provider [mandatory]:: +Once all the cookies are withdrawn, a cache backend can withdraw all the +volumes, calling:: - const char *name + void fscache_withdraw_volume(struct fscache_volume *volume); - This isn't strictly an operation, but should be pointed at a string naming - the backend. +to tell fscache that a volume has been withdrawn. This waits for all +outstanding accesses on the volume to complete before returning. +When the the cache is completely withdrawn, fscache should be notified by +calling:: - * Allocate a new object [mandatory]:: + void fscache_cache_relinquish(struct fscache_cache *cache); - struct fscache_object *(*alloc_object)(struct fscache_cache *cache, - struct fscache_cookie *cookie) +to clear fields in the cookie and discard the caller's ref on it. - This method is used to allocate a cache object representation to back a - cookie in a particular cache. fscache_object_init() should be called on - the object to initialise it prior to returning. - This function may also be used to parse the index key to be used for - multiple lookup calls to turn it into a more convenient form. FS-Cache - will call the lookup_complete() method to allow the cache to release the - form once lookup is complete or aborted. +Volume Cookies +============== +Within a cache, the data storage objects are organised into logical volumes. +These are represented in the API as objects of type:: - * Look up and create object [mandatory]:: + struct fscache_volume { + struct fscache_cache *cache; + void *cache_priv; + unsigned int debug_id; + char *key; + unsigned int key_hash; + ... + u8 coherency_len; + u8 coherency[]; + }; - void (*lookup_object)(struct fscache_object *object) +There are a number of fields here that are of interest to the caching backend: - This method is used to look up an object, given that the object is already - allocated and attached to the cookie. This should instantiate that object - in the cache if it can. + * ``cache`` - The parent cache cookie. - The method should call fscache_object_lookup_negative() as soon as - possible if it determines the object doesn't exist in the cache. If the - object is found to exist and the netfs indicates that it is valid then - fscache_obtained_object() should be called once the object is in a - position to have data stored in it. Similarly, fscache_obtained_object() - should also be called once a non-present object has been created. + * ``cache_priv`` - A place for the cache to stash private data. - If a lookup error occurs, fscache_object_lookup_error() should be called - to abort the lookup of that object. + * ``debug_id`` - A debugging ID for logging in tracepoints. + * ``key`` - A printable string with no '/' characters in it that represents + the index key for the volume. The key is NUL-terminated and padded out to + a multiple of 4 bytes. - * Release lookup data [mandatory]:: + * ``key_hash`` - A hash of the index key. This should work out the same, no + matter the cpu arch and endianness. - void (*lookup_complete)(struct fscache_object *object) + * ``coherency`` - A piece of coherency data that should be checked when the + volume is bound to in the cache. - This method is called to ask the cache to release any resources it was - using to perform a lookup. + * ``coherency_len`` - The amount of data in the coherency buffer. - * Increment object refcount [mandatory]:: +Data Storage Cookies +==================== - struct fscache_object *(*grab_object)(struct fscache_object *object) +A volume is a logical group of data storage objects, each of which is +represented to the network filesystem by a cookie. Cookies are represented in +the API as objects of type:: - This method is called to increment the reference count on an object. It - may fail (for instance if the cache is being withdrawn) by returning NULL. - It should return the object pointer if successful. + struct fscache_cookie { + struct fscache_volume *volume; + void *cache_priv; + unsigned long flags; + unsigned int debug_id; + unsigned int inval_counter; + loff_t object_size; + u8 advice; + u32 key_hash; + u8 key_len; + u8 aux_len; + ... + }; +The fields in the cookie that are of interest to the cache backend are: - * Lock/Unlock object [mandatory]:: + * ``volume`` - The parent volume cookie. - void (*lock_object)(struct fscache_object *object) - void (*unlock_object)(struct fscache_object *object) + * ``cache_priv`` - A place for the cache to stash private data. - These methods are used to exclusively lock an object. It must be possible - to schedule with the lock held, so a spinlock isn't sufficient. + * ``flags`` - A collection of bit flags, including: + * FSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the + cache to be read as the cookie has been created or invalidated. - * Pin/Unpin object [optional]:: + * FSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has + been changed and needs committing. - int (*pin_object)(struct fscache_object *object) - void (*unpin_object)(struct fscache_object *object) + * FSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified + locally, so the cache object may be in an incoherent state with respect + to the server. - These methods are used to pin an object into the cache. Once pinned an - object cannot be reclaimed to make space. Return -ENOSPC if there's not - enough space in the cache to permit this. + * FSCACHE_COOKIE_HAVE_DATA - The backend should set this if it + successfully stores data into the cache. + * FSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was + relinquished and the cached data should be discarded. - * Check coherency state of an object [mandatory]:: + * ``debug_id`` - A debugging ID for logging in tracepoints. - int (*check_consistency)(struct fscache_object *object) + * ``inval_counter`` - The number of invalidations done on the cookie. - This method is called to have the cache check the saved auxiliary data of - the object against the netfs's idea of the state. 0 should be returned - if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS - may also be returned. + * ``advice`` - Information about how the cookie is to be used. - * Update object [mandatory]:: + * ``key_hash`` - A hash of the index key. This should work out the same, no + matter the cpu arch and endianness. - int (*update_object)(struct fscache_object *object) + * ``key_len`` - The length of the index key. - This is called to update the index entry for the specified object. The - new information should be in object->cookie->netfs_data. This can be - obtained by calling object->cookie->def->get_aux()/get_attr(). + * ``aux_len`` - The length of the coherency data buffer. +Each cookie has an index key, which may be stored inline to the cookie or +elsewhere. A pointer to this can be obtained by calling:: - * Invalidate data object [mandatory]:: + void *fscache_get_key(struct fscache_cookie *cookie); - int (*invalidate_object)(struct fscache_operation *op) +The index key is a binary blob, the storage for which is padded out to a +multiple of 4 bytes. - This is called to invalidate a data object (as pointed to by op->object). - All the data stored for this object should be discarded and an - attr_changed operation should be performed. The caller will follow up - with an object update operation. +Each cookie also has a buffer for coherency data. This may also be inline or +detached from the cookie and a pointer is obtained by calling:: - fscache_op_complete() must be called on op before returning. + void *fscache_get_aux(struct fscache_cookie *cookie); - * Discard object [mandatory]:: - void (*drop_object)(struct fscache_object *object) +Cookie Accounting +================= - This method is called to indicate that an object has been unbound from its - cookie, and that the cache should release the object's resources and - retire it if it's in state FSCACHE_OBJECT_RECYCLING. +Data storage cookies are counted and this is used to block cache withdrawal +completion until all objects have been destroyed. The following functions are +provided to the cache to deal with that:: - This method should not attempt to release any references held by the - caller. The caller will invoke the put_object() method as appropriate. + void fscache_count_object(struct fscache_cache *cache); + void fscache_uncount_object(struct fscache_cache *cache); + void fscache_wait_for_objects(struct fscache_cache *cache); +The count function records the allocation of an object in a cache and the +uncount function records its destruction. Warning: by the time the uncount +function returns, the cache may have been destroyed. - * Release object reference [mandatory]:: +The wait function can be used during the withdrawal procedure to wait for +fscache to finish withdrawing all the objects in the cache. When it completes, +there will be no remaining objects referring to the cache object or any volume +objects. - void (*put_object)(struct fscache_object *object) - This method is used to discard a reference to an object. The object may - be freed when all the references to it are released. +Cache Management API +==================== +The cache backend implements the cache management API by providing a table of +operations that fscache can use to manage various aspects of the cache. These +are held in a structure of type:: - * Synchronise a cache [mandatory]:: + struct fscache_cache_ops { + const char *name; + ... + }; - void (*sync)(struct fscache_cache *cache) +This contains a printable name for the cache backend driver plus a number of +pointers to methods to allow fscache to request management of the cache: - This is called to ask the backend to synchronise a cache with its backing - device. + * Set up a volume cookie [optional]:: + void (*acquire_volume)(struct fscache_volume *volume); - * Dissociate a cache [mandatory]:: + This method is called when a volume cookie is being created. The caller + holds a cache-level access pin to prevent the cache from going away for + the duration. This method should set up the resources to access a volume + in the cache and should not return until it has done so. - void (*dissociate_pages)(struct fscache_cache *cache) + If successful, it can set ``cache_priv`` to its own data. - This is called to ask a cache to perform any page dissociations as part of - cache withdrawal. + * Clean up volume cookie [optional]:: - * Notification that the attributes on a netfs file changed [mandatory]:: + void (*free_volume)(struct fscache_volume *volume); - int (*attr_changed)(struct fscache_object *object); + This method is called when a volume cookie is being released if + ``cache_priv`` is set. - This is called to indicate to the cache that certain attributes on a netfs - file have changed (for example the maximum size a file may reach). The - cache can read these from the netfs by calling the cookie's get_attr() - method. - The cache may use the file size information to reserve space on the cache. - It should also call fscache_set_store_limit() to indicate to FS-Cache the - highest byte it's willing to store for an object. + * Look up a cookie in the cache [mandatory]:: - This method may return -ve if an error occurred or the cache object cannot - be expanded. In such a case, the object will be withdrawn from service. + bool (*lookup_cookie)(struct fscache_cookie *cookie); - This operation is run asynchronously from FS-Cache's thread pool, and - storage and retrieval operations from the netfs are excluded during the - execution of this operation. + This method is called to look up/create the resources needed to access the + data storage for a cookie. It is called from a worker thread with a + volume-level access pin in the cache to prevent it from being withdrawn. + True should be returned if successful and false otherwise. If false is + returned, the withdraw_cookie op (see below) will be called. - * Reserve cache space for an object's data [optional]:: + If lookup fails, but the object could still be created (e.g. it hasn't + been cached before), then:: - int (*reserve_space)(struct fscache_object *object, loff_t size); + void fscache_cookie_lookup_negative( + struct fscache_cookie *cookie); - This is called to request that cache space be reserved to hold the data - for an object and the metadata used to track it. Zero size should be - taken as request to cancel a reservation. + can be called to let the network filesystem proceed and start downloading + stuff whilst the cache backend gets on with the job of creating things. - This should return 0 if successful, -ENOSPC if there isn't enough space - available, or -ENOMEM or -EIO on other errors. + If successful, ``cookie->cache_priv`` can be set. - The reservation may exceed the current size of the object, thus permitting - future expansion. If the amount of space consumed by an object would - exceed the reservation, it's permitted to refuse requests to allocate - pages, but not required. An object may be pruned down to its reservation - size if larger than that already. + * Withdraw an object without any cookie access counts held [mandatory]:: - * Request page be read from cache [mandatory]:: + void (*withdraw_cookie)(struct fscache_cookie *cookie); - int (*read_or_alloc_page)(struct fscache_retrieval *op, - struct page *page, - gfp_t gfp) + This method is called to withdraw a cookie from service. It will be + called when the cookie is relinquished by the netfs, withdrawn or culled + by the cache backend or closed after a period of non-use by fscache. - This is called to attempt to read a netfs page from the cache, or to - reserve a backing block if not. FS-Cache will have done as much checking - as it can before calling, but most of the work belongs to the backend. + The caller doesn't hold any access pins, but it is called from a + non-reentrant work item to manage races between the various ways + withdrawal can occur. - If there's no page in the cache, then -ENODATA should be returned if the - backend managed to reserve a backing block; -ENOBUFS or -ENOMEM if it - didn't. + The cookie will have the ``FSCACHE_COOKIE_RETIRED`` flag set on it if the + associated data is to be removed from the cache. - If there is suitable data in the cache, then a read operation should be - queued and 0 returned. When the read finishes, fscache_end_io() should be - called. - The fscache_mark_pages_cached() should be called for the page if any cache - metadata is retained. This will indicate to the netfs that the page needs - explicit uncaching. This operation takes a pagevec, thus allowing several - pages to be marked at once. + * Change the size of a data storage object [mandatory]:: - The retrieval record pointed to by op should be retained for each page - queued and released when I/O on the page has been formally ended. - fscache_get/put_retrieval() are available for this purpose. + void (*resize_cookie)(struct netfs_cache_resources *cres, + loff_t new_size); - The retrieval record may be used to get CPU time via the FS-Cache thread - pool. If this is desired, the op->op.processor should be set to point to - the appropriate processing routine, and fscache_enqueue_retrieval() should - be called at an appropriate point to request CPU time. For instance, the - retrieval routine could be enqueued upon the completion of a disk read. - The to_do field in the retrieval record is provided to aid in this. + This method is called to inform the cache backend of a change in size of + the netfs file due to local truncation. The cache backend should make all + of the changes it needs to make before returning as this is done under the + netfs inode mutex. - If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS - returned if possible or fscache_end_io() called with a suitable error - code. + The caller holds a cookie-level access pin to prevent a race with + withdrawal and the netfs must have the cookie marked in-use to prevent + garbage collection or culling from removing any resources. - fscache_put_retrieval() should be called after a page or pages are dealt - with. This will complete the operation when all pages are dealt with. + * Invalidate a data storage object [mandatory]:: - * Request pages be read from cache [mandatory]:: + bool (*invalidate_cookie)(struct fscache_cookie *cookie); - int (*read_or_alloc_pages)(struct fscache_retrieval *op, - struct list_head *pages, - unsigned *nr_pages, - gfp_t gfp) + This is called when the network filesystem detects a third-party + modification or when an O_DIRECT write is made locally. This requests + that the cache backend should throw away all the data in the cache for + this object and start afresh. It should return true if successful and + false otherwise. - This is like the read_or_alloc_page() method, except it is handed a list - of pages instead of one page. Any pages on which a read operation is - started must be added to the page cache for the specified mapping and also - to the LRU. Such pages must also be removed from the pages list and - ``*nr_pages`` decremented per page. + On entry, new I O/operations are blocked. Once the cache is in a position + to accept I/O again, the backend should release the block by calling:: - If there was an error such as -ENOMEM, then that should be returned; else - if one or more pages couldn't be read or allocated, then -ENOBUFS should - be returned; else if one or more pages couldn't be read, then -ENODATA - should be returned. If all the pages are dispatched then 0 should be - returned. + void fscache_resume_after_invalidation(struct fscache_cookie *cookie); + If the method returns false, caching will be withdrawn for this cookie. - * Request page be allocated in the cache [mandatory]:: - int (*allocate_page)(struct fscache_retrieval *op, - struct page *page, - gfp_t gfp) + * Prepare to make local modifications to the cache [mandatory]:: - This is like the read_or_alloc_page() method, except that it shouldn't - read from the cache, even if there's data there that could be retrieved. - It should, however, set up any internal metadata required such that - the write_page() method can write to the cache. + void (*prepare_to_write)(struct fscache_cookie *cookie); - If there's no backing block available, then -ENOBUFS should be returned - (or -ENOMEM if there were other problems). If a block is successfully - allocated, then the netfs page should be marked and 0 returned. + This method is called when the network filesystem finds that it is going + to need to modify the contents of the cache due to local writes or + truncations. This gives the cache a chance to note that a cache object + may be incoherent with respect to the server and may need writing back + later. This may also cause the cached data to be scrapped on later + rebinding if not properly committed. - * Request pages be allocated in the cache [mandatory]:: + * Begin an operation for the netfs lib [mandatory]:: - int (*allocate_pages)(struct fscache_retrieval *op, - struct list_head *pages, - unsigned *nr_pages, - gfp_t gfp) + bool (*begin_operation)(struct netfs_cache_resources *cres, + enum fscache_want_state want_state); - This is an multiple page version of the allocate_page() method. pages and - nr_pages should be treated as for the read_or_alloc_pages() method. + This method is called when an I/O operation is being set up (read, write + or resize). The caller holds an access pin on the cookie and must have + marked the cookie as in-use. + If it can, the backend should attach any resources it needs to keep around + to the netfs_cache_resources object and return true. - * Request page be written to cache [mandatory]:: + If it can't complete the setup, it should return false. - int (*write_page)(struct fscache_storage *op, - struct page *page); + The want_state parameter indicates the state the caller needs the cache + object to be in and what it wants to do during the operation: - This is called to write from a page on which there was a previously - successful read_or_alloc_page() call or similar. FS-Cache filters out - pages that don't have mappings. + * ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache + object parameters; it doesn't need to do data I/O yet. - This method is called asynchronously from the FS-Cache thread pool. It is - not required to actually store anything, provided -ENODATA is then - returned to the next read of this page. + * ``FSCACHE_WANT_READ`` - The caller wants to read data. - If an error occurred, then a negative error code should be returned, - otherwise zero should be returned. FS-Cache will take appropriate action - in response to an error, such as withdrawing this object. + * ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the + cache object. - If this method returns success then FS-Cache will inform the netfs - appropriately. + Note that there won't necessarily be anything attached to the cookie's + cache_priv yet if the cookie is still being created. - * Discard retained per-page metadata [mandatory]:: +Data I/O API +============ - void (*uncache_page)(struct fscache_object *object, struct page *page) +A cache backend provides a data I/O API by through the netfs library's ``struct +netfs_cache_ops`` attached to a ``struct netfs_cache_resources`` by the +``begin_operation`` method described above. - This is called when a netfs page is being evicted from the pagecache. The - cache backend should tear down any internal representation or tracking it - maintains for this page. +See the Documentation/filesystems/netfs_library.rst for a description. -FS-Cache Utilities -================== +Miscellaneous Functions +======================= FS-Cache provides some utilities that a cache backend may make use of: * Note occurrence of an I/O error in a cache:: - void fscache_io_error(struct fscache_cache *cache) + void fscache_io_error(struct fscache_cache *cache); - This tells FS-Cache that an I/O error occurred in the cache. After this - has been called, only resource dissociation operations (object and page - release) will be passed from the netfs to the cache backend for the - specified cache. + This tells FS-Cache that an I/O error occurred in the cache. This + prevents any new I/O from being started on the cache. This does not actually withdraw the cache. That must be done separately. + * Note cessation of caching on a cookie due to failure:: - * Invoke the retrieval I/O completion function:: - - void fscache_end_io(struct fscache_retrieval *op, struct page *page, - int error); - - This is called to note the end of an attempt to retrieve a page. The - error value should be 0 if successful and an error otherwise. - - - * Record that one or more pages being retrieved or allocated have been dealt - with:: - - void fscache_retrieval_complete(struct fscache_retrieval *op, - int n_pages); - - This is called to record the fact that one or more pages have been dealt - with and are no longer the concern of this operation. When the number of - pages remaining in the operation reaches 0, the operation will be - completed. - - - * Record operation completion:: - - void fscache_op_complete(struct fscache_operation *op); - - This is called to record the completion of an operation. This deducts - this operation from the parent object's run state, potentially permitting - one or more pending operations to start running. - - - * Set highest store limit:: - - void fscache_set_store_limit(struct fscache_object *object, - loff_t i_size); - - This sets the limit FS-Cache imposes on the highest byte it's willing to - try and store for a netfs. Any page over this limit is automatically - rejected by fscache_read_alloc_page() and co with -ENOBUFS. - - - * Mark pages as being cached:: - - void fscache_mark_pages_cached(struct fscache_retrieval *op, - struct pagevec *pagevec); - - This marks a set of pages as being cached. After this has been called, - the netfs must call fscache_uncache_page() to unmark the pages. - - - * Perform coherency check on an object:: - - enum fscache_checkaux fscache_check_aux(struct fscache_object *object, - const void *data, - uint16_t datalen); - - This asks the netfs to perform a coherency check on an object that has - just been looked up. The cookie attached to the object will determine the - netfs to use. data and datalen should specify where the auxiliary data - retrieved from the cache can be found. - - One of three values will be returned: - - FSCACHE_CHECKAUX_OKAY - The coherency data indicates the object is valid as is. - - FSCACHE_CHECKAUX_NEEDS_UPDATE - The coherency data needs updating, but otherwise the object is - valid. - - FSCACHE_CHECKAUX_OBSOLETE - The coherency data indicates that the object is obsolete and should - be discarded. - - - * Initialise a freshly allocated object:: - - void fscache_object_init(struct fscache_object *object); - - This initialises all the fields in an object representation. - - - * Indicate the destruction of an object:: - - void fscache_object_destroyed(struct fscache_cache *cache); - - This must be called to inform FS-Cache that an object that belonged to a - cache has been destroyed and deallocated. This will allow continuation - of the cache withdrawal process when it is stopped pending destruction of - all the objects. - - - * Indicate negative lookup on an object:: - - void fscache_object_lookup_negative(struct fscache_object *object); - - This is called to indicate to FS-Cache that a lookup process for an object - found a negative result. - - This changes the state of an object to permit reads pending on lookup - completion to go off and start fetching data from the netfs server as it's - known at this point that there can't be any data in the cache. - - This may be called multiple times on an object. Only the first call is - significant - all subsequent calls are ignored. - - - * Indicate an object has been obtained:: - - void fscache_obtained_object(struct fscache_object *object); - - This is called to indicate to FS-Cache that a lookup process for an object - produced a positive result, or that an object was created. This should - only be called once for any particular object. - - This changes the state of an object to indicate: - - (1) if no call to fscache_object_lookup_negative() has been made on - this object, that there may be data available, and that reads can - now go and look for it; and - - (2) that writes may now proceed against this object. - - - * Indicate that object lookup failed:: - - void fscache_object_lookup_error(struct fscache_object *object); - - This marks an object as having encountered a fatal error (usually EIO) - and causes it to move into a state whereby it will be withdrawn as soon - as possible. - - - * Indicate that a stale object was found and discarded:: - - void fscache_object_retrying_stale(struct fscache_object *object); - - This is called to indicate that the lookup procedure found an object in - the cache that the netfs decided was stale. The object has been - discarded from the cache and the lookup will be performed again. - - - * Indicate that the caching backend killed an object:: - - void fscache_object_mark_killed(struct fscache_object *object, - enum fscache_why_object_killed why); - - This is called to indicate that the cache backend preemptively killed an - object. The why parameter should be set to indicate the reason: + void fscache_caching_failed(struct fscache_cookie *cookie); - FSCACHE_OBJECT_IS_STALE - - the object was stale and needs discarding. + This notes that a the caching that was being done on a cookie failed in + some way, for instance the backing storage failed to be created or + invalidation failed and that no further I/O operations should take place + on it until the cache is reset. - FSCACHE_OBJECT_NO_SPACE - - there was insufficient cache space + * Count I/O requests:: - FSCACHE_OBJECT_WAS_RETIRED - - the object was retired when relinquished. + void fscache_count_read(void); + void fscache_count_write(void); - FSCACHE_OBJECT_WAS_CULLED - - the object was culled to make space. + These record reads and writes from/to the cache. The numbers are + displayed in /proc/fs/fscache/stats. + * Count out-of-space errors:: - * Get and release references on a retrieval record:: + void fscache_count_no_write_space(void); + void fscache_count_no_create_space(void); - void fscache_get_retrieval(struct fscache_retrieval *op); - void fscache_put_retrieval(struct fscache_retrieval *op); + These record ENOSPC errors in the cache, divided into failures of data + writes and failures of filesystem object creations (e.g. mkdir). - These two functions are used to retain a retrieval record while doing - asynchronous data retrieval and block allocation. + * Count objects culled:: + void fscache_count_culled(void); - * Enqueue a retrieval record for processing:: + This records the culling of an object. - void fscache_enqueue_retrieval(struct fscache_retrieval *op); + * Get the cookie from a set of cache resources:: - This enqueues a retrieval record for processing by the FS-Cache thread - pool. One of the threads in the pool will invoke the retrieval record's - op->op.processor callback function. This function may be called from - within the callback function. + struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres) + Pull a pointer to the cookie from the cache resources. This may return a + NULL cookie if no cookie was set. - * List of object state names:: - const char *fscache_object_states[]; +API Function Reference +====================== - For debugging purposes, this may be used to turn the state that an object - is in into a text string for display purposes. +.. kernel-doc:: include/linux/fscache-cache.h diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst index e58bc1fd312a..8bf396b76359 100644 --- a/Documentation/filesystems/caching/cachefiles.rst +++ b/Documentation/filesystems/caching/cachefiles.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -=============================================== -CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM -=============================================== +=================================== +Cache on Already Mounted Filesystem +=================================== .. Contents: diff --git a/Documentation/filesystems/caching/fscache.rst b/Documentation/filesystems/caching/fscache.rst index 70de86922b6a..a74d7b052dc1 100644 --- a/Documentation/filesystems/caching/fscache.rst +++ b/Documentation/filesystems/caching/fscache.rst @@ -10,25 +10,25 @@ Overview This facility is a general purpose cache for network filesystems, though it could be used for caching other things such as ISO9660 filesystems too. -FS-Cache mediates between cache backends (such as CacheFS) and network +FS-Cache mediates between cache backends (such as CacheFiles) and network filesystems:: +---------+ - | | +--------------+ - | NFS |--+ | | - | | | +-->| CacheFS | - +---------+ | +----------+ | | /dev/hda5 | - | | | | +--------------+ - +---------+ +-->| | | - | | | |--+ - | AFS |----->| FS-Cache | - | | | |--+ - +---------+ +-->| | | - | | | | +--------------+ - +---------+ | +----------+ | | | - | | | +-->| CacheFiles | - | ISOFS |--+ | /var/cache | - | | +--------------+ + | | +--------------+ + | NFS |--+ | | + | | | +-->| CacheFS | + +---------+ | +----------+ | | /dev/hda5 | + | | | | +--------------+ + +---------+ +-------------->| | | + | | +-------+ | |--+ + | AFS |----->| | | FS-Cache | + | | | netfs |-->| |--+ + +---------+ +-->| lib | | | | + | | | | | | +--------------+ + +---------+ | +-------+ +----------+ | | | + | | | +-->| CacheFiles | + | 9P |--+ | /var/cache | + | | +--------------+ +---------+ Or to look at it another way, FS-Cache is a module that provides a caching @@ -84,101 +84,62 @@ then serving the pages out of that cache rather than the netfs inode because: one-off access of a small portion of it (such as might be done with the "file" program). -It instead serves the cache out in PAGE_SIZE chunks as and when requested by -the netfs('s) using it. +It instead serves the cache out in chunks as and when requested by the netfs +using it. FS-Cache provides the following facilities: - (1) More than one cache can be used at once. Caches can be selected + * More than one cache can be used at once. Caches can be selected explicitly by use of tags. - (2) Caches can be added / removed at any time. + * Caches can be added / removed at any time, even whilst being accessed. - (3) The netfs is provided with an interface that allows either party to + * The netfs is provided with an interface that allows either party to withdraw caching facilities from a file (required for (2)). - (4) The interface to the netfs returns as few errors as possible, preferring + * The interface to the netfs returns as few errors as possible, preferring rather to let the netfs remain oblivious. - (5) Cookies are used to represent indices, files and other objects to the - netfs. The simplest cookie is just a NULL pointer - indicating nothing - cached there. - - (6) The netfs is allowed to propose - dynamically - any index hierarchy it - desires, though it must be aware that the index search function is - recursive, stack space is limited, and indices can only be children of - indices. - - (7) Data I/O is done direct to and from the netfs's pages. The netfs - indicates that page A is at index B of the data-file represented by cookie - C, and that it should be read or written. The cache backend may or may - not start I/O on that page, but if it does, a netfs callback will be - invoked to indicate completion. The I/O may be either synchronous or - asynchronous. - - (8) Cookies can be "retired" upon release. At this point FS-Cache will mark - them as obsolete and the index hierarchy rooted at that point will get - recycled. - - (9) The netfs provides a "match" function for index searches. In addition to - saying whether a match was made or not, this can also specify that an - entry should be updated or deleted. - -(10) As much as possible is done asynchronously. - - -FS-Cache maintains a virtual indexing tree in which all indices, files, objects -and pages are kept. Bits of this tree may actually reside in one or more -caches:: - - FSDEF - | - +------------------------------------+ - | | - NFS AFS - | | - +--------------------------+ +-----------+ - | | | | - homedir mirror afs.org redhat.com - | | | - +------------+ +---------------+ +----------+ - | | | | | | - 00001 00002 00007 00125 vol00001 vol00002 - | | | | | - +---+---+ +-----+ +---+ +------+------+ +-----+----+ - | | | | | | | | | | | | | - PG0 PG1 PG2 PG0 XATTR PG0 PG1 DIRENT DIRENT DIRENT R/W R/O Bak - | | - PG0 +-------+ - | | - 00001 00003 - | - +---+---+ - | | | - PG0 PG1 PG2 - -In the example above, you can see two netfs's being backed: NFS and AFS. These -have different index hierarchies: - - * The NFS primary index contains per-server indices. Each server index is - indexed by NFS file handles to get data file objects. Each data file - objects can have an array of pages, but may also have further child - objects, such as extended attributes and directory entries. Extended - attribute objects themselves have page-array contents. - - * The AFS primary index contains per-cell indices. Each cell index contains - per-logical-volume indices. Each of volume index contains up to three - indices for the read-write, read-only and backup mirrors of those volumes. - Each of these contains vnode data file objects, each of which contains an - array of pages. - -The very top index is the FS-Cache master index in which individual netfs's -have entries. - -Any index object may reside in more than one cache, provided it only has index -children. Any index with non-index object children will be assumed to only -reside in one cache. + * There are three types of cookie: cache, volume and data file cookies. + Cache cookies represent the cache as a whole and are not normally visible + to the netfs; the netfs gets a volume cookie to represent a collection of + files (typically something that a netfs would get for a superblock); and + data file cookies are used to cache data (something that would be got for + an inode). + + * Volumes are matched using a key. This is a printable string that is used + to encode all the information that might be needed to distinguish one + superblock, say, from another. This would be a compound of things like + cell name or server address, volume name or share path. It must be a + valid pathname. + + * Cookies are matched using a key. This is a binary blob and is used to + represent the object within a volume (so the volume key need not form + part of the blob). This might include things like an inode number and + uniquifier or a file handle. + + * Cookie resources are set up and pinned by marking the cookie in-use. + This prevents the backing resources from being culled. Timed garbage + collection is employed to eliminate cookies that haven't been used for a + short while, thereby reducing resource overload. This is intended to be + used when a file is opened or closed. + + A cookie can be marked in-use multiple times simultaneously; each mark + must be unused. + + * Begin/end access functions are provided to delay cache withdrawal for the + duration of an operation and prevent structs from being freed whilst + we're looking at them. + + * Data I/O is done by asynchronous DIO to/from a buffer described by the + netfs using an iov_iter. + + * An invalidation facility is available to discard data from the cache and + to deal with I/O that's in progress that is accessing old data. + + * Cookies can be "retired" upon release, thereby causing the object to be + removed from the cache. The netfs API to FS-Cache can be found in: @@ -189,11 +150,6 @@ The cache backend API to FS-Cache can be found in: Documentation/filesystems/caching/backend-api.rst -A description of the internal representations and object state machine can be -found in: - - Documentation/filesystems/caching/object.rst - Statistical Information ======================= @@ -201,333 +157,162 @@ Statistical Information If FS-Cache is compiled with the following options enabled:: CONFIG_FSCACHE_STATS=y - CONFIG_FSCACHE_HISTOGRAM=y -then it will gather certain statistics and display them through a number of -proc files. +then it will gather certain statistics and display them through: -/proc/fs/fscache/stats ----------------------- + /proc/fs/fscache/stats - This shows counts of a number of events that can happen in FS-Cache: +This shows counts of a number of events that can happen in FS-Cache: +--------------+-------+-------------------------------------------------------+ |CLASS |EVENT |MEANING | +==============+=======+=======================================================+ -|Cookies |idx=N |Number of index cookies allocated | -+ +-------+-------------------------------------------------------+ -| |dat=N |Number of data storage cookies allocated | +|Cookies |n=N |Number of data storage cookies allocated | + +-------+-------------------------------------------------------+ -| |spc=N |Number of special cookies allocated | -+--------------+-------+-------------------------------------------------------+ -|Objects |alc=N |Number of objects allocated | -+ +-------+-------------------------------------------------------+ -| |nal=N |Number of object allocation failures | +| |v=N |Number of volume index cookies allocated | + +-------+-------------------------------------------------------+ -| |avl=N |Number of objects that reached the available state | -+ +-------+-------------------------------------------------------+ -| |ded=N |Number of objects that reached the dead state | -+--------------+-------+-------------------------------------------------------+ -|ChkAux |non=N |Number of objects that didn't have a coherency check | +| |vcol=N |Number of volume index key collisions | + +-------+-------------------------------------------------------+ -| |ok=N |Number of objects that passed a coherency check | -+ +-------+-------------------------------------------------------+ -| |upd=N |Number of objects that needed a coherency data update | -+ +-------+-------------------------------------------------------+ -| |obs=N |Number of objects that were declared obsolete | -+--------------+-------+-------------------------------------------------------+ -|Pages |mrk=N |Number of pages marked as being cached | -| |unc=N |Number of uncache page requests seen | +| |voom=N |Number of OOM events when allocating volume cookies | +--------------+-------+-------------------------------------------------------+ |Acquire |n=N |Number of acquire cookie requests seen | + +-------+-------------------------------------------------------+ -| |nul=N |Number of acq reqs given a NULL parent | -+ +-------+-------------------------------------------------------+ -| |noc=N |Number of acq reqs rejected due to no cache available | -+ +-------+-------------------------------------------------------+ | |ok=N |Number of acq reqs succeeded | + +-------+-------------------------------------------------------+ -| |nbf=N |Number of acq reqs rejected due to error | -+ +-------+-------------------------------------------------------+ | |oom=N |Number of acq reqs failed on ENOMEM | +--------------+-------+-------------------------------------------------------+ -|Lookups |n=N |Number of lookup calls made on cache backends | +|LRU |n=N |Number of cookies currently on the LRU | + +-------+-------------------------------------------------------+ -| |neg=N |Number of negative lookups made | +| |exp=N |Number of cookies expired off of the LRU | + +-------+-------------------------------------------------------+ -| |pos=N |Number of positive lookups made | +| |rmv=N |Number of cookies removed from the LRU | + +-------+-------------------------------------------------------+ -| |crt=N |Number of objects created by lookup | +| |drp=N |Number of LRU'd cookies relinquished/withdrawn | + +-------+-------------------------------------------------------+ -| |tmo=N |Number of lookups timed out and requeued | +| |at=N |Time till next LRU cull (jiffies) | ++--------------+-------+-------------------------------------------------------+ +|Invals |n=N |Number of invalidations | +--------------+-------+-------------------------------------------------------+ |Updates |n=N |Number of update cookie requests seen | + +-------+-------------------------------------------------------+ -| |nul=N |Number of upd reqs given a NULL parent | +| |rsz=N |Number of resize requests | + +-------+-------------------------------------------------------+ -| |run=N |Number of upd reqs granted CPU time | +| |rsn=N |Number of skipped resize requests | +--------------+-------+-------------------------------------------------------+ |Relinqs |n=N |Number of relinquish cookie requests seen | + +-------+-------------------------------------------------------+ -| |nul=N |Number of rlq reqs given a NULL parent | +| |rtr=N |Number of rlq reqs with retire=true | + +-------+-------------------------------------------------------+ -| |wcr=N |Number of rlq reqs waited on completion of creation | +| |drop=N |Number of cookies no longer blocking re-acquisition | +--------------+-------+-------------------------------------------------------+ -|AttrChg |n=N |Number of attribute changed requests seen | -+ +-------+-------------------------------------------------------+ -| |ok=N |Number of attr changed requests queued | -+ +-------+-------------------------------------------------------+ -| |nbf=N |Number of attr changed rejected -ENOBUFS | +|NoSpace |nwr=N |Number of write requests refused due to lack of space | + +-------+-------------------------------------------------------+ -| |oom=N |Number of attr changed failed -ENOMEM | +| |ncr=N |Number of create requests refused due to lack of space | + +-------+-------------------------------------------------------+ -| |run=N |Number of attr changed ops given CPU time | +| |cull=N |Number of objects culled to make space | +--------------+-------+-------------------------------------------------------+ -|Allocs |n=N |Number of allocation requests seen | +|IO |rd=N |Number of read operations in the cache | + +-------+-------------------------------------------------------+ -| |ok=N |Number of successful alloc reqs | -+ +-------+-------------------------------------------------------+ -| |wt=N |Number of alloc reqs that waited on lookup completion | -+ +-------+-------------------------------------------------------+ -| |nbf=N |Number of alloc reqs rejected -ENOBUFS | -+ +-------+-------------------------------------------------------+ -| |int=N |Number of alloc reqs aborted -ERESTARTSYS | -+ +-------+-------------------------------------------------------+ -| |ops=N |Number of alloc reqs submitted | -+ +-------+-------------------------------------------------------+ -| |owt=N |Number of alloc reqs waited for CPU time | -+ +-------+-------------------------------------------------------+ -| |abt=N |Number of alloc reqs aborted due to object death | -+--------------+-------+-------------------------------------------------------+ -|Retrvls |n=N |Number of retrieval (read) requests seen | -+ +-------+-------------------------------------------------------+ -| |ok=N |Number of successful retr reqs | -+ +-------+-------------------------------------------------------+ -| |wt=N |Number of retr reqs that waited on lookup completion | -+ +-------+-------------------------------------------------------+ -| |nod=N |Number of retr reqs returned -ENODATA | -+ +-------+-------------------------------------------------------+ -| |nbf=N |Number of retr reqs rejected -ENOBUFS | -+ +-------+-------------------------------------------------------+ -| |int=N |Number of retr reqs aborted -ERESTARTSYS | -+ +-------+-------------------------------------------------------+ -| |oom=N |Number of retr reqs failed -ENOMEM | -+ +-------+-------------------------------------------------------+ -| |ops=N |Number of retr reqs submitted | -+ +-------+-------------------------------------------------------+ -| |owt=N |Number of retr reqs waited for CPU time | -+ +-------+-------------------------------------------------------+ -| |abt=N |Number of retr reqs aborted due to object death | -+--------------+-------+-------------------------------------------------------+ -|Stores |n=N |Number of storage (write) requests seen | -+ +-------+-------------------------------------------------------+ -| |ok=N |Number of successful store reqs | -+ +-------+-------------------------------------------------------+ -| |agn=N |Number of store reqs on a page already pending storage | -+ +-------+-------------------------------------------------------+ -| |nbf=N |Number of store reqs rejected -ENOBUFS | -+ +-------+-------------------------------------------------------+ -| |oom=N |Number of store reqs failed -ENOMEM | -+ +-------+-------------------------------------------------------+ -| |ops=N |Number of store reqs submitted | -+ +-------+-------------------------------------------------------+ -| |run=N |Number of store reqs granted CPU time | -+ +-------+-------------------------------------------------------+ -| |pgs=N |Number of pages given store req processing time | -+ +-------+-------------------------------------------------------+ -| |rxd=N |Number of store reqs deleted from tracking tree | -+ +-------+-------------------------------------------------------+ -| |olm=N |Number of store reqs over store limit | -+--------------+-------+-------------------------------------------------------+ -|VmScan |nos=N |Number of release reqs against pages with no | -| | |pending store | -+ +-------+-------------------------------------------------------+ -| |gon=N |Number of release reqs against pages stored by | -| | |time lock granted | -+ +-------+-------------------------------------------------------+ -| |bsy=N |Number of release reqs ignored due to in-progress store| -+ +-------+-------------------------------------------------------+ -| |can=N |Number of page stores cancelled due to release req | -+--------------+-------+-------------------------------------------------------+ -|Ops |pend=N |Number of times async ops added to pending queues | -+ +-------+-------------------------------------------------------+ -| |run=N |Number of times async ops given CPU time | -+ +-------+-------------------------------------------------------+ -| |enq=N |Number of times async ops queued for processing | -+ +-------+-------------------------------------------------------+ -| |can=N |Number of async ops cancelled | -+ +-------+-------------------------------------------------------+ -| |rej=N |Number of async ops rejected due to object | -| | |lookup/create failure | -+ +-------+-------------------------------------------------------+ -| |ini=N |Number of async ops initialised | -+ +-------+-------------------------------------------------------+ -| |dfr=N |Number of async ops queued for deferred release | -+ +-------+-------------------------------------------------------+ -| |rel=N |Number of async ops released | -| | |(should equal ini=N when idle) | -+ +-------+-------------------------------------------------------+ -| |gc=N |Number of deferred-release async ops garbage collected | -+--------------+-------+-------------------------------------------------------+ -|CacheOp |alo=N |Number of in-progress alloc_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |luo=N |Number of in-progress lookup_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |luc=N |Number of in-progress lookup_complete() cache ops | -+ +-------+-------------------------------------------------------+ -| |gro=N |Number of in-progress grab_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |upo=N |Number of in-progress update_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |dro=N |Number of in-progress drop_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |pto=N |Number of in-progress put_object() cache ops | -+ +-------+-------------------------------------------------------+ -| |syn=N |Number of in-progress sync_cache() cache ops | -+ +-------+-------------------------------------------------------+ -| |atc=N |Number of in-progress attr_changed() cache ops | -+ +-------+-------------------------------------------------------+ -| |rap=N |Number of in-progress read_or_alloc_page() cache ops | -+ +-------+-------------------------------------------------------+ -| |ras=N |Number of in-progress read_or_alloc_pages() cache ops | -+ +-------+-------------------------------------------------------+ -| |alp=N |Number of in-progress allocate_page() cache ops | -+ +-------+-------------------------------------------------------+ -| |als=N |Number of in-progress allocate_pages() cache ops | -+ +-------+-------------------------------------------------------+ -| |wrp=N |Number of in-progress write_page() cache ops | -+ +-------+-------------------------------------------------------+ -| |ucp=N |Number of in-progress uncache_page() cache ops | -+ +-------+-------------------------------------------------------+ -| |dsp=N |Number of in-progress dissociate_pages() cache ops | -+--------------+-------+-------------------------------------------------------+ -|CacheEv |nsp=N |Number of object lookups/creations rejected due to | -| | |lack of space | -+ +-------+-------------------------------------------------------+ -| |stl=N |Number of stale objects deleted | -+ +-------+-------------------------------------------------------+ -| |rtr=N |Number of objects retired when relinquished | -+ +-------+-------------------------------------------------------+ -| |cul=N |Number of objects culled | +| |wr=N |Number of write operations in the cache | +--------------+-------+-------------------------------------------------------+ +Netfslib will also add some stats counters of its own. -/proc/fs/fscache/histogram --------------------------- +Cache List +========== - :: +FS-Cache provides a list of cache cookies: - cat /proc/fs/fscache/histogram - JIFS SECS OBJ INST OP RUNS OBJ RUNS RETRV DLY RETRIEVLS - ===== ===== ========= ========= ========= ========= ========= + /proc/fs/fscache/cookies - This shows the breakdown of the number of times each amount of time - between 0 jiffies and HZ-1 jiffies a variety of tasks took to run. The - columns are as follows: +This will look something like:: - ========= ======================================================= - COLUMN TIME MEASUREMENT - ========= ======================================================= - OBJ INST Length of time to instantiate an object - OP RUNS Length of time a call to process an operation took - OBJ RUNS Length of time a call to process an object event took - RETRV DLY Time between an requesting a read and lookup completing - RETRIEVLS Time between beginning and end of a retrieval - ========= ======================================================= + # cat /proc/fs/fscache/caches + CACHE REF VOLS OBJS ACCES S NAME + ======== ===== ===== ===== ===== = =============== + 00000001 2 1 2123 1 A default - Each row shows the number of events that took a particular range of times. - Each step is 1 jiffy in size. The JIFS column indicates the particular - jiffy range covered, and the SECS field the equivalent number of seconds. +where the columns are: + ======= =============================================================== + COLUMN DESCRIPTION + ======= =============================================================== + CACHE Cache cookie debug ID (also appears in traces) + REF Number of references on the cache cookie + VOLS Number of volumes cookies in this cache + OBJS Number of cache objects in use + ACCES Number of accesses pinning the cache + S State + NAME Name of the cache. + ======= =============================================================== + +The state can be (-) Inactive, (P)reparing, (A)ctive, (E)rror or (W)ithdrawing. -Object List +Volume List =========== -If CONFIG_FSCACHE_OBJECT_LIST is enabled, the FS-Cache facility will maintain a -list of all the objects currently allocated and allow them to be viewed -through:: +FS-Cache provides a list of volume cookies: - /proc/fs/fscache/objects + /proc/fs/fscache/volumes This will look something like:: - [root@andromeda ~]# head /proc/fs/fscache/objects - OBJECT PARENT STAT CHLDN OPS OOP IPR EX READS EM EV F S | NETFS_COOKIE_DEF TY FL NETFS_DATA OBJECT_KEY, AUX_DATA - ======== ======== ==== ===== === === === == ===== == == = = | ================ == == ================ ================ - 17e4b 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88001dd82820 010006017edcf8bbc93b43298fdfbe71e50b57b13a172c0117f38472, e567634700000000000000000000000063f2404a000000000000000000000000c9030000000000000000000063f2404a - 1693a 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88002db23380 010006017edcf8bbc93b43298fdfbe71e50b57b1e0162c01a2df0ea6, 420ebc4a000000000000000000000000420ebc4a0000000000000000000000000e1801000000000000000000420ebc4a + VOLUME REF nCOOK ACC FL CACHE KEY + ======== ===== ===== === == =============== ================ + 00000001 55 54 1 00 default afs,example.com,100058 -where the first set of columns before the '|' describe the object: +where the columns are: ======= =============================================================== COLUMN DESCRIPTION ======= =============================================================== - OBJECT Object debugging ID (appears as OBJ%x in some debug messages) - PARENT Debugging ID of parent object - STAT Object state - CHLDN Number of child objects of this object - OPS Number of outstanding operations on this object - OOP Number of outstanding child object management operations - IPR - EX Number of outstanding exclusive operations - READS Number of outstanding read operations - EM Object's event mask - EV Events raised on this object - F Object flags - S Object work item busy state mask (1:pending 2:running) + VOLUME The volume cookie debug ID (also appears in traces) + REF Number of references on the volume cookie + nCOOK Number of cookies in the volume + ACC Number of accesses pinning the cache + FL Flags on the volume cookie + CACHE Name of the cache or "-" + KEY The indexing key for the volume ======= =============================================================== -and the second set of columns describe the object's cookie, if present: - - ================ ====================================================== - COLUMN DESCRIPTION - ================ ====================================================== - NETFS_COOKIE_DEF Name of netfs cookie definition - TY Cookie type (IX - index, DT - data, hex - special) - FL Cookie flags - NETFS_DATA Netfs private data stored in the cookie - OBJECT_KEY Object key } 1 column, with separating comma - AUX_DATA Object aux data } presence may be configured - ================ ====================================================== - -The data shown may be filtered by attaching the a key to an appropriate keyring -before viewing the file. Something like:: - - keyctl add user fscache:objlist <restrictions> @s - -where <restrictions> are a selection of the following letters: - == ========================================================= - K Show hexdump of object key (don't show if not given) - A Show hexdump of object aux data (don't show if not given) - == ========================================================= +Cookie List +=========== -and the following paired letters: +FS-Cache provides a list of cookies: - == ========================================================= - C Show objects that have a cookie - c Show objects that don't have a cookie - B Show objects that are busy - b Show objects that aren't busy - W Show objects that have pending writes - w Show objects that don't have pending writes - R Show objects that have outstanding reads - r Show objects that don't have outstanding reads - S Show objects that have work queued - s Show objects that don't have work queued - == ========================================================= + /proc/fs/fscache/cookies -If neither side of a letter pair is given, then both are implied. For example: +This will look something like:: - keyctl add user fscache:objlist KB @s + # head /proc/fs/fscache/cookies + COOKIE VOLUME REF ACT ACC S FL DEF + ======== ======== === === === = == ================ + 00000435 00000001 1 0 -1 - 08 0000000201d080070000000000000000, 0000000000000000 + 00000436 00000001 1 0 -1 - 00 0000005601d080080000000000000000, 0000000000000051 + 00000437 00000001 1 0 -1 - 08 00023b3001d0823f0000000000000000, 0000000000000000 + 00000438 00000001 1 0 -1 - 08 0000005801d0807b0000000000000000, 0000000000000000 + 00000439 00000001 1 0 -1 - 08 00023b3201d080a10000000000000000, 0000000000000000 + 0000043a 00000001 1 0 -1 - 08 00023b3401d080a30000000000000000, 0000000000000000 + 0000043b 00000001 1 0 -1 - 08 00023b3601d080b30000000000000000, 0000000000000000 + 0000043c 00000001 1 0 -1 - 08 00023b3801d080b40000000000000000, 0000000000000000 -shows objects that are busy, and lists their object keys, but does not dump -their auxiliary data. It also implies "CcWwRrSs", but as 'B' is given, 'b' is -not implied. +where the columns are: -By default all objects and all fields will be shown. + ======= =============================================================== + COLUMN DESCRIPTION + ======= =============================================================== + COOKIE The cookie debug ID (also appears in traces) + VOLUME The parent volume cookie debug ID + REF Number of references on the volume cookie + ACT Number of times the cookie is marked for in use + ACC Number of access pins in the cookie + S State of the cookie + FL Flags on the cookie + DEF Key, auxiliary data + ======= =============================================================== Debugging @@ -549,10 +334,8 @@ This is a bitmask of debugging streams to enable: 3 8 Cookie management Function entry trace 4 16 Function exit trace 5 32 General - 6 64 Page handling Function entry trace - 7 128 Function exit trace - 8 256 General - 9 512 Operation management Function entry trace + 6-8 (Not used) + 9 512 I/O operation management Function entry trace 10 1024 Function exit trace 11 2048 General ======= ======= =============================== ======================= @@ -560,6 +343,6 @@ This is a bitmask of debugging streams to enable: The appropriate set of values should be OR'd together and the result written to the control file. For example:: - echo $((1|8|64)) >/sys/module/fscache/parameters/debug + echo $((1|8|512)) >/sys/module/fscache/parameters/debug will turn on all function entry debugging. diff --git a/Documentation/filesystems/caching/index.rst b/Documentation/filesystems/caching/index.rst index 033da7ac7c6e..df4307124b00 100644 --- a/Documentation/filesystems/caching/index.rst +++ b/Documentation/filesystems/caching/index.rst @@ -7,8 +7,6 @@ Filesystem Caching :maxdepth: 2 fscache - object + netfs-api backend-api cachefiles - netfs-api - operations diff --git a/Documentation/filesystems/caching/netfs-api.rst b/Documentation/filesystems/caching/netfs-api.rst index d9f14b8610ba..5066113acad5 100644 --- a/Documentation/filesystems/caching/netfs-api.rst +++ b/Documentation/filesystems/caching/netfs-api.rst @@ -1,896 +1,453 @@ .. SPDX-License-Identifier: GPL-2.0 -=============================== -FS-Cache Network Filesystem API -=============================== +============================== +Network Filesystem Caching API +============================== -There's an API by which a network filesystem can make use of the FS-Cache -facilities. This is based around a number of principles: +Fscache provides an API by which a network filesystem can make use of local +caching facilities. The API is arranged around a number of principles: - (1) Caches can store a number of different object types. There are two main - object types: indices and files. The first is a special type used by - FS-Cache to make finding objects faster and to make retiring of groups of - objects easier. + (1) A cache is logically organised into volumes and data storage objects + within those volumes. - (2) Every index, file or other object is represented by a cookie. This cookie - may or may not have anything associated with it, but the netfs doesn't - need to care. + (2) Volumes and data storage objects are represented by various types of + cookie. - (3) Barring the top-level index (one entry per cached netfs), the index - hierarchy for each netfs is structured according the whim of the netfs. + (3) Cookies have keys that distinguish them from their peers. -This API is declared in <linux/fscache.h>. + (4) Cookies have coherency data that allows a cache to determine if the + cached data is still valid. -.. This document contains the following sections: - - (1) Network filesystem definition - (2) Index definition - (3) Object definition - (4) Network filesystem (un)registration - (5) Cache tag lookup - (6) Index registration - (7) Data file registration - (8) Miscellaneous object registration - (9) Setting the data file size - (10) Page alloc/read/write - (11) Page uncaching - (12) Index and data file consistency - (13) Cookie enablement - (14) Miscellaneous cookie operations - (15) Cookie unregistration - (16) Index invalidation - (17) Data file invalidation - (18) FS-Cache specific page flags. - - -Network Filesystem Definition -============================= - -FS-Cache needs a description of the network filesystem. This is specified -using a record of the following structure:: - - struct fscache_netfs { - uint32_t version; - const char *name; - struct fscache_cookie *primary_index; - ... - }; - -This first two fields should be filled in before registration, and the third -will be filled in by the registration function; any other fields should just be -ignored and are for internal use only. - -The fields are: - - (1) The name of the netfs (used as the key in the toplevel index). - - (2) The version of the netfs (if the name matches but the version doesn't, the - entire in-cache hierarchy for this netfs will be scrapped and begun - afresh). - - (3) The cookie representing the primary index will be allocated according to - another parameter passed into the registration function. - -For example, kAFS (linux/fs/afs/) uses the following definitions to describe -itself:: - - struct fscache_netfs afs_cache_netfs = { - .version = 0, - .name = "afs", - }; - - -Index Definition -================ - -Indices are used for two purposes: - - (1) To aid the finding of a file based on a series of keys (such as AFS's - "cell", "volume ID", "vnode ID"). - - (2) To make it easier to discard a subset of all the files cached based around - a particular key - for instance to mirror the removal of an AFS volume. - -However, since it's unlikely that any two netfs's are going to want to define -their index hierarchies in quite the same way, FS-Cache tries to impose as few -restraints as possible on how an index is structured and where it is placed in -the tree. The netfs can even mix indices and data files at the same level, but -it's not recommended. - -Each index entry consists of a key of indeterminate length plus some auxiliary -data, also of indeterminate length. - -There are some limits on indices: - - (1) Any index containing non-index objects should be restricted to a single - cache. Any such objects created within an index will be created in the - first cache only. The cache in which an index is created can be - controlled by cache tags (see below). - - (2) The entry data must be atomically journallable, so it is limited to about - 400 bytes at present. At least 400 bytes will be available. - - (3) The depth of the index tree should be judged with care as the search - function is recursive. Too many layers will run the kernel out of stack. - - -Object Definition -================= - -To define an object, a structure of the following type should be filled out:: - - struct fscache_cookie_def - { - uint8_t name[16]; - uint8_t type; - - struct fscache_cache_tag *(*select_cache)( - const void *parent_netfs_data, - const void *cookie_netfs_data); - - enum fscache_checkaux (*check_aux)(void *cookie_netfs_data, - const void *data, - uint16_t datalen, - loff_t object_size); - - void (*get_context)(void *cookie_netfs_data, void *context); - - void (*put_context)(void *cookie_netfs_data, void *context); - - void (*mark_pages_cached)(void *cookie_netfs_data, - struct address_space *mapping, - struct pagevec *cached_pvec); - }; - -This has the following fields: - - (1) The type of the object [mandatory]. - - This is one of the following values: - - FSCACHE_COOKIE_TYPE_INDEX - This defines an index, which is a special FS-Cache type. - - FSCACHE_COOKIE_TYPE_DATAFILE - This defines an ordinary data file. - - Any other value between 2 and 255 - This defines an extraordinary object such as an XATTR. - - (2) The name of the object type (NUL terminated unless all 16 chars are used) - [optional]. - - (3) A function to select the cache in which to store an index [optional]. - - This function is invoked when an index needs to be instantiated in a cache - during the instantiation of a non-index object. Only the immediate index - parent for the non-index object will be queried. Any indices above that - in the hierarchy may be stored in multiple caches. This function does not - need to be supplied for any non-index object or any index that will only - have index children. - - If this function is not supplied or if it returns NULL then the first - cache in the parent's list will be chosen, or failing that, the first - cache in the master list. - - (4) A function to check the auxiliary data [optional]. - - This function will be called to check that a match found in the cache for - this object is valid. For instance with AFS it could check the auxiliary - data against the data version number returned by the server to determine - whether the index entry in a cache is still valid. - - If this function is absent, it will be assumed that matching objects in a - cache are always valid. - - The function is also passed the cache's idea of the object size and may - use this to manage coherency also. - - If present, the function should return one of the following values: - - FSCACHE_CHECKAUX_OKAY - - the entry is okay as is - - FSCACHE_CHECKAUX_NEEDS_UPDATE - - the entry requires update - - FSCACHE_CHECKAUX_OBSOLETE - - the entry should be deleted + (5) I/O is done asynchronously where possible. - This function can also be used to extract data from the auxiliary data in - the cache and copy it into the netfs's structures. +This API is used by:: - (5) A pair of functions to manage contexts for the completion callback - [optional]. + #include <linux/fscache.h>. - The cache read/write functions are passed a context which is then passed - to the I/O completion callback function. To ensure this context remains - valid until after the I/O completion is called, two functions may be - provided: one to get an extra reference on the context, and one to drop a - reference to it. - - If the context is not used or is a type of object that won't go out of - scope, then these functions are not required. These functions are not - required for indices as indices may not contain data. These functions may - be called in interrupt context and so may not sleep. - - (6) A function to mark a page as retaining cache metadata [optional]. - - This is called by the cache to indicate that it is retaining in-memory - information for this page and that the netfs should uncache the page when - it has finished. This does not indicate whether there's data on the disk - or not. Note that several pages at once may be presented for marking. - - The PG_fscache bit is set on the pages before this function would be - called, so the function need not be provided if this is sufficient. - - This function is not required for indices as they're not permitted data. - - (7) A function to unmark all the pages retaining cache metadata [mandatory]. - - This is called by FS-Cache to indicate that a backing store is being - unbound from a cookie and that all the marks on the pages should be - cleared to prevent confusion. Note that the cache will have torn down all - its tracking information so that the pages don't need to be explicitly - uncached. - - This function is not required for indices as they're not permitted data. - - -Network Filesystem (Un)registration -=================================== - -The first step is to declare the network filesystem to the cache. This also -involves specifying the layout of the primary index (for AFS, this would be the -"cell" level). - -The registration function is:: - - int fscache_register_netfs(struct fscache_netfs *netfs); - -It just takes a pointer to the netfs definition. It returns 0 or an error as -appropriate. - -For kAFS, registration is done as follows:: - - ret = fscache_register_netfs(&afs_cache_netfs); - -The last step is, of course, unregistration:: - - void fscache_unregister_netfs(struct fscache_netfs *netfs); - - -Cache Tag Lookup -================ - -FS-Cache permits the use of more than one cache. To permit particular index -subtrees to be bound to particular caches, the second step is to look up cache -representation tags. This step is optional; it can be left entirely up to -FS-Cache as to which cache should be used. The problem with doing that is that -FS-Cache will always pick the first cache that was registered. - -To get the representation for a named tag:: - - struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name); - -This takes a text string as the name and returns a representation of a tag. It -will never return an error. It may return a dummy tag, however, if it runs out -of memory; this will inhibit caching with this tag. - -Any representation so obtained must be released by passing it to this function:: - - void fscache_release_cache_tag(struct fscache_cache_tag *tag); +.. This document contains the following sections: -The tag will be retrieved by FS-Cache when it calls the object definition -operation select_cache(). + (1) Overview + (2) Volume registration + (3) Data file registration + (4) Declaring a cookie to be in use + (5) Resizing a data file (truncation) + (6) Data I/O API + (7) Data file coherency + (8) Data file invalidation + (9) Write back resource management + (10) Caching of local modifications + (11) Page release and invalidation + + +Overview +======== + +The fscache hierarchy is organised on two levels from a network filesystem's +point of view. The upper level represents "volumes" and the lower level +represents "data storage objects". These are represented by two types of +cookie, hereafter referred to as "volume cookies" and "cookies". + +A network filesystem acquires a volume cookie for a volume using a volume key, +which represents all the information that defines that volume (e.g. cell name +or server address, volume ID or share name). This must be rendered as a +printable string that can be used as a directory name (ie. no '/' characters +and shouldn't begin with a '.'). The maximum name length is one less than the +maximum size of a filename component (allowing the cache backend one char for +its own purposes). + +A filesystem would typically have a volume cookie for each superblock. + +The filesystem then acquires a cookie for each file within that volume using an +object key. Object keys are binary blobs and only need to be unique within +their parent volume. The cache backend is reponsible for rendering the binary +blob into something it can use and may employ hash tables, trees or whatever to +improve its ability to find an object. This is transparent to the network +filesystem. + +A filesystem would typically have a cookie for each inode, and would acquire it +in iget and relinquish it when evicting the cookie. + +Once it has a cookie, the filesystem needs to mark the cookie as being in use. +This causes fscache to send the cache backend off to look up/create resources +for the cookie in the background, to check its coherency and, if necessary, to +mark the object as being under modification. + +A filesystem would typically "use" the cookie in its file open routine and +unuse it in file release and it needs to use the cookie around calls to +truncate the cookie locally. It *also* needs to use the cookie when the +pagecache becomes dirty and unuse it when writeback is complete. This is +slightly tricky, and provision is made for it. + +When performing a read, write or resize on a cookie, the filesystem must first +begin an operation. This copies the resources into a holding struct and puts +extra pins into the cache to stop cache withdrawal from tearing down the +structures being used. The actual operation can then be issued and conflicting +invalidations can be detected upon completion. + +The filesystem is expected to use netfslib to access the cache, but that's not +actually required and it can use the fscache I/O API directly. + + +Volume Registration +=================== + +The first step for a network filsystem is to acquire a volume cookie for the +volume it wants to access:: + + struct fscache_volume * + fscache_acquire_volume(const char *volume_key, + const char *cache_name, + const void *coherency_data, + size_t coherency_len); + +This function creates a volume cookie with the specified volume key as its name +and notes the coherency data. + +The volume key must be a printable string with no '/' characters in it. It +should begin with the name of the filesystem and should be no longer than 254 +characters. It should uniquely represent the volume and will be matched with +what's stored in the cache. + +The caller may also specify the name of the cache to use. If specified, +fscache will look up or create a cache cookie of that name and will use a cache +of that name if it is online or comes online. If no cache name is specified, +it will use the first cache that comes to hand and set the name to that. + +The specified coherency data is stored in the cookie and will be matched +against coherency data stored on disk. The data pointer may be NULL if no data +is provided. If the coherency data doesn't match, the entire cache volume will +be invalidated. + +This function can return errors such as EBUSY if the volume key is already in +use by an acquired volume or ENOMEM if an allocation failure occured. It may +also return a NULL volume cookie if fscache is not enabled. It is safe to +pass a NULL cookie to any function that takes a volume cookie. This will +cause that function to do nothing. + + +When the network filesystem has finished with a volume, it should relinquish it +by calling:: + + void fscache_relinquish_volume(struct fscache_volume *volume, + const void *coherency_data, + bool invalidate); + +This will cause the volume to be committed or removed, and if sealed the +coherency data will be set to the value supplied. The amount of coherency data +must match the length specified when the volume was acquired. Note that all +data cookies obtained in this volume must be relinquished before the volume is +relinquished. -Index Registration -================== +Data File Registration +====================== -The third step is to inform FS-Cache about part of an index hierarchy that can -be used to locate files. This is done by requesting a cookie for each index in -the path to the file:: +Once it has a volume cookie, a network filesystem can use it to acquire a +cookie for data storage:: struct fscache_cookie * - fscache_acquire_cookie(struct fscache_cookie *parent, - const struct fscache_object_def *def, + fscache_acquire_cookie(struct fscache_volume *volume, + u8 advice, const void *index_key, size_t index_key_len, const void *aux_data, size_t aux_data_len, - void *netfs_data, - loff_t object_size, - bool enable); + loff_t object_size) -This function creates an index entry in the index represented by parent, -filling in the index entry by calling the operations pointed to by def. +This creates the cookie in the volume using the specified index key. The index +key is a binary blob of the given length and must be unique for the volume. +This is saved into the cookie. There are no restrictions on the content, but +its length shouldn't exceed about three quarters of the maximum filename length +to allow for encoding. -A unique key that represents the object within the parent must be pointed to by -index_key and is of length index_key_len. +The caller should also pass in a piece of coherency data in aux_data. A buffer +of size aux_data_len will be allocated and the coherency data copied in. It is +assumed that the size is invariant over time. The coherency data is used to +check the validity of data in the cache. Functions are provided by which the +coherency data can be updated. -An optional blob of auxiliary data that is to be stored within the cache can be -pointed to with aux_data and should be of length aux_data_len. This would -typically be used for storing coherency data. +The file size of the object being cached should also be provided. This may be +used to trim the data and will be stored with the coherency data. -The netfs may pass an arbitrary value in netfs_data and this will be presented -to it in the event of any calling back. This may also be used in tracing or -logging of messages. +This function never returns an error, though it may return a NULL cookie on +allocation failure or if fscache is not enabled. It is safe to pass in a NULL +volume cookie and pass the NULL cookie returned to any function that takes it. +This will cause that function to do nothing. -The cache tracks the size of the data attached to an object and this set to be -object_size. For indices, this should be 0. This value will be passed to the -->check_aux() callback. -Note that this function never returns an error - all errors are handled -internally. It may, however, return NULL to indicate no cookie. It is quite -acceptable to pass this token back to this function as the parent to another -acquisition (or even to the relinquish cookie, read page and write page -functions - see below). +When the network filesystem has finished with a cookie, it should relinquish it +by calling:: -Note also that no indices are actually created in a cache until a non-index -object needs to be created somewhere down the hierarchy. Furthermore, an index -may be created in several different caches independently at different times. -This is all handled transparently, and the netfs doesn't see any of it. + void fscache_relinquish_cookie(struct fscache_cookie *cookie, + bool retire); -A cookie will be created in the disabled state if enabled is false. A cookie -must be enabled to do anything with it. A disabled cookie can be enabled by -calling fscache_enable_cookie() (see below). +This will cause fscache to either commit the storage backing the cookie or +delete it. -For example, with AFS, a cell would be added to the primary index. This index -entry would have a dependent inode containing volume mappings within this cell:: - cell->cache = - fscache_acquire_cookie(afs_cache_netfs.primary_index, - &afs_cell_cache_index_def, - cell->name, strlen(cell->name), - NULL, 0, - cell, 0, true); +Marking A Cookie In-Use +======================= -And then a particular volume could be added to that index by ID, creating -another index for vnodes (AFS inode equivalents):: +Once a cookie has been acquired by a network filesystem, the filesystem should +tell fscache when it intends to use the cookie (typically done on file open) +and should say when it has finished with it (typically on file close):: - volume->cache = - fscache_acquire_cookie(volume->cell->cache, - &afs_volume_cache_index_def, - &volume->vid, sizeof(volume->vid), - NULL, 0, - volume, 0, true); + void fscache_use_cookie(struct fscache_cookie *cookie, + bool will_modify); + void fscache_unuse_cookie(struct fscache_cookie *cookie, + const void *aux_data, + const loff_t *object_size); +The *use* function tells fscache that it will use the cookie and, additionally, +indicate if the user is intending to modify the contents locally. If not yet +done, this will trigger the cache backend to go and gather the resources it +needs to access/store data in the cache. This is done in the background, and +so may not be complete by the time the function returns. -Data File Registration -====================== +The *unuse* function indicates that a filesystem has finished using a cookie. +It optionally updates the stored coherency data and object size and then +decreases the in-use counter. When the last user unuses the cookie, it is +scheduled for garbage collection. If not reused within a short time, the +resources will be released to reduce system resource consumption. -The fourth step is to request a data file be created in the cache. This is -identical to index cookie acquisition. The only difference is that the type in -the object definition should be something other than index type:: +A cookie must be marked in-use before it can be accessed for read, write or +resize - and an in-use mark must be kept whilst there is dirty data in the +pagecache in order to avoid an oops due to trying to open a file during process +exit. - vnode->cache = - fscache_acquire_cookie(volume->cache, - &afs_vnode_cache_object_def, - &key, sizeof(key), - &aux, sizeof(aux), - vnode, vnode->status.size, true); +Note that in-use marks are cumulative. For each time a cookie is marked +in-use, it must be unused. -Miscellaneous Object Registration +Resizing A Data File (Truncation) ================================= -An optional step is to request an object of miscellaneous type be created in -the cache. This is almost identical to index cookie acquisition. The only -difference is that the type in the object definition should be something other -than index type. While the parent object could be an index, it's more likely -it would be some other type of object such as a data file:: - - xattr->cache = - fscache_acquire_cookie(vnode->cache, - &afs_xattr_cache_object_def, - &xattr->name, strlen(xattr->name), - NULL, 0, - xattr, strlen(xattr->val), true); - -Miscellaneous objects might be used to store extended attributes or directory -entries for example. - - -Setting the Data File Size -========================== - -The fifth step is to set the physical attributes of the file, such as its size. -This doesn't automatically reserve any space in the cache, but permits the -cache to adjust its metadata for data tracking appropriately:: +If a network filesystem file is resized locally by truncation, the following +should be called to notify the cache:: - int fscache_attr_changed(struct fscache_cookie *cookie); + void fscache_resize_cookie(struct fscache_cookie *cookie, + loff_t new_size); -The cache will return -ENOBUFS if there is no backing cache or if there is no -space to allocate any extra metadata required in the cache. +The caller must have first marked the cookie in-use. The cookie and the new +size are passed in and the cache is synchronously resized. This is expected to +be called from ``->setattr()`` inode operation under the inode lock. -Note that attempts to read or write data pages in the cache over this size may -be rebuffed with -ENOBUFS. -This operation schedules an attribute adjustment to happen asynchronously at -some point in the future, and as such, it may happen after the function returns -to the caller. The attribute adjustment excludes read and write operations. +Data I/O API +============ +To do data I/O operations directly through a cookie, the following functions +are available:: -Page alloc/read/write -===================== + int fscache_begin_read_operation(struct netfs_cache_resources *cres, + struct fscache_cookie *cookie); + int fscache_read(struct netfs_cache_resources *cres, + loff_t start_pos, + struct iov_iter *iter, + enum netfs_read_from_hole read_hole, + netfs_io_terminated_t term_func, + void *term_func_priv); + int fscache_write(struct netfs_cache_resources *cres, + loff_t start_pos, + struct iov_iter *iter, + netfs_io_terminated_t term_func, + void *term_func_priv); -And the sixth step is to store and retrieve pages in the cache. There are -three functions that are used to do this. +The *begin* function sets up an operation, attaching the resources required to +the cache resources block from the cookie. Assuming it doesn't return an error +(for instance, it will return -ENOBUFS if given a NULL cookie, but otherwise do +nothing), then one of the other two functions can be issued. -Note: +The *read* and *write* functions initiate a direct-IO operation. Both take the +previously set up cache resources block, an indication of the start file +position, and an I/O iterator that describes buffer and indicates the amount of +data. - (1) A page should not be re-read or re-allocated without uncaching it first. +The read function also takes a parameter to indicate how it should handle a +partially populated region (a hole) in the disk content. This may be to ignore +it, skip over an initial hole and place zeros in the buffer or give an error. - (2) A read or allocated page must be uncached when the netfs page is released - from the pagecache. - - (3) A page should only be written to the cache if previous read or allocated. - -This permits the cache to maintain its page tracking in proper order. - - -PAGE READ ---------- - -Firstly, the netfs should ask FS-Cache to examine the caches and read the -contents cached for a particular page of a particular file if present, or else -allocate space to store the contents if not:: +The read and write functions can be given an optional termination function that +will be run on completion:: typedef - void (*fscache_rw_complete_t)(struct page *page, - void *context, - int error); - - int fscache_read_or_alloc_page(struct fscache_cookie *cookie, - struct page *page, - fscache_rw_complete_t end_io_func, - void *context, - gfp_t gfp); - -The cookie argument must specify a cookie for an object that isn't an index, -the page specified will have the data loaded into it (and is also used to -specify the page number), and the gfp argument is used to control how any -memory allocations made are satisfied. - -If the cookie indicates the inode is not cached: - - (1) The function will return -ENOBUFS. - -Else if there's a copy of the page resident in the cache: - - (1) The mark_pages_cached() cookie operation will be called on that page. - - (2) The function will submit a request to read the data from the cache's - backing device directly into the page specified. + void (*netfs_io_terminated_t)(void *priv, ssize_t transferred_or_error, + bool was_async); - (3) The function will return 0. +If a termination function is given, the operation will be run asynchronously +and the termination function will be called upon completion. If not given, the +operation will be run synchronously. Note that in the asynchronous case, it is +possible for the operation to complete before the function returns. - (4) When the read is complete, end_io_func() will be invoked with: +Both the read and write functions end the operation when they complete, +detaching any pinned resources. - * The netfs data supplied when the cookie was created. +The read operation will fail with ESTALE if invalidation occurred whilst the +operation was ongoing. - * The page descriptor. - * The context argument passed to the above function. This will be - maintained with the get_context/put_context functions mentioned above. +Data File Coherency +=================== - * An argument that's 0 on success or negative for an error code. - - If an error occurs, it should be assumed that the page contains no usable - data. fscache_readpages_cancel() may need to be called. - - end_io_func() will be called in process context if the read is results in - an error, but it might be called in interrupt context if the read is - successful. - -Otherwise, if there's not a copy available in cache, but the cache may be able -to store the page: - - (1) The mark_pages_cached() cookie operation will be called on that page. - - (2) A block may be reserved in the cache and attached to the object at the - appropriate place. - - (3) The function will return -ENODATA. - -This function may also return -ENOMEM or -EINTR, in which case it won't have -read any data from the cache. - - -Page Allocate -------------- - -Alternatively, if there's not expected to be any data in the cache for a page -because the file has been extended, a block can simply be allocated instead:: - - int fscache_alloc_page(struct fscache_cookie *cookie, - struct page *page, - gfp_t gfp); - -This is similar to the fscache_read_or_alloc_page() function, except that it -never reads from the cache. It will return 0 if a block has been allocated, -rather than -ENODATA as the other would. One or the other must be performed -before writing to the cache. - -The mark_pages_cached() cookie operation will be called on the page if -successful. - - -Page Write ----------- - -Secondly, if the netfs changes the contents of the page (either due to an -initial download or if a user performs a write), then the page should be -written back to the cache:: - - int fscache_write_page(struct fscache_cookie *cookie, - struct page *page, - loff_t object_size, - gfp_t gfp); - -The cookie argument must specify a data file cookie, the page specified should -contain the data to be written (and is also used to specify the page number), -object_size is the revised size of the object and the gfp argument is used to -control how any memory allocations made are satisfied. - -The page must have first been read or allocated successfully and must not have -been uncached before writing is performed. - -If the cookie indicates the inode is not cached then: - - (1) The function will return -ENOBUFS. - -Else if space can be allocated in the cache to hold this page: - - (1) PG_fscache_write will be set on the page. - - (2) The function will submit a request to write the data to cache's backing - device directly from the page specified. - - (3) The function will return 0. - - (4) When the write is complete PG_fscache_write is cleared on the page and - anyone waiting for that bit will be woken up. - -Else if there's no space available in the cache, -ENOBUFS will be returned. It -is also possible for the PG_fscache_write bit to be cleared when no write took -place if unforeseen circumstances arose (such as a disk error). - -Writing takes place asynchronously. - - -Multiple Page Read ------------------- - -A facility is provided to read several pages at once, as requested by the -readpages() address space operation:: - - int fscache_read_or_alloc_pages(struct fscache_cookie *cookie, - struct address_space *mapping, - struct list_head *pages, - int *nr_pages, - fscache_rw_complete_t end_io_func, - void *context, - gfp_t gfp); - -This works in a similar way to fscache_read_or_alloc_page(), except: - - (1) Any page it can retrieve data for is removed from pages and nr_pages and - dispatched for reading to the disk. Reads of adjacent pages on disk may - be merged for greater efficiency. - - (2) The mark_pages_cached() cookie operation will be called on several pages - at once if they're being read or allocated. - - (3) If there was an general error, then that error will be returned. - - Else if some pages couldn't be allocated or read, then -ENOBUFS will be - returned. - - Else if some pages couldn't be read but were allocated, then -ENODATA will - be returned. - - Otherwise, if all pages had reads dispatched, then 0 will be returned, the - list will be empty and ``*nr_pages`` will be 0. - - (4) end_io_func will be called once for each page being read as the reads - complete. It will be called in process context if error != 0, but it may - be called in interrupt context if there is no error. - -Note that a return of -ENODATA, -ENOBUFS or any other error does not preclude -some of the pages being read and some being allocated. Those pages will have -been marked appropriately and will need uncaching. - - -Cancellation of Unread Pages ----------------------------- - -If one or more pages are passed to fscache_read_or_alloc_pages() but not then -read from the cache and also not read from the underlying filesystem then -those pages will need to have any marks and reservations removed. This can be -done by calling:: - - void fscache_readpages_cancel(struct fscache_cookie *cookie, - struct list_head *pages); - -prior to returning to the caller. The cookie argument should be as passed to -fscache_read_or_alloc_pages(). Every page in the pages list will be examined -and any that have PG_fscache set will be uncached. - - -Page Uncaching -============== - -To uncache a page, this function should be called:: - - void fscache_uncache_page(struct fscache_cookie *cookie, - struct page *page); - -This function permits the cache to release any in-memory representation it -might be holding for this netfs page. This function must be called once for -each page on which the read or write page functions above have been called to -make sure the cache's in-memory tracking information gets torn down. - -Note that pages can't be explicitly deleted from the a data file. The whole -data file must be retired (see the relinquish cookie function below). - -Furthermore, note that this does not cancel the asynchronous read or write -operation started by the read/alloc and write functions, so the page -invalidation functions must use:: - - bool fscache_check_page_write(struct fscache_cookie *cookie, - struct page *page); - -to see if a page is being written to the cache, and:: - - void fscache_wait_on_page_write(struct fscache_cookie *cookie, - struct page *page); - -to wait for it to finish if it is. - - -When releasepage() is being implemented, a special FS-Cache function exists to -manage the heuristics of coping with vmscan trying to eject pages, which may -conflict with the cache trying to write pages to the cache (which may itself -need to allocate memory):: - - bool fscache_maybe_release_page(struct fscache_cookie *cookie, - struct page *page, - gfp_t gfp); - -This takes the netfs cookie, and the page and gfp arguments as supplied to -releasepage(). It will return false if the page cannot be released yet for -some reason and if it returns true, the page has been uncached and can now be -released. - -To make a page available for release, this function may wait for an outstanding -storage request to complete, or it may attempt to cancel the storage request - -in which case the page will not be stored in the cache this time. - - -Bulk Image Page Uncache ------------------------ - -A convenience routine is provided to perform an uncache on all the pages -attached to an inode. This assumes that the pages on the inode correspond on a -1:1 basis with the pages in the cache:: - - void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie, - struct inode *inode); - -This takes the netfs cookie that the pages were cached with and the inode that -the pages are attached to. This function will wait for pages to finish being -written to the cache and for the cache to finish with the page generally. No -error is returned. - - -Index and Data File consistency -=============================== - -To find out whether auxiliary data for an object is up to data within the -cache, the following function can be called:: - - int fscache_check_consistency(struct fscache_cookie *cookie, - const void *aux_data); - -This will call back to the netfs to check whether the auxiliary data associated -with a cookie is correct; if aux_data is non-NULL, it will update the auxiliary -data buffer first. It returns 0 if it is and -ESTALE if it isn't; it may also -return -ENOMEM and -ERESTARTSYS. - -To request an update of the index data for an index or other object, the -following function should be called:: +To request an update of the coherency data and file size on a cookie, the +following should be called:: void fscache_update_cookie(struct fscache_cookie *cookie, - const void *aux_data); - -This function will update the cookie's auxiliary data buffer from aux_data if -that is non-NULL and then schedule this to be stored on disk. The update -method in the parent index definition will be called to transfer the data. - -Note that partial updates may happen automatically at other times, such as when -data blocks are added to a data file object. - - -Cookie Enablement -================= - -Cookies exist in one of two states: enabled and disabled. If a cookie is -disabled, it ignores all attempts to acquire child cookies; check, update or -invalidate its state; allocate, read or write backing pages - though it is -still possible to uncache pages and relinquish the cookie. - -The initial enablement state is set by fscache_acquire_cookie(), but the cookie -can be enabled or disabled later. To disable a cookie, call:: - - void fscache_disable_cookie(struct fscache_cookie *cookie, - const void *aux_data, - bool invalidate); - -If the cookie is not already disabled, this locks the cookie against other -enable and disable ops, marks the cookie as being disabled, discards or -invalidates any backing objects and waits for cessation of activity on any -associated object before unlocking the cookie. - -All possible failures are handled internally. The caller should consider -calling fscache_uncache_all_inode_pages() afterwards to make sure all page -markings are cleared up. - -Cookies can be enabled or reenabled with:: - - void fscache_enable_cookie(struct fscache_cookie *cookie, const void *aux_data, - loff_t object_size, - bool (*can_enable)(void *data), - void *data) - -If the cookie is not already enabled, this locks the cookie against other -enable and disable ops, invokes can_enable() and, if the cookie is not an index -cookie, will begin the procedure of acquiring backing objects. - -The optional can_enable() function is passed the data argument and returns a -ruling as to whether or not enablement should actually be permitted to begin. - -All possible failures are handled internally. The cookie will only be marked -as enabled if provisional backing objects are allocated. + const loff_t *object_size); -The object's data size is updated from object_size and is passed to the -->check_aux() function. +This will update the cookie's coherency data and/or file size. -In both cases, the cookie's auxiliary data buffer is updated from aux_data if -that is non-NULL inside the enablement lock before proceeding. +Data File Invalidation +====================== -Miscellaneous Cookie operations -=============================== - -There are a number of operations that can be used to control cookies: - - * Cookie pinning:: +Sometimes it will be necessary to invalidate an object that contains data. +Typically this will be necessary when the server informs the network filesystem +of a remote third-party change - at which point the filesystem has to throw +away the state and cached data that it had for an file and reload from the +server. - int fscache_pin_cookie(struct fscache_cookie *cookie); - void fscache_unpin_cookie(struct fscache_cookie *cookie); +To indicate that a cache object should be invalidated, the following should be +called:: - These operations permit data cookies to be pinned into the cache and to - have the pinning removed. They are not permitted on index cookies. + void fscache_invalidate(struct fscache_cookie *cookie, + const void *aux_data, + loff_t size, + unsigned int flags); + +This increases the invalidation counter in the cookie to cause outstanding +reads to fail with -ESTALE, sets the coherency data and file size from the +information supplied, blocks new I/O on the cookie and dispatches the cache to +go and get rid of the old data. - The pinning function will return 0 if successful, -ENOBUFS in the cookie - isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning, - -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or - -EIO if there's any other problem. +Invalidation runs asynchronously in a worker thread so that it doesn't block +too much. - * Data space reservation:: - int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size); +Write-Back Resource Management +============================== - This permits a netfs to request cache space be reserved to store up to the - given amount of a file. It is permitted to ask for more than the current - size of the file to allow for future file expansion. +To write data to the cache from network filesystem writeback, the cache +resources required need to be pinned at the point the modification is made (for +instance when the page is marked dirty) as it's not possible to open a file in +a thread that's exiting. - If size is given as zero then the reservation will be cancelled. +The following facilities are provided to manage this: - The function will return 0 if successful, -ENOBUFS in the cookie isn't - backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations, - -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or - -EIO if there's any other problem. + * An inode flag, ``I_PINNING_FSCACHE_WB``, is provided to indicate that an + in-use is held on the cookie for this inode. It can only be changed if the + the inode lock is held. - Note that this doesn't pin an object in a cache; it can still be culled to - make space if it's not in use. + * A flag, ``unpinned_fscache_wb`` is placed in the ``writeback_control`` + struct that gets set if ``__writeback_single_inode()`` clears + ``I_PINNING_FSCACHE_WB`` because all the dirty pages were cleared. +To support this, the following functions are provided:: -Cookie Unregistration -===================== + bool fscache_dirty_folio(struct address_space *mapping, + struct folio *folio, + struct fscache_cookie *cookie); + void fscache_unpin_writeback(struct writeback_control *wbc, + struct fscache_cookie *cookie); + void fscache_clear_inode_writeback(struct fscache_cookie *cookie, + struct inode *inode, + const void *aux); -To get rid of a cookie, this function should be called:: +The *set* function is intended to be called from the filesystem's +``dirty_folio`` address space operation. If ``I_PINNING_FSCACHE_WB`` is not +set, it sets that flag and increments the use count on the cookie (the caller +must already have called ``fscache_use_cookie()``). - void fscache_relinquish_cookie(struct fscache_cookie *cookie, - const void *aux_data, - bool retire); +The *unpin* function is intended to be called from the filesystem's +``write_inode`` superblock operation. It cleans up after writing by unusing +the cookie if unpinned_fscache_wb is set in the writeback_control struct. -If retire is non-zero, then the object will be marked for recycling, and all -copies of it will be removed from all active caches in which it is present. -Not only that but all child objects will also be retired. +The *clear* function is intended to be called from the netfs's ``evict_inode`` +superblock operation. It must be called *after* +``truncate_inode_pages_final()``, but *before* ``clear_inode()``. This cleans +up any hanging ``I_PINNING_FSCACHE_WB``. It also allows the coherency data to +be updated. -If retire is zero, then the object may be available again when next the -acquisition function is called. Retirement here will overrule the pinning on a -cookie. -The cookie's auxiliary data will be updated from aux_data if that is non-NULL -so that the cache can lazily update it on disk. +Caching of Local Modifications +============================== -One very important note - relinquish must NOT be called for a cookie unless all -the cookies for "child" indices, objects and pages have been relinquished -first. +If a network filesystem has locally modified data that it wants to write to the +cache, it needs to mark the pages to indicate that a write is in progress, and +if the mark is already present, it needs to wait for it to be removed first +(presumably due to an already in-progress operation). This prevents multiple +competing DIO writes to the same storage in the cache. +Firstly, the netfs should determine if caching is available by doing something +like:: -Index Invalidation -================== + bool caching = fscache_cookie_enabled(cookie); -There is no direct way to invalidate an index subtree. To do this, the caller -should relinquish and retire the cookie they have, and then acquire a new one. +If caching is to be attempted, pages should be waited for and then marked using +the following functions provided by the netfs helper library:: + void set_page_fscache(struct page *page); + void wait_on_page_fscache(struct page *page); + int wait_on_page_fscache_killable(struct page *page); -Data File Invalidation -====================== +Once all the pages in the span are marked, the netfs can ask fscache to +schedule a write of that region:: -Sometimes it will be necessary to invalidate an object that contains data. -Typically this will be necessary when the server tells the netfs of a foreign -change - at which point the netfs has to throw away all the state it had for an -inode and reload from the server. + void fscache_write_to_cache(struct fscache_cookie *cookie, + struct address_space *mapping, + loff_t start, size_t len, loff_t i_size, + netfs_io_terminated_t term_func, + void *term_func_priv, + bool caching) -To indicate that a cache object should be invalidated, the following function -can be called:: +And if an error occurs before that point is reached, the marks can be removed +by calling:: - void fscache_invalidate(struct fscache_cookie *cookie); + void fscache_clear_page_bits(struct fscache_cookie *cookie, + struct address_space *mapping, + loff_t start, size_t len, + bool caching) -This can be called with spinlocks held as it defers the work to a thread pool. -All extant storage, retrieval and attribute change ops at this point are -cancelled and discarded. Some future operations will be rejected until the -cache has had a chance to insert a barrier in the operations queue. After -that, operations will be queued again behind the invalidation operation. +In both of these functions, the cookie representing the cache object to be +written to and a pointer to the mapping to which the source pages are attached +are passed in; start and len indicate the size of the region that's going to be +written (it doesn't have to align to page boundaries necessarily, but it does +have to align to DIO boundaries on the backing filesystem). The caching +parameter indicates if caching should be skipped, and if false, the functions +do nothing. -The invalidation operation will perform an attribute change operation and an -auxiliary data update operation as it is very likely these will have changed. +The write function takes some additional parameters: i_size indicates the size +of the netfs file and term_func indicates an optional completion function, to +which term_func_priv will be passed, along with the error or amount written. -Using the following function, the netfs can wait for the invalidation operation -to have reached a point at which it can start submitting ordinary operations -once again:: +Note that the write function will always run asynchronously and will unmark all +the pages upon completion before calling term_func. - void fscache_wait_on_invalidate(struct fscache_cookie *cookie); +Page Release and Invalidation +============================= -FS-cache Specific Page Flag -=========================== +Fscache keeps track of whether we have any data in the cache yet for a cache +object we've just created. It knows it doesn't have to do any reading until it +has done a write and then the page it wrote from has been released by the VM, +after which it *has* to look in the cache. -FS-Cache makes use of a page flag, PG_private_2, for its own purpose. This is -given the alternative name PG_fscache. +To inform fscache that a page might now be in the cache, the following function +should be called from the ``releasepage`` address space op:: -PG_fscache is used to indicate that the page is known by the cache, and that -the cache must be informed if the page is going to go away. It's an indication -to the netfs that the cache has an interest in this page, where an interest may -be a pointer to it, resources allocated or reserved for it, or I/O in progress -upon it. + void fscache_note_page_release(struct fscache_cookie *cookie); -The netfs can use this information in methods such as releasepage() to -determine whether it needs to uncache a page or update it. +if the page has been released (ie. releasepage returned true). -Furthermore, if this bit is set, releasepage() and invalidatepage() operations -will be called on a page to get rid of it, even if PG_private is not set. This -allows caching to attempted on a page before read_cache_pages() to be called -after fscache_read_or_alloc_pages() as the former will try and release pages it -was given under certain circumstances. +Page release and page invalidation should also wait for any mark left on the +page to say that a DIO write is underway from that page:: -This bit does not overlap with such as PG_private. This means that FS-Cache -can be used with a filesystem that uses the block buffering code. + void wait_on_page_fscache(struct page *page); + int wait_on_page_fscache_killable(struct page *page); -There are a number of operations defined on this flag:: - int PageFsCache(struct page *page); - void SetPageFsCache(struct page *page) - void ClearPageFsCache(struct page *page) - int TestSetPageFsCache(struct page *page) - int TestClearPageFsCache(struct page *page) +API Function Reference +====================== -These functions are bit test, bit set, bit clear, bit test and set and bit -test and clear operations on PG_fscache. +.. kernel-doc:: include/linux/fscache.h diff --git a/Documentation/filesystems/caching/object.rst b/Documentation/filesystems/caching/object.rst deleted file mode 100644 index ce0e043ccd33..000000000000 --- a/Documentation/filesystems/caching/object.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -==================================================== -In-Kernel Cache Object Representation and Management -==================================================== - -By: David Howells <dhowells@redhat.com> - -.. Contents: - - (*) Representation - - (*) Object management state machine. - - - Provision of cpu time. - - Locking simplification. - - (*) The set of states. - - (*) The set of events. - - -Representation -============== - -FS-Cache maintains an in-kernel representation of each object that a netfs is -currently interested in. Such objects are represented by the fscache_cookie -struct and are referred to as cookies. - -FS-Cache also maintains a separate in-kernel representation of the objects that -a cache backend is currently actively caching. Such objects are represented by -the fscache_object struct. The cache backends allocate these upon request, and -are expected to embed them in their own representations. These are referred to -as objects. - -There is a 1:N relationship between cookies and objects. A cookie may be -represented by multiple objects - an index may exist in more than one cache - -or even by no objects (it may not be cached). - -Furthermore, both cookies and objects are hierarchical. The two hierarchies -correspond, but the cookies tree is a superset of the union of the object trees -of multiple caches:: - - NETFS INDEX TREE : CACHE 1 : CACHE 2 - : : - : +-----------+ : - +----------->| IObject | : - +-----------+ | : +-----------+ : - | ICookie |-------+ : | : - +-----------+ | : | : +-----------+ - | +------------------------------>| IObject | - | : | : +-----------+ - | : V : | - | : +-----------+ : | - V +----------->| IObject | : | - +-----------+ | : +-----------+ : | - | ICookie |-------+ : | : V - +-----------+ | : | : +-----------+ - | +------------------------------>| IObject | - +-----+-----+ : | : +-----------+ - | | : | : | - V | : V : | - +-----------+ | : +-----------+ : | - | ICookie |------------------------->| IObject | : | - +-----------+ | : +-----------+ : | - | V : | : V - | +-----------+ : | : +-----------+ - | | ICookie |-------------------------------->| IObject | - | +-----------+ : | : +-----------+ - V | : V : | - +-----------+ | : +-----------+ : | - | DCookie |------------------------->| DObject | : | - +-----------+ | : +-----------+ : | - | : : | - +-------+-------+ : : | - | | : : | - V V : : V - +-----------+ +-----------+ : : +-----------+ - | DCookie | | DCookie |------------------------>| DObject | - +-----------+ +-----------+ : : +-----------+ - : : - -In the above illustration, ICookie and IObject represent indices and DCookie -and DObject represent data storage objects. Indices may have representation in -multiple caches, but currently, non-index objects may not. Objects of any type -may also be entirely unrepresented. - -As far as the netfs API goes, the netfs is only actually permitted to see -pointers to the cookies. The cookies themselves and any objects attached to -those cookies are hidden from it. - - -Object Management State Machine -=============================== - -Within FS-Cache, each active object is managed by its own individual state -machine. The state for an object is kept in the fscache_object struct, in -object->state. A cookie may point to a set of objects that are in different -states. - -Each state has an action associated with it that is invoked when the machine -wakes up in that state. There are four logical sets of states: - - (1) Preparation: states that wait for the parent objects to become ready. The - representations are hierarchical, and it is expected that an object must - be created or accessed with respect to its parent object. - - (2) Initialisation: states that perform lookups in the cache and validate - what's found and that create on disk any missing metadata. - - (3) Normal running: states that allow netfs operations on objects to proceed - and that update the state of objects. - - (4) Termination: states that detach objects from their netfs cookies, that - delete objects from disk, that handle disk and system errors and that free - up in-memory resources. - - -In most cases, transitioning between states is in response to signalled events. -When a state has finished processing, it will usually set the mask of events in -which it is interested (object->event_mask) and relinquish the worker thread. -Then when an event is raised (by calling fscache_raise_event()), if the event -is not masked, the object will be queued for processing (by calling -fscache_enqueue_object()). - - -Provision of CPU Time ---------------------- - -The work to be done by the various states was given CPU time by the threads of -the slow work facility. This was used in preference to the workqueue facility -because: - - (1) Threads may be completely occupied for very long periods of time by a - particular work item. These state actions may be doing sequences of - synchronous, journalled disk accesses (lookup, mkdir, create, setxattr, - getxattr, truncate, unlink, rmdir, rename). - - (2) Threads may do little actual work, but may rather spend a lot of time - sleeping on I/O. This means that single-threaded and 1-per-CPU-threaded - workqueues don't necessarily have the right numbers of threads. - - -Locking Simplification ----------------------- - -Because only one worker thread may be operating on any particular object's -state machine at once, this simplifies the locking, particularly with respect -to disconnecting the netfs's representation of a cache object (fscache_cookie) -from the cache backend's representation (fscache_object) - which may be -requested from either end. - - -The Set of States -================= - -The object state machine has a set of states that it can be in. There are -preparation states in which the object sets itself up and waits for its parent -object to transit to a state that allows access to its children: - - (1) State FSCACHE_OBJECT_INIT. - - Initialise the object and wait for the parent object to become active. In - the cache, it is expected that it will not be possible to look an object - up from the parent object, until that parent object itself has been looked - up. - -There are initialisation states in which the object sets itself up and accesses -disk for the object metadata: - - (2) State FSCACHE_OBJECT_LOOKING_UP. - - Look up the object on disk, using the parent as a starting point. - FS-Cache expects the cache backend to probe the cache to see whether this - object is represented there, and if it is, to see if it's valid (coherency - management). - - The cache should call fscache_object_lookup_negative() to indicate lookup - failure for whatever reason, and should call fscache_obtained_object() to - indicate success. - - At the completion of lookup, FS-Cache will let the netfs go ahead with - read operations, no matter whether the file is yet cached. If not yet - cached, read operations will be immediately rejected with ENODATA until - the first known page is uncached - as to that point there can be no data - to be read out of the cache for that file that isn't currently also held - in the pagecache. - - (3) State FSCACHE_OBJECT_CREATING. - - Create an object on disk, using the parent as a starting point. This - happens if the lookup failed to find the object, or if the object's - coherency data indicated what's on disk is out of date. In this state, - FS-Cache expects the cache to create - - The cache should call fscache_obtained_object() if creation completes - successfully, fscache_object_lookup_negative() otherwise. - - At the completion of creation, FS-Cache will start processing write - operations the netfs has queued for an object. If creation failed, the - write ops will be transparently discarded, and nothing recorded in the - cache. - -There are some normal running states in which the object spends its time -servicing netfs requests: - - (4) State FSCACHE_OBJECT_AVAILABLE. - - A transient state in which pending operations are started, child objects - are permitted to advance from FSCACHE_OBJECT_INIT state, and temporary - lookup data is freed. - - (5) State FSCACHE_OBJECT_ACTIVE. - - The normal running state. In this state, requests the netfs makes will be - passed on to the cache. - - (6) State FSCACHE_OBJECT_INVALIDATING. - - The object is undergoing invalidation. When the state comes here, it - discards all pending read, write and attribute change operations as it is - going to clear out the cache entirely and reinitialise it. It will then - continue to the FSCACHE_OBJECT_UPDATING state. - - (7) State FSCACHE_OBJECT_UPDATING. - - The state machine comes here to update the object in the cache from the - netfs's records. This involves updating the auxiliary data that is used - to maintain coherency. - -And there are terminal states in which an object cleans itself up, deallocates -memory and potentially deletes stuff from disk: - - (8) State FSCACHE_OBJECT_LC_DYING. - - The object comes here if it is dying because of a lookup or creation - error. This would be due to a disk error or system error of some sort. - Temporary data is cleaned up, and the parent is released. - - (9) State FSCACHE_OBJECT_DYING. - - The object comes here if it is dying due to an error, because its parent - cookie has been relinquished by the netfs or because the cache is being - withdrawn. - - Any child objects waiting on this one are given CPU time so that they too - can destroy themselves. This object waits for all its children to go away - before advancing to the next state. - -(10) State FSCACHE_OBJECT_ABORT_INIT. - - The object comes to this state if it was waiting on its parent in - FSCACHE_OBJECT_INIT, but its parent died. The object will destroy itself - so that the parent may proceed from the FSCACHE_OBJECT_DYING state. - -(11) State FSCACHE_OBJECT_RELEASING. -(12) State FSCACHE_OBJECT_RECYCLING. - - The object comes to one of these two states when dying once it is rid of - all its children, if it is dying because the netfs relinquished its - cookie. In the first state, the cached data is expected to persist, and - in the second it will be deleted. - -(13) State FSCACHE_OBJECT_WITHDRAWING. - - The object transits to this state if the cache decides it wants to - withdraw the object from service, perhaps to make space, but also due to - error or just because the whole cache is being withdrawn. - -(14) State FSCACHE_OBJECT_DEAD. - - The object transits to this state when the in-memory object record is - ready to be deleted. The object processor shouldn't ever see an object in - this state. - - -The Set of Events ------------------ - -There are a number of events that can be raised to an object state machine: - - FSCACHE_OBJECT_EV_UPDATE - The netfs requested that an object be updated. The state machine will ask - the cache backend to update the object, and the cache backend will ask the - netfs for details of the change through its cookie definition ops. - - FSCACHE_OBJECT_EV_CLEARED - This is signalled in two circumstances: - - (a) when an object's last child object is dropped and - - (b) when the last operation outstanding on an object is completed. - - This is used to proceed from the dying state. - - FSCACHE_OBJECT_EV_ERROR - This is signalled when an I/O error occurs during the processing of some - object. - - FSCACHE_OBJECT_EV_RELEASE, FSCACHE_OBJECT_EV_RETIRE - These are signalled when the netfs relinquishes a cookie it was using. - The event selected depends on whether the netfs asks for the backing - object to be retired (deleted) or retained. - - FSCACHE_OBJECT_EV_WITHDRAW - This is signalled when the cache backend wants to withdraw an object. - This means that the object will have to be detached from the netfs's - cookie. - -Because the withdrawing releasing/retiring events are all handled by the object -state machine, it doesn't matter if there's a collision with both ends trying -to sever the connection at the same time. The state machine can just pick -which one it wants to honour, and that effects the other. diff --git a/Documentation/filesystems/caching/operations.rst b/Documentation/filesystems/caching/operations.rst deleted file mode 100644 index 9983e1675447..000000000000 --- a/Documentation/filesystems/caching/operations.rst +++ /dev/null @@ -1,210 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================================ -Asynchronous Operations Handling -================================ - -By: David Howells <dhowells@redhat.com> - -.. Contents: - - (*) Overview. - - (*) Operation record initialisation. - - (*) Parameters. - - (*) Procedure. - - (*) Asynchronous callback. - - -Overview -======== - -FS-Cache has an asynchronous operations handling facility that it uses for its -data storage and retrieval routines. Its operations are represented by -fscache_operation structs, though these are usually embedded into some other -structure. - -This facility is available to and expected to be used by the cache backends, -and FS-Cache will create operations and pass them off to the appropriate cache -backend for completion. - -To make use of this facility, <linux/fscache-cache.h> should be #included. - - -Operation Record Initialisation -=============================== - -An operation is recorded in an fscache_operation struct:: - - struct fscache_operation { - union { - struct work_struct fast_work; - struct slow_work slow_work; - }; - unsigned long flags; - fscache_operation_processor_t processor; - ... - }; - -Someone wanting to issue an operation should allocate something with this -struct embedded in it. They should initialise it by calling:: - - void fscache_operation_init(struct fscache_operation *op, - fscache_operation_release_t release); - -with the operation to be initialised and the release function to use. - -The op->flags parameter should be set to indicate the CPU time provision and -the exclusivity (see the Parameters section). - -The op->fast_work, op->slow_work and op->processor flags should be set as -appropriate for the CPU time provision (see the Parameters section). - -FSCACHE_OP_WAITING may be set in op->flags prior to each submission of the -operation and waited for afterwards. - - -Parameters -========== - -There are a number of parameters that can be set in the operation record's flag -parameter. There are three options for the provision of CPU time in these -operations: - - (1) The operation may be done synchronously (FSCACHE_OP_MYTHREAD). A thread - may decide it wants to handle an operation itself without deferring it to - another thread. - - This is, for example, used in read operations for calling readpages() on - the backing filesystem in CacheFiles. Although readpages() does an - asynchronous data fetch, the determination of whether pages exist is done - synchronously - and the netfs does not proceed until this has been - determined. - - If this option is to be used, FSCACHE_OP_WAITING must be set in op->flags - before submitting the operation, and the operating thread must wait for it - to be cleared before proceeding:: - - wait_on_bit(&op->flags, FSCACHE_OP_WAITING, - TASK_UNINTERRUPTIBLE); - - - (2) The operation may be fast asynchronous (FSCACHE_OP_FAST), in which case it - will be given to keventd to process. Such an operation is not permitted - to sleep on I/O. - - This is, for example, used by CacheFiles to copy data from a backing fs - page to a netfs page after the backing fs has read the page in. - - If this option is used, op->fast_work and op->processor must be - initialised before submitting the operation:: - - INIT_WORK(&op->fast_work, do_some_work); - - - (3) The operation may be slow asynchronous (FSCACHE_OP_SLOW), in which case it - will be given to the slow work facility to process. Such an operation is - permitted to sleep on I/O. - - This is, for example, used by FS-Cache to handle background writes of - pages that have just been fetched from a remote server. - - If this option is used, op->slow_work and op->processor must be - initialised before submitting the operation:: - - fscache_operation_init_slow(op, processor) - - -Furthermore, operations may be one of two types: - - (1) Exclusive (FSCACHE_OP_EXCLUSIVE). Operations of this type may not run in - conjunction with any other operation on the object being operated upon. - - An example of this is the attribute change operation, in which the file - being written to may need truncation. - - (2) Shareable. Operations of this type may be running simultaneously. It's - up to the operation implementation to prevent interference between other - operations running at the same time. - - -Procedure -========= - -Operations are used through the following procedure: - - (1) The submitting thread must allocate the operation and initialise it - itself. Normally this would be part of a more specific structure with the - generic op embedded within. - - (2) The submitting thread must then submit the operation for processing using - one of the following two functions:: - - int fscache_submit_op(struct fscache_object *object, - struct fscache_operation *op); - - int fscache_submit_exclusive_op(struct fscache_object *object, - struct fscache_operation *op); - - The first function should be used to submit non-exclusive ops and the - second to submit exclusive ones. The caller must still set the - FSCACHE_OP_EXCLUSIVE flag. - - If successful, both functions will assign the operation to the specified - object and return 0. -ENOBUFS will be returned if the object specified is - permanently unavailable. - - The operation manager will defer operations on an object that is still - undergoing lookup or creation. The operation will also be deferred if an - operation of conflicting exclusivity is in progress on the object. - - If the operation is asynchronous, the manager will retain a reference to - it, so the caller should put their reference to it by passing it to:: - - void fscache_put_operation(struct fscache_operation *op); - - (3) If the submitting thread wants to do the work itself, and has marked the - operation with FSCACHE_OP_MYTHREAD, then it should monitor - FSCACHE_OP_WAITING as described above and check the state of the object if - necessary (the object might have died while the thread was waiting). - - When it has finished doing its processing, it should call - fscache_op_complete() and fscache_put_operation() on it. - - (4) The operation holds an effective lock upon the object, preventing other - exclusive ops conflicting until it is released. The operation can be - enqueued for further immediate asynchronous processing by adjusting the - CPU time provisioning option if necessary, eg:: - - op->flags &= ~FSCACHE_OP_TYPE; - op->flags |= ~FSCACHE_OP_FAST; - - and calling:: - - void fscache_enqueue_operation(struct fscache_operation *op) - - This can be used to allow other things to have use of the worker thread - pools. - - -Asynchronous Callback -===================== - -When used in asynchronous mode, the worker thread pool will invoke the -processor method with a pointer to the operation. This should then get at the -container struct by using container_of():: - - static void fscache_write_op(struct fscache_operation *_op) - { - struct fscache_storage *op = - container_of(_op, struct fscache_storage, op); - ... - } - -The caller holds a reference on the operation, and will invoke -fscache_put_operation() when the processor function returns. The processor -function is at liberty to call fscache_enqueue_operation() or to take extra -references. diff --git a/Documentation/filesystems/ceph.rst b/Documentation/filesystems/ceph.rst index 7d2ef4e27273..4942e018db85 100644 --- a/Documentation/filesystems/ceph.rst +++ b/Documentation/filesystems/ceph.rst @@ -82,7 +82,7 @@ Mount Syntax The basic mount syntax is:: - # mount -t ceph monip[:port][,monip2[:port]...]:/[subdir] mnt + # mount -t ceph user@fsid.fs_name=/[subdir] mnt -o mon_addr=monip1[:port][/monip2[:port]] You only need to specify a single monitor, as the client will get the full list when it connects. (However, if the monitor you specify @@ -90,16 +90,35 @@ happens to be down, the mount won't succeed.) The port can be left off if the monitor is using the default. So if the monitor is at 1.2.3.4:: - # mount -t ceph 1.2.3.4:/ /mnt/ceph + # mount -t ceph cephuser@07fe3187-00d9-42a3-814b-72a4d5e7d5be.cephfs=/ /mnt/ceph -o mon_addr=1.2.3.4 is sufficient. If /sbin/mount.ceph is installed, a hostname can be -used instead of an IP address. +used instead of an IP address and the cluster FSID can be left out +(as the mount helper will fill it in by reading the ceph configuration +file):: + # mount -t ceph cephuser@cephfs=/ /mnt/ceph -o mon_addr=mon-addr +Multiple monitor addresses can be passed by separating each address with a slash (`/`):: + + # mount -t ceph cephuser@cephfs=/ /mnt/ceph -o mon_addr=192.168.1.100/192.168.1.101 + +When using the mount helper, monitor address can be read from ceph +configuration file if available. Note that, the cluster FSID (passed as part +of the device string) is validated by checking it with the FSID reported by +the monitor. Mount Options ============= + mon_addr=ip_address[:port][/ip_address[:port]] + Monitor address to the cluster. This is used to bootstrap the + connection to the cluster. Once connection is established, the + monitor addresses in the monitor map are followed. + + fsid=cluster-id + FSID of the cluster (from `ceph fsid` command). + ip=A.B.C.D[:N] Specify the IP and/or port the client should bind to locally. There is normally not much reason to do this. If the IP is not diff --git a/Documentation/filesystems/dax.rst b/Documentation/filesystems/dax.rst index 9a1b8fd9e82b..c04609d8ee24 100644 --- a/Documentation/filesystems/dax.rst +++ b/Documentation/filesystems/dax.rst @@ -23,11 +23,11 @@ on it as usual. The `DAX` code currently only supports files with a block size equal to your kernel's `PAGE_SIZE`, so you may need to specify a block size when creating the filesystem. -Currently 3 filesystems support `DAX`: ext2, ext4 and xfs. Enabling `DAX` on them -is different. +Currently 5 filesystems support `DAX`: ext2, ext4, xfs, virtiofs and erofs. +Enabling `DAX` on them is different. -Enabling DAX on ext2 --------------------- +Enabling DAX on ext2 and erofs +------------------------------ When mounting the filesystem, use the ``-o dax`` option on the command line or add 'dax' to the options in ``/etc/fstab``. This works to enable `DAX` on all files @@ -168,6 +168,22 @@ if the underlying media does not support dax and/or the filesystem is overridden with a mount option. +Enabling DAX on virtiofs +---------------------------- +The semantic of DAX on virtiofs is basically equal to that on ext4 and xfs, +except that when '-o dax=inode' is specified, virtiofs client derives the hint +whether DAX shall be enabled or not from virtiofs server through FUSE protocol, +rather than the persistent `FS_XFLAG_DAX` flag. That is, whether DAX shall be +enabled or not is completely determined by virtiofs server, while virtiofs +server itself may deploy various algorithm making this decision, e.g. depending +on the persistent `FS_XFLAG_DAX` flag on the host. + +It is still supported to set or clear persistent `FS_XFLAG_DAX` flag inside +guest, but it is not guaranteed that DAX will be enabled or disabled for +corresponding file then. Users inside guest still need to call statx(2) and +check the statx flag `STATX_ATTR_DAX` to see if DAX is enabled for this file. + + Implementation Tips for Block Driver Writers -------------------------------------------- diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 01df283c7d04..bef6d3040ce4 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -40,7 +40,7 @@ Here is the main features of EROFS: Inode metadata size 32 bytes 64 bytes Max file size 4 GB 16 EB (also limited by max. vol size) Max uids/gids 65536 4294967296 - File change time no yes (64 + 32-bit timestamp) + Per-inode timestamp no yes (64 + 32-bit timestamp) Max hardlinks 65536 4294967296 Metadata reserved 4 bytes 14 bytes ===================== ============ ===================================== @@ -93,6 +93,14 @@ dax A legacy option which is an alias for ``dax=always``. device=%s Specify a path to an extra device to be used together. =================== ========================================================= +Sysfs Entries +============= + +Information about mounted erofs file systems can be found in /sys/fs/erofs. +Each mounted filesystem will have a directory in /sys/fs/erofs based on its +device name (i.e., /sys/fs/erofs/sda). +(see also Documentation/ABI/testing/sysfs-fs-erofs) + On-disk details =============== diff --git a/Documentation/filesystems/ext4/blocks.rst b/Documentation/filesystems/ext4/blocks.rst index bd722ecd92d6..b0f80ea87c90 100644 --- a/Documentation/filesystems/ext4/blocks.rst +++ b/Documentation/filesystems/ext4/blocks.rst @@ -39,7 +39,7 @@ For 32-bit filesystems, limits are as follows: - 4TiB - 8TiB - 16TiB - - 256PiB + - 256TiB * - Blocks Per Block Group - 8,192 - 16,384 diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index d7b84695f56a..4a2426f0485a 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -198,6 +198,7 @@ fault_type=%d Support configuring fault injection type, should be FAULT_WRITE_IO 0x000004000 FAULT_SLAB_ALLOC 0x000008000 FAULT_DQUOT_INIT 0x000010000 + FAULT_LOCK_OP 0x000020000 =================== =========== mode=%s Control block allocation mode which supports "adaptive" and "lfs". In "lfs" mode, there should be no random diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 4d5d50dca65c..6ccd5efb25b7 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -1047,8 +1047,8 @@ astute users may notice some differences in behavior: may be used to overwrite the source files but isn't guaranteed to be effective on all filesystems and storage devices. -- Direct I/O is not supported on encrypted files. Attempts to use - direct I/O on such files will fall back to buffered I/O. +- Direct I/O is supported on encrypted files only under some + circumstances. For details, see `Direct I/O support`_. - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will @@ -1179,6 +1179,27 @@ Inline encryption doesn't affect the ciphertext or other aspects of the on-disk format, so users may freely switch back and forth between using "inlinecrypt" and not using "inlinecrypt". +Direct I/O support +================== + +For direct I/O on an encrypted file to work, the following conditions +must be met (in addition to the conditions for direct I/O on an +unencrypted file): + +* The file must be using inline encryption. Usually this means that + the filesystem must be mounted with ``-o inlinecrypt`` and inline + encryption hardware must be present. However, a software fallback + is also available. For details, see `Inline encryption support`_. + +* The I/O request must be fully aligned to the filesystem block size. + This means that the file position the I/O is targeting, the lengths + of all I/O segments, and the memory addresses of all I/O buffers + must be multiples of this value. Note that the filesystem block + size may be greater than the logical block size of the block device. + +If either of the above conditions is not met, then direct I/O on the +encrypted file will fall back to buffered I/O. + Implementation details ====================== diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst index 1229a75ec75d..7a879ec3b6bf 100644 --- a/Documentation/filesystems/idmappings.rst +++ b/Documentation/filesystems/idmappings.rst @@ -952,75 +952,3 @@ The raw userspace id that is put on disk is ``u1000`` so when the user takes their home directory back to their home computer where they are assigned ``u1000`` using the initial idmapping and mount the filesystem with the initial idmapping they will see all those files owned by ``u1000``. - -Shortcircuting --------------- - -Currently, the implementation of idmapped mounts enforces that the filesystem -is mounted with the initial idmapping. The reason is simply that none of the -filesystems that we targeted were mountable with a non-initial idmapping. But -that might change soon enough. As we've seen above, thanks to the properties of -idmappings the translation works for both filesystems mounted with the initial -idmapping and filesystem with non-initial idmappings. - -Based on this current restriction to filesystem mounted with the initial -idmapping two noticeable shortcuts have been taken: - -1. We always stash a reference to the initial user namespace in ``struct - vfsmount``. Idmapped mounts are thus mounts that have a non-initial user - namespace attached to them. - - In order to support idmapped mounts this needs to be changed. Instead of - stashing the initial user namespace the user namespace the filesystem was - mounted with must be stashed. An idmapped mount is then any mount that has - a different user namespace attached then the filesystem was mounted with. - This has no user-visible consequences. - -2. The translation algorithms in ``mapped_fs*id()`` and ``i_*id_into_mnt()`` - are simplified. - - Let's consider ``mapped_fs*id()`` first. This function translates the - caller's kernel id into a kernel id in the filesystem's idmapping via - a mount's idmapping. The full algorithm is:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - make_kuid(filesystem-idmapping, uid) = kuid - - We know that the filesystem is always mounted with the initial idmapping as - we enforce this in ``mount_setattr()``. So this can be shortened to:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - KUIDT_INIT(uid) = kuid - - Similarly, for ``i_*id_into_mnt()`` which translated the filesystem's kernel - id into a mount's kernel id:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - from_kuid(filesystem-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - - Again, we know that the filesystem is always mounted with the initial - idmapping as we enforce this in ``mount_setattr()``. So this can be - shortened to:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - __kuid_val(kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - -Handling filesystems mounted with non-initial idmappings requires that the -translation functions be converted to their full form. They can still be -shortcircuited on non-idmapped mounts. This has no user-visible consequences. diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index d36fe79167b3..2998cec9af4b 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -169,7 +169,6 @@ prototypes:: int (*show_options)(struct seq_file *, struct dentry *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); - int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); locking rules: All may block [not true, see below] @@ -194,7 +193,6 @@ umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) -bdev_try_to_free_page: no (see below) ====================== ============ ======================== ->statfs() has s_umount (shared) when called by ustat(2) (native or @@ -210,9 +208,6 @@ dqio_sem) (unless an admin really wants to screw up something and writes to quota files with quotas on). For other details about locking see also dquot_operations section. -->bdev_try_to_free_page is called from the ->releasepage handler of -the block device inode. See there for more details. - file_system_type ================ @@ -244,7 +239,7 @@ prototypes:: int (*writepage)(struct page *page, struct writeback_control *wbc); int (*readpage)(struct file *, struct page *); int (*writepages)(struct address_space *, struct writeback_control *); - int (*set_page_dirty)(struct page *page); + bool (*dirty_folio)(struct address_space *, struct folio *folio); void (*readahead)(struct readahead_control *); int (*readpages)(struct file *filp, struct address_space *mapping, struct list_head *pages, unsigned nr_pages); @@ -255,21 +250,21 @@ prototypes:: loff_t pos, unsigned len, unsigned copied, struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); - void (*invalidatepage) (struct page *, unsigned int, unsigned int); + void (*invalidate_folio) (struct folio *, size_t start, size_t len); int (*releasepage) (struct page *, int); void (*freepage)(struct page *); int (*direct_IO)(struct kiocb *, struct iov_iter *iter); bool (*isolate_page) (struct page *, isolate_mode_t); int (*migratepage)(struct address_space *, struct page *, struct page *); void (*putback_page) (struct page *); - int (*launder_page)(struct page *); - int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); + int (*launder_folio)(struct folio *); + bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count); int (*error_remove_page)(struct address_space *, struct page *); int (*swap_activate)(struct file *); int (*swap_deactivate)(struct file *); locking rules: - All except set_page_dirty and freepage may block + All except dirty_folio and freepage may block ====================== ======================== ========= =============== ops PageLocked(page) i_rwsem invalidate_lock @@ -277,20 +272,20 @@ ops PageLocked(page) i_rwsem invalidate_lock writepage: yes, unlocks (see below) readpage: yes, unlocks shared writepages: -set_page_dirty no +dirty_folio maybe readahead: yes, unlocks shared readpages: no shared write_begin: locks the page exclusive write_end: yes, unlocks exclusive bmap: -invalidatepage: yes exclusive +invalidate_folio: yes exclusive releasepage: yes freepage: yes direct_IO: isolate_page: yes migratepage: yes (both) putback_page: yes -launder_page: yes +launder_folio: yes is_partially_uptodate: yes error_remove_page: yes swap_activate: no @@ -366,22 +361,22 @@ If nr_to_write is NULL, all dirty pages must be written. writepages should _only_ write pages which are present on mapping->io_pages. -->set_page_dirty() is called from various places in the kernel -when the target page is marked as needing writeback. It may be called -under spinlock (it cannot block) and is sometimes called with the page -not locked. +->dirty_folio() is called from various places in the kernel when +the target folio is marked as needing writeback. The folio cannot be +truncated because either the caller holds the folio lock, or the caller +has found the folio while holding the page table lock which will block +truncation. ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some filesystems and by the swapper. The latter will eventually go away. Please, keep it that way and don't breed new callers. -->invalidatepage() is called when the filesystem must attempt to drop +->invalidate_folio() is called when the filesystem must attempt to drop some or all of the buffers from the page when it is being truncated. It -returns zero on success. If ->invalidatepage is zero, the kernel uses -block_invalidatepage() instead. The filesystem must exclusively acquire -invalidate_lock before invalidating page cache in truncate / hole punch path -(and thus calling into ->invalidatepage) to block races between page cache -invalidation and page cache filling functions (fault, read, ...). +returns zero on success. The filesystem must exclusively acquire +invalidate_lock before invalidating page cache in truncate / hole punch +path (and thus calling into ->invalidate_folio) to block races between page +cache invalidation and page cache filling functions (fault, read, ...). ->releasepage() is called when the kernel is about to try to drop the buffers from the page in preparation for freeing it. It returns zero to @@ -391,9 +386,9 @@ the kernel assumes that the fs has no private interest in the buffers. ->freepage() is called when the kernel is done dropping the page from the page cache. -->launder_page() may be called prior to releasing a page if -it is still found to be dirty. It returns zero if the page was successfully -cleaned, or an error value if not. Note that in order to prevent the page +->launder_folio() may be called prior to releasing a folio if +it is still found to be dirty. It returns zero if the folio was successfully +cleaned, or an error value if not. Note that in order to prevent the folio getting mapped back in and redirtied, it needs to be kept locked across the entire operation. @@ -443,13 +438,13 @@ prototypes:: locking rules: ====================== ============= ================= ========= -ops inode->i_lock blocked_lock_lock may block +ops flc_lock blocked_lock_lock may block ====================== ============= ================= ========= -lm_notify: yes yes no +lm_notify: no yes no lm_grant: no no no lm_break: yes no no lm_change yes no no -lm_breaker_owns_lease: no no no +lm_breaker_owns_lease: yes no no ====================== ============= ================= ========= buffer_head diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index 375baca7edcd..4f373a8ec47b 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -454,13 +454,18 @@ operation table looks like the following:: void *term_func_priv); int (*prepare_write)(struct netfs_cache_resources *cres, - loff_t *_start, size_t *_len, loff_t i_size); + loff_t *_start, size_t *_len, loff_t i_size, + bool no_space_allocated_yet); int (*write)(struct netfs_cache_resources *cres, loff_t start_pos, struct iov_iter *iter, netfs_io_terminated_t term_func, void *term_func_priv); + + int (*query_occupancy)(struct netfs_cache_resources *cres, + loff_t start, size_t len, size_t granularity, + loff_t *_data_start, size_t *_data_len); }; With a termination handler function pointer:: @@ -515,11 +520,14 @@ The methods defined in the table are: * ``prepare_write()`` - [Required] Called to adjust a write to the cache and check that there is - sufficient space in the cache. The start and length values indicate the - size of the write that netfslib is proposing, and this can be adjusted by - the cache to respect DIO boundaries. The file size is passed for - information. + [Required] Called to prepare a write to the cache to take place. This + involves checking to see whether the cache has sufficient space to honour + the write. ``*_start`` and ``*_len`` indicate the region to be written; the + region can be shrunk or it can be expanded to a page boundary either way as + necessary to align for direct I/O. i_size holds the size of the object and + is provided for reference. no_space_allocated_yet is set to true if the + caller is certain that no data has been written to that region - for example + if it tried to do a read from there already. * ``write()`` @@ -532,6 +540,18 @@ The methods defined in the table are: indicating whether the termination is definitely happening in the caller's context. + * ``query_occupancy()`` + + [Required] Called to find out where the next piece of data is within a + particular region of the cache. The start and length of the region to be + queried are passed in, along with the granularity to which the answer needs + to be aligned. The function passes back the start and length of the data, + if any, available within that region. Note that there may be a hole at the + front. + + It returns 0 if some data was found, -ENODATA if there was no usable data + within the region or -ENOBUFS if there is no caching on this file. + Note that these methods are passed a pointer to the cache resource structure, not the read request structure as they could be used in other situations where there isn't a read request structure as well, such as writing dirty data to the diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index bf19fd6b86e7..7c1583dbeb59 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -45,6 +45,12 @@ typically between calling iget_locked() and unlocking the inode. At some point that will become mandatory. +**mandatory** + +The foo_inode_info should always be allocated through alloc_inode_sb() rather +than kmem_cache_alloc() or kmalloc() related to set up the inode reclaim context +correctly. + --- **mandatory** diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 8d7f141c6fc7..061744c436d9 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -426,12 +426,14 @@ with the memory region, as the case would be with BSS (uninitialized data). The "pathname" shows the name associated file for this mapping. If the mapping is not associated with a file: - ======= ==================================== + ============= ==================================== [heap] the heap of the program [stack] the stack of the main process [vdso] the "virtual dynamic shared object", the kernel system call handler - ======= ==================================== + [anon:<name>] an anonymous mapping that has been + named by userspace + ============= ==================================== or if empty, the mapping is anonymous. diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index bf5c48066fac..4f14edf93941 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -658,7 +658,7 @@ pages, however the address_space has finer control of write sizes. The read process essentially only requires 'readpage'. The write process is more complicated and uses write_begin/write_end or -set_page_dirty to write data into the address_space, and writepage and +dirty_folio to write data into the address_space, and writepage and writepages to writeback data to storage. Adding and removing pages to/from an address_space is protected by the @@ -724,7 +724,7 @@ cache in your filesystem. The following members are defined: int (*writepage)(struct page *page, struct writeback_control *wbc); int (*readpage)(struct file *, struct page *); int (*writepages)(struct address_space *, struct writeback_control *); - int (*set_page_dirty)(struct page *page); + bool (*dirty_folio)(struct address_space *, struct folio *); void (*readahead)(struct readahead_control *); int (*readpages)(struct file *filp, struct address_space *mapping, struct list_head *pages, unsigned nr_pages); @@ -735,7 +735,7 @@ cache in your filesystem. The following members are defined: loff_t pos, unsigned len, unsigned copied, struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); - void (*invalidatepage) (struct page *, unsigned int, unsigned int); + void (*invalidate_folio) (struct folio *, size_t start, size_t len); int (*releasepage) (struct page *, int); void (*freepage)(struct page *); ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter); @@ -745,10 +745,10 @@ cache in your filesystem. The following members are defined: int (*migratepage) (struct page *, struct page *); /* put migration-failed page back to right list */ void (*putback_page) (struct page *); - int (*launder_page) (struct page *); + int (*launder_folio) (struct folio *); - int (*is_partially_uptodate) (struct page *, unsigned long, - unsigned long); + bool (*is_partially_uptodate) (struct folio *, size_t from, + size_t count); void (*is_dirty_writeback) (struct page *, bool *, bool *); int (*error_remove_page) (struct mapping *mapping, struct page *page); int (*swap_activate)(struct file *); @@ -793,25 +793,29 @@ cache in your filesystem. The following members are defined: This will choose pages from the address space that are tagged as DIRTY and will pass them to ->writepage. -``set_page_dirty`` - called by the VM to set a page dirty. This is particularly - needed if an address space attaches private data to a page, and - that data needs to be updated when a page is dirtied. This is +``dirty_folio`` + called by the VM to mark a folio as dirty. This is particularly + needed if an address space attaches private data to a folio, and + that data needs to be updated when a folio is dirtied. This is called, for example, when a memory mapped page gets modified. - If defined, it should set the PageDirty flag, and the - PAGECACHE_TAG_DIRTY tag in the radix tree. + If defined, it should set the folio dirty flag, and the + PAGECACHE_TAG_DIRTY search mark in i_pages. ``readahead`` Called by the VM to read pages associated with the address_space object. The pages are consecutive in the page cache and are locked. The implementation should decrement the page refcount after starting I/O on each page. Usually the page will be - unlocked by the I/O completion handler. If the filesystem decides - to stop attempting I/O before reaching the end of the readahead - window, it can simply return. The caller will decrement the page - refcount and unlock the remaining pages for you. Set PageUptodate - if the I/O completes successfully. Setting PageError on any page - will be ignored; simply unlock the page if an I/O error occurs. + unlocked by the I/O completion handler. The set of pages are + divided into some sync pages followed by some async pages, + rac->ra->async_size gives the number of async pages. The + filesystem should attempt to read all sync pages but may decide + to stop once it reaches the async pages. If it does decide to + stop attempting I/O, it can simply return. The caller will + remove the remaining pages from the address space, unlock them + and decrement the page refcount. Set PageUptodate if the I/O + completes successfully. Setting PageError on any page will be + ignored; simply unlock the page if an I/O error occurs. ``readpages`` called by the VM to read pages associated with the address_space @@ -868,15 +872,15 @@ cache in your filesystem. The following members are defined: to find out where the blocks in the file are and uses those addresses directly. -``invalidatepage`` - If a page has PagePrivate set, then invalidatepage will be - called when part or all of the page is to be removed from the +``invalidate_folio`` + If a folio has private data, then invalidate_folio will be + called when part or all of the folio is to be removed from the address space. This generally corresponds to either a truncation, punch hole or a complete invalidation of the address space (in the latter case 'offset' will always be 0 and 'length' - will be PAGE_SIZE). Any private data associated with the page + will be folio_size()). Any private data associated with the page should be updated to reflect this truncation. If offset is 0 - and length is PAGE_SIZE, then the private data should be + and length is folio_size(), then the private data should be released, because the page must be able to be completely discarded. This may be done by calling the ->releasepage function, but in this case the release MUST succeed. @@ -930,16 +934,16 @@ cache in your filesystem. The following members are defined: ``putback_page`` Called by the VM when isolated page's migration fails. -``launder_page`` - Called before freeing a page - it writes back the dirty page. - To prevent redirtying the page, it is kept locked during the +``launder_folio`` + Called before freeing a folio - it writes back the dirty folio. + To prevent redirtying the folio, it is kept locked during the whole operation. ``is_partially_uptodate`` Called by the VM when reading a file through the pagecache when - the underlying blocksize != pagesize. If the required block is - up to date then the read can complete without needing the IO to - bring the whole page up to date. + the underlying blocksize is smaller than the size of the folio. + If the required block is up to date then the read can complete + without needing I/O to bring the whole page up to date. ``is_dirty_writeback`` Called by the VM when attempting to reclaim a page. The VM uses diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 74b830b2fd59..c414646a1bb4 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -19,16 +19,17 @@ possible we decided to do following: platform devices. - Devices behind real busses where there is a connector resource - are represented as struct spi_device or struct i2c_device - (standard UARTs are not busses so there is no struct uart_device). + are represented as struct spi_device or struct i2c_device. Note + that standard UARTs are not busses so there is no struct uart_device, + although some of them may be represented by sturct serdev_device. As both ACPI and Device Tree represent a tree of devices (and their resources) this implementation follows the Device Tree way as much as possible. -The ACPI implementation enumerates devices behind busses (platform, SPI and -I2C), creates the physical devices and binds them to their ACPI handle in -the ACPI namespace. +The ACPI implementation enumerates devices behind busses (platform, SPI, +I2C, and in some cases UART), creates the physical devices and binds them +to their ACPI handle in the ACPI namespace. This means that when ACPI_HANDLE(dev) returns non-NULL the device was enumerated from ACPI namespace. This handle can be used to extract other @@ -46,18 +47,16 @@ some minor changes. Adding ACPI support for an existing driver should be pretty straightforward. Here is the simplest example:: - #ifdef CONFIG_ACPI static const struct acpi_device_id mydrv_acpi_match[] = { /* ACPI IDs here */ { } }; MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); - #endif static struct platform_driver my_driver = { ... .driver = { - .acpi_match_table = ACPI_PTR(mydrv_acpi_match), + .acpi_match_table = mydrv_acpi_match, }, }; @@ -155,7 +154,7 @@ Here is what the ACPI namespace for a SPI slave might look like:: Device (EEP0) { Name (_ADR, 1) - Name (_CID, Package() { + Name (_CID, Package () { "ATML0025", "AT25", }) @@ -172,59 +171,51 @@ The SPI device drivers only need to add ACPI IDs in a similar way than with the platform device drivers. Below is an example where we add ACPI support to at25 SPI eeprom driver (this is meant for the above ACPI snippet):: - #ifdef CONFIG_ACPI static const struct acpi_device_id at25_acpi_match[] = { { "AT25", 0 }, - { }, + { } }; MODULE_DEVICE_TABLE(acpi, at25_acpi_match); - #endif static struct spi_driver at25_driver = { .driver = { ... - .acpi_match_table = ACPI_PTR(at25_acpi_match), + .acpi_match_table = at25_acpi_match, }, }; Note that this driver actually needs more information like page size of the -eeprom etc. but at the time writing this there is no standard way of -passing those. One idea is to return this in _DSM method like:: +eeprom, etc. This information can be passed via _DSD method like:: Device (EEP0) { ... - Method (_DSM, 4, NotSerialized) + Name (_DSD, Package () { - Store (Package (6) + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { - "byte-len", 1024, - "addr-mode", 2, - "page-size, 32 - }, Local0) - - // Check UUIDs etc. - - Return (Local0) - } - -Then the at25 SPI driver can get this configuration by calling _DSM on its -ACPI handle like:: - - struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; - struct acpi_object_list input; - acpi_status status; + Package () { "size", 1024 }, + Package () { "pagesize", 32 }, + Package () { "address-width", 16 }, + } + }) + } - /* Fill in the input buffer */ +Then the at25 SPI driver can get this configuration by calling device property +APIs during ->probe() phase like:: - status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", - &input, &output); - if (ACPI_FAILURE(status)) - /* Handle the error */ + err = device_property_read_u32(dev, "size", &size); + if (err) + ...error handling... - /* Extract the data here */ + err = device_property_read_u32(dev, "pagesize", &page_size); + if (err) + ...error handling... - kfree(output.pointer); + err = device_property_read_u32(dev, "address-width", &addr_width); + if (err) + ...error handling... I2C serial bus support ====================== @@ -237,26 +228,24 @@ registered. Below is an example of how to add ACPI support to the existing mpu3050 input driver:: - #ifdef CONFIG_ACPI static const struct acpi_device_id mpu3050_acpi_match[] = { { "MPU3050", 0 }, - { }, + { } }; MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); - #endif static struct i2c_driver mpu3050_i2c_driver = { .driver = { .name = "mpu3050", - .owner = THIS_MODULE, .pm = &mpu3050_pm, .of_match_table = mpu3050_of_match, - .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), + .acpi_match_table = mpu3050_acpi_match, }, .probe = mpu3050_probe, .remove = mpu3050_remove, .id_table = mpu3050_ids, }; + module_i2c_driver(mpu3050_i2c_driver); Reference to PWM device ======================= @@ -282,9 +271,9 @@ introduced, i.e.:: } } } - }) ... + } In the above example the PWM-based LED driver references to the PWM channel 0 of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that @@ -306,26 +295,13 @@ For example:: { Name (SBUF, ResourceTemplate() { - ... // Used to power on/off the device - GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, - IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", - 0x00, ResourceConsumer,,) - { - // Pin List - 0x0055 - } + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly, + "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 85 } // Interrupt for the device - GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, - 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) - { - // Pin list - 0x0058 - } - - ... - + GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0, + "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 88 } } Return (SBUF) @@ -337,11 +313,12 @@ For example:: ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, - Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, + Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } }, + Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } }, } }) ... + } These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" specifies the path to the controller. In order to use these GPIOs in Linux @@ -460,10 +437,10 @@ namespace link:: Device (TMP0) { Name (_HID, "PRP0001") - Name (_DSD, Package() { + Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package (2) { "compatible", "ti,tmp75" }, + Package () { "compatible", "ti,tmp75" }, } }) Method (_CRS, 0, Serialized) diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index df4b711053ee..eaec732cc77c 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -21,18 +21,18 @@ index, like the ASL example below shows:: Name (_CRS, ResourceTemplate () { GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {15} + "\\_SB.GPO0", 0, ResourceConsumer) { 15 } GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} + "\\_SB.GPO0", 0, ResourceConsumer) { 27, 31 } }) Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () - { - Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }}, - Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }}, + { + Package () { "reset-gpios", Package () { ^BTH, 1, 1, 0 } }, + Package () { "shutdown-gpios", Package () { ^BTH, 0, 0, 0 } }, } }) } @@ -123,17 +123,17 @@ Example:: // _DSD Hierarchical Properties Extension UUID ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () {"hog-gpio8", "G8PU"} + Package () { "hog-gpio8", "G8PU" } } }) Name (G8PU, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () {"gpio-hog", 1}, - Package () {"gpios", Package () {8, 0}}, - Package () {"output-high", 1}, - Package () {"line-name", "gpio8-pullup"}, + Package () { "gpio-hog", 1 }, + Package () { "gpios", Package () { 8, 0 } }, + Package () { "output-high", 1 }, + Package () { "line-name", "gpio8-pullup" }, } }) @@ -266,15 +266,17 @@ have a device like below:: Name (_CRS, ResourceTemplate () { GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {15} + "\\_SB.GPO0", 0, ResourceConsumer) { 15 } GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {27} + "\\_SB.GPO0", 0, ResourceConsumer) { 27 } }) } The driver might expect to get the right GPIO when it does:: desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); + if (IS_ERR(desc)) + ...error handling... but since there is no way to know the mapping between "reset" and the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index da138dd39883..a1212b5b3026 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -300,30 +300,6 @@ Contact: Daniel Vetter, Noralf Tronnes Level: Advanced -Garbage collect fbdev scrolling acceleration --------------------------------------------- - -Scroll acceleration has been disabled in fbcon. Now it works as the old -SCROLL_REDRAW mode. A ton of code was removed in fbcon.c and the hook bmove was -removed from fbcon_ops. -Remaining tasks: - -- a bunch of the hooks in fbcon_ops could be removed or simplified by calling - directly instead of the function table (with a switch on p->rotate) - -- fb_copyarea is unused after this, and can be deleted from all drivers - -- after that, fb_copyarea can be deleted from fb_ops in include/linux/fb.h as - well as cfb_copyarea - -Note that not all acceleration code can be deleted, since clearing and cursor -support is still accelerated, which might be good candidates for further -deletion projects. - -Contact: Daniel Vetter - -Level: Intermediate - idr_init_base() --------------- diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 1f4bb4ba2e4b..3373e27b707d 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -6,22 +6,21 @@ Kernel driver aquacomputer-d5next Supported devices: * Aquacomputer D5 Next watercooling pump +* Aquacomputer Farbwerk 360 RGB controller Author: Aleksa Savic Description ----------- -This driver exposes hardware sensors of the Aquacomputer D5 Next watercooling -pump, which communicates through a proprietary USB HID protocol. +This driver exposes hardware sensors of listed Aquacomputer devices, which +communicate through proprietary USB HID protocols. -Available sensors are pump and fan speed, power, voltage and current, as -well as coolant temperature. Also available through debugfs are the serial -number, firmware version and power-on count. - -Attaching a fan is optional and allows it to be controlled using temperature -curves directly from the pump. If it's not connected, the fan-related sensors -will report zeroes. +For the D5 Next pump, available sensors are pump and fan speed, power, voltage +and current, as well as coolant temperature. Also available through debugfs are +the serial number, firmware version and power-on count. Attaching a fan to it is +optional and allows it to be controlled using temperature curves directly from the +pump. If it's not connected, the fan-related sensors will report zeroes. The pump can be configured either through software or via its physical interface. Configuring the pump through this driver is not implemented, as it @@ -29,33 +28,31 @@ seems to require sending it a complete configuration. That includes addressable RGB LEDs, for which there is no standard sysfs interface. Thus, that task is better suited for userspace tools. +The Farbwerk 360 exposes four temperature sensors. Depending on the device, +not all sysfs and debugfs entries will be available. + Usage notes ----------- -The pump communicates via HID reports. The driver is loaded automatically by +The devices communicate via HID reports. The driver is loaded automatically by the kernel and supports hotswapping. Sysfs entries ------------- -============ ============================================= -temp1_input Coolant temperature (in millidegrees Celsius) -fan1_input Pump speed (in RPM) -fan2_input Fan speed (in RPM) -power1_input Pump power (in micro Watts) -power2_input Fan power (in micro Watts) -in0_input Pump voltage (in milli Volts) -in1_input Fan voltage (in milli Volts) -in2_input +5V rail voltage (in milli Volts) -curr1_input Pump current (in milli Amperes) -curr2_input Fan current (in milli Amperes) -============ ============================================= +================ ============================================= +temp[1-4]_input Temperature sensors (in millidegrees Celsius) +fan[1-2]_input Pump/fan speed (in RPM) +power[1-2]_input Pump/fan power (in micro Watts) +in[0-2]_input Pump/fan voltage (in milli Volts) +curr[1-2]_input Pump/fan current (in milli Amperes) +================ ============================================= Debugfs entries --------------- -================ =============================================== -serial_number Serial number of the pump +================ ================================================= +serial_number Serial number of the device firmware_version Version of installed firmware -power_cycles Count of how many times the pump was powered on -================ =============================================== +power_cycles Count of how many times the device was powered on +================ ================================================= diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst new file mode 100644 index 000000000000..e7e8f1640f45 --- /dev/null +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_ec_sensors +================================= + +Supported boards: + * PRIME X570-PRO, + * Pro WS X570-ACE, + * ROG CROSSHAIR VIII DARK HERO, + * ROG CROSSHAIR VIII HERO (WI-FI) + * ROG CROSSHAIR VIII FORMULA, + * ROG CROSSHAIR VIII HERO, + * ROG CROSSHAIR VIII IMPACT, + * ROG STRIX B550-E GAMING, + * ROG STRIX B550-I GAMING, + * ROG STRIX X570-E GAMING, + * ROG STRIX X570-F GAMING, + * ROG STRIX X570-I GAMING + +Authors: + - Eugene Shalygin <eugene.shalygin@gmail.com> + +Description: +------------ +ASUS mainboards publish hardware monitoring information via Super I/O +chip and the ACPI embedded controller (EC) registers. Some of the sensors +are only available via the EC. + +The driver is aware of and reads the following sensors: + +1. Chipset (PCH) temperature +2. CPU package temperature +3. Motherboard temperature +4. Readings from the T_Sensor header +5. VRM temperature +6. CPU_Opt fan RPM +7. VRM heatsink fan RPM +8. Chipset fan RPM +9. Readings from the "Water flow meter" header (RPM) +10. Readings from the "Water In" and "Water Out" temperature headers +11. CPU current +12. CPU core voltage + +Sensor values are read from EC registers, and to avoid race with the board +firmware the driver acquires ACPI mutex, the one used by the WMI when its +methods access the EC. + +Module Parameters +----------------- + * mutex_path: string + The driver holds path to the ACPI mutex for each board (actually, + the path is mostly identical for them). If ASUS changes this path + in a future BIOS update, this parameter can be used to override + the stored in the driver value until it gets updated. diff --git a/Documentation/hwmon/asus_wmi_ec_sensors.rst b/Documentation/hwmon/asus_wmi_ec_sensors.rst new file mode 100644 index 000000000000..1b287f229e86 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_ec_sensors.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_ec_sensors +================================= + +Supported boards: + * PRIME X570-PRO, + * Pro WS X570-ACE, + * ROG CROSSHAIR VIII DARK HERO, + * ROG CROSSHAIR VIII FORMULA, + * ROG CROSSHAIR VIII HERO, + * ROG STRIX B550-E GAMING, + * ROG STRIX B550-I GAMING, + * ROG STRIX X570-E GAMING. + +Authors: + - Eugene Shalygin <eugene.shalygin@gmail.com> + +Description: +------------ +ASUS mainboards publish hardware monitoring information via Super I/O +chip and the ACPI embedded controller (EC) registers. Some of the sensors +are only available via the EC. + +ASUS WMI interface provides a method (BREC) to read data from EC registers, +which is utilized by this driver to publish those sensor readings to the +HWMON system. The driver is aware of and reads the following sensors: + +1. Chipset (PCH) temperature +2. CPU package temperature +3. Motherboard temperature +4. Readings from the T_Sensor header +5. VRM temperature +6. CPU_Opt fan RPM +7. Chipset fan RPM +8. Readings from the "Water flow meter" header (RPM) +9. Readings from the "Water In" and "Water Out" temperature headers +10. CPU current diff --git a/Documentation/hwmon/asus_wmi_sensors.rst b/Documentation/hwmon/asus_wmi_sensors.rst new file mode 100644 index 000000000000..8f2096cf5183 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_sensors.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_sensors +================================= + +Supported boards: + * PRIME X399-A, + * PRIME X470-PRO, + * ROG CROSSHAIR VI EXTREME, + * ROG CROSSHAIR VI HERO, + * ROG CROSSHAIR VI HERO (WI-FI AC), + * ROG CROSSHAIR VII HERO, + * ROG CROSSHAIR VII HERO (WI-FI), + * ROG STRIX B450-E GAMING, + * ROG STRIX B450-F GAMING, + * ROG STRIX B450-I GAMING, + * ROG STRIX X399-E GAMING, + * ROG STRIX X470-F GAMING, + * ROG STRIX X470-I GAMING, + * ROG ZENITH EXTREME, + * ROG ZENITH EXTREME ALPHA. + +Authors: + - Ed Brindley <kernel@maidavale.org> + +Description: +------------ +ASUS mainboards publish hardware monitoring information via WMI interface. + +ASUS WMI interface provides a methods to get list of sensors and values of +such, which is utilized by this driver to publish those sensor readings to the +HWMON system. + +The driver is aware of and reads the following sensors: + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * VDDP Voltage, + * 1.8V PLL Voltage, + * +12V Voltage, + * +5V Voltage, + * 3VSB Voltage, + * VBAT Voltage, + * AVCC3 Voltage, + * SB 1.05V Voltage, + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * CPU Fan RPM, + * Chassis Fan 1 RPM, + * Chassis Fan 2 RPM, + * Chassis Fan 3 RPM, + * HAMP Fan RPM, + * Water Pump RPM, + * CPU OPT RPM, + * Water Flow RPM, + * AIO Pump RPM, + * CPU Temperature, + * CPU Socket Temperature, + * Motherboard Temperature, + * Chipset Temperature, + * Tsensor 1 Temperature, + * CPU VRM Temperature, + * Water In, + * Water Out, + * CPU VRM Output Current. + +Known Issues: + * The WMI implementation in some of Asus' BIOSes is buggy. This can result in + fans stopping, fans getting stuck at max speed, or temperature readouts + getting stuck. This is not an issue with the driver, but the BIOS. The Prime + X470 Pro seems particularly bad for this. The more frequently the WMI + interface is polled the greater the potential for this to happen. Until you + have subjected your computer to an extended soak test while polling the + sensors frequently, don't leave you computer unattended. Upgrading to new + BIOS version with method version greater than or equal to two should + rectify the issue. + * A few boards report 12v voltages to be ~10v. diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst index beec88491171..d3323a96665d 100644 --- a/Documentation/hwmon/dell-smm-hwmon.rst +++ b/Documentation/hwmon/dell-smm-hwmon.rst @@ -165,3 +165,183 @@ obtain the same information and to control the fan status. The ioctl interface can be accessed from C programs or from shell using the i8kctl utility. See the source file of ``i8kutils`` for more information on how to use the ioctl interface. + +SMM Interface +------------- + +.. warning:: The SMM interface was reverse-engineered by trial-and-error + since Dell did not provide any Documentation, + please keep that in mind. + +The driver uses the SMM interface to send commands to the system BIOS. +This interface is normally used by Dell's 32-bit diagnostic program or +on newer notebook models by the buildin BIOS diagnostics. +The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``, +and may cause short hangs when the BIOS code is taking too long to +execute. + +The SMM handler inside the system BIOS looks at the contents of the +``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers. +Each register has a special purpose: + +=============== ================================== +Register Purpose +=============== ================================== +eax Holds the command code before SMM, + holds the first result after SMM. +ebx Holds the arguments. +ecx Unknown, set to 0. +edx Holds the second result after SMM. +esi Unknown, set to 0. +edi Unknown, set to 0. +=============== ================================== + +The SMM handler can signal a failure by either: + +- setting the lower sixteen bits of ``eax`` to ``0xffff`` +- not modifying ``eax`` at all +- setting the carry flag + +SMM command codes +----------------- + +=============== ======================= ================================================ +Command Code Command Name Description +=============== ======================= ================================================ +``0x0025`` Get Fn key status Returns the Fn key pressed after SMM: + + - 9th bit in ``eax`` indicates Volume up + - 10th bit in ``eax`` indicates Volume down + - both bits indicate Volume mute + +``0xa069`` Get power status Returns current power status after SMM: + + - 1st bit in ``eax`` indicates Battery connected + - 3th bit in ``eax`` indicates AC connected + +``0x00a3`` Get fan state Returns current fan state after SMM: + + - 1st byte in ``eax`` holds the current + fan state (0 - 2 or 3) + +``0x01a3`` Set fan state Sets the fan speed: + + - 1st byte in ``ebx`` holds the fan number + - 2nd byte in ``ebx`` holds the desired + fan state (0 - 2 or 3) + +``0x02a3`` Get fan speed Returns the current fan speed in RPM: + + - 1st byte in ``ebx`` holds the fan number + - 1st word in ``eax`` holds the current + fan speed in RPM (after SMM) + +``0x03a3`` Get fan type Returns the fan type: + + - 1st byte in ``ebx`` holds the fan number + - 1st byte in ``eax`` holds the + fan type (after SMM): + + - 5th bit indicates docking fan + - 1 indicates Processor fan + - 2 indicates Motherboard fan + - 3 indicates Video fan + - 4 indicates Power supply fan + - 5 indicates Chipset fan + - 6 indicates other fan type + +``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state: + + - 1st byte in ``ebx`` holds the fan number + - 2nd byte in ``ebx`` holds the fan state + in question (0 - 2 or 3) + - 1st word in ``eax`` holds the nominal + fan speed in RPM (after SMM) + +``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state: + + - 1st byte in ``ebx`` holds the fan number + - 2nd byte in ``ebx`` holds the fan state + in question (0 - 2 or 3) + - 1st byte in ``eax`` returns the speed + tolerance + +``0x10a3`` Get sensor temperature Returns the measured temperature: + + - 1st byte in ``ebx`` holds the sensor number + - 1st byte in ``eax`` holds the measured + temperature (after SMM) + +``0x11a3`` Get sensor type Returns the sensor type: + + - 1st byte in ``ebx`` holds the sensor number + - 1st byte in ``eax`` holds the + temperature type (after SMM): + + - 1 indicates CPU sensor + - 2 indicates GPU sensor + - 3 indicates SODIMM sensor + - 4 indicates other sensor type + - 5 indicates Ambient sensor + - 6 indicates other sensor type + +``0xfea3`` Get SMM signature Returns Dell signature if interface + is supported (after SMM): + + - ``eax`` holds 1145651527 + (0x44494147 or "DIAG") + - ``edx`` holds 1145392204 + (0x44454c4c or "DELL") + +``0xffa3`` Get SMM signature Same as ``0xfea3``, check both. +=============== ======================= ================================================ + +There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and +disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control. +The commands are however causing severe sideeffects on many machines, so +they are not used by default. + +On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the +fans supports a 4th "magic" state, which signals the BIOS that automatic +fan control should be enabled for a specific fan. +However there are also some machines who do support a 4th regular fan state too, +but in case of the "magic" state, the nominal RPM reported for this state is a +placeholder value, which however is not always detectable. + +Firmware Bugs +------------- + +The SMM calls can behave erratic on some machines: + +======================================================= ================= +Firmware Bug Affected Machines +======================================================= ================= +Reading of fan states return spurious errors. Precision 490 + +Reading of fan types causes erratic fan behaviour. Studio XPS 8000 + + Studio XPS 8100 + + Inspiron 580 + +Fan-related SMM calls take too long (about 500ms). Inspiron 7720 + + Vostro 3360 + + XPS 13 9333 + + XPS 15 L502X +======================================================= ================= + +In case you experience similar issues on your Dell machine, please +submit a bugreport on bugzilla to we can apply workarounds. + +Limitations +----------- + +The SMM calls can take too long to execute on some machines, causing +short hangs and/or audio glitches. +Also the fan state needs to be restored after suspend, as well as +the automatic mode settings. +When reading a temperature sensor, values above 127 degrees indicate +a BIOS read error or a deactivated sensor. diff --git a/Documentation/hwmon/ina238.rst b/Documentation/hwmon/ina238.rst new file mode 100644 index 000000000000..d9f479984420 --- /dev/null +++ b/Documentation/hwmon/ina238.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver ina238 +==================== + +Supported chips: + + * Texas Instruments INA238 + + Prefix: 'ina238' + + Addresses: I2C 0x40 - 0x4f + + Datasheet: + https://www.ti.com/lit/gpn/ina238 + +Author: Nathan Rossi <nathan.rossi@digi.com> + +Description +----------- + +The INA238 is a current shunt, power and temperature monitor with an I2C +interface. It includes a number of programmable functions including alerts, +conversion rate, sample averaging and selectable shunt voltage accuracy. + +The shunt value in micro-ohms can be set via platform data or device tree at +compile-time or via the shunt_resistor attribute in sysfs at run-time. Please +refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings +if the device tree is used. + +Sysfs entries +------------- + +======================= ======================================================= +in0_input Shunt voltage (mV) +in0_min Minimum shunt voltage threshold (mV) +in0_min_alarm Minimum shunt voltage alarm +in0_max Maximum shunt voltage threshold (mV) +in0_max_alarm Maximum shunt voltage alarm + +in1_input Bus voltage (mV) +in1_min Minimum bus voltage threshold (mV) +in1_min_alarm Minimum shunt voltage alarm +in1_max Maximum bus voltage threshold (mV) +in1_max_alarm Maximum shunt voltage alarm + +power1_input Power measurement (uW) +power1_max Maximum power threshold (uW) +power1_max_alarm Maximum power alarm + +curr1_input Current measurement (mA) + +temp1_input Die temperature measurement (mC) +temp1_max Maximum die temperature threshold (mC) +temp1_max_alarm Maximum die temperature alarm +======================= ======================================================= diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 7046bf1870d9..9d2787a12a69 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -43,6 +43,9 @@ Hardware Monitoring Kernel Drivers asb100 asc7621 aspeed-pwm-tacho + asus_ec_sensors + asus_wmi_ec_sensors + asus_wmi_sensors bcm54140 bel-pfe bpa-rs600 @@ -76,6 +79,7 @@ Hardware Monitoring Kernel Drivers ibmpowernv ina209 ina2xx + ina238 ina3221 intel-m10-bmc-hwmon ir35221 @@ -142,6 +146,7 @@ Hardware Monitoring Kernel Drivers mlxreg-fan mp2888 mp2975 + mp5023 nct6683 nct6775 nct7802 @@ -150,11 +155,13 @@ Hardware Monitoring Kernel Drivers nsa320 ntc_thermistor nzxt-kraken2 + nzxt-smart2 occ pc87360 pc87427 pcf8591 pim4328 + pli1209bc pm6764tr pmbus powr1220 @@ -188,6 +195,7 @@ Hardware Monitoring Kernel Drivers tmp108 tmp401 tmp421 + tmp464 tmp513 tps23861 tps40422 diff --git a/Documentation/hwmon/ir38064.rst b/Documentation/hwmon/ir38064.rst index c455d755a267..e1148f21ea2a 100644 --- a/Documentation/hwmon/ir38064.rst +++ b/Documentation/hwmon/ir38064.rst @@ -3,14 +3,38 @@ Kernel driver ir38064 Supported chips: + * Infineon IR38060 + + Prefix: 'IR38060' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38060M-DS-v03_16-EN.pdf?fileId=5546d4625c167129015c3291ea9a4cee + * Infineon IR38064 Prefix: 'ir38064' Addresses scanned: - - Datasheet: Publicly available at the Infineon webiste + Datasheet: Publicly available at the Infineon website https://www.infineon.com/dgdl/Infineon-IR38064MTRPBF-DS-v03_07-EN.pdf?fileId=5546d462584d1d4a0158db0d9efb67ca + * Infineon IR38164 + + Prefix: 'ir38164' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38164M-DS-v02_02-EN.pdf?fileId=5546d462636cc8fb01640046efea1248 + + * Infineon ir38263 + + Prefix: 'ir38263' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38263M-DataSheet-v03_05-EN.pdf?fileId=5546d4625b62cd8a015bcf81f90a6e52 + Authors: - Maxim Sloyko <maxims@google.com> - Patrick Venture <venture@google.com> @@ -18,7 +42,7 @@ Authors: Description ----------- -IR38064 is a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. +IR38x6x are a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. Usage Notes ----------- diff --git a/Documentation/hwmon/lm70.rst b/Documentation/hwmon/lm70.rst index 6ddc5b67ccb5..11303a7e16a8 100644 --- a/Documentation/hwmon/lm70.rst +++ b/Documentation/hwmon/lm70.rst @@ -15,6 +15,10 @@ Supported chips: Information: https://www.ti.com/product/tmp122 + * Texas Instruments TMP125 + + Information: https://www.ti.com/product/tmp125 + * National Semiconductor LM71 Datasheet: https://www.ti.com/product/LM71 @@ -53,6 +57,9 @@ The LM74 and TMP121/TMP122/TMP123/TMP124 are very similar; main difference is The TMP122/TMP124 also feature configurable temperature thresholds. +The TMP125 is less accurate and provides 10-bit temperature data +with 0.25 degrees Celsius resolution. + The LM71 is also very similar; main difference is 14-bit temperature data (0.03125 degrees celsius resolution). diff --git a/Documentation/hwmon/max6639.rst b/Documentation/hwmon/max6639.rst index 3da54225f83c..c85d285a3489 100644 --- a/Documentation/hwmon/max6639.rst +++ b/Documentation/hwmon/max6639.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: I2C 0x2c, 0x2e, 0x2f - Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6639.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX6639-MAX6639F.pdf Authors: - He Changqing <hechangqing@semptian.com> diff --git a/Documentation/hwmon/mp5023.rst b/Documentation/hwmon/mp5023.rst new file mode 100644 index 000000000000..af5ab1345a91 --- /dev/null +++ b/Documentation/hwmon/mp5023.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp5023 +==================== + +Supported chips: + + * MPS MP5023 + + Prefix: 'mp5023' + + * Datasheet + + Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5023.html + +Author: + + Howard Chiu <howard.chiu@quantatw.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP5023 Hot-Swap Controller. + +Device complaint with: + +- PMBus rev 1.3 interface. + +Device supports direct format for reading input voltage, output voltage, +output current, input power and temperature. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_max** + +**in1_max_alarm** + +**in1_min** + +**in1_min_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_alarm** + +The driver provides the following attributes for output current: + +**curr1_input** + +**curr1_label** + +**curr1_alarm** + +**curr1_max** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +**power1_alarm** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_max** + +**temp1_max_alarm** + +**temp1_crit** + +**temp1_crit_alarm** diff --git a/Documentation/hwmon/nzxt-smart2.rst b/Documentation/hwmon/nzxt-smart2.rst new file mode 100644 index 000000000000..d9d1b2742665 --- /dev/null +++ b/Documentation/hwmon/nzxt-smart2.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-smart2 +========================= + +Supported devices: + +- NZXT RGB & Fan controller +- NZXT Smart Device v2 + +Description +----------- + +This driver implements monitoring and control of fans plugged into the device. +Besides typical speed monitoring and PWM duty cycle control, voltage and current +is reported for every fan. + +The device also has two connectors for RGB LEDs; support for them isn't +implemented (mainly because there is no standardized sysfs interface). + +Also, the device has a noise sensor, but the sensor seems to be completely +useless (and very imprecise), so support for it isn't implemented too. + +Usage Notes +----------- + +The device should be autodetected, and the driver should load automatically. + +If fans are plugged in/unplugged while the system is powered on, the driver +must be reloaded to detect configuration changes; otherwise, new fans can't +be controlled (`pwm*` changes will be ignored). It is necessary because the +device has a dedicated "detect fans" command, and currently, it is executed only +during initialization. Speed, voltage, current monitoring will work even without +reload. As an alternative to reloading the module, a userspace tool (like +`liquidctl`_) can be used to run "detect fans" command through hidraw interface. + +The driver coexists with userspace tools that access the device through hidraw +interface with no known issues. + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Sysfs entries +------------- + +======================= ======================================================== +fan[1-3]_input Fan speed monitoring (in rpm). +curr[1-3]_input Current supplied to the fan (in milliamperes). +in[0-2]_input Voltage supplied to the fan (in millivolts). +pwm[1-3] Controls fan speed: PWM duty cycle for PWM-controlled + fans, voltage for other fans. Voltage can be changed in + 9-12 V range, but the value of the sysfs attribute is + always in 0-255 range (1 = 9V, 255 = 12V). Setting the + attribute to 0 turns off the fan completely. +pwm[1-3]_enable 1 if the fan can be controlled by writing to the + corresponding pwm* attribute, 0 otherwise. The device + can control only the fans it detected itself, so the + attribute is read-only. +pwm[1-3]_mode Read-only, 1 for PWM-controlled fans, 0 for other fans + (or if no fan connected). +update_interval The interval at which all inputs are updated (in + milliseconds). The default is 1000ms. Minimum is 250ms. +======================= ======================================================== diff --git a/Documentation/hwmon/pli1209bc.rst b/Documentation/hwmon/pli1209bc.rst new file mode 100644 index 000000000000..ea5b3f68a515 --- /dev/null +++ b/Documentation/hwmon/pli1209bc.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver pli1209bc +======================= + +Supported chips: + + * Digital Supervisor PLI1209BC + + Prefix: 'pli1209bc' + + Addresses scanned: 0x50 - 0x5F + + Datasheet: https://www.vicorpower.com/documents/datasheets/ds-PLI1209BCxyzz-VICOR.pdf + +Authors: + - Marcello Sylvester Bauer <sylv@sylv.io> + +Description +----------- + +The Vicor PLI1209BC is an isolated digital power system supervisor that provides +a communication interface between a host processor and one Bus Converter Module +(BCM). The PLI communicates with a system controller via a PMBus compatible +interface over an isolated UART interface. Through the PLI, the host processor +can configure, set protection limits, and monitor the BCM. + +Sysfs entries +------------- + +======================= ======================================================== +in1_label "vin2" +in1_input Input voltage. +in1_rated_min Minimum rated input voltage. +in1_rated_max Maximum rated input voltage. +in1_max Maximum input voltage. +in1_max_alarm Input voltage high alarm. +in1_crit Critical input voltage. +in1_crit_alarm Input voltage critical alarm. + +in2_label "vout2" +in2_input Output voltage. +in2_rated_min Minimum rated output voltage. +in2_rated_max Maximum rated output voltage. +in2_alarm Output voltage alarm + +curr1_label "iin2" +curr1_input Input current. +curr1_max Maximum input current. +curr1_max_alarm Maximum input current high alarm. +curr1_crit Critical input current. +curr1_crit_alarm Input current critical alarm. + +curr2_label "iout2" +curr2_input Output current. +curr2_crit Critical output current. +curr2_crit_alarm Output current critical alarm. +curr2_max Maximum output current. +curr2_max_alarm Output current high alarm. + +power1_label "pin2" +power1_input Input power. +power1_alarm Input power alarm. + +power2_label "pout2" +power2_input Output power. +power2_rated_max Maximum rated output power. + +temp1_input Die temperature. +temp1_alarm Die temperature alarm. +temp1_max Maximum die temperature. +temp1_max_alarm Die temperature high alarm. +temp1_crit Critical die temperature. +temp1_crit_alarm Die temperature critical alarm. +======================= ======================================================== diff --git a/Documentation/hwmon/sch5627.rst b/Documentation/hwmon/sch5627.rst index 187682e99114..ecb4fc84d045 100644 --- a/Documentation/hwmon/sch5627.rst +++ b/Documentation/hwmon/sch5627.rst @@ -20,6 +20,10 @@ Description SMSC SCH5627 Super I/O chips include complete hardware monitoring capabilities. They can monitor up to 5 voltages, 4 fans and 8 temperatures. +In addition, the SCH5627 exports data describing which temperature sensors +affect the speed of each fan. Setting pwmX_auto_channels_temp to 0 forces +the corresponding fan to full speed until another value is written. + The SMSC SCH5627 hardware monitoring part also contains an integrated watchdog. In order for this watchdog to function some motherboard specific initialization most be done by the BIOS, so if the watchdog is not enabled diff --git a/Documentation/hwmon/sysfs-interface.rst b/Documentation/hwmon/sysfs-interface.rst index 85652a6aaa3e..209626fb2405 100644 --- a/Documentation/hwmon/sysfs-interface.rst +++ b/Documentation/hwmon/sysfs-interface.rst @@ -99,6 +99,10 @@ Global attributes `name` The chip name. +`label` + A descriptive label that allows to uniquely identify a device + within the system. + `update_interval` The interval at which the chip will update readings. diff --git a/Documentation/hwmon/tmp464.rst b/Documentation/hwmon/tmp464.rst new file mode 100644 index 000000000000..7596e7623d06 --- /dev/null +++ b/Documentation/hwmon/tmp464.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver tmp464 +==================== + +Supported chips: + + * Texas Instruments TMP464 + + Prefix: 'tmp464' + + Addresses scanned: I2C 0x48, 0x49, 0x4a and 0x4b + + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp464.html + + * Texas Instruments TMP468 + + Prefix: 'tmp468' + + Addresses scanned: I2C 0x48, 0x49, 0x4a and 0x4b + + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp468.html + +Authors: + + Agathe Porte <agathe.porte@nokia.com> + Guenter Roeck <linux@roeck-us.net> + +Description +----------- + +This driver implements support for Texas Instruments TMP464 and TMP468 +temperature sensor chips. TMP464 provides one local and four remote +sensors. TMP468 provides one local and eight remote sensors. +Temperature is measured in degrees Celsius. The chips are wired over +I2C/SMBus and specified over a temperature range of -40 to +125 degrees +Celsius. Resolution for both the local and remote channels is 0.0625 +degree C. + +The chips support only temperature measurements. The driver exports +temperature values, limits, and alarms via the following sysfs files: + +**temp[1-9]_input** + +**temp[1-9]_max** + +**temp[1-9]_max_hyst** + +**temp[1-9]_max_alarm** + +**temp[1-9]_crit** + +**temp[1-9]_crit_alarm** + +**temp[1-9]_crit_hyst** + +**temp[2-9]_offset** + +**temp[2-9]_fault** + +Each sensor can be individually disabled via Devicetree or from sysfs +via: + +**temp[1-9]_enable** + +If labels were specified in Devicetree, additional sysfs files will +be present: + +**temp[1-9]_label** + +The update interval is configurable with the following sysfs attribute. + +**update_interval** diff --git a/Documentation/hwmon/xdpe12284.rst b/Documentation/hwmon/xdpe12284.rst index 67d1f87808e5..a224dc74ad35 100644 --- a/Documentation/hwmon/xdpe12284.rst +++ b/Documentation/hwmon/xdpe12284.rst @@ -5,6 +5,10 @@ Kernel driver xdpe122 Supported chips: + * Infineon XDPE11280 + + Prefix: 'xdpe11280' + * Infineon XDPE12254 Prefix: 'xdpe12254' @@ -20,10 +24,10 @@ Authors: Description ----------- -This driver implements support for Infineon Multi-phase XDPE122 family -dual loop voltage regulators. -The family includes XDPE12284 and XDPE12254 devices. -The devices from this family complaint with: +This driver implements support for Infineon Multi-phase XDPE112 and XDPE122 +family dual loop voltage regulators. +These families include XDPE11280, XDPE12284 and XDPE12254 devices. +The devices from this family compliant with: - Intel VR13 and VR13HC rev 1.3, IMVP8 rev 1.2 and IMPVP9 rev 1.3 DC-DC converter specification. diff --git a/Documentation/index.rst b/Documentation/index.rst index 54ce34fd6fbd..b58692d687f6 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -137,6 +137,7 @@ needed). misc-devices/index scheduler/index mhi/index + tty/index Architecture-agnostic documentation ----------------------------------- @@ -165,6 +166,7 @@ to ReStructured Text format, or are simply too old. .. toctree:: :maxdepth: 2 + tools/index staging/index watch_queue diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 98c24183d8c3..93a5b6e1fabd 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -176,7 +176,7 @@ applicable everywhere (see syntax). y y y Y/m/n n m n N/m m m m M/n - y m n M/n + y m m M/n y n * N === === ============= ============== diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index e6cd40663ea5..4cbd50edf277 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -295,7 +295,7 @@ Pete Zaitcev gives the following summary: - If you are in a process context (any syscall) and want to lock other process out, use a mutex. You can take a mutex and sleep - (``copy_from_user*(`` or ``kmalloc(x,GFP_KERNEL)``). + (``copy_from_user()`` or ``kmalloc(x,GFP_KERNEL)``). - Otherwise (== data can be touched in an interrupt), use spin_lock_irqsave() and diff --git a/Documentation/livepatch/api.rst b/Documentation/livepatch/api.rst new file mode 100644 index 000000000000..78944b63d74b --- /dev/null +++ b/Documentation/livepatch/api.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +Livepatching APIs +================= + +Livepatch Enablement +==================== + +.. kernel-doc:: kernel/livepatch/core.c + :export: + + +Shadow Variables +================ + +.. kernel-doc:: kernel/livepatch/shadow.c + :export: + +System State Changes +==================== + +.. kernel-doc:: kernel/livepatch/state.c + :export: + +Object Types +============ + +.. kernel-doc:: include/linux/livepatch.h + :identifiers: klp_patch klp_object klp_func klp_callbacks klp_state diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst index 43cce5fad705..cebf1c71d4a5 100644 --- a/Documentation/livepatch/index.rst +++ b/Documentation/livepatch/index.rst @@ -14,6 +14,7 @@ Kernel Livepatching shadow-vars system-state reliable-stacktrace + api .. only:: subproject and html diff --git a/Documentation/livepatch/shadow-vars.rst b/Documentation/livepatch/shadow-vars.rst index 6a7d43a8787d..7a7098bfb5c8 100644 --- a/Documentation/livepatch/shadow-vars.rst +++ b/Documentation/livepatch/shadow-vars.rst @@ -82,8 +82,8 @@ to do actions that can be done only once when a new variable is allocated. - call destructor function if defined - free shadow variable -* klp_shadow_free_all() - detach and free all <*, id> shadow variables - - find and remove any <*, id> references from global hashtable +* klp_shadow_free_all() - detach and free all <_, id> shadow variables + - find and remove any <_, id> references from global hashtable - if found diff --git a/Documentation/livepatch/system-state.rst b/Documentation/livepatch/system-state.rst index c6d127c2d9aa..7a3935fd812b 100644 --- a/Documentation/livepatch/system-state.rst +++ b/Documentation/livepatch/system-state.rst @@ -52,12 +52,12 @@ struct klp_state: The state can be manipulated using two functions: - - *klp_get_state(patch, id)* + - klp_get_state() - Get struct klp_state associated with the given livepatch and state id. - - *klp_get_prev_state(id)* + - klp_get_prev_state() - Get struct klp_state associated with the given feature id and already installed livepatches. diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 4fd7b70fcde1..bfa75ea1b66a 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -247,7 +247,7 @@ based on rt_mutex which changes the semantics: Non-PREEMPT_RT kernels disable preemption to get this effect. PREEMPT_RT kernels use a per-CPU lock for serialization which keeps - preemption disabled. The lock disables softirq handlers and also + preemption enabled. The lock disables softirq handlers and also prevents reentrancy due to task preemption. PREEMPT_RT kernels preserve all other spinlock_t semantics: diff --git a/Documentation/networking/rds.rst b/Documentation/networking/rds.rst index 44936c27ab3a..498395f5fbcb 100644 --- a/Documentation/networking/rds.rst +++ b/Documentation/networking/rds.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -== +=== RDS === diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 855a70b80269..bd36ecb29409 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -197,14 +197,29 @@ the build process, for example, or editor backup files) in the patch. The file "dontdiff" in the Documentation directory can help in this regard; pass it to diff with the "-X" option. -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in -the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -document; what follows here is a brief summary. Each of these lines has -the format: +The tags already briefly mentioned above are used to provide insights how +the patch came into being. They are described in detail in the +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document; what follows here is a brief summary. -:: +One tag is used to refer to earlier commits which introduced problems fixed by +the patch:: + + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Another tag is used for linking web pages with additional backgrounds or +details, for example a report about a bug fixed by the patch or a document +with a specification implemented by the patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +Many maintainers when applying a patch also add this tag to link to the +latest public review posting of the patch; often this is automatically done +by tools like b4 or a git hook like the one described in +'Documentation/maintainer/configure-git.rst'. + +A third kind of tag is used to document who was involved in the development of +the patch. Each of these uses this format:: tag: Full Name <email address> optional-other-stuff diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index c2121c1e55d7..c269f5e1a0a3 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -249,6 +249,10 @@ The 5.x.y (-stable) and 5.x patches live at https://www.kernel.org/pub/linux/kernel/v5.x/ +The 5.x.y incremental patches live at + + https://www.kernel.org/pub/linux/kernel/v5.x/incr/ + The -rc patches are not stored on the webserver but are generated on demand from git tags such as @@ -308,12 +312,11 @@ versions. If no 5.x.y kernel is available, then the highest numbered 5.x kernel is the current stable kernel. -.. note:: +The -stable team provides normal as well as incremental patches. Below is +how to apply these patches. - The -stable team usually do make incremental patches available as well - as patches against the latest mainline release, but I only cover the - non-incremental ones below. The incremental ones can be found at - https://www.kernel.org/pub/linux/kernel/v5.x/incr/ +Normal patches +~~~~~~~~~~~~~~ These patches are not incremental, meaning that for example the 5.7.3 patch does not apply on top of the 5.7.2 kernel source, but rather on top @@ -331,6 +334,21 @@ Here's a small example:: $ cd .. $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir +Incremental patches +~~~~~~~~~~~~~~~~~~~ + +Incremental patches are different: instead of being applied on top +of base 5.x kernel, they are applied on top of previous stable kernel +(5.x.y-1). + +Here's the example to apply these:: + + $ cd ~/linux-5.7.2 # change to the kernel source dir + $ patch -p1 < ../patch-5.7.2-3 # apply the new 5.7.3 patch + $ cd .. + $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir + + The -rc kernels =============== diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index cf908d79666e..a337e8eabfe1 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -30,7 +30,7 @@ you probably needn't concern yourself with pcmciautils. Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 5.1 gcc --version -Clang/LLVM (optional) 10.0.1 clang --version +Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 388cb19f5dbb..a6e36d9c3d14 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -71,6 +71,9 @@ Instead, the 2-factor form of the allocator should be used:: foo = kmalloc_array(count, size, GFP_KERNEL); +Specifically, kmalloc() can be replaced with kmalloc_array(), and +kzalloc() can be replaced with kcalloc(). + If no 2-factor form is available, the saturate-on-overflow helpers should be used:: @@ -91,9 +94,20 @@ Instead, use the helper:: array usage and switch to a `flexible array member <#zero-length-and-one-element-arrays>`_ instead. -See array_size(), array3_size(), and struct_size(), -for more details as well as the related check_add_overflow() and -check_mul_overflow() family of functions. +For other calculations, please compose the use of the size_mul(), +size_add(), and size_sub() helpers. For example, in the case of:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +Instead, use the helpers:: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +For more details, also see array3_size() and flex_array_size(), +as well as the related check_mul_overflow(), check_add_overflow(), +check_sub_overflow(), and check_shl_overflow() family of functions. simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() ---------------------------------------------------------------------- diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst new file mode 100644 index 000000000000..abb741b1aeee --- /dev/null +++ b/Documentation/process/handling-regressions.rst @@ -0,0 +1,746 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. See the bottom of this file for additional redistribution information. + +Handling regressions +++++++++++++++++++++ + +*We don't cause regressions* -- this document describes what this "first rule of +Linux kernel development" means in practice for developers. It complements +Documentation/admin-guide/reporting-regressions.rst, which covers the topic from a +user's point of view; if you never read that text, go and at least skim over it +before continuing here. + +The important bits (aka "The TL;DR") +==================================== + +#. Ensure subscribers of the `regression mailing list <https://lore.kernel.org/regressions/>`_ + (regressions@lists.linux.dev) quickly become aware of any new regression + report: + + * When receiving a mailed report that did not CC the list, bring it into the + loop by immediately sending at least a brief "Reply-all" with the list + CCed. + + * Forward or bounce any reports submitted in bug trackers to the list. + +#. Make the Linux kernel regression tracking bot "regzbot" track the issue (this + is optional, but recommended): + + * For mailed reports, check if the reporter included a line like ``#regzbot + introduced v5.13..v5.14-rc1``. If not, send a reply (with the regressions + list in CC) containing a paragraph like the following, which tells regzbot + when the issue started to happen:: + + #regzbot ^introduced 1f2e3d4c5b6a + + * When forwarding reports from a bug tracker to the regressions list (see + above), include a paragraph like the following:: + + #regzbot introduced: v5.13..v5.14-rc1 + #regzbot from: Some N. Ice Human <some.human@example.com> + #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 + +#. When submitting fixes for regressions, add "Link:" tags to the patch + description pointing to all places where the issue was reported, as + mandated by Documentation/process/submitting-patches.rst and + :ref:`Documentation/process/5.Posting.rst <development_posting>`. + +#. Try to fix regressions quickly once the culprit has been identified; fixes + for most regressions should be merged within two weeks, but some need to be + resolved within two or three days. + + +All the details on Linux kernel regressions relevant for developers +=================================================================== + + +The important basics in more detail +----------------------------------- + + +What to do when receiving regression reports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ensure the Linux kernel's regression tracker and others subscribers of the +`regression mailing list <https://lore.kernel.org/regressions/>`_ +(regressions@lists.linux.dev) become aware of any newly reported regression: + + * When you receive a report by mail that did not CC the list, immediately bring + it into the loop by sending at least a brief "Reply-all" with the list CCed; + try to ensure it gets CCed again in case you reply to a reply that omitted + the list. + + * If a report submitted in a bug tracker hits your Inbox, forward or bounce it + to the list. Consider checking the list archives beforehand, if the reporter + already forwarded the report as instructed by + Documentation/admin-guide/reporting-issues.rst. + +When doing either, consider making the Linux kernel regression tracking bot +"regzbot" immediately start tracking the issue: + + * For mailed reports, check if the reporter included a "regzbot command" like + ``#regzbot introduced 1f2e3d4c5b6a``. If not, send a reply (with the + regressions list in CC) with a paragraph like the following::: + + #regzbot ^introduced: v5.13..v5.14-rc1 + + This tells regzbot the version range in which the issue started to happen; + you can specify a range using commit-ids as well or state a single commit-id + in case the reporter bisected the culprit. + + Note the caret (^) before the "introduced": it tells regzbot to treat the + parent mail (the one you reply to) as the initial report for the regression + you want to see tracked; that's important, as regzbot will later look out + for patches with "Link:" tags pointing to the report in the archives on + lore.kernel.org. + + * When forwarding a regressions reported to a bug tracker, include a paragraph + with these regzbot commands:: + + #regzbot introduced: 1f2e3d4c5b6a + #regzbot from: Some N. Ice Human <some.human@example.com> + #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 + + Regzbot will then automatically associate patches with the report that + contain "Link:" tags pointing to your mail or the mentioned ticket. + +What's important when fixing regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You don't need to do anything special when submitting fixes for regression, just +remember to do what Documentation/process/submitting-patches.rst, +:ref:`Documentation/process/5.Posting.rst <development_posting>`, and +Documentation/process/stable-kernel-rules.rst already explain in more detail: + + * Point to all places where the issue was reported using "Link:" tags:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 + + * Add a "Fixes:" tag to specify the commit causing the regression. + + * If the culprit was merged in an earlier development cycle, explicitly mark + the fix for backporting using the ``Cc: stable@vger.kernel.org`` tag. + +All this is expected from you and important when it comes to regression, as +these tags are of great value for everyone (you included) that might be looking +into the issue weeks, months, or years later. These tags are also crucial for +tools and scripts used by other kernel developers or Linux distributions; one of +these tools is regzbot, which heavily relies on the "Link:" tags to associate +reports for regression with changes resolving them. + +Prioritize work on fixing regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You should fix any reported regression as quickly as possible, to provide +affected users with a solution in a timely manner and prevent more users from +running into the issue; nevertheless developers need to take enough time and +care to ensure regression fixes do not cause additional damage. + +In the end though, developers should give their best to prevent users from +running into situations where a regression leaves them only three options: "run +a kernel with a regression that seriously impacts usage", "continue running an +outdated and thus potentially insecure kernel version for more than two weeks +after a regression's culprit was identified", and "downgrade to a still +supported kernel series that lack required features". + +How to realize this depends a lot on the situation. Here are a few rules of +thumb for you, in order or importance: + + * Prioritize work on handling regression reports and fixing regression over all + other Linux kernel work, unless the latter concerns acute security issues or + bugs causing data loss or damage. + + * Always consider reverting the culprit commits and reapplying them later + together with necessary fixes, as this might be the least dangerous and + quickest way to fix a regression. + + * Developers should handle regressions in all supported kernel series, but are + free to delegate the work to the stable team, if the issue probably at no + point in time occurred with mainline. + + * Try to resolve any regressions introduced in the current development before + its end. If you fear a fix might be too risky to apply only days before a new + mainline release, let Linus decide: submit the fix separately to him as soon + as possible with the explanation of the situation. He then can make a call + and postpone the release if necessary, for example if multiple such changes + show up in his inbox. + + * Address regressions in stable, longterm, or proper mainline releases with + more urgency than regressions in mainline pre-releases. That changes after + the release of the fifth pre-release, aka "-rc5": mainline then becomes as + important, to ensure all the improvements and fixes are ideally tested + together for at least one week before Linus releases a new mainline version. + + * Fix regressions within two or three days, if they are critical for some + reason -- for example, if the issue is likely to affect many users of the + kernel series in question on all or certain architectures. Note, this + includes mainline, as issues like compile errors otherwise might prevent many + testers or continuous integration systems from testing the series. + + * Aim to fix regressions within one week after the culprit was identified, if + the issue was introduced in either: + + * a recent stable/longterm release + + * the development cycle of the latest proper mainline release + + In the latter case (say Linux v5.14), try to address regressions even + quicker, if the stable series for the predecessor (v5.13) will be abandoned + soon or already was stamped "End-of-Life" (EOL) -- this usually happens about + three to four weeks after a new mainline release. + + * Try to fix all other regressions within two weeks after the culprit was + found. Two or three additional weeks are acceptable for performance + regressions and other issues which are annoying, but don't prevent anyone + from running Linux (unless it's an issue in the current development cycle, + as those should ideally be addressed before the release). A few weeks in + total are acceptable if a regression can only be fixed with a risky change + and at the same time is affecting only a few users; as much time is + also okay if the regression is already present in the second newest longterm + kernel series. + +Note: The aforementioned time frames for resolving regressions are meant to +include getting the fix tested, reviewed, and merged into mainline, ideally with +the fix being in linux-next at least briefly. This leads to delays you need to +account for. + +Subsystem maintainers are expected to assist in reaching those periods by doing +timely reviews and quick handling of accepted patches. They thus might have to +send git-pull requests earlier or more often than usual; depending on the fix, +it might even be acceptable to skip testing in linux-next. Especially fixes for +regressions in stable and longterm kernels need to be handled quickly, as fixes +need to be merged in mainline before they can be backported to older series. + + +More aspects regarding regressions developers should be aware of +---------------------------------------------------------------- + + +How to deal with changes where a risk of regression is known +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Evaluate how big the risk of regressions is, for example by performing a code +search in Linux distributions and Git forges. Also consider asking other +developers or projects likely to be affected to evaluate or even test the +proposed change; if problems surface, maybe some solution acceptable for all +can be found. + +If the risk of regressions in the end seems to be relatively small, go ahead +with the change, but let all involved parties know about the risk. Hence, make +sure your patch description makes this aspect obvious. Once the change is +merged, tell the Linux kernel's regression tracker and the regressions mailing +list about the risk, so everyone has the change on the radar in case reports +trickle in. Depending on the risk, you also might want to ask the subsystem +maintainer to mention the issue in his mainline pull request. + +What else is there to known about regressions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check out Documentation/admin-guide/reporting-regressions.rst, it covers a lot +of other aspects you want might want to be aware of: + + * the purpose of the "no regressions rule" + + * what issues actually qualify as regression + + * who's in charge for finding the root cause of a regression + + * how to handle tricky situations, e.g. when a regression is caused by a + security fix or when fixing a regression might cause another one + +Whom to ask for advice when it comes to regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Send a mail to the regressions mailing list (regressions@lists.linux.dev) while +CCing the Linux kernel's regression tracker (regressions@leemhuis.info); if the +issue might better be dealt with in private, feel free to omit the list. + + +More about regression tracking and regzbot +------------------------------------------ + + +Why the Linux kernel has a regression tracker, and why is regzbot used? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rules like "no regressions" need someone to ensure they are followed, otherwise +they are broken either accidentally or on purpose. History has shown this to be +true for the Linux kernel as well. That's why Thorsten Leemhuis volunteered to +keep an eye on things as the Linux kernel's regression tracker, who's +occasionally helped by other people. Neither of them are paid to do this, +that's why regression tracking is done on a best effort basis. + +Earlier attempts to manually track regressions have shown it's an exhausting and +frustrating work, which is why they were abandoned after a while. To prevent +this from happening again, Thorsten developed regzbot to facilitate the work, +with the long term goal to automate regression tracking as much as possible for +everyone involved. + +How does regression tracking work with regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bot watches for replies to reports of tracked regressions. Additionally, +it's looking out for posted or committed patches referencing such reports +with "Link:" tags; replies to such patch postings are tracked as well. +Combined this data provides good insights into the current state of the fixing +process. + +Regzbot tries to do its job with as little overhead as possible for both +reporters and developers. In fact, only reporters are burdened with an extra +duty: they need to tell regzbot about the regression report using the ``#regzbot +introduced`` command outlined above; if they don't do that, someone else can +take care of that using ``#regzbot ^introduced``. + +For developers there normally is no extra work involved, they just need to make +sure to do something that was expected long before regzbot came to light: add +"Link:" tags to the patch description pointing to all reports about the issue +fixed. + +Do I have to use regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's in the interest of everyone if you do, as kernel maintainers like Linus +Torvalds partly rely on regzbot's tracking in their work -- for example when +deciding to release a new version or extend the development phase. For this they +need to be aware of all unfixed regression; to do that, Linus is known to look +into the weekly reports sent by regzbot. + +Do I have to tell regzbot about every regression I stumble upon? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ideally yes: we are all humans and easily forget problems when something more +important unexpectedly comes up -- for example a bigger problem in the Linux +kernel or something in real life that's keeping us away from keyboards for a +while. Hence, it's best to tell regzbot about every regression, except when you +immediately write a fix and commit it to a tree regularly merged to the affected +kernel series. + +How to see which regressions regzbot tracks currently? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check `regzbot's web-interface <https://linux-regtracking.leemhuis.info/regzbot/>`_ +for the latest info; alternatively, `search for the latest regression report +<https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot>`_, +which regzbot normally sends out once a week on Sunday evening (UTC), which is a +few hours before Linus usually publishes new (pre-)releases. + +What places is regzbot monitoring? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regzbot is watching the most important Linux mailing lists as well as the git +repositories of linux-next, mainline, and stable/longterm. + +What kind of issues are supposed to be tracked by regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bot is meant to track regressions, hence please don't involve regzbot for +regular issues. But it's okay for the Linux kernel's regression tracker if you +use regzbot to track severe issues, like reports about hangs, corrupted data, +or internal errors (Panic, Oops, BUG(), warning, ...). + +Can I add regressions found by CI systems to regzbot's tracking? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Feel free to do so, if the particular regression likely has impact on practical +use cases and thus might be noticed by users; hence, please don't involve +regzbot for theoretical regressions unlikely to show themselves in real world +usage. + +How to interact with regzbot? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By using a 'regzbot command' in a direct or indirect reply to the mail with the +regression report. These commands need to be in their own paragraph (IOW: they +need to be separated from the rest of the mail using blank lines). + +One such command is ``#regzbot introduced <version or commit>``, which makes +regzbot consider your mail as a regressions report added to the tracking, as +already described above; ``#regzbot ^introduced <version or commit>`` is another +such command, which makes regzbot consider the parent mail as a report for a +regression which it starts to track. + +Once one of those two commands has been utilized, other regzbot commands can be +used in direct or indirect replies to the report. You can write them below one +of the `introduced` commands or in replies to the mail that used one of them +or itself is a reply to that mail: + + * Set or update the title:: + + #regzbot title: foo + + * Monitor a discussion or bugzilla.kernel.org ticket where additions aspects of + the issue or a fix are discussed -- for example the posting of a patch fixing + the regression:: + + #regzbot monitor: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/ + + Monitoring only works for lore.kernel.org and bugzilla.kernel.org; regzbot + will consider all messages in that thread or ticket as related to the fixing + process. + + * Point to a place with further details of interest, like a mailing list post + or a ticket in a bug tracker that are slightly related, but about a different + topic:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * Mark a regression as fixed by a commit that is heading upstream or already + landed:: + + #regzbot fixed-by: 1f2e3d4c5d + + * Mark a regression as a duplicate of another one already tracked by regzbot:: + + #regzbot dup-of: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/ + + * Mark a regression as invalid:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Is there more to tell about regzbot and its commands? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +More detailed and up-to-date information about the Linux +kernel's regression tracking bot can be found on its +`project page <https://gitlab.com/knurd42/regzbot>`_, which among others +contains a `getting started guide <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +and `reference documentation <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ +which both cover more details than the above section. + +Quotes from Linus about regression +---------------------------------- + +Find below a few real life examples of how Linus Torvalds expects regressions to +be handled: + + * From `2017-10-26 (1/2) + <https://lore.kernel.org/lkml/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_:: + + If you break existing user space setups THAT IS A REGRESSION. + + It's not ok to say "but we'll fix the user space setup". + + Really. NOT OK. + + [...] + + The first rule is: + + - we don't cause regressions + + and the corollary is that when regressions *do* occur, we admit to + them and fix them, instead of blaming user space. + + The fact that you have apparently been denying the regression now for + three weeks means that I will revert, and I will stop pulling apparmor + requests until the people involved understand how kernel development + is done. + + * From `2017-10-26 (2/2) + <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: + + People should basically always feel like they can update their kernel + and simply not have to worry about it. + + I refuse to introduce "you can only update the kernel if you also + update that other program" kind of limitations. If the kernel used to + work for you, the rule is that it continues to work for you. + + There have been exceptions, but they are few and far between, and they + generally have some major and fundamental reasons for having happened, + that were basically entirely unavoidable, and people _tried_hard_ to + avoid them. Maybe we can't practically support the hardware any more + after it is decades old and nobody uses it with modern kernels any + more. Maybe there's a serious security issue with how we did things, + and people actually depended on that fundamentally broken model. Maybe + there was some fundamental other breakage that just _had_ to have a + flag day for very core and fundamental reasons. + + And notice that this is very much about *breaking* peoples environments. + + Behavioral changes happen, and maybe we don't even support some + feature any more. There's a number of fields in /proc/<pid>/stat that + are printed out as zeroes, simply because they don't even *exist* in + the kernel any more, or because showing them was a mistake (typically + an information leak). But the numbers got replaced by zeroes, so that + the code that used to parse the fields still works. The user might not + see everything they used to see, and so behavior is clearly different, + but things still _work_, even if they might no longer show sensitive + (or no longer relevant) information. + + But if something actually breaks, then the change must get fixed or + reverted. And it gets fixed in the *kernel*. Not by saying "well, fix + your user space then". It was a kernel change that exposed the + problem, it needs to be the kernel that corrects for it, because we + have a "upgrade in place" model. We don't have a "upgrade with new + user space". + + And I seriously will refuse to take code from people who do not + understand and honor this very simple rule. + + This rule is also not going to change. + + And yes, I realize that the kernel is "special" in this respect. I'm + proud of it. + + I have seen, and can point to, lots of projects that go "We need to + break that use case in order to make progress" or "you relied on + undocumented behavior, it sucks to be you" or "there's a better way to + do what you want to do, and you have to change to that new better + way", and I simply don't think that's acceptable outside of very early + alpha releases that have experimental users that know what they signed + up for. The kernel hasn't been in that situation for the last two + decades. + + We do API breakage _inside_ the kernel all the time. We will fix + internal problems by saying "you now need to do XYZ", but then it's + about internal kernel API's, and the people who do that then also + obviously have to fix up all the in-kernel users of that API. Nobody + can say "I now broke the API you used, and now _you_ need to fix it + up". Whoever broke something gets to fix it too. + + And we simply do not break user space. + + * From `2020-05-21 + <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: + + The rules about regressions have never been about any kind of + documented behavior, or where the code lives. + + The rules about regressions are always about "breaks user workflow". + + Users are literally the _only_ thing that matters. + + No amount of "you shouldn't have used this" or "that behavior was + undefined, it's your own fault your app broke" or "that used to work + simply because of a kernel bug" is at all relevant. + + Now, reality is never entirely black-and-white. So we've had things + like "serious security issue" etc that just forces us to make changes + that may break user space. But even then the rule is that we don't + really have other options that would allow things to continue. + + And obviously, if users take years to even notice that something + broke, or if we have sane ways to work around the breakage that + doesn't make for too much trouble for users (ie "ok, there are a + handful of users, and they can use a kernel command line to work + around it" kind of things) we've also been a bit less strict. + + But no, "that was documented to be broken" (whether it's because the + code was in staging or because the man-page said something else) is + irrelevant. If staging code is so useful that people end up using it, + that means that it's basically regular kernel code with a flag saying + "please clean this up". + + The other side of the coin is that people who talk about "API + stability" are entirely wrong. API's don't matter either. You can make + any changes to an API you like - as long as nobody notices. + + Again, the regression rule is not about documentation, not about + API's, and not about the phase of the moon. + + It's entirely about "we caused problems for user space that used to work". + + * From `2017-11-05 + <https://lore.kernel.org/all/CA+55aFzUvbGjD8nQ-+3oiMBx14c_6zOj2n7KLN3UsJ-qsd4Dcw@mail.gmail.com/>`_:: + + And our regression rule has never been "behavior doesn't change". + That would mean that we could never make any changes at all. + + For example, we do things like add new error handling etc all the + time, which we then sometimes even add tests for in our kselftest + directory. + + So clearly behavior changes all the time and we don't consider that a + regression per se. + + The rule for a regression for the kernel is that some real user + workflow breaks. Not some test. Not a "look, I used to be able to do + X, now I can't". + + * From `2018-08-03 + <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: + + YOU ARE MISSING THE #1 KERNEL RULE. + + We do not regress, and we do not regress exactly because your are 100% wrong. + + And the reason you state for your opinion is in fact exactly *WHY* you + are wrong. + + Your "good reasons" are pure and utter garbage. + + The whole point of "we do not regress" is so that people can upgrade + the kernel and never have to worry about it. + + > Kernel had a bug which has been fixed + + That is *ENTIRELY* immaterial. + + Guys, whether something was buggy or not DOES NOT MATTER. + + Why? + + Bugs happen. That's a fact of life. Arguing that "we had to break + something because we were fixing a bug" is completely insane. We fix + tens of bugs every single day, thinking that "fixing a bug" means that + we can break something is simply NOT TRUE. + + So bugs simply aren't even relevant to the discussion. They happen, + they get found, they get fixed, and it has nothing to do with "we + break users". + + Because the only thing that matters IS THE USER. + + How hard is that to understand? + + Anybody who uses "but it was buggy" as an argument is entirely missing + the point. As far as the USER was concerned, it wasn't buggy - it + worked for him/her. + + Maybe it worked *because* the user had taken the bug into account, + maybe it worked because the user didn't notice - again, it doesn't + matter. It worked for the user. + + Breaking a user workflow for a "bug" is absolutely the WORST reason + for breakage you can imagine. + + It's basically saying "I took something that worked, and I broke it, + but now it's better". Do you not see how f*cking insane that statement + is? + + And without users, your program is not a program, it's a pointless + piece of code that you might as well throw away. + + Seriously. This is *why* the #1 rule for kernel development is "we + don't break users". Because "I fixed a bug" is absolutely NOT AN + ARGUMENT if that bug fix broke a user setup. You actually introduced a + MUCH BIGGER bug by "fixing" something that the user clearly didn't + even care about. + + And dammit, we upgrade the kernel ALL THE TIME without upgrading any + other programs at all. It is absolutely required, because flag-days + and dependencies are horribly bad. + + And it is also required simply because I as a kernel developer do not + upgrade random other tools that I don't even care about as I develop + the kernel, and I want any of my users to feel safe doing the same + time. + + So no. Your rule is COMPLETELY wrong. If you cannot upgrade a kernel + without upgrading some other random binary, then we have a problem. + + * From `2021-06-05 + <https://lore.kernel.org/all/CAHk-=wiUVqHN76YUwhkjZzwTdjMMJf_zN4+u7vEJjmEGh3recw@mail.gmail.com/>`_:: + + THERE ARE NO VALID ARGUMENTS FOR REGRESSIONS. + + Honestly, security people need to understand that "not working" is not + a success case of security. It's a failure case. + + Yes, "not working" may be secure. But security in that case is *pointless*. + + * From `2011-05-06 (1/3) + <https://lore.kernel.org/all/BANLkTim9YvResB+PwRp7QTK-a5VNg2PvmQ@mail.gmail.com/>`_:: + + Binary compatibility is more important. + + And if binaries don't use the interface to parse the format (or just + parse it wrongly - see the fairly recent example of adding uuid's to + /proc/self/mountinfo), then it's a regression. + + And regressions get reverted, unless there are security issues or + similar that makes us go "Oh Gods, we really have to break things". + + I don't understand why this simple logic is so hard for some kernel + developers to understand. Reality matters. Your personal wishes matter + NOT AT ALL. + + If you made an interface that can be used without parsing the + interface description, then we're stuck with the interface. Theory + simply doesn't matter. + + You could help fix the tools, and try to avoid the compatibility + issues that way. There aren't that many of them. + + From `2011-05-06 (2/3) + <https://lore.kernel.org/all/BANLkTi=KVXjKR82sqsz4gwjr+E0vtqCmvA@mail.gmail.com/>`_:: + + it's clearly NOT an internal tracepoint. By definition. It's being + used by powertop. + + From `2011-05-06 (3/3) + <https://lore.kernel.org/all/BANLkTinazaXRdGovYL7rRVp+j6HbJ7pzhg@mail.gmail.com/>`_:: + + We have programs that use that ABI and thus it's a regression if they break. + + * From `2012-07-06 <https://lore.kernel.org/all/CA+55aFwnLJ+0sjx92EGREGTWOx84wwKaraSzpTNJwPVV8edw8g@mail.gmail.com/>`_:: + + > Now this got me wondering if Debian _unstable_ actually qualifies as a + > standard distro userspace. + + Oh, if the kernel breaks some standard user space, that counts. Tons + of people run Debian unstable + + * From `2019-09-15 + <https://lore.kernel.org/lkml/CAHk-=wiP4K8DRJWsCo=20hn_6054xBamGKF2kPgUzpB5aMaofA@mail.gmail.com/>`_:: + + One _particularly_ last-minute revert is the top-most commit (ignoring + the version change itself) done just before the release, and while + it's very annoying, it's perhaps also instructive. + + What's instructive about it is that I reverted a commit that wasn't + actually buggy. In fact, it was doing exactly what it set out to do, + and did it very well. In fact it did it _so_ well that the much + improved IO patterns it caused then ended up revealing a user-visible + regression due to a real bug in a completely unrelated area. + + The actual details of that regression are not the reason I point that + revert out as instructive, though. It's more that it's an instructive + example of what counts as a regression, and what the whole "no + regressions" kernel rule means. The reverted commit didn't change any + API's, and it didn't introduce any new bugs. But it ended up exposing + another problem, and as such caused a kernel upgrade to fail for a + user. So it got reverted. + + The point here being that we revert based on user-reported _behavior_, + not based on some "it changes the ABI" or "it caused a bug" concept. + The problem was really pre-existing, and it just didn't happen to + trigger before. The better IO patterns introduced by the change just + happened to expose an old bug, and people had grown to depend on the + previously benign behavior of that old issue. + + And never fear, we'll re-introduce the fix that improved on the IO + patterns once we've decided just how to handle the fact that we had a + bad interaction with an interface that people had then just happened + to rely on incidental behavior for before. It's just that we'll have + to hash through how to do that (there are no less than three different + patches by three different developers being discussed, and there might + be more coming...). In the meantime, I reverted the thing that exposed + the problem to users for this release, even if I hope it will be + re-introduced (perhaps even backported as a stable patch) once we have + consensus about the issue it exposed. + + Take-away from the whole thing: it's not about whether you change the + kernel-userspace ABI, or fix a bug, or about whether the old code + "should never have worked in the first place". It's about whether + something breaks existing users' workflow. + + Anyway, that was my little aside on the whole regression thing. Since + it's that "first rule of kernel programming", I felt it is perhaps + worth just bringing it up every once in a while + +.. + end-of-content +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/handling-regressions.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 9f1b88492bb3..3587dae4d0ef 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -25,6 +25,7 @@ Below are the essential guides that every developer should read. code-of-conduct-interpretation development-process submitting-patches + handling-regressions programming-language coding-style maintainer-handbooks @@ -48,6 +49,7 @@ Other guides to the community that are of interest to most developers are: deprecated embargoed-hardware-issues maintainers + researcher-guidelines These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst new file mode 100644 index 000000000000..afc944e0e898 --- /dev/null +++ b/Documentation/process/researcher-guidelines.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _researcher_guidelines: + +Researcher Guidelines ++++++++++++++++++++++ + +The Linux kernel community welcomes transparent research on the Linux +kernel, the activities involved in producing it, and any other byproducts +of its development. Linux benefits greatly from this kind of research, and +most aspects of Linux are driven by research in one form or another. + +The community greatly appreciates if researchers can share preliminary +findings before making their results public, especially if such research +involves security. Getting involved early helps both improve the quality +of research and ability for Linux to improve from it. In any case, +sharing open access copies of the published research with the community +is recommended. + +This document seeks to clarify what the Linux kernel community considers +acceptable and non-acceptable practices when conducting such research. At +the very least, such research and related activities should follow +standard research ethics rules. For more background on research ethics +generally, ethics in technology, and research of developer communities +in particular, see: + +* `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_ +* `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_ +* `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_ + +The Linux kernel community expects that everyone interacting with the +project is participating in good faith to make Linux better. Research on +any publicly-available artifact (including, but not limited to source +code) produced by the Linux kernel community is welcome, though research +on developers must be distinctly opt-in. + +Passive research that is based entirely on publicly available sources, +including posts to public mailing lists and commits to public +repositories, is clearly permissible. Though, as with any research, +standard ethics must still be followed. + +Active research on developer behavior, however, must be done with the +explicit agreement of, and full disclosure to, the individual developers +involved. Developers cannot be interacted with/experimented on without +consent; this, too, is standard research ethics. + +To help clarify: sending patches to developers *is* interacting +with them, but they have already consented to receiving *good faith +contributions*. Sending intentionally flawed/vulnerable patches or +contributing misleading information to discussions is not consented +to. Such communication can be damaging to the developer (e.g. draining +time, effort, and morale) and damaging to the project by eroding +the entire developer community's trust in the contributor (and the +contributor's organization as a whole), undermining efforts to provide +constructive feedback to contributors, and putting end users at risk of +software flaws. + +Participation in the development of Linux itself by researchers, as +with anyone, is welcomed and encouraged. Research into Linux code is +a common practice, especially when it comes to developing or running +analysis tools that produce actionable results. + +When engaging with the developer community, sending a patch has +traditionally been the best way to make an impact. Linux already has +plenty of known bugs -- what's much more helpful is having vetted fixes. +Before contributing, carefully read the appropriate documentation: + +* Documentation/process/development-process.rst +* Documentation/process/submitting-patches.rst +* Documentation/admin-guide/reporting-issues.rst +* Documentation/admin-guide/security-bugs.rst + +Then send a patch (including a commit log with all the details listed +below) and follow up on any feedback from other developers. + +When sending patches produced from research, the commit logs should +contain at least the following details, so that developers have +appropriate context for understanding the contribution. Answer: + +* What is the specific problem that has been found? +* How could the problem be reached on a running system? +* What effect would encountering the problem have on the system? +* How was the problem found? Specifically include details about any + testing, static or dynamic analysis programs, and any other tools or + methods used to perform the work. +* Which version of Linux was the problem found on? Using the most recent + release or a recent linux-next branch is strongly preferred (see + Documentation/process/howto.rst). +* What was changed to fix the problem, and why it is believed to be correct? +* How was the change build tested and run-time tested? +* What prior commit does this change fix? This should go in a "Fixes:" + tag as the documentation describes. +* Who else has reviewed this patch? This should go in appropriate + "Reviewed-by:" tags; see below. + +For example:: + + From: Author <author@email> + Subject: [PATCH] drivers/foo_bar: Add missing kfree() + + The error path in foo_bar driver does not correctly free the allocated + struct foo_bar_info. This can happen if the attached foo_bar device + rejects the initialization packets sent during foo_bar_probe(). This + would result in a 64 byte slab memory leak once per device attach, + wasting memory resources over time. + + This flaw was found using an experimental static analysis tool we are + developing, LeakMagic[1], which reported the following warning when + analyzing the v5.15 kernel release: + + path/to/foo_bar.c:187: missing kfree() call? + + Add the missing kfree() to the error path. No other references to + this memory exist outside the probe function, so this is the only + place it can be freed. + + x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC + 11.2 show no new warnings, and LeakMagic no longer warns about this + code path. As we don't have a FooBar device to test with, no runtime + testing was able to be performed. + + [1] https://url/to/leakmagic/details + + Reported-by: Researcher <researcher@email> + Fixes: aaaabbbbccccdddd ("Introduce support for FooBar") + Signed-off-by: Author <author@email> + Reviewed-by: Reviewer <reviewer@email> + +If you are a first time contributor it is recommended that the patch +itself be vetted by others privately before being posted to public lists. +(This is required if you have been explicitly told your patches need +more careful internal review.) These people are expected to have their +"Reviewed-by" tag included in the resulting patch. Finding another +developer familiar with Linux contribution, especially within your own +organization, and having them help with reviews before sending them to +the public mailing lists tends to significantly improve the quality of the +resulting patches, and there by reduces the burden on other developers. + +If no one can be found to internally review patches and you need +help finding such a person, or if you have any other questions +related to this document and the developer community's expectations, +please reach out to the private Technical Advisory Board mailing list: +<tech-board@lists.linux-foundation.org>. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 6b3aaed66fba..fb496b2ebfd3 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -271,25 +271,6 @@ least a notification of the change, so that some information makes its way into the manual pages. User-space API changes should also be copied to linux-api@vger.kernel.org. -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. - -Trivial patches must qualify for one of the following rules: - -- Spelling fixes in documentation -- Spelling fixes for errors which could break :manpage:`grep(1)` -- Warning fixes (cluttering with useless warnings is bad) -- Compilation fixes (only if they are actually correct) -- Runtime fixes (only if they actually fix things) -- Removing use of deprecated functions/macros -- Contact detail and documentation fixes -- Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) -- Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - No MIME, no links, no compression, no attachments. Just plain text ------------------------------------------------------------------- @@ -514,7 +495,8 @@ Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: The Reported-by tag gives credit to people who find bugs and report them and it hopefully inspires them to help us again in the future. Please note that if the bug was reported in private, then ask for permission first before using the -Reported-by tag. +Reported-by tag. The tag is intended for bugs; please do not use it to credit +feature requests. A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/riscv/vm-layout.rst index b7f98930d38d..1bd687b97104 100644 --- a/Documentation/riscv/vm-layout.rst +++ b/Documentation/riscv/vm-layout.rst @@ -47,12 +47,12 @@ RISC-V Linux Kernel SV39 | Kernel-space virtual memory, shared between all processes: ____________________________________________________________|___________________________________________________________ | | | | - ffffffc000000000 | -256 GB | ffffffc7ffffffff | 32 GB | kasan - ffffffcefee00000 | -196 GB | ffffffcefeffffff | 2 MB | fixmap - ffffffceff000000 | -196 GB | ffffffceffffffff | 16 MB | PCI io - ffffffcf00000000 | -196 GB | ffffffcfffffffff | 4 GB | vmemmap - ffffffd000000000 | -192 GB | ffffffdfffffffff | 64 GB | vmalloc/ioremap space - ffffffe000000000 | -128 GB | ffffffff7fffffff | 124 GB | direct mapping of all physical memory + ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB | fixmap + ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB | PCI io + ffffffc700000000 | -228 GB | ffffffc7ffffffff | 4 GB | vmemmap + ffffffc800000000 | -224 GB | ffffffd7ffffffff | 64 GB | vmalloc/ioremap space + ffffffd800000000 | -160 GB | fffffff6ffffffff | 124 GB | direct mapping of all physical memory + fffffff700000000 | -36 GB | fffffffeffffffff | 32 GB | kasan __________________|____________|__________________|_________|____________________________________________________________ | | diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst index 88900aabdbf7..b430d856056a 100644 --- a/Documentation/scheduler/index.rst +++ b/Documentation/scheduler/index.rst @@ -14,9 +14,11 @@ Linux Scheduler sched-domains sched-capacity sched-energy + schedutil sched-nice-design sched-rt-group sched-stats + sched-debug text_files diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index 173c14110c85..f166b182ff95 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -74,7 +74,6 @@ Quota, period and burst are managed within the cpu subsystem via cgroupfs. to cgroup v1. For cgroup v2, see :ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2-cpu>`. -- cpu.cfs_quota_us: the total available run-time within a period (in - cpu.cfs_quota_us: run-time replenished within a period (in microseconds) - cpu.cfs_period_us: the length of a period (in microseconds) - cpu.stat: exports throttling statistics [explained further below] @@ -135,7 +134,7 @@ cpu.stat: of the group have been throttled. - nr_bursts: Number of periods burst occurs. - burst_time: Cumulative wall-time (in nanoseconds) that any CPUs has used - above quota in respective periods + above quota in respective periods. This interface is read-only. @@ -238,7 +237,7 @@ Examples additionally, in case accumulation has been done. With 50ms period, 20ms quota will be equivalent to 40% of 1 CPU. - And 10ms burst will be equivalent to 20% of 1 CPU. + And 10ms burst will be equivalent to 20% of 1 CPU:: # echo 20000 > cpu.cfs_quota_us /* quota = 20ms */ # echo 50000 > cpu.cfs_period_us /* period = 50ms */ diff --git a/Documentation/scheduler/sched-debug.rst b/Documentation/scheduler/sched-debug.rst new file mode 100644 index 000000000000..4d3d24f2a439 --- /dev/null +++ b/Documentation/scheduler/sched-debug.rst @@ -0,0 +1,54 @@ +================= +Scheduler debugfs +================= + +Booting a kernel with CONFIG_SCHED_DEBUG=y will give access to +scheduler specific debug files under /sys/kernel/debug/sched. Some of +those files are described below. + +numa_balancing +============== + +`numa_balancing` directory is used to hold files to control NUMA +balancing feature. If the system overhead from the feature is too +high then the rate the kernel samples for NUMA hinting faults may be +controlled by the `scan_period_min_ms, scan_delay_ms, +scan_period_max_ms, scan_size_mb` files. + + +scan_period_min_ms, scan_delay_ms, scan_period_max_ms, scan_size_mb +------------------------------------------------------------------- + +Automatic NUMA balancing scans tasks address space and unmaps pages to +detect if pages are properly placed or if the data should be migrated to a +memory node local to where the task is running. Every "scan delay" the task +scans the next "scan size" number of pages in its address space. When the +end of the address space is reached the scanner restarts from the beginning. + +In combination, the "scan delay" and "scan size" determine the scan rate. +When "scan delay" decreases, the scan rate increases. The scan delay and +hence the scan rate of every task is adaptive and depends on historical +behaviour. If pages are properly placed then the scan delay increases, +otherwise the scan delay decreases. The "scan size" is not adaptive but +the higher the "scan size", the higher the scan rate. + +Higher scan rates incur higher system overhead as page faults must be +trapped and potentially data must be migrated. However, the higher the scan +rate, the more quickly a tasks memory is migrated to a local node if the +workload pattern changes and minimises performance impact due to remote +memory accesses. These files control the thresholds for scan delays and +the number of pages scanned. + +``scan_period_min_ms`` is the minimum time in milliseconds to scan a +tasks virtual memory. It effectively controls the maximum scanning +rate for each task. + +``scan_delay_ms`` is the starting "scan delay" used for a task when it +initially forks. + +``scan_period_max_ms`` is the maximum time in milliseconds to scan a +tasks virtual memory. It effectively controls the minimum scanning +rate for each task. + +``scan_size_mb`` is how many megabytes worth of pages are scanned for +a given scan. diff --git a/Documentation/scheduler/sched-domains.rst b/Documentation/scheduler/sched-domains.rst index 84dcdcd2911c..e57ad28301bd 100644 --- a/Documentation/scheduler/sched-domains.rst +++ b/Documentation/scheduler/sched-domains.rst @@ -37,10 +37,10 @@ rebalancing event for the current runqueue has arrived. The actual load balancing workhorse, run_rebalance_domains()->rebalance_domains(), is then run in softirq context (SCHED_SOFTIRQ). -The latter function takes two arguments: the current CPU and whether it was idle -at the time the scheduler_tick() happened and iterates over all sched domains -our CPU is on, starting from its base domain and going up the ->parent chain. -While doing that, it checks to see if the current domain has exhausted its +The latter function takes two arguments: the runqueue of current CPU and whether +the CPU was idle at the time the scheduler_tick() happened and iterates over all +sched domains our CPU is on, starting from its base domain and going up the ->parent +chain. While doing that, it checks to see if the current domain has exhausted its rebalance interval. If so, it runs load_balance() on that domain. It then checks the parent sched_domain (if it exists), and the parent of the parent and so forth. diff --git a/Documentation/scheduler/schedutil.txt b/Documentation/scheduler/schedutil.rst index 78f6b91e2291..32c7d69fc86c 100644 --- a/Documentation/scheduler/schedutil.txt +++ b/Documentation/scheduler/schedutil.rst @@ -1,11 +1,15 @@ +========= +Schedutil +========= +.. note:: -NOTE; all this assumes a linear relation between frequency and work capacity, -we know this is flawed, but it is the best workable approximation. + All this assumes a linear relation between frequency and work capacity, + we know this is flawed, but it is the best workable approximation. PELT (Per Entity Load Tracking) -------------------------------- +=============================== With PELT we track some metrics across the various scheduler entities, from individual tasks to task-group slices to CPU runqueues. As the basis for this @@ -38,8 +42,8 @@ while 'runnable' will increase to reflect the amount of contention. For more detail see: kernel/sched/pelt.c -Frequency- / CPU Invariance ---------------------------- +Frequency / CPU Invariance +========================== Because consuming the CPU for 50% at 1GHz is not the same as consuming the CPU for 50% at 2GHz, nor is running 50% on a LITTLE CPU the same as running 50% on @@ -47,7 +51,7 @@ a big CPU, we allow architectures to scale the time delta with two ratios, one Dynamic Voltage and Frequency Scaling (DVFS) ratio and one microarch ratio. For simple DVFS architectures (where software is in full control) we trivially -compute the ratio as: +compute the ratio as:: f_cur r_dvfs := ----- @@ -55,7 +59,7 @@ compute the ratio as: For more dynamic systems where the hardware is in control of DVFS we use hardware counters (Intel APERF/MPERF, ARMv8.4-AMU) to provide us this ratio. -For Intel specifically, we use: +For Intel specifically, we use:: APERF f_cur := ----- * P0 @@ -87,7 +91,7 @@ For more detail see: UTIL_EST / UTIL_EST_FASTUP --------------------------- +========================== Because periodic tasks have their averages decayed while they sleep, even though when running their expected utilization will be the same, they suffer a @@ -106,7 +110,7 @@ For more detail see: kernel/sched/fair.c:util_est_dequeue() UCLAMP ------- +====== It is possible to set effective u_min and u_max clamps on each CFS or RT task; the runqueue keeps an max aggregate of these clamps for all running tasks. @@ -115,7 +119,7 @@ For more detail see: include/uapi/linux/sched/types.h Schedutil / DVFS ----------------- +================ Every time the scheduler load tracking is updated (task wakeup, task migration, time progression) we call out to schedutil to update the hardware @@ -123,7 +127,7 @@ DVFS state. The basis is the CPU runqueue's 'running' metric, which per the above it is the frequency invariant utilization estimate of the CPU. From this we compute -a desired frequency like: +a desired frequency like:: max( running, util_est ); if UTIL_EST u_cfs := { running; otherwise @@ -135,7 +139,7 @@ a desired frequency like: f_des := min( f_max, 1.25 u * f_max ) -XXX IO-wait; when the update is due to a task wakeup from IO-completion we +XXX IO-wait: when the update is due to a task wakeup from IO-completion we boost 'u' above. This frequency is then used to select a P-state/OPP or directly munged into a @@ -153,7 +157,7 @@ For more information see: kernel/sched/cpufreq_schedutil.c NOTES ------ +===== - On low-load scenarios, where DVFS is most relevant, the 'running' numbers will closely reflect utilization. diff --git a/Documentation/security/SCTP.rst b/Documentation/security/SCTP.rst index d5fd6ccc3dcb..b73eb764a001 100644 --- a/Documentation/security/SCTP.rst +++ b/Documentation/security/SCTP.rst @@ -15,10 +15,7 @@ For security module support, three SCTP specific hooks have been implemented:: security_sctp_assoc_request() security_sctp_bind_connect() security_sctp_sk_clone() - -Also the following security hook has been utilised:: - - security_inet_conn_established() + security_sctp_assoc_established() The usage of these hooks are described below with the SELinux implementation described in the `SCTP SELinux Support`_ chapter. @@ -122,11 +119,12 @@ calls **sctp_peeloff**\(3). @newsk - pointer to new sock structure. -security_inet_conn_established() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Called when a COOKIE ACK is received:: +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Called when a COOKIE ACK is received, and the peer secid will be +saved into ``@asoc->peer_secid`` for client:: - @sk - pointer to sock structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of the COOKIE ACK packet. @@ -134,7 +132,7 @@ Security Hooks used for Association Establishment ------------------------------------------------- The following diagram shows the use of ``security_sctp_bind_connect()``, -``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when +``security_sctp_assoc_request()``, ``security_sctp_assoc_established()`` when establishing an association. :: @@ -172,7 +170,7 @@ establishing an association. <------------------------------------------- COOKIE ACK | | sctp_sf_do_5_1E_ca | - Call security_inet_conn_established() | + Call security_sctp_assoc_established() | to set the peer label. | | | | If SCTP_SOCKET_TCP or peeled off @@ -198,7 +196,7 @@ hooks with the SELinux specifics expanded below:: security_sctp_assoc_request() security_sctp_bind_connect() security_sctp_sk_clone() - security_inet_conn_established() + security_sctp_assoc_established() security_sctp_assoc_request() @@ -271,12 +269,12 @@ sockets sid and peer sid to that contained in the ``@asoc sid`` and @newsk - pointer to new sock structure. -security_inet_conn_established() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Called when a COOKIE ACK is received where it sets the connection's peer sid to that in ``@skb``:: - @sk - pointer to sock structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of the COOKIE ACK packet. diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 80d5a5af62a1..f614dad7de12 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -107,12 +107,13 @@ Encrypted Keys -------------- Encrypted keys do not depend on a trust source, and are faster, as they use AES -for encryption/decryption. New keys are created from kernel-generated random -numbers, and are encrypted/decrypted using a specified ‘master’ key. The -‘master’ key can either be a trusted-key or user-key type. The main disadvantage -of encrypted keys is that if they are not rooted in a trusted key, they are only -as secure as the user key encrypting them. The master user key should therefore -be loaded in as secure a way as possible, preferably early in boot. +for encryption/decryption. New keys are created either from kernel-generated +random numbers or user-provided decrypted data, and are encrypted/decrypted +using a specified ‘master’ key. The ‘master’ key can either be a trusted-key or +user-key type. The main disadvantage of encrypted keys is that if they are not +rooted in a trusted key, they are only as secure as the user key encrypting +them. The master user key should therefore be loaded in as secure a way as +possible, preferably early in boot. Usage @@ -199,6 +200,8 @@ Usage:: keyctl add encrypted name "new [format] key-type:master-key-name keylen" ring + keyctl add encrypted name "new [format] key-type:master-key-name keylen + decrypted-data" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name" @@ -303,6 +306,16 @@ Load an encrypted key "evm" from saved blob:: 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc +Instantiate an encrypted key "evm" using user-provided decrypted data:: + + $ keyctl add encrypted evm "new default user:kmk 32 `cat evm_decrypted_data.blob`" @u + 794890253 + + $ keyctl print 794890253 + default user:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382d + bbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0247 + 17c64 5972dcb82ab2dde83376d82b2e3c09ffc + Other uses for trusted and encrypted keys, such as for disk and file encryption are anticipated. In particular the new format 'ecryptfs' has been defined in order to use encrypted keys to mount an eCryptfs filesystem. More details diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index f584fb74b4ff..910668e665cb 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -81,8 +81,7 @@ of the kernel, gaining the protection of the kernel's strict memory permissions as described above. For variables that are initialized once at ``__init`` time, these can -be marked with the (new and under development) ``__ro_after_init`` -attribute. +be marked with the ``__ro_after_init`` attribute. What remains are variables that are updated rarely (e.g. GDT). These will need another infrastructure (similar to the temporary exceptions diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index 459ec5b29d68..f6f2b941a5d6 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -1,14 +1,14 @@ /* -*- coding: utf-8; mode: css -*- * * Sphinx HTML theme customization: read the doc - * + * Please don't add any color definition here, as the theme should + * work for both normal and dark modes. */ /* Improve contrast and increase size for easier reading. */ body { font-family: serif; - color: black; font-size: 100%; } @@ -16,17 +16,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { font-family: sans-serif; } -.wy-menu-vertical li.current a { - color: #505050; -} - -.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { - color: #303030; -} - div[class^="highlight"] pre { font-family: monospace; - color: black; font-size: 100%; } @@ -104,13 +95,10 @@ div[class^="highlight"] pre { /* Menu selection and keystrokes */ span.menuselection { - color: blue; font-family: "Courier New", Courier, monospace } code.kbd, code.kbd span { - color: white; - background-color: darkblue; font-weight: bold; font-family: "Courier New", Courier, monospace } diff --git a/Documentation/sphinx-static/theme_rtd_colors.css b/Documentation/sphinx-static/theme_rtd_colors.css new file mode 100644 index 000000000000..55b6e1c3664b --- /dev/null +++ b/Documentation/sphinx-static/theme_rtd_colors.css @@ -0,0 +1,37 @@ +/* -*- coding: utf-8; mode: css -*- + * + * Sphinx HTML theme customization: color settings for RTD (non-dark) theme + * + */ + +/* Improve contrast and increase size for easier reading. */ + +body { + color: black; +} + +.wy-menu-vertical li.current a { + color: #505050; +} + +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { + color: #303030; +} + +div[class^="highlight"] pre { + color: black; +} + +@media screen { + + /* Menu selection and keystrokes */ + + span.menuselection { + color: blue; + } + + code.kbd, code.kbd span { + color: white; + background-color: darkblue; + } +} diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index acf5473002f3..cc348b219fca 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -271,19 +271,30 @@ def get_c_namespace(app, docname): def auto_markup(app, doctree, name): global c_namespace c_namespace = get_c_namespace(app, name) + def text_but_not_a_reference(node): + # The nodes.literal test catches ``literal text``, its purpose is to + # avoid adding cross-references to functions that have been explicitly + # marked with cc:func:. + if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal): + return False + + child_of_reference = False + parent = node.parent + while parent: + if isinstance(parent, nodes.Referential): + child_of_reference = True + break + parent = parent.parent + return not child_of_reference + # # This loop could eventually be improved on. Someday maybe we # want a proper tree traversal with a lot of awareness of which # kinds of nodes to prune. But this works well for now. # - # The nodes.literal test catches ``literal text``, its purpose is to - # avoid adding cross-references to functions that have been explicitly - # marked with cc:func:. - # for para in doctree.traverse(nodes.paragraph): - for node in para.traverse(nodes.Text): - if not isinstance(node.parent, nodes.literal): - node.parent.replace(node, markup_refs(name, app, node)) + for node in para.traverse(condition=text_but_not_a_reference): + node.parent.replace(node, markup_refs(name, app, node)) def setup(app): app.connect('doctree-resolved', auto_markup) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index efe760e410c4..4392b3cb4020 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -104,7 +104,7 @@ class KernelCmd(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index c91ea2b27697..8138d69a6987 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -106,7 +106,7 @@ class KernelFeat(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty new file mode 100644 index 000000000000..9d0204dc38be --- /dev/null +++ b/Documentation/sphinx/kerneldoc-preamble.sty @@ -0,0 +1,226 @@ +% -*- coding: utf-8 -*- +% SPDX-License-Identifier: GPL-2.0 +% +% LaTeX preamble for "make latexdocs" or "make pdfdocs" including: +% - TOC width settings +% - Setting of tabulary (\tymin) +% - Headheight setting for fancyhdr +% - Fontfamily settings for CJK (Chinese, Japanese, and Korean) translations +% +% Note on the suffix of .sty: +% This is not implemented as a LaTeX style file, but as a file containing +% plain LaTeX code to be included into preamble. +% ".sty" is chosen because ".tex" would cause the build scripts to confuse +% this file with a LaTeX main file. +% +% Copyright (C) 2022 Akira Yokosawa + +% Custom width parameters for TOC +% - Redefine low-level commands defined in report.cls. +% - Indent of 2 chars is preserved for ease of comparison. +% Summary of changes from default params: +% Width of page number (\@pnumwidth): 1.55em -> 2.7em +% Width of chapter number: 1.5em -> 1.8em +% Indent of section number: 1.5em -> 1.8em +% Width of section number: 2.6em -> 3.2em +% Indent of sebsection number: 4.1em -> 5em +% Width of subsection number: 3.5em -> 4.3em +% +% These params can have 4 digit page counts, 2 digit chapter counts, +% section counts of 4 digits + 1 period (e.g., 18.10), and subsection counts +% of 5 digits + 2 periods (e.g., 18.7.13). +\makeatletter +%% Redefine \@pnumwidth (page number width) +\renewcommand*\@pnumwidth{2.7em} +%% Redefine \l@chapter (chapter list entry) +\renewcommand*\l@chapter[2]{% + \ifnum \c@tocdepth >\m@ne + \addpenalty{-\@highpenalty}% + \vskip 1.0em \@plus\p@ + \setlength\@tempdima{1.8em}% + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \bfseries + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil + \nobreak\hb@xt@\@pnumwidth{\hss #2% + \kern-\p@\kern\p@}\par + \penalty\@highpenalty + \endgroup + \fi} +%% Redefine \l@section and \l@subsection +\renewcommand*\l@section{\@dottedtocline{1}{1.8em}{3.2em}} +\renewcommand*\l@subsection{\@dottedtocline{2}{5em}{4.3em}} +\makeatother +%% Sphinx < 1.8 doesn't have \sphinxtableofcontentshook +\providecommand{\sphinxtableofcontentshook}{} +%% Undefine it for compatibility with Sphinx 1.7.9 +\renewcommand{\sphinxtableofcontentshook}{} % Empty the hook + +% Prevent column squeezing of tabulary. \tymin is set by Sphinx as: +% \setlength{\tymin}{3\fontcharwd\font`0 } +% , which is too short. +\setlength{\tymin}{20em} + +% Adjust \headheight for fancyhdr +\addtolength{\headheight}{1.6pt} +\addtolength{\topmargin}{-1.6pt} + +% Translations have Asian (CJK) characters which are only displayed if +% xeCJK is used +\IfFontExistsTF{Noto Sans CJK SC}{ + % Load xeCJK when CJK font is available + \usepackage{xeCJK} + % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits + % its emulation. + % Select KR variant at the beginning of each document so that quotation + % and apostorph symbols of half-width is used in TOC of Latin documents. + \IfFontExistsTF{Noto Serif CJK KR}{ + \setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant] + }{ + \setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant] + } + \setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant] + \setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant] + % Teach xeCJK of half-width symbols + \xeCJKDeclareCharClass{HalfLeft}{`“,`‘} + \xeCJKDeclareCharClass{HalfRight}{`â€,`’} + % CJK Language-specific font choices + %% for Simplified Chinese + \IfFontExistsTF{Noto Serif CJK SC}{ + \newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant] + \newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant] + }{ + \newCJKfontfamily[SCmain]\scmain{Noto Sans CJK SC}[AutoFakeSlant] + \newCJKfontfamily[SCserif]\scserif{Noto Sans CJK SC}[AutoFakeSlant] + } + \newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant] + \newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant] + %% for Traditional Chinese + \IfFontExistsTF{Noto Serif CJK TC}{ + \newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant] + \newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant] + }{ + \newCJKfontfamily[TCmain]\tcmain{Noto Sans CJK TC}[AutoFakeSlant] + \newCJKfontfamily[TCserif]\tcserif{Noto Sans CJK TC}[AutoFakeSlant] + } + \newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant] + \newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant] + %% for Korean + \IfFontExistsTF{Noto Serif CJK KR}{ + \newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant] + \newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant] + }{ + \newCJKfontfamily[KRmain]\krmain{Noto Sans CJK KR}[AutoFakeSlant] + \newCJKfontfamily[KRserif]\krserif{Noto Sans CJK KR}[AutoFakeSlant] + } + \newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant] + \newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant] + %% for Japanese + \IfFontExistsTF{Noto Serif CJK JP}{ + \newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant] + \newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant] + }{ + \newCJKfontfamily[JPmain]\jpmain{Noto Sans CJK JP}[AutoFakeSlant] + \newCJKfontfamily[JPserif]\jpserif{Noto Sans CJK JP}[AutoFakeSlant] + } + \newCJKfontfamily[JPsans]\jpsans{Noto Sans CJK JP}[AutoFakeSlant] + \newCJKfontfamily[JPmono]\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant] + % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support) + \providecommand{\onehalfspacing}{} + \providecommand{\singlespacing}{} + % Define custom macros to on/off CJK + %% One and half spacing for CJK contents + \newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing} + \newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing} + % Define custom macros for switching CJK font setting + %% for Simplified Chinese + \newcommand{\kerneldocBeginSC}{% + \begingroup% + \scmain% + \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in SC + \xeCJKDeclareCharClass{FullRight}{`â€,`’}% Full-width in SC + \renewcommand{\CJKrmdefault}{SCserif}% + \renewcommand{\CJKsfdefault}{SCsans}% + \renewcommand{\CJKttdefault}{SCmono}% + \xeCJKsetup{CJKspace = false}% gobble white spaces by ' ' + % For CJK ascii-art alignment + \setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]% + } + \newcommand{\kerneldocEndSC}{\endgroup} + %% for Traditional Chinese + \newcommand{\kerneldocBeginTC}{% + \begingroup% + \tcmain% + \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in TC + \xeCJKDeclareCharClass{FullRight}{`â€,`’}% Full-width in TC + \renewcommand{\CJKrmdefault}{TCserif}% + \renewcommand{\CJKsfdefault}{TCsans}% + \renewcommand{\CJKttdefault}{TCmono}% + \xeCJKsetup{CJKspace = false}% gobble white spaces by ' ' + % For CJK ascii-art alignment + \setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]% + } + \newcommand{\kerneldocEndTC}{\endgroup} + %% for Korean + \newcommand{\kerneldocBeginKR}{% + \begingroup% + \krmain% + \renewcommand{\CJKrmdefault}{KRserif}% + \renewcommand{\CJKsfdefault}{KRsans}% + \renewcommand{\CJKttdefault}{KRmono}% + % \xeCJKsetup{CJKspace = true} % true by default + % For CJK ascii-art alignment (still misaligned for Hangul) + \setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]% + } + \newcommand{\kerneldocEndKR}{\endgroup} + %% for Japanese + \newcommand{\kerneldocBeginJP}{% + \begingroup% + \jpmain% + \renewcommand{\CJKrmdefault}{JPserif}% + \renewcommand{\CJKsfdefault}{JPsans}% + \renewcommand{\CJKttdefault}{JPmono}% + \xeCJKsetup{CJKspace = false}% gobble white space by ' ' + % For CJK ascii-art alignment + \setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]% + } + \newcommand{\kerneldocEndJP}{\endgroup} + + % Single spacing in literal blocks + \fvset{baselinestretch=1} + % To customize \sphinxtableofcontents + \usepackage{etoolbox} + % Inactivate CJK after tableofcontents + \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{} + \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC +}{ % No CJK font found + % Custom macros to on/off CJK and switch CJK fonts (Dummy) + \newcommand{\kerneldocCJKon}{} + \newcommand{\kerneldocCJKoff}{} + %% By defining \kerneldocBegin(SC|TC|KR|JP) as commands with an argument + %% and ignore the argument (#1) in their definitions, whole contents of + %% CJK chapters can be ignored. + \newcommand{\kerneldocBeginSC}[1]{% + %% Put a note on missing CJK fonts in place of zh_CN translation. + \begin{sphinxadmonition}{note}{Note on missing fonts:} + Translations of Simplified Chinese (zh\_CN), Traditional Chinese + (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped + due to the lack of suitable font families. + + If you want them, please install ``Noto Sans CJK'' font families + by following instructions from + \sphinxcode{./scripts/sphinx-pre-install}. + Having optional ``Noto Serif CJK'' font families will improve + the looks of those translations. + \end{sphinxadmonition}} + \newcommand{\kerneldocEndSC}{} + \newcommand{\kerneldocBeginTC}[1]{} + \newcommand{\kerneldocEndTC}{} + \newcommand{\kerneldocBeginKR}[1]{} + \newcommand{\kerneldocEndKR}{} + \newcommand{\kerneldocBeginJP}[1]{} + \newcommand{\kerneldocEndJP}{} +} diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index 3c78828330be..24d2b2addcce 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -31,10 +31,13 @@ u""" * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not available, the DOT language is inserted as literal-block. + For conversion to PDF, ``rsvg-convert(1)`` of librsvg + (https://gitlab.gnome.org/GNOME/librsvg) is used when available. * SVG to PDF: To generate PDF, you need at least one of this tools: - ``convert(1)``: ImageMagick (https://www.imagemagick.org) + - ``inkscape(1)``: Inkscape (https://inkscape.org/) List of customizations: @@ -49,6 +52,7 @@ import os from os import path import subprocess from hashlib import sha1 +import re from docutils import nodes from docutils.statemachine import ViewList from docutils.parsers.rst import directives @@ -109,10 +113,20 @@ def pass_handle(self, node): # pylint: disable=W0613 # Graphviz's dot(1) support dot_cmd = None +# dot(1) -Tpdf should be used +dot_Tpdf = False # ImageMagick' convert(1) support convert_cmd = None +# librsvg's rsvg-convert(1) support +rsvg_convert_cmd = None + +# Inkscape's inkscape(1) support +inkscape_cmd = None +# Inkscape prior to 1.0 uses different command options +inkscape_ver_one = False + def setup(app): # check toolchain first @@ -160,23 +174,62 @@ def setupTools(app): This function is called once, when the builder is initiated. """ - global dot_cmd, convert_cmd # pylint: disable=W0603 + global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd # pylint: disable=W0603 + global inkscape_cmd, inkscape_ver_one # pylint: disable=W0603 kernellog.verbose(app, "kfigure: check installed tools ...") dot_cmd = which('dot') convert_cmd = which('convert') + rsvg_convert_cmd = which('rsvg-convert') + inkscape_cmd = which('inkscape') if dot_cmd: kernellog.verbose(app, "use dot(1) from: " + dot_cmd) + + try: + dot_Thelp_list = subprocess.check_output([dot_cmd, '-Thelp'], + stderr=subprocess.STDOUT) + except subprocess.CalledProcessError as err: + dot_Thelp_list = err.output + pass + + dot_Tpdf_ptn = b'pdf' + dot_Tpdf = re.search(dot_Tpdf_ptn, dot_Thelp_list) else: kernellog.warn(app, "dot(1) not found, for better output quality install " "graphviz from https://www.graphviz.org") - if convert_cmd: - kernellog.verbose(app, "use convert(1) from: " + convert_cmd) + if inkscape_cmd: + kernellog.verbose(app, "use inkscape(1) from: " + inkscape_cmd) + inkscape_ver = subprocess.check_output([inkscape_cmd, '--version'], + stderr=subprocess.DEVNULL) + ver_one_ptn = b'Inkscape 1' + inkscape_ver_one = re.search(ver_one_ptn, inkscape_ver) + convert_cmd = None + rsvg_convert_cmd = None + dot_Tpdf = False + else: - kernellog.warn(app, - "convert(1) not found, for SVG to PDF conversion install " - "ImageMagick (https://www.imagemagick.org)") + if convert_cmd: + kernellog.verbose(app, "use convert(1) from: " + convert_cmd) + else: + kernellog.warn(app, + "Neither inkscape(1) nor convert(1) found.\n" + "For SVG to PDF conversion, " + "install either Inkscape (https://inkscape.org/) (preferred) or\n" + "ImageMagick (https://www.imagemagick.org)") + + if rsvg_convert_cmd: + kernellog.verbose(app, "use rsvg-convert(1) from: " + rsvg_convert_cmd) + kernellog.verbose(app, "use 'dot -Tsvg' and rsvg-convert(1) for DOT -> PDF conversion") + dot_Tpdf = False + else: + kernellog.verbose(app, + "rsvg-convert(1) not found.\n" + " SVG rendering of convert(1) is done by ImageMagick-native renderer.") + if dot_Tpdf: + kernellog.verbose(app, "use 'dot -Tpdf' for DOT -> PDF conversion") + else: + kernellog.verbose(app, "use 'dot -Tsvg' and convert(1) for DOT -> PDF conversion") # integrate conversion tools @@ -242,7 +295,7 @@ def convert_image(img_node, translator, src_fname=None): elif in_ext == '.svg': if translator.builder.format == 'latex': - if convert_cmd is None: + if not inkscape_cmd and convert_cmd is None: kernellog.verbose(app, "no SVG to PDF conversion available / include SVG raw.") img_node.replace_self(file2literal(src_fname)) @@ -266,7 +319,14 @@ def convert_image(img_node, translator, src_fname=None): if in_ext == '.dot': kernellog.verbose(app, 'convert DOT to: {out}/' + _name) - ok = dot2format(app, src_fname, dst_fname) + if translator.builder.format == 'latex' and not dot_Tpdf: + svg_fname = path.join(translator.builder.outdir, fname + '.svg') + ok1 = dot2format(app, src_fname, svg_fname) + ok2 = svg2pdf_by_rsvg(app, svg_fname, dst_fname) + ok = ok1 and ok2 + + else: + ok = dot2format(app, src_fname, dst_fname) elif in_ext == '.svg': kernellog.verbose(app, 'convert SVG to: {out}/' + _name) @@ -303,22 +363,70 @@ def dot2format(app, dot_fname, out_fname): return bool(exit_code == 0) def svg2pdf(app, svg_fname, pdf_fname): - """Converts SVG to PDF with ``convert(1)`` command. + """Converts SVG to PDF with ``inkscape(1)`` or ``convert(1)`` command. - Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for - conversion. Returns ``True`` on success and ``False`` if an error occurred. + Uses ``inkscape(1)`` from Inkscape (https://inkscape.org/) or ``convert(1)`` + from ImageMagick (https://www.imagemagick.org) for conversion. + Returns ``True`` on success and ``False`` if an error occurred. * ``svg_fname`` pathname of the input SVG file with extension (``.svg``) * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``) """ cmd = [convert_cmd, svg_fname, pdf_fname] - # use stdout and stderr from parent - exit_code = subprocess.call(cmd) + cmd_name = 'convert(1)' + + if inkscape_cmd: + cmd_name = 'inkscape(1)' + if inkscape_ver_one: + cmd = [inkscape_cmd, '-o', pdf_fname, svg_fname] + else: + cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname] + + try: + warning_msg = subprocess.check_output(cmd, stderr=subprocess.STDOUT) + exit_code = 0 + except subprocess.CalledProcessError as err: + warning_msg = err.output + exit_code = err.returncode + pass + if exit_code != 0: kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + if warning_msg: + kernellog.warn(app, "Warning msg from %s: %s" + % (cmd_name, str(warning_msg, 'utf-8'))) + elif warning_msg: + kernellog.verbose(app, "Warning msg from %s (likely harmless):\n%s" + % (cmd_name, str(warning_msg, 'utf-8'))) + return bool(exit_code == 0) +def svg2pdf_by_rsvg(app, svg_fname, pdf_fname): + """Convert SVG to PDF with ``rsvg-convert(1)`` command. + + * ``svg_fname`` pathname of input SVG file, including extension ``.svg`` + * ``pdf_fname`` pathname of output PDF file, including extension ``.pdf`` + + Input SVG file should be the one generated by ``dot2format()``. + SVG -> PDF conversion is done by ``rsvg-convert(1)``. + + If ``rsvg-convert(1)`` is unavailable, fall back to ``svg2pdf()``. + + """ + + if rsvg_convert_cmd is None: + ok = svg2pdf(app, svg_fname, pdf_fname) + else: + cmd = [rsvg_convert_cmd, '--format=pdf', '-o', pdf_fname, svg_fname] + # use stdout and stderr from parent + exit_code = subprocess.call(cmd) + if exit_code != 0: + kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + ok = bool(exit_code == 0) + + return ok + # image handling # --------------------- diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst index 6312968acfe9..716f65d87d04 100644 --- a/Documentation/spi/pxa2xx.rst +++ b/Documentation/spi/pxa2xx.rst @@ -101,8 +101,6 @@ device. All fields are optional. u8 rx_threshold; u8 dma_burst_size; u32 timeout; - u8 enable_loopback; - void (*cs_control)(u32 command); }; The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are @@ -128,16 +126,6 @@ dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific slave device. Please note that the PXA2xx SSP 1 does not support trailing byte timeouts and must busy-wait any trailing bytes. -The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting -into internal loopback mode. In this mode the SSP controller internally -connects the SSPTX pin to the SSPRX pin. This is useful for initial setup -testing. - -The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific -function for asserting/deasserting a slave device chip select. If the field is -NULL, the pxa2xx_spi master controller driver assumes that the SSP port is -configured to use GPIO or SSPFRM instead. - NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the chipselect is dropped after each spi_transfer. Most devices need chip select asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor) @@ -152,30 +140,11 @@ field. Below is a sample configuration using the PXA255 NSSP. :: - /* Chip Select control for the CS8415A SPI slave device */ - static void cs8415a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(2) = GPIO_bit(2); - else - GPSR(2) = GPIO_bit(2); - } - - /* Chip Select control for the CS8405A SPI slave device */ - static void cs8405a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(3) = GPIO_bit(3); - else - GPSR(3) = GPIO_bit(3); - } - static struct pxa2xx_spi_chip cs8415a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8415a_cs_control, /* Use external chip select */ }; static struct pxa2xx_spi_chip cs8405a_chip_info = { @@ -183,7 +152,6 @@ field. Below is a sample configuration using the PXA255 NSSP. .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8405a_cs_control, /* Use external chip select */ }; static struct spi_board_info streetracer_spi_board_info[] __initdata = { diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst index f05dbc5ccdbc..369c657ba435 100644 --- a/Documentation/spi/spidev.rst +++ b/Documentation/spi/spidev.rst @@ -29,21 +29,49 @@ of the driver stack) that are not accessible to userspace. DEVICE CREATION, DRIVER BINDING =============================== -The simplest way to arrange to use this driver is to just list it in the -spi_board_info for a device as the driver it should use: the "modalias" -entry is "spidev", matching the name of the driver exposing this API. -Set up the other device characteristics (bits per word, SPI clocking, -chipselect polarity, etc) as usual, so you won't always need to override -them later. - -(Sysfs also supports userspace driven binding/unbinding of drivers to -devices. That mechanism might be supported here in the future.) - -When you do that, the sysfs node for the SPI device will include a child -device node with a "dev" attribute that will be understood by udev or mdev. -(Larger systems will have "udev". Smaller ones may configure "mdev" into -busybox; it's less featureful, but often enough.) For a SPI device with -chipselect C on bus B, you should see: + +The spidev driver contains lists of SPI devices that are supported for +the different hardware topology representations. + +The following are the SPI device tables supported by the spidev driver: + + - struct spi_device_id spidev_spi_ids[]: list of devices that can be + bound when these are defined using a struct spi_board_info with a + .modalias field matching one of the entries in the table. + + - struct of_device_id spidev_dt_ids[]: list of devices that can be + bound when these are defined using a Device Tree node that has a + compatible string matching one of the entries in the table. + + - struct acpi_device_id spidev_acpi_ids[]: list of devices that can + be bound when these are defined using a ACPI device object with a + _HID matching one of the entries in the table. + +You are encouraged to add an entry for your SPI device name to relevant +tables, if these don't already have an entry for the device. To do that, +post a patch for spidev to the linux-spi@vger.kernel.org mailing list. + +It used to be supported to define an SPI device using the "spidev" name. +For example, as .modalias = "spidev" or compatible = "spidev". But this +is no longer supported by the Linux kernel and instead a real SPI device +name as listed in one of the tables must be used. + +Not having a real SPI device name will lead to an error being printed and +the spidev driver failing to probe. + +Sysfs also supports userspace driven binding/unbinding of drivers to +devices that do not bind automatically using one of the tables above. +To make the spidev driver bind to such a device, use the following: + + echo spidev > /sys/bus/spi/devices/spiB.C/driver_override + echo spiB.C > /sys/bus/spi/drivers/spidev/bind + +When the spidev driver is bound to a SPI device, the sysfs node for the +device will include a child device node with a "dev" attribute that will +be understood by udev or mdev (udev replacement from BusyBox; it's less +featureful, but often enough). + +For a SPI device with chipselect C on bus B, you should see: /dev/spidevB.C ... character special device, major number 153 with diff --git a/Documentation/staging/tee.rst b/Documentation/staging/tee.rst index 3c63d8dcd61e..498343c7ab08 100644 --- a/Documentation/staging/tee.rst +++ b/Documentation/staging/tee.rst @@ -255,7 +255,7 @@ The following picture shows a high level overview of AMD-TEE:: +--------------------------+ +---------+--------------------+ At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the -CPU to PSP mailbox regsister to submit commands to the PSP. The format of the +CPU to PSP mailbox register to submit commands to the PSP. The format of the command buffer is opaque to the ASP driver. It's role is to submit commands to the secure processor and return results to AMD-TEE driver. The interface between AMD-TEE driver and AMD Secure Processor driver can be found in [6]. @@ -290,7 +290,7 @@ cancel_req driver callback is not supported by AMD-TEE. The GlobalPlatform TEE Client API [5] can be used by the user space (client) to talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening -a session, invoking commands and clossing session with TA. +a session, invoking commands and closing session with TA. References ========== diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index 20ad23a6c618..f8786be15183 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -184,16 +184,12 @@ There are situations in which idle CPUs cannot be permitted to enter either dyntick-idle mode or adaptive-tick mode, the most common being when that CPU has RCU callbacks pending. -The CONFIG_RCU_FAST_NO_HZ=y Kconfig option may be used to cause such CPUs -to enter dyntick-idle mode or adaptive-tick mode anyway. In this case, -a timer will awaken these CPUs every four jiffies in order to ensure -that the RCU callbacks are processed in a timely fashion. - -Another approach is to offload RCU callback processing to "rcuo" kthreads +Avoid this by offloading RCU callback processing to "rcuo" kthreads using the CONFIG_RCU_NOCB_CPU=y Kconfig option. The specific CPUs to offload may be selected using The "rcu_nocbs=" kernel boot parameter, which takes a comma-separated list of CPUs and CPU ranges, for example, -"1,3-5" selects CPUs 1, 3, 4, and 5. +"1,3-5" selects CPUs 1, 3, 4, and 5. Note that CPUs specified by +the "nohz_full" kernel boot parameter are also offloaded. The offloaded CPUs will never queue RCU callbacks, and therefore RCU never prevents offloaded CPUs from entering either dyntick-idle mode diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst new file mode 100644 index 000000000000..0bb1e61bdcc0 --- /dev/null +++ b/Documentation/tools/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Kernel tools +============ + +This book covers user-space tools that are shipped with the kernel source; +more additions are needed here: + +.. toctree:: + :maxdepth: 1 + + rtla/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/tools/rtla/Makefile b/Documentation/tools/rtla/Makefile new file mode 100644 index 000000000000..9f2b84af1a6c --- /dev/null +++ b/Documentation/tools/rtla/Makefile @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only +# Based on bpftool's Documentation Makefile + +INSTALL ?= install +RM ?= rm -f +RMDIR ?= rmdir --ignore-fail-on-non-empty + +PREFIX ?= /usr/share +MANDIR ?= $(PREFIX)/man +MAN1DIR = $(MANDIR)/man1 + +MAN1_RST = $(wildcard rtla*.rst) + +_DOC_MAN1 = $(patsubst %.rst,%.1,$(MAN1_RST)) +DOC_MAN1 = $(addprefix $(OUTPUT),$(_DOC_MAN1)) + +RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) +RST2MAN_OPTS += --verbose + +$(OUTPUT)%.1: %.rst +ifndef RST2MAN_DEP + $(error "rst2man not found, but required to generate man pages") +endif + rst2man $(RST2MAN_OPTS) $< > $@ + +man1: $(DOC_MAN1) +man: man1 + +clean: + $(RM) $(DOC_MAN1) + +install: man + $(INSTALL) -d -m 755 $(DESTDIR)$(MAN1DIR) + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(MAN1DIR) + +uninstall: + $(RM) $(addprefix $(DESTDIR)$(MAN1DIR)/,$(_DOC_MAN1)) + $(RMDIR) $(DESTDIR)$(MAN1DIR) + +.PHONY: man man1 clean install uninstall +.DEFAULT_GOAL := man diff --git a/Documentation/tools/rtla/common_appendix.rst b/Documentation/tools/rtla/common_appendix.rst new file mode 100644 index 000000000000..b494084acccd --- /dev/null +++ b/Documentation/tools/rtla/common_appendix.rst @@ -0,0 +1,12 @@ +REPORTING BUGS +============== +Report bugs to <lkml@vger.kernel.org> + +LICENSE +======= +**rtla** is Free Software licensed under the GNU GPLv2 + +COPYING +======= +Copyright \(C) 2021 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/tools/rtla/common_hist_options.rst b/Documentation/tools/rtla/common_hist_options.rst new file mode 100644 index 000000000000..df53ff835bfb --- /dev/null +++ b/Documentation/tools/rtla/common_hist_options.rst @@ -0,0 +1,23 @@ +**-b**, **--bucket-size** *N* + + Set the histogram bucket size (default *1*). + +**-E**, **--entries** *N* + + Set the number of entries of the histogram (default 256). + +**--no-header** + + Do not print header. + +**--no-summary** + + Do not print summary. + +**--no-index** + + Do not print index. + +**--with-zeros** + + Print zero only entries. diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.rst new file mode 100644 index 000000000000..721790ad984e --- /dev/null +++ b/Documentation/tools/rtla/common_options.rst @@ -0,0 +1,28 @@ +**-c**, **--cpus** *cpu-list* + + Set the osnoise tracer to run the sample threads in the cpu-list. + +**-d**, **--duration** *time[s|m|h|d]* + + Set the duration of the session. + +**-D**, **--debug** + + Print debug info. + +**-t**, **--trace**\[*=file*] + + Save the stopped trace to [*file|osnoise_trace.txt*]. + +**-P**, **--priority** *o:prio|r:prio|f:prio|d:runtime:period* + + Set scheduling parameters to the osnoise tracer threads, the format to set the priority are: + + - *o:prio* - use SCHED_OTHER with *prio*; + - *r:prio* - use SCHED_RR with *prio*; + - *f:prio* - use SCHED_FIFO with *prio*; + - *d:runtime[us|ms|s]:period[us|ms|s]* - use SCHED_DEADLINE with *runtime* and *period* in nanoseconds. + +**-h**, **--help** + + Print help menu. diff --git a/Documentation/tools/rtla/common_osnoise_description.rst b/Documentation/tools/rtla/common_osnoise_description.rst new file mode 100644 index 000000000000..d5d61615b967 --- /dev/null +++ b/Documentation/tools/rtla/common_osnoise_description.rst @@ -0,0 +1,8 @@ +The **rtla osnoise** tool is an interface for the *osnoise* tracer. The +*osnoise* tracer dispatches a kernel thread per-cpu. These threads read the +time in a loop while with preemption, softirq and IRQs enabled, thus +allowing all the sources of operating system noise during its execution. +The *osnoise*'s tracer threads take note of the delta between each time +read, along with an interference counter of all sources of interference. +At the end of each period, the *osnoise* tracer displays a summary of +the results. diff --git a/Documentation/tools/rtla/common_osnoise_options.rst b/Documentation/tools/rtla/common_osnoise_options.rst new file mode 100644 index 000000000000..d556883e4e26 --- /dev/null +++ b/Documentation/tools/rtla/common_osnoise_options.rst @@ -0,0 +1,17 @@ +**-p**, **--period** *us* + + Set the *osnoise* tracer period in microseconds. + +**-r**, **--runtime** *us* + + Set the *osnoise* tracer runtime in microseconds. + +**-s**, **--stop** *us* + + Stop the trace if a single sample is higher than the argument in microseconds. + If **-T** is set, it will also save the trace to the output. + +**-S**, **--stop-total** *us* + + Stop the trace if the total sample is higher than the argument in microseconds. + If **-T** is set, it will also save the trace to the output. diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst new file mode 100644 index 000000000000..321201cb8597 --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_description.rst @@ -0,0 +1,10 @@ +The **rtla timerlat** tool is an interface for the *timerlat* tracer. The +*timerlat* tracer dispatches a kernel thread per-cpu. These threads +set a periodic timer to wake themselves up and go back to sleep. After +the wakeup, they collect and generate useful information for the +debugging of operating system timer latency. + +The *timerlat* tracer outputs information in two ways. It periodically +prints the timer latency at the timer *IRQ* handler and the *Thread* +handler. It also enable the trace of the most relevant information via +**osnoise:** tracepoints. diff --git a/Documentation/tools/rtla/common_timerlat_options.rst b/Documentation/tools/rtla/common_timerlat_options.rst new file mode 100644 index 000000000000..e9c1bfd55d48 --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_options.rst @@ -0,0 +1,16 @@ +**-p**, **--period** *us* + + Set the *timerlat* tracer period in microseconds. + +**-i**, **--irq** *us* + + Stop trace if the *IRQ* latency is higher than the argument in us. + +**-T**, **--thread** *us* + + Stop trace if the *Thread* latency is higher than the argument in us. + +**-s**, **--stack** *us* + + Save the stack trace at the *IRQ* if a *Thread* latency is higher than the + argument in us. diff --git a/Documentation/tools/rtla/common_top_options.rst b/Documentation/tools/rtla/common_top_options.rst new file mode 100644 index 000000000000..f48878938f84 --- /dev/null +++ b/Documentation/tools/rtla/common_top_options.rst @@ -0,0 +1,3 @@ +**-q**, **--quiet** + + Print only a summary at the end of the session. diff --git a/Documentation/tools/rtla/index.rst b/Documentation/tools/rtla/index.rst new file mode 100644 index 000000000000..840f0bf3e803 --- /dev/null +++ b/Documentation/tools/rtla/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +The realtime Linux analysis tool +================================ + +RTLA provides a set of tools for the analysis of the kernel's realtime +behavior on specific hardware. + +.. toctree:: + :maxdepth: 1 + + rtla + rtla-osnoise + rtla-osnoise-hist + rtla-osnoise-top + rtla-timerlat + rtla-timerlat-hist + rtla-timerlat-top + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/tools/rtla/rtla-osnoise-hist.rst b/Documentation/tools/rtla/rtla-osnoise-hist.rst new file mode 100644 index 000000000000..f2e79d22c4c4 --- /dev/null +++ b/Documentation/tools/rtla/rtla-osnoise-hist.rst @@ -0,0 +1,66 @@ +=================== +rtla-osnoise-hist +=================== +------------------------------------------------------ +Display a histogram of the osnoise tracer samples +------------------------------------------------------ + +:Manual section: 1 + +SYNOPSIS +======== +**rtla osnoise hist** [*OPTIONS*] + +DESCRIPTION +=========== +.. include:: common_osnoise_description.rst + +The **rtla osnoise hist** tool collects all **osnoise:sample_threshold** +occurrence in a histogram, displaying the results in a user-friendly way. +The tool also allows many configurations of the *osnoise* tracer and the +collection of the tracer output. + +OPTIONS +======= +.. include:: common_osnoise_options.rst + +.. include:: common_hist_options.rst + +.. include:: common_options.rst + +EXAMPLE +======= +In the example below, *osnoise* tracer threads are set to run with real-time +priority *FIFO:1*, on CPUs *0-11*, for *900ms* at each period (*1s* by +default). The reason for reducing the runtime is to avoid starving the +**rtla** tool. The tool is also set to run for *one minute*. The output +histogram is set to group outputs in buckets of *10us* and *25* entries:: + + [root@f34 ~/]# rtla osnoise hist -P F:1 -c 0-11 -r 900000 -d 1M -b 10 -E 25 + # RTLA osnoise histogram + # Time unit is microseconds (us) + # Duration: 0 00:01:00 + Index CPU-000 CPU-001 CPU-002 CPU-003 CPU-004 CPU-005 CPU-006 CPU-007 CPU-008 CPU-009 CPU-010 CPU-011 + 0 42982 46287 51779 53740 52024 44817 49898 36500 50408 50128 49523 52377 + 10 12224 8356 2912 878 2667 10155 4573 18894 4214 4836 5708 2413 + 20 8 5 12 2 13 24 20 41 29 53 39 39 + 30 1 1 0 0 10 3 6 19 15 31 30 38 + 40 0 0 0 0 0 4 2 7 2 3 8 11 + 50 0 0 0 0 0 0 0 0 0 1 1 2 + over: 0 0 0 0 0 0 0 0 0 0 0 0 + count: 55215 54649 54703 54620 54714 55003 54499 55461 54668 55052 55309 54880 + min: 0 0 0 0 0 0 0 0 0 0 0 0 + avg: 0 0 0 0 0 0 0 0 0 0 0 0 + max: 30 30 20 20 30 40 40 40 40 50 50 50 + +SEE ALSO +======== +**rtla-osnoise**\(1), **rtla-osnoise-top**\(1) + +*osnoise* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla-osnoise-top.rst b/Documentation/tools/rtla/rtla-osnoise-top.rst new file mode 100644 index 000000000000..5d75d1394516 --- /dev/null +++ b/Documentation/tools/rtla/rtla-osnoise-top.rst @@ -0,0 +1,61 @@ +=================== +rtla-osnoise-top +=================== +----------------------------------------------- +Display a summary of the operating system noise +----------------------------------------------- + +:Manual section: 1 + +SYNOPSIS +======== +**rtla osnoise top** [*OPTIONS*] + +DESCRIPTION +=========== +.. include:: common_osnoise_description.rst + +**rtla osnoise top** collects the periodic summary from the *osnoise* tracer, +including the counters of the occurrence of the interference source, +displaying the results in a user-friendly format. + +The tool also allows many configurations of the *osnoise* tracer and the +collection of the tracer output. + +OPTIONS +======= +.. include:: common_osnoise_options.rst + +.. include:: common_top_options.rst + +.. include:: common_options.rst + +EXAMPLE +======= +In the example below, the **rtla osnoise top** tool is set to run with a +real-time priority *FIFO:1*, on CPUs *0-3*, for *900ms* at each period +(*1s* by default). The reason for reducing the runtime is to avoid starving +the rtla tool. The tool is also set to run for *one minute* and to display +a summary of the report at the end of the session:: + + [root@f34 ~]# rtla osnoise top -P F:1 -c 0-3 -r 900000 -d 1M -q + Operating System Noise + duration: 0 00:01:00 | time is in us + CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI IRQ Softirq Thread + 0 #59 53100000 304896 99.42580 6978 56 549 0 53111 1590 13 + 1 #59 53100000 338339 99.36282 8092 24 399 0 53130 1448 31 + 2 #59 53100000 290842 99.45227 6582 39 855 0 53110 1406 12 + 3 #59 53100000 204935 99.61405 6251 33 290 0 53156 1460 12 + +SEE ALSO +======== + +**rtla-osnoise**\(1), **rtla-osnoise-hist**\(1) + +Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla-osnoise.rst b/Documentation/tools/rtla/rtla-osnoise.rst new file mode 100644 index 000000000000..c129b206ce34 --- /dev/null +++ b/Documentation/tools/rtla/rtla-osnoise.rst @@ -0,0 +1,59 @@ +=============== +rtla-osnoise +=============== +------------------------------------------------------------------ +Measure the operating system noise +------------------------------------------------------------------ + +:Manual section: 1 + +SYNOPSIS +======== +**rtla osnoise** [*MODE*] ... + +DESCRIPTION +=========== + +.. include:: common_osnoise_description.rst + +The *osnoise* tracer outputs information in two ways. It periodically prints +a summary of the noise of the operating system, including the counters of +the occurrence of the source of interference. It also provides information +for each noise via the **osnoise:** tracepoints. The **rtla osnoise top** +mode displays information about the periodic summary from the *osnoise* tracer. +The **rtla osnoise hist** mode displays information about the noise using +the **osnoise:** tracepoints. For further details, please refer to the +respective man page. + +MODES +===== +**top** + + Prints the summary from osnoise tracer. + +**hist** + + Prints a histogram of osnoise samples. + +If no MODE is given, the top mode is called, passing the arguments. + +OPTIONS +======= + +**-h**, **--help** + + Display the help text. + +For other options, see the man page for the corresponding mode. + +SEE ALSO +======== +**rtla-osnoise-top**\(1), **rtla-osnoise-hist**\(1) + +Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla-timerlat-hist.rst b/Documentation/tools/rtla/rtla-timerlat-hist.rst new file mode 100644 index 000000000000..e12eae1f3301 --- /dev/null +++ b/Documentation/tools/rtla/rtla-timerlat-hist.rst @@ -0,0 +1,106 @@ +===================== +rtla-timerlat-hist +===================== +------------------------------------------------ +Histograms of the operating system timer latency +------------------------------------------------ + +:Manual section: 1 + +SYNOPSIS +======== +**rtla timerlat hist** [*OPTIONS*] ... + +DESCRIPTION +=========== + +.. include:: common_timerlat_description.rst + +The **rtla timerlat hist** displays a histogram of each tracer event +occurrence. This tool uses the periodic information, and the +**osnoise:** tracepoints are enabled when using the **-T** option. + +OPTIONS +======= + +.. include:: common_timerlat_options.rst + +.. include:: common_hist_options.rst + +.. include:: common_options.rst + +EXAMPLE +======= +In the example below, **rtla timerlat hist** is set to run for *10* minutes, +in the cpus *0-4*, *skipping zero* only lines. Moreover, **rtla timerlat +hist** will change the priority of the *timelat* threads to run under +*SCHED_DEADLINE* priority, with a *10us* runtime every *1ms* period. The +*1ms* period is also passed to the *timerlat* tracer:: + + [root@alien ~]# timerlat hist -d 10m -c 0-4 -P d:100us:1ms -p 1ms + # RTLA timerlat histogram + # Time unit is microseconds (us) + # Duration: 0 00:10:00 + Index IRQ-000 Thr-000 IRQ-001 Thr-001 IRQ-002 Thr-002 IRQ-003 Thr-003 IRQ-004 Thr-004 + 0 276489 0 206089 0 466018 0 481102 0 205546 0 + 1 318327 35487 388149 30024 94531 48382 83082 71078 388026 55730 + 2 3282 122584 4019 126527 28231 109012 23311 89309 4568 98739 + 3 940 11815 837 9863 6209 16227 6895 17196 910 9780 + 4 444 17287 424 11574 2097 38443 2169 36736 462 13476 + 5 206 43291 255 25581 1223 101908 1304 101137 236 28913 + 6 132 101501 96 64584 635 213774 757 215471 99 73453 + 7 74 169347 65 124758 350 57466 441 53639 69 148573 + 8 53 85183 31 156751 229 9052 306 9026 39 139907 + 9 22 10387 12 42762 161 2554 225 2689 19 26192 + 10 13 1898 8 5770 114 1247 128 1405 13 3772 + 11 9 560 9 924 71 686 76 765 8 713 + 12 4 256 2 360 50 411 64 474 3 278 + 13 2 167 2 172 43 256 53 350 4 180 + 14 1 88 1 116 15 198 42 223 0 115 + 15 2 63 3 94 11 139 20 150 0 58 + 16 2 37 0 56 5 78 10 102 0 39 + 17 0 18 0 28 4 57 8 80 0 15 + 18 0 8 0 17 2 50 6 56 0 12 + 19 0 9 0 5 0 19 0 48 0 18 + 20 0 4 0 8 0 11 2 27 0 4 + 21 0 2 0 3 1 9 1 18 0 6 + 22 0 1 0 3 1 7 0 3 0 5 + 23 0 2 0 4 0 2 0 7 0 2 + 24 0 2 0 2 1 3 0 3 0 5 + 25 0 0 0 1 0 1 0 1 0 3 + 26 0 1 0 0 0 2 0 2 0 0 + 27 0 0 0 3 0 1 0 0 0 1 + 28 0 0 0 3 0 0 0 1 0 0 + 29 0 0 0 2 0 2 0 1 0 3 + 30 0 1 0 0 0 0 0 0 0 0 + 31 0 1 0 0 0 0 0 2 0 2 + 32 0 0 0 1 0 2 0 0 0 0 + 33 0 0 0 2 0 0 0 0 0 1 + 34 0 0 0 0 0 0 0 0 0 2 + 35 0 1 0 1 0 0 0 0 0 1 + 36 0 1 0 0 0 1 0 1 0 0 + 37 0 0 0 1 0 0 0 0 0 0 + 40 0 0 0 0 0 1 0 1 0 0 + 41 0 0 0 0 0 0 0 0 0 1 + 42 0 0 0 0 0 0 0 0 0 1 + 44 0 0 0 0 0 1 0 0 0 0 + 46 0 0 0 0 0 0 0 1 0 0 + 47 0 0 0 0 0 0 0 0 0 1 + 50 0 0 0 0 0 0 0 0 0 1 + 54 0 0 0 1 0 0 0 0 0 0 + 58 0 0 0 1 0 0 0 0 0 0 + over: 0 0 0 0 0 0 0 0 0 0 + count: 600002 600002 600002 600002 600002 600002 600002 600002 600002 600002 + min: 0 1 0 1 0 1 0 1 0 1 + avg: 0 5 0 5 0 4 0 4 0 5 + max: 16 36 15 58 24 44 21 46 13 50 + +SEE ALSO +======== +**rtla-timerlat**\(1), **rtla-timerlat-top**\(1) + +*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> diff --git a/Documentation/tools/rtla/rtla-timerlat-top.rst b/Documentation/tools/rtla/rtla-timerlat-top.rst new file mode 100644 index 000000000000..1c321de1c171 --- /dev/null +++ b/Documentation/tools/rtla/rtla-timerlat-top.rst @@ -0,0 +1,145 @@ +==================== +rtla-timerlat-top +==================== +------------------------------------------- +Measures the operating system timer latency +------------------------------------------- + +:Manual section: 1 + +SYNOPSIS +======== +**rtla timerlat top** [*OPTIONS*] ... + +DESCRIPTION +=========== + +.. include:: common_timerlat_description.rst + +The **rtla timerlat top** displays a summary of the periodic output +from the *timerlat* tracer. It also provides information for each +operating system noise via the **osnoise:** tracepoints that can be +seem with the option **-T**. + +OPTIONS +======= + +.. include:: common_timerlat_options.rst + +.. include:: common_top_options.rst + +.. include:: common_options.rst + +EXAMPLE +======= + +In the example below, the *timerlat* tracer is set to capture the stack trace at +the IRQ handler, printing it to the buffer if the *Thread* timer latency is +higher than *30 us*. It is also set to stop the session if a *Thread* timer +latency higher than *30 us* is hit. Finally, it is set to save the trace +buffer if the stop condition is hit:: + + [root@alien ~]# rtla timerlat top -s 30 -t 30 -T + Timer Latency + 0 00:00:59 | IRQ Timer Latency (us) | Thread Timer Latency (us) + CPU COUNT | cur min avg max | cur min avg max + 0 #58634 | 1 0 1 10 | 11 2 10 23 + 1 #58634 | 1 0 1 9 | 12 2 9 23 + 2 #58634 | 0 0 1 11 | 10 2 9 23 + 3 #58634 | 1 0 1 11 | 11 2 9 24 + 4 #58634 | 1 0 1 10 | 11 2 9 26 + 5 #58634 | 1 0 1 8 | 10 2 9 25 + 6 #58634 | 12 0 1 12 | 30 2 10 30 <--- CPU with spike + 7 #58634 | 1 0 1 9 | 11 2 9 23 + 8 #58633 | 1 0 1 9 | 11 2 9 26 + 9 #58633 | 1 0 1 9 | 10 2 9 26 + 10 #58633 | 1 0 1 13 | 11 2 9 28 + 11 #58633 | 1 0 1 13 | 12 2 9 24 + 12 #58633 | 1 0 1 8 | 10 2 9 23 + 13 #58633 | 1 0 1 10 | 10 2 9 22 + 14 #58633 | 1 0 1 18 | 12 2 9 27 + 15 #58633 | 1 0 1 10 | 11 2 9 28 + 16 #58633 | 0 0 1 11 | 7 2 9 26 + 17 #58633 | 1 0 1 13 | 10 2 9 24 + 18 #58633 | 1 0 1 9 | 13 2 9 22 + 19 #58633 | 1 0 1 10 | 11 2 9 23 + 20 #58633 | 1 0 1 12 | 11 2 9 28 + 21 #58633 | 1 0 1 14 | 11 2 9 24 + 22 #58633 | 1 0 1 8 | 11 2 9 22 + 23 #58633 | 1 0 1 10 | 11 2 9 27 + timerlat hit stop tracing + saving trace to timerlat_trace.txt + [root@alien bristot]# tail -60 timerlat_trace.txt + [...] + timerlat/5-79755 [005] ....... 426.271226: #58634 context thread timer_latency 10823 ns + sh-109404 [006] dnLh213 426.271247: #58634 context irq timer_latency 12505 ns + sh-109404 [006] dNLh313 426.271258: irq_noise: local_timer:236 start 426.271245463 duration 12553 ns + sh-109404 [006] d...313 426.271263: thread_noise: sh:109404 start 426.271245853 duration 4769 ns + timerlat/6-79756 [006] ....... 426.271264: #58634 context thread timer_latency 30328 ns + timerlat/6-79756 [006] ....1.. 426.271265: <stack trace> + => timerlat_irq + => __hrtimer_run_queues + => hrtimer_interrupt + => __sysvec_apic_timer_interrupt + => sysvec_apic_timer_interrupt + => asm_sysvec_apic_timer_interrupt + => _raw_spin_unlock_irqrestore <---- spinlock that disabled interrupt. + => try_to_wake_up + => autoremove_wake_function + => __wake_up_common + => __wake_up_common_lock + => ep_poll_callback + => __wake_up_common + => __wake_up_common_lock + => fsnotify_add_event + => inotify_handle_inode_event + => fsnotify + => __fsnotify_parent + => __fput + => task_work_run + => exit_to_user_mode_prepare + => syscall_exit_to_user_mode + => do_syscall_64 + => entry_SYSCALL_64_after_hwframe + => 0x7265000001378c + => 0x10000cea7 + => 0x25a00000204a + => 0x12e302d00000000 + => 0x19b51010901b6 + => 0x283ce00726500 + => 0x61ea308872 + => 0x00000fe3 + bash-109109 [007] d..h... 426.271265: #58634 context irq timer_latency 1211 ns + timerlat/6-79756 [006] ....... 426.271267: timerlat_main: stop tracing hit on cpu 6 + +In the trace, it is possible the notice that the *IRQ* timer latency was +already high, accounting *12505 ns*. The IRQ delay was caused by the +*bash-109109* process that disabled IRQs in the wake-up path +(*_try_to_wake_up()* function). The duration of the IRQ handler that woke +up the timerlat thread, informed with the **osnoise:irq_noise** event, was +also high and added more *12553 ns* to the Thread latency. Finally, the +**osnoise:thread_noise** added by the currently running thread (including +the scheduling overhead) added more *4769 ns*. Summing up these values, +the *Thread* timer latency accounted for *30328 ns*. + +The primary reason for this high value is the wake-up path that was hit +twice during this case: when the *bash-109109* was waking up a thread +and then when the *timerlat* thread was awakened. This information can +then be used as the starting point of a more fine-grained analysis. + +Note that **rtla timerlat** was dispatched without changing *timerlat* tracer +threads' priority. That is generally not needed because these threads hava +priority *FIFO:95* by default, which is a common priority used by real-time +kernel developers to analyze scheduling delays. + +SEE ALSO +-------- +**rtla-timerlat**\(1), **rtla-timerlat-hist**\(1) + +*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html> + +AUTHOR +------ +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla-timerlat.rst b/Documentation/tools/rtla/rtla-timerlat.rst new file mode 100644 index 000000000000..44a49e6f302b --- /dev/null +++ b/Documentation/tools/rtla/rtla-timerlat.rst @@ -0,0 +1,57 @@ +================ +rtla-timerlat +================ +------------------------------------------- +Measures the operating system timer latency +------------------------------------------- + +:Manual section: 1 + +SYNOPSIS +======== +**rtla timerlat** [*MODE*] ... + +DESCRIPTION +=========== + +.. include:: common_timerlat_description.rst + +The *timerlat* tracer outputs information in two ways. It periodically +prints the timer latency at the timer *IRQ* handler and the *Thread* handler. +It also provides information for each noise via the **osnoise:** tracepoints. +The **rtla timerlat top** mode displays a summary of the periodic output +from the *timerlat* tracer. The **rtla hist hist** mode displays a histogram +of each tracer event occurrence. For further details, please refer to the +respective man page. + +MODES +===== +**top** + + Prints the summary from *timerlat* tracer. + +**hist** + + Prints a histogram of timerlat samples. + +If no *MODE* is given, the top mode is called, passing the arguments. + +OPTIONS +======= +**-h**, **--help** + + Display the help text. + +For other options, see the man page for the corresponding mode. + +SEE ALSO +======== +**rtla-timerlat-top**\(1), **rtla-timerlat-hist**\(1) + +*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla.rst b/Documentation/tools/rtla/rtla.rst new file mode 100644 index 000000000000..fc0d233efcd5 --- /dev/null +++ b/Documentation/tools/rtla/rtla.rst @@ -0,0 +1,48 @@ +========= +rtla +========= +-------------------------------- +Real-time Linux Analysis tool +-------------------------------- + +:Manual section: 1 + +SYNOPSIS +======== +**rtla** *COMMAND* [*OPTIONS*] + +DESCRIPTION +=========== +The **rtla** is a meta-tool that includes a set of commands that aims to +analyze the real-time properties of Linux. But instead of testing Linux +as a black box, **rtla** leverages kernel tracing capabilities to provide +precise information about the properties and root causes of unexpected +results. + +COMMANDS +======== +**osnoise** + + Gives information about the operating system noise (osnoise). + +**timerlat** + + Measures the IRQ and thread timer latency. + +OPTIONS +======= +**-h**, **--help** + + Display the help text. + +For other options, see the man page for the corresponding command. + +SEE ALSO +======== +**rtla-osnoise**\(1), **rtla-timerlat**\(1) + +AUTHOR +====== +Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index 6dcfbc64014d..d594597201fd 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -131,9 +131,7 @@ Ftrace Histogram Options Since it is too long to write a histogram action as a string for per-event action option, there are tree-style options under per-event 'hist' subkey for the histogram actions. For the detail of the each parameter, -please read the event histogram document [3]_. - -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>` +please read the event histogram document (Documentation/trace/histogram.rst) ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]] Set histogram key parameters. (Mandatory) diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst index a4e3ef295240..6d5ffa6f7347 100644 --- a/Documentation/trace/coresight/coresight-config.rst +++ b/Documentation/trace/coresight/coresight-config.rst @@ -155,14 +155,14 @@ follows:: autofdo $ cd autofdo/ $ ls - description preset1 preset3 preset5 preset7 preset9 - feature_refs preset2 preset4 preset6 preset8 + description feature_refs preset1 preset3 preset5 preset7 preset9 + enable preset preset2 preset4 preset6 preset8 $ cat description Setup ETMs with strobing for autofdo $ cat feature_refs strobing -Each preset declared has a preset<n> subdirectory declared. The values for +Each preset declared has a 'preset<n>' subdirectory declared. The values for the preset can be examined:: $ cat preset1/values @@ -170,6 +170,9 @@ the preset can be examined:: $ cat preset2/values strobing.window = 0x1388 strobing.period = 0x4 +The 'enable' and 'preset' files allow the control of a configuration when +using CoreSight with sysfs. + The features referenced by the configuration can be examined in the features directory:: @@ -211,19 +214,13 @@ also declared in the perf 'cs_etm' event infrastructure so that they can be selected when running trace under perf:: $ ls /sys/devices/cs_etm - configurations format perf_event_mux_interval_ms sinks type - events nr_addr_filters power - -Key directories here are 'configurations' - which lists the loaded -configurations, and 'events' - a generic perf directory which allows -selection on the perf command line.:: + cpu0 cpu2 events nr_addr_filters power subsystem uevent + cpu1 cpu3 format perf_event_mux_interval_ms sinks type - $ ls configurations/ - autofdo - $ cat configurations/autofdo - 0xa7c3dddd +The key directory here is 'events' - a generic perf directory which allows +selection on the perf command line. As with the sinks entries, this provides +a hash of the configuration name. -As with the sinks entries, this provides a hash of the configuration name. The entry in the 'events' directory uses perfs built in syntax generator to substitute the syntax for the name when evaluating the command:: @@ -242,3 +239,56 @@ A preset to override the current parameter values can also be selected:: When configurations are selected in this way, then the trace sink used is automatically selected. + +Using Configurations in sysfs +============================= + +Coresight can be controlled using sysfs. When this is in use then a configuration +can be made active for the devices that are used in the sysfs session. + +In a configuration there are 'enable' and 'preset' files. + +To enable a configuration for use with sysfs:: + + $ cd configurations/autofdo + $ echo 1 > enable + +This will then use any default parameter values in the features - which can be +adjusted as described above. + +To use a preset<n> set of parameter values:: + + $ echo 3 > preset + +This will select preset3 for the configuration. +The valid values for preset are 0 - to deselect presets, and any value of +<n> where a preset<n> sub-directory is present. + +Note that the active sysfs configuration is a global parameter, therefore +only a single configuration can be active for sysfs at any one time. +Attempting to enable a second configuration will result in an error. +Additionally, attempting to disable the configuration while in use will +also result in an error. + +The use of the active configuration by sysfs is independent of the configuration +used in perf. + + +Creating and Loading Custom Configurations +========================================== + +Custom configurations and / or features can be dynamically loaded into the +system by using a loadable module. + +An example of a custom configuration is found in ./samples/coresight. + +This creates a new configuration that uses the existing built in +strobing feature, but provides a different set of presets. + +When the module is loaded, then the configuration appears in the configfs +file system and is selectable in the same way as the built in configuration +described above. + +Configurations can use previously loaded features. The system will ensure +that it is not possible to unload a feature that is currently in use, by +enforcing the unload order as the strict reverse of the load order. diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index 8ddb9b09451c..c47f381d0c00 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -198,6 +198,15 @@ The glob (~) accepts a wild card character (\*,?) and character classes prev_comm ~ "*sh*" prev_comm ~ "ba*sh" +If the field is a pointer that points into user space (for example +"filename" from sys_enter_openat), then you have to append ".ustring" to the +field name:: + + filename.ustring ~ "password" + +As the kernel will have to know how to retrieve the memory that the pointer +is at from user space. + 5.2 Setting filters ------------------- @@ -230,6 +239,16 @@ Currently the caret ('^') for an error always appears at the beginning of the filter string; the error message should still be useful though even without more accurate position info. +5.2.1 Filter limitations +------------------------ + +If a filter is placed on a string pointer ``(char *)`` that does not point +to a string on the ring buffer, but instead points to kernel or user space +memory, then, for safety reasons, at most 1024 bytes of the content is +copied onto a temporary buffer to do the compare. If the copy of the memory +faults (the pointer points to memory that should not be accessed), then the +string compare will be treated as not matching. + 5.3 Clearing filters -------------------- diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index b3166c4a7867..45b8c56af67a 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -3370,7 +3370,7 @@ one of the latency tracers, you will get the following results. Instances --------- -In the tracefs tracing directory is a directory called "instances". +In the tracefs tracing directory, there is a directory called "instances". This directory can have new directories created inside of it using mkdir, and removing directories with rmdir. The directory created with mkdir in this directory will already contain files and other diff --git a/Documentation/trace/osnoise-tracer.rst b/Documentation/trace/osnoise-tracer.rst index b648cb9bf1f0..963def9f97c6 100644 --- a/Documentation/trace/osnoise-tracer.rst +++ b/Documentation/trace/osnoise-tracer.rst @@ -51,7 +51,7 @@ For example:: [root@f32 ~]# cd /sys/kernel/tracing/ [root@f32 tracing]# echo osnoise > current_tracer -It is possible to follow the trace by reading the trace trace file:: +It is possible to follow the trace by reading the trace file:: [root@f32 tracing]# cat trace # tracer: osnoise @@ -108,7 +108,7 @@ The tracer has a set of options inside the osnoise directory, they are: option. - tracing_threshold: the minimum delta between two time() reads to be considered as noise, in us. When set to 0, the default value will - will be used, which is currently 5 us. + be used, which is currently 5 us. Additional Tracing ------------------ diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py deleted file mode 100644 index 92cdbba74229..000000000000 --- a/Documentation/translations/conf.py +++ /dev/null @@ -1,12 +0,0 @@ -# -*- coding: utf-8 -*- -# SPDX-License-Identifier: GPL-2.0 - -# -- Additinal options for LaTeX output ---------------------------------- -# font config for ascii-art alignment - -latex_elements['preamble'] += ''' - \\IfFontExistsTF{Noto Sans CJK SC}{ - % For CJK ascii-art alignment - \\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant] - }{} -''' diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index c2fb712a1377..4fb5b3aa306d 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -276,25 +276,6 @@ cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche all'API dello spazio utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -Per le piccole patch potreste aggiungere in CC l'indirizzo -*Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere -le patch "banali". Date uno sguardo al file MAINTAINERS per vedere chi -è l'attuale amministratore. - -Le patch banali devono rientrare in una delle seguenti categorie: - -- errori grammaticali nella documentazione -- errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)` -- correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo) -- correzione di errori di compilazione (solo se correggono qualcosa sul serio) -- rimozione di funzioni/macro deprecate -- sostituzione di codice non potabile con uno portabile (anche in codice - specifico per un'architettura, dato che le persone copiano, fintanto che - la modifica sia banale) -- qualsiasi modifica dell'autore/manutentore di un file (in pratica - "patch monkey" in modalità ritrasmissione) - - Niente: MIME, links, compressione, allegati. Solo puro testo ------------------------------------------------------------- diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 6854f5add72e..0d308edef781 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -208,21 +208,6 @@ VGER.KERNEL.ORG ã§ãƒ›ã‚¹ãƒ†ã‚£ãƒ³ã‚°ã•ã‚Œã¦ã„るメーリングリストã®ä ãŸã¨ãˆã€ãƒ¡ãƒ³ãƒ†ãƒŠãŒ #5 ã§åå¿œãŒãªã‹ã£ãŸã¨ã—ã¦ã‚‚ã€ãƒ¡ãƒ³ãƒ†ãƒŠã®ã‚³ãƒ¼ãƒ‰ã«å¤‰æ›´ã‚’ åŠ ãˆãŸã¨ãã«ã¯ã€ã„ã¤ã‚‚メンテナ㫠CC ã™ã‚‹ã®ã‚’忘れãªã„よã†ã«ã—ã¦ãã ã•ã„。 -å°ã•ãªãƒ‘ッãƒã§ã‚ã‚Œã°ã€Trivial Patch Monkey(ã¡ã‚‡ã£ã¨ã—ãŸãƒ‘ッãƒã‚’集ã‚ã¦ã„ã‚‹) -<trivial@kernel.org>ã« CC ã—ã¦ã‚‚ã„ã„ã§ã™ã€‚ãã®ç¾ç®¡ç†è€…ã«ã¤ã„ã¦ã¯ MAINTAINERS -ファイルを見ã¦ãã ã•ã„。ã¡ã‚‡ã£ã¨ã—ãŸãƒ‘ッãƒã¨ã¯ä»¥ä¸‹ã®ãƒ«ãƒ¼ãƒ«ã®ã©ã‚Œã‹1ã¤ã‚’満ãŸã—㦠-ã„ãªã‘ã‚Œã°ãªã‚Šã¾ã›ã‚“。 - ・ドã‚ュメントã®ã‚¹ãƒšãƒ«ãƒŸã‚¹ã®ä¿®æ£ - ・grep(1) コマンドã«ã‚ˆã‚‹æ¤œç´¢ã‚’困難ã«ã—ã¦ã„るスペルã®ä¿®æ£ - ・コンパイル時ã®è¦å‘Šã®ä¿®æ£(無駄ãªè¦å‘ŠãŒæ•£ä¹±ã™ã‚‹ã“ã¨ã¯å¥½ã¾ã—ããªã„㟠- ã‚ã§ã™) - ・コンパイルå•é¡Œã®ä¿®æ£(ãれらã®ä¿®æ£ãŒæœ¬å½“ã«æ£ã—ã„å ´åˆã«é™ã‚‹) - ・実行時ã®å•é¡Œã®ä¿®æ£(ãれらã®ä¿®æ£ãŒæœ¬å½“ã«å•é¡Œã‚’ä¿®æ£ã—ã¦ã„ã‚‹å ´åˆã«é™ã‚‹) - ・廃æ¢äºˆå®šã®é–¢æ•°ã‚„マクãƒã‚’使用ã—ã¦ã„るコードã®é™¤åŽ»(例 check_region ) - ・å•ã„åˆã‚ã›å…ˆã‚„ドã‚ュメントã®ä¿®æ£ - ・移æ¤æ€§ã®ãªã„コードã‹ã‚‰ç§»æ¤æ€§ã®ã‚るコードã¸ã®ç½®ãæ›ãˆ(å°ã•ã„範囲㧠- ã‚ã‚Œã°ã‚¢ãƒ¼ã‚テクãƒãƒ£ç‰¹æœ‰ã®ã“ã¨ã§ã‚‚ä»–ã®äººãŒã‚³ãƒ”ーã§ãã¾ã™) - ・作者やメンテナã«ã‚ˆã‚‹ä¿®æ£(ã™ãªã‚ã¡ patch monkey ã®å†è»¢é€ãƒ¢ãƒ¼ãƒ‰) 7) MIME やリンクや圧縮ファイルや添付ファイルã§ã¯ãªãプレインテã‚ストã®ã¿ diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst index 88d4d98eed15..20738c931d02 100644 --- a/Documentation/translations/ja_JP/index.rst +++ b/Documentation/translations/ja_JP/index.rst @@ -3,7 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginJP + \kerneldocBeginJP{ Japanese translations ===================== @@ -15,4 +15,4 @@ Japanese translations .. raw:: latex - \kerneldocEndJP + }\kerneldocEndJP diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst index f636b482fb4c..4add6b2fe1f2 100644 --- a/Documentation/translations/ko_KR/index.rst +++ b/Documentation/translations/ko_KR/index.rst @@ -3,7 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginKR + \kerneldocBeginKR{ í•œêµì–´ ë²ˆì— =========== @@ -26,5 +26,4 @@ .. raw:: latex - \normalsize - \kerneldocEndKR + }\kerneldocEndKR diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst index 5c96017e9f41..16acb2bd9b58 100644 --- a/Documentation/translations/zh_CN/PCI/index.rst +++ b/Documentation/translations/zh_CN/PCI/index.rst @@ -22,13 +22,14 @@ Linux PCI总线å系统 :numbered: pci - -Todolist: - pciebus-howto pci-iov-howto msi-howto sysfs-pci + + +Todolist: + acpi-info pci-error-recovery pcieaer-howto diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst new file mode 100644 index 000000000000..7ea4d50cdad2 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -0,0 +1,233 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/msi-howto.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +=========== +MSIé©±åŠ¨æŒ‡å— +=========== + +:作者: Tom L Nguyen; Martine Silbermann; Matthew Wilcox + +:版æƒ: 2003, 2008 Intel Corporation + +å…³äºŽæœ¬æŒ‡å— +========== + +本指å—介ç»äº†æ¶ˆæ¯æ ‡è®°ä¸æ–（MSI）的基本知识，使用MSIç›¸å¯¹äºŽä¼ ç»Ÿä¸æ–机制的优势，如何 +改å˜ä½ 的驱动程åºä»¥ä½¿ç”¨MSI或MSI-X，以åŠåœ¨è®¾å¤‡ä¸æ”¯æŒMSIæ—¶å¯ä»¥å°è¯•çš„一些基本诊æ–方法。 + + +什么是MSI? +========== + +ä¿¡æ¯ä¿¡å·ä¸æ–是指从设备写到一个特殊的地å€ï¼Œå¯¼è‡´CPU接收到一个ä¸æ–。 + +MSI能力首次在PCI 2.2ä¸è§„定，åŽæ¥åœ¨PCI 3.0ä¸å¾—到增强，å…许对æ¯ä¸ªä¸æ–进行å•ç‹¬å±è”½ã€‚ +MSI-X功能也éšç€PCI 3.0被引入。它比MSI支æŒæ¯ä¸ªè®¾å¤‡æ›´å¤šçš„ä¸æ–，并å…许独立é…ç½®ä¸æ–。 + +设备å¯ä»¥åŒæ—¶æ”¯æŒMSIå’ŒMSI-X，但一次åªèƒ½å¯ç”¨ä¸€ä¸ªã€‚ + + +为什么用MSI? +============ + +æœ‰ä¸‰ä¸ªåŽŸå› å¯ä»¥è¯´æ˜Žä¸ºä»€ä¹ˆä½¿ç”¨MSIæ¯”ä¼ ç»Ÿçš„åŸºäºŽé’ˆè„šçš„ä¸æ–有优势。 + +基于针脚的PCIä¸æ–é€šå¸¸åœ¨å‡ ä¸ªè®¾å¤‡ä¹‹é—´å…±äº«ã€‚ä¸ºäº†æ”¯æŒè¿™ä¸€ç‚¹ï¼Œå†…æ ¸å¿…é¡»è°ƒç”¨æ¯ä¸ªä¸Žä¸æ–相 +关的ä¸æ–处ç†ç¨‹åºï¼Œè¿™å¯¼è‡´äº†æ•´ä¸ªç³»ç»Ÿæ€§èƒ½çš„é™ä½Žã€‚MSI从ä¸å…±äº«ï¼Œæ‰€ä»¥è¿™ä¸ªé—®é¢˜ä¸ä¼šå‡ºçŽ°ã€‚ + +当一个设备将数æ®å†™å…¥å†…å˜ï¼Œç„¶åŽå¼•å‘一个基于引脚的ä¸æ–时，有å¯èƒ½åœ¨æ‰€æœ‰çš„æ•°æ®åˆ°è¾¾å†…å˜ +之å‰ï¼Œä¸æ–就已ç»åˆ°è¾¾äº†ï¼ˆè¿™åœ¨PCI-PCIæ¡¥åŽé¢çš„设备ä¸å˜å¾—更有å¯èƒ½ï¼‰ã€‚为了确ä¿æ‰€æœ‰çš„æ•° +æ®å·²ç»åˆ°è¾¾å†…å˜ä¸ï¼Œä¸æ–处ç†ç¨‹åºå¿…须在引å‘ä¸æ–的设备上读å–一个寄å˜å™¨ã€‚PCI事务排åºè§„ +则è¦æ±‚所有的数æ®åœ¨è¿”回寄å˜å™¨çš„值之å‰åˆ°è¾¾å†…å˜ã€‚使用MSIå¯ä»¥é¿å…è¿™ä¸ªé—®é¢˜ï¼Œå› ä¸ºä¸æ–产 +生的写入ä¸èƒ½é€šè¿‡æ•°æ®å†™å…¥ï¼Œæ‰€ä»¥å½“ä¸æ–å‘生时，驱动程åºçŸ¥é“所有的数æ®å·²ç»åˆ°è¾¾å†…å˜ä¸ã€‚ + +PCI设备æ¯ä¸ªåŠŸèƒ½åªèƒ½æ”¯æŒä¸€ä¸ªåŸºäºŽå¼•è„šçš„ä¸æ–。通常情况下，驱动程åºå¿…须查询设备以找出 +å‘生了什么事件，这就å‡æ…¢äº†å¯¹å¸¸è§æƒ…况的ä¸æ–处ç†ã€‚有了MSI，设备å¯ä»¥æ”¯æŒæ›´å¤šçš„ä¸æ–， +å…许æ¯ä¸ªä¸æ–被专门用于ä¸åŒçš„目的。一ç§å¯èƒ½çš„设计是给ä¸ç»å¸¸å‘生的情况（如错误）æä¾› +自己的ä¸æ–，这使得驱动程åºå¯ä»¥æ›´æœ‰æ•ˆåœ°å¤„ç†æ£å¸¸çš„ä¸æ–处ç†è·¯å¾„。其他å¯èƒ½çš„设计包括给 +网å¡çš„æ¯ä¸ªæ•°æ®åŒ…队列或å˜å‚¨æŽ§åˆ¶å™¨çš„æ¯ä¸ªç«¯å£æ供一个ä¸æ–。 + + +如何使用MSI +=========== + +PCI设备被åˆå§‹åŒ–为使用基于引脚的ä¸æ–。设备驱动程åºå¿…须将设备设置为使用MSI或MSI-X。 +并éžæ‰€æœ‰çš„机器都能æ£ç¡®åœ°æ”¯æŒMSI，对于这些机器，下é¢æè¿°çš„API将简å•åœ°å¤±è´¥ï¼Œè®¾å¤‡å°† +继ç»ä½¿ç”¨åŸºäºŽå¼•è„šçš„ä¸æ–。 + +åŠ å…¥å†…æ ¸å¯¹MSIçš„æ”¯æŒ +------------------- + +为了支æŒMSI或MSI-Xï¼Œå†…æ ¸åœ¨æž„å»ºæ—¶å¿…é¡»å¯ç”¨CONFIG_PCI_MSI选项。这个选项åªåœ¨æŸäº›æž¶ +构上å¯ç”¨ï¼Œè€Œä¸”它å¯èƒ½å–决于其他一些选项的设置。例如，在x86ä¸Šï¼Œä½ å¿…é¡»åŒæ—¶å¯ç”¨X86_UP_APIC +或SMP，æ‰èƒ½çœ‹åˆ°CONFIG_PCI_MSI选项。 + +使用MSI +------- + +大部分沉é‡çš„工作是在PCI层为驱动程åºå®Œæˆçš„。驱动程åºåªéœ€è¦è¯·æ±‚PCI层为这个设备设置 +MSI功能。 + +è¦è‡ªåŠ¨ä½¿ç”¨MSI或MSI-Xä¸æ–å‘é‡ï¼Œè¯·ä½¿ç”¨ä»¥ä¸‹å‡½æ•°:: + + int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, + unsigned int max_vecs, unsigned int flags); + +它为一个PCI设备分é…最多至max_vecsçš„ä¸æ–å‘é‡ã€‚它返回分é…çš„å‘é‡æ•°é‡æˆ–一个负的错误。 +如果设备对最å°æ•°é‡çš„å‘é‡æœ‰è¦æ±‚，驱动程åºå¯ä»¥ä¼ 递一个min_vecså‚数，设置为这个é™åˆ¶ï¼Œ +如果PCIæ ¸ä¸èƒ½æ»¡è¶³æœ€å°æ•°é‡çš„å‘é‡ï¼Œå°†è¿”回-ENOSPC。 + +flagså‚数用æ¥æŒ‡å®šè®¾å¤‡å’Œé©±åŠ¨ç¨‹åºå¯ä»¥ä½¿ç”¨å“ªç§ç±»åž‹çš„ä¸æ–（PCI_IRQ_LEGACY, PCI_IRQ_MSI, +PCI_IRQ_MSIX）。一个方便的çŸè¯ï¼ˆPCI_IRQ_ALL_TYPES）也å¯ä»¥ç”¨æ¥è¦æ±‚任何å¯èƒ½çš„ä¸æ–类型。 +如果PCI_IRQ_AFFINITYæ ‡å¿—è¢«è®¾ç½®ï¼Œpci_alloc_irq_vectors()将把ä¸æ–分散到å¯ç”¨çš„CPU上。 + +è¦èŽ·å¾—ä¼ é€’ç»™require_irq()å’Œfree_irq()çš„Linux IRQå·ç å’Œå‘é‡ï¼Œè¯·ä½¿ç”¨ä»¥ä¸‹å‡½æ•°:: + + int pci_irq_vector(struct pci_dev *dev, unsigned int nr); + +åœ¨åˆ é™¤è®¾å¤‡ä¹‹å‰ï¼Œåº”使用以下功能释放任何已分é…的资æº:: + + void pci_free_irq_vectors(struct pci_dev *dev); + +如果一个设备åŒæ—¶æ”¯æŒMSI-Xå’ŒMSI功能，这个API将优先使用MSI-X，而ä¸æ˜¯MSI。MSI-X支 +æŒ1到2048之间的任何数é‡çš„ä¸æ–。相比之下，MSI被é™åˆ¶ä¸ºæœ€å¤š32个ä¸æ–（而且必须是2的幂）。 +æ¤å¤–，MSIä¸æ–å‘é‡å¿…须连ç»åˆ†é…，所以系统å¯èƒ½æ— 法为MSI分é…åƒMSI-Xé‚£æ ·å¤šçš„å‘é‡ã€‚在一 +些平å°ä¸Šï¼ŒMSIä¸æ–必须全部针对åŒä¸€ç»„CPU，而MSI-Xä¸æ–å¯ä»¥å…¨éƒ¨é’ˆå¯¹ä¸åŒçš„CPU。 + +如果一个设备既ä¸æ”¯æŒMSI-X，也ä¸æ”¯æŒMSIï¼Œå®ƒå°±ä¼šé€€å›žåˆ°ä¸€ä¸ªä¼ ç»Ÿçš„IRQå‘é‡ã€‚ + +MSI或MSI-Xä¸æ–的典型用法是分é…å°½å¯èƒ½å¤šçš„å‘é‡ï¼Œå¯èƒ½è¾¾åˆ°è®¾å¤‡æ”¯æŒçš„æžé™ã€‚如果nvec大于 +设备支æŒçš„æ•°é‡ï¼Œå®ƒå°†è‡ªåŠ¨è¢«é™åˆ¶åœ¨æ”¯æŒçš„é™åº¦å†…，所以没有必è¦äº‹å…ˆæŸ¥è¯¢æ”¯æŒçš„å‘é‡çš„æ•°é‡ã€‚:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) + if (nvec < 0) + goto out_err; + +如果一个驱动程åºä¸èƒ½æˆ–ä¸æ„¿æ„处ç†å¯å˜æ•°é‡çš„MSIä¸æ–，它å¯ä»¥è¦æ±‚一个特定数é‡çš„ä¸æ–，将该 +æ•°é‡ä½œä¸ºâ€œmin_vecs“和“max_vecs“å‚æ•°ä¼ é€’ç»™pci_alloc_irq_vectors()函数。:: + + ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +上述请求类型的最è‡åæ˜è‘—的例å是为一个设备å¯ç”¨å•ä¸€çš„MSI模å¼ã€‚它å¯ä»¥é€šè¿‡ä¼ 递两个1作为 +'min_vecs'å’Œ'max_vecs'æ¥å®žçŽ°:: + + ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +一些设备å¯èƒ½ä¸æ”¯æŒä½¿ç”¨ä¼ 统的线路ä¸æ–，在这ç§æƒ…况下，驱动程åºå¯ä»¥æŒ‡å®šåªæŽ¥å—MSI或MSI-X。:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); + if (nvec < 0) + goto out_err; + +ä¼ ç»ŸAPI +----------- + +以下用于å¯ç”¨å’Œç¦ç”¨MSI或MSI-Xä¸æ–çš„æ—§APIä¸åº”该在新代ç ä¸ä½¿ç”¨:: + + pci_enable_msi() /* deprecated */ + pci_disable_msi() /* deprecated */ + pci_enable_msix_range() /* deprecated */ + pci_enable_msix_exact() /* deprecated */ + pci_disable_msix() /* deprecated */ + +æ¤å¤–，还有一些APIæ¥æ供支æŒçš„MSI或MSI-Xå‘é‡çš„æ•°é‡ï¼špci_msi_vec_count()å’Œ +pci_msix_vec_count()。一般æ¥è¯´ï¼Œåº”该é¿å…使用这些方法，而是让pci_alloc_irq_vectors() +æ¥é™åˆ¶å‘é‡çš„æ•°é‡ã€‚å¦‚æžœä½ å¯¹å‘é‡çš„æ•°é‡æœ‰åˆæ³•çš„特殊用例，我们å¯èƒ½è¦é‡æ–°å®¡è§†è¿™ä¸ªå†³å®šï¼Œ +å¹¶å¢žåŠ ä¸€ä¸ªpci_nr_irq_vectors()助手，é€æ˜Žåœ°å¤„ç†MSIå’ŒMSI-X。 + +使用MSI时需è¦è€ƒè™‘çš„å› ç´ +----------------------- + +è‡ªæ—‹é” +~~~~~~ + +大多数设备驱动程åºéƒ½æœ‰ä¸€ä¸ªæ¯çš„自旋é”，在ä¸æ–处ç†ç¨‹åºä¸è¢«å 用。对于基于引脚的ä¸æ– +或å•ä¸€çš„MSI，没有必è¦ç¦ç”¨ä¸æ–（Linuxä¿è¯åŒä¸€ä¸æ–ä¸ä¼šè¢«é‡æ–°è¾“入）。如果一个设备 +使用多个ä¸æ–，驱动程åºå¿…须在é”被æŒæœ‰çš„时候ç¦ç”¨ä¸æ–。如果设备å‘出一个ä¸åŒçš„ä¸æ–， +驱动程åºå°†æ»é”，试图递归地获å–自旋é”。这ç§æ»é”å¯ä»¥é€šè¿‡ä½¿ç”¨spin_lock_irqsave() +或spin_lock_irq()æ¥é¿å…，它们å¯ä»¥ç¦ç”¨æœ¬åœ°ä¸æ–并获å–é”（è§ã€Šä¸å¯é çš„é”定指å—》）。 + +如何判æ–一个设备上是å¦å¯ç”¨äº†MSI/MSI-X +------------------------------------- + +使用“lspci -v“（以root身份）å¯èƒ½ä¼šæ˜¾ç¤ºä¸€äº›å…·æœ‰â€œMSI“ã€â€œMessage Signalled Interrupts“ +或“MSI-X“功能的设备。这些功能ä¸çš„æ¯ä¸€ä¸ªéƒ½æœ‰ä¸€ä¸ªâ€œå¯ç”¨â€œæ ‡å¿—，åŽé¢æ˜¯â€œ+“（å¯ç”¨ï¼‰ +或“-“（ç¦ç”¨ï¼‰ã€‚ + + +MSI特性 +======= + +众所周知，一些PCI芯片组或设备ä¸æ”¯æŒMSI。PCIåè®®æ ˆæ供了三ç§ç¦ç”¨MSI的方法: + +1. 全局的 +2. 在一个特定的桥åŽé¢çš„所有设备上 +3. 在å•ä¸€è®¾å¤‡ä¸Š + +全局ç¦ç”¨MSI +----------- + +ä¸€äº›ä¸»æŽ§èŠ¯ç‰‡ç»„æ ¹æœ¬æ— æ³•æ£ç¡®æ”¯æŒMSI。如果我们幸è¿çš„è¯ï¼Œåˆ¶é€ 商知é“这一点，并在 +ACPI FADT表ä¸æŒ‡æ˜Žäº†å®ƒã€‚在这ç§æƒ…况下，Linux会自动ç¦ç”¨MSI。有些æ¿å¡åœ¨è¡¨ä¸æ²¡ +有包括这一信æ¯ï¼Œå› æ¤æˆ‘们必须自己检测它们。完整的列表å¯ä»¥åœ¨drivers/pci/quirks.c +ä¸çš„quirk_disable_all_msi()函数附近找到。 + +å¦‚æžœä½ æœ‰ä¸€å—有MSI问题的æ¿åï¼Œä½ å¯ä»¥åœ¨å†…æ ¸å‘½ä»¤è¡Œä¸ä¼ 递pci=nomsiæ¥ç¦ç”¨æ‰€æœ‰è®¾ +备上的MSIã€‚ä½ æœ€å¥½æŠŠé—®é¢˜æŠ¥å‘Šç»™linux-pci@vger.kernel.org，包括完整的 +“lspci -vâ€œï¼Œè¿™æ ·æˆ‘ä»¬å°±å¯ä»¥æŠŠè¿™äº›æ€ªç™–æ·»åŠ åˆ°å†…æ ¸ä¸ã€‚ + +ç¦ç”¨æ¡¥ä¸‹çš„MSI +------------- + +一些PCI桥接器ä¸èƒ½åœ¨æ€»çº¿ä¹‹é—´æ£ç¡®åœ°è·¯ç”±MSI。在这ç§æƒ…况下，必须在桥接器åŽé¢çš„所 +有设备上ç¦ç”¨MSI。 + +一些桥接器å…è®¸ä½ é€šè¿‡æ”¹å˜PCIé…置空间的一些ä½æ¥å¯ç”¨MSI（特别是Hypertransport +芯片组，如nVidia nForceå’ŒServerworks HT2000ï¼‰ã€‚ä¸Žä¸»æœºèŠ¯ç‰‡ç»„ä¸€æ ·ï¼ŒLinux大 +多知é“它们，如果å¯ä»¥çš„è¯ï¼Œä¼šè‡ªåŠ¨å¯ç”¨MSIã€‚å¦‚æžœä½ æœ‰ä¸€ä¸ªLinuxä¸çŸ¥é“çš„ç½‘æ¡¥ï¼Œä½ å¯ä»¥ +ç”¨ä½ çŸ¥é“的任何方法在é…置空间ä¸å¯ç”¨MSI，然åŽé€šè¿‡ä»¥ä¸‹æ–¹å¼åœ¨è¯¥ç½‘桥上å¯ç”¨MSI:: + + echo 1 > /sys/bus/pci/devices/$bridge/msi_bus + +å…¶ä¸$bridgeæ˜¯ä½ æ‰€å¯ç”¨çš„桥的PCI地å€ï¼ˆä¾‹å¦‚0000:00:0e.0）。 + +è¦ç¦ç”¨MSI，请回显0而ä¸æ˜¯1。改å˜è¿™ä¸ªå€¼åº”è¯¥è°¨æ…Žè¿›è¡Œï¼Œå› ä¸ºå®ƒå¯èƒ½ä¼šç ´å这个桥下é¢æ‰€ +有设备的ä¸æ–处ç†ã€‚ + +åŒæ ·ï¼Œè¯·é€šçŸ¥ linux-pci@vger.kernel.org 任何需è¦ç‰¹æ®Šå¤„ç†çš„桥。 + +在å•ä¸€è®¾å¤‡ä¸Šå…³é—MSIs +-------------------- + +众所周知，有些设备的MSI实现是有问题的。通常情况下，这是在å•ä¸ªè®¾å¤‡é©±åŠ¨ç¨‹åºä¸å¤„ç†çš„， +但å¶å°”也有必è¦ç”¨ä¸€ä¸ªå¤æ€ªçš„方法æ¥å¤„ç†ã€‚一些驱动程åºæœ‰ä¸€ä¸ªé€‰é¡¹å¯ä»¥ç¦ç”¨MSI的使用。虽然 +这对驱动程åºçš„作者æ¥è¯´æ˜¯ä¸€ä¸ªæ–¹ä¾¿çš„å˜é€šåŠžæ³•ï¼Œä½†è¿™ä¸æ˜¯ä¸€ä¸ªå¥½çš„åšæ³•ï¼Œä¸åº”该被模仿。 + +寻找设备上MSI被ç¦ç”¨çš„åŽŸå› +------------------------- + +ä»Žä»¥ä¸Šä¸‰ä¸ªéƒ¨åˆ†ï¼Œä½ å¯ä»¥çœ‹åˆ°æœ‰è®¸å¤šåŽŸå› 导致MSI没有在æŸä¸ªè®¾å¤‡ä¸Šè¢«å¯ç”¨ã€‚ä½ çš„ç¬¬ä¸€æ¥åº”该是 +ä»”ç»†æ£€æŸ¥ä½ çš„dmesgä»¥ç¡®å®šä½ çš„æœºå™¨æ˜¯å¦å¯ç”¨äº†MSIã€‚ä½ è¿˜åº”è¯¥æ£€æŸ¥ä½ çš„.configä»¥ç¡®å®šä½ å·²ç» +å¯ç”¨äº†CONFIG_PCI_MSI。 + +然åŽï¼Œâ€œlspci -t“给出一个设备上é¢çš„ç½‘åˆ—è¡¨ã€‚è¯»å– ``/sys/bus/pci/devices/*/msi_bus`` +å°†å‘Šè¯‰ä½ MSI是å¦è¢«å¯ç”¨ï¼ˆ1）或ç¦ç”¨ï¼ˆ0）。如果在任何属于PCIæ ¹å’Œè®¾å¤‡ä¹‹é—´çš„æ¡¥çš„msi_bus +文件ä¸å‘现0，说明MSI被ç¦ç”¨ã€‚ + +也需è¦æ£€æŸ¥è®¾å¤‡é©±åŠ¨ç¨‹åºï¼Œçœ‹å®ƒæ˜¯å¦æ”¯æŒMSI。例如，它å¯èƒ½åŒ…å«å¯¹å¸¦æœ‰PCI_IRQ_MSI或 +PCI_IRQ_MSIXæ ‡å¿—çš„pci_alloc_irq_vectors（）的调用。 diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst new file mode 100644 index 000000000000..fbc83dfdcead --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pci-iov-howto.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +.. _cn_pci-iov-howto: + +========================== +PCI Express I/O è™šæ‹ŸåŒ–æŒ‡å— +========================== + +:版æƒ: |copy| 2009 Intel Corporation +:作者: - Yu Zhao <yu.zhao@intel.com> + - Donald Dutile <ddutile@redhat.com> + +概述 +==== + +什么是SR-IOV +------------ + +å•æ ¹I/O虚拟化（SR-IOV）是一ç§PCI Express扩展功能，它使一个物ç†è®¾å¤‡æ˜¾ç¤ºä¸ºå¤šä¸ª +虚拟设备。物ç†è®¾å¤‡è¢«ç§°ä¸ºç‰©ç†åŠŸèƒ½ï¼ˆPF），而虚拟设备被称为虚拟功能（VF）。VF的分 +é…å¯ä»¥ç”±PF通过å°è£…在该功能ä¸çš„寄å˜å™¨åŠ¨æ€æŽ§åˆ¶ã€‚默认情况下，该功能未被å¯ç”¨ï¼ŒPF表 +çŽ°ä¸ºä¼ ç»Ÿçš„PCIe设备。一旦开å¯ï¼Œæ¯ä¸ªVFçš„PCIé…置空间都å¯ä»¥é€šè¿‡è‡ªå·±çš„总线ã€è®¾å¤‡å’Œ +功能编å·ï¼ˆè·¯ç”±ID）æ¥è®¿é—®ã€‚而且æ¯ä¸ªVF也有PCI内å˜ç©ºé—´ï¼Œç”¨äºŽæ˜ 射其寄å˜å™¨é›†ã€‚VF设 +备驱动程åºå¯¹å¯„å˜å™¨é›†è¿›è¡Œæ“ä½œï¼Œè¿™æ ·å®ƒå°±å¯ä»¥å‘挥功能，并作为一个真æ£çš„现有PCI设备 +出现。 + +ä½¿ç”¨æŒ‡å— +======== + +æˆ‘æ€Žæ ·æ‰èƒ½å¯ç”¨SR-IOV功能 +------------------------ + +有多ç§æ–¹æ³•å¯ç”¨äºŽSR-IOVçš„å¯ç”¨ã€‚在第一ç§æ–¹æ³•ä¸ï¼Œè®¾å¤‡é©±åŠ¨ï¼ˆPF驱动）将通过SR-IOV +æ ¸å¿ƒæ供的API控制功能的å¯ç”¨å’Œç¦ç”¨ã€‚如果硬件具有SR-IOVèƒ½åŠ›ï¼ŒåŠ è½½å…¶PFé©±åŠ¨å™¨å°†å¯ +用它和与PF相关的所有VF。一些PF驱动需è¦è®¾ç½®ä¸€ä¸ªæ¨¡å—å‚数，以确定è¦å¯ç”¨çš„VFçš„æ•°é‡ã€‚ +在第二ç§æ–¹æ³•ä¸ï¼Œå¯¹sysfs文件sriov_numvfs的写入将å¯ç”¨å’Œç¦ç”¨ä¸ŽPCIe PF相关的VF。 +è¿™ç§æ–¹æ³•å®žçŽ°äº†æ¯ä¸ªPFçš„VFå¯ç”¨/ç¦ç”¨å€¼ï¼Œè€Œç¬¬ä¸€ç§æ–¹æ³•åˆ™é€‚用于åŒä¸€è®¾å¤‡çš„所有PF。æ¤å¤–， +PCI SRIOVæ ¸å¿ƒæ”¯æŒç¡®ä¿å¯ç”¨/ç¦ç”¨æ“作是有效的，以å‡å°‘åŒä¸€æ£€æŸ¥åœ¨å¤šä¸ªé©±åŠ¨ç¨‹åºä¸çš„é‡ +å¤ï¼Œä¾‹å¦‚，如果å¯ç”¨VF，检查numvfs == 0，确ä¿numvfs <= totalvfs。 +第二ç§æ–¹æ³•æ˜¯å¯¹æ–°çš„/未æ¥çš„VF设备的推è方法。 + +æˆ‘æ€Žæ ·æ‰èƒ½ä½¿ç”¨è™šæ‹ŸåŠŸèƒ½ +---------------------- + +åœ¨å†…æ ¸ä¸ï¼ŒVF被视为çƒæ’拔的PCI设备，所以它们应该能够以与真æ£çš„PCI设备相åŒçš„æ–¹å¼ +工作。VF需è¦çš„设备驱动与普通PCI设备的驱动相åŒã€‚ + +å¼€å‘è€…æŒ‡å— +========== + +SR-IOV API +---------- + +用æ¥å¼€å¯SR-IOV功能: + +(a) 对于第一ç§æ–¹æ³•ï¼Œåœ¨é©±åŠ¨ç¨‹åºä¸:: + + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); + +nr_virtfn'是è¦å¯ç”¨çš„VFçš„ç¼–å·ã€‚ + +(b) 对于第二ç§æ–¹æ³•ï¼Œä»Žsysfs:: + + echo 'nr_virtfn' > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +用æ¥å…³é—SR-IOV功能: + +(a) 对于第一ç§æ–¹æ³•ï¼Œåœ¨é©±åŠ¨ç¨‹åºä¸:: + + void pci_disable_sriov(struct pci_dev *dev); + +(b) 对于第二ç§æ–¹æ³•ï¼Œä»Žsysfs:: + + echo 0 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +è¦æƒ³é€šè¿‡ä¸»æœºä¸Šçš„兼容驱动å¯ç”¨è‡ªåŠ¨æŽ¢æµ‹VF，在å¯ç”¨SR-IOV功能之å‰è¿è¡Œä¸‹é¢çš„命令。这 +是默认的行为。 +:: + + echo 1 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe + +è¦ç¦æ¢ä¸»æœºä¸Šçš„兼容驱动自动探测VF，请在å¯ç”¨SR-IOV功能之å‰è¿è¡Œä»¥ä¸‹å‘½ä»¤ã€‚更新这个 +å…¥å£ä¸ä¼šå½±å“å·²ç»è¢«æŽ¢æµ‹çš„VF。 +:: + + echo 0 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe + +用例 +---- + +下é¢çš„代ç 演示了SR-IOV API的用法 +:: + + static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) + { + pci_enable_sriov(dev, NR_VIRTFN); + + ... + + return 0; + } + + static void dev_remove(struct pci_dev *dev) + { + pci_disable_sriov(dev); + + ... + } + + static int dev_suspend(struct pci_dev *dev, pm_message_t state) + { + ... + + return 0; + } + + static int dev_resume(struct pci_dev *dev) + { + ... + + return 0; + } + + static void dev_shutdown(struct pci_dev *dev) + { + ... + } + + static int dev_sriov_configure(struct pci_dev *dev, int numvfs) + { + if (numvfs > 0) { + ... + pci_enable_sriov(dev, numvfs); + ... + return numvfs; + } + if (numvfs == 0) { + .... + pci_disable_sriov(dev); + ... + return 0; + } + } + + static struct pci_driver dev_driver = { + .name = "SR-IOV Physical Function driver", + .id_table = dev_id_table, + .probe = dev_probe, + .remove = dev_remove, + .suspend = dev_suspend, + .resume = dev_resume, + .shutdown = dev_shutdown, + .sriov_configure = dev_sriov_configure, + }; diff --git a/Documentation/translations/zh_CN/PCI/pciebus-howto.rst b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst new file mode 100644 index 000000000000..65c4301f12cd --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pciebus-howto.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +.. _cn_pciebus-howto: + +=========================== +PCI Express端å£æ€»çº¿é©±åŠ¨æŒ‡å— +=========================== + +:作者: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004 +:版æƒ: |copy| 2004 Intel Corporation + +å…³äºŽæœ¬æŒ‡å— +========== + +本指å—介ç»äº†PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºçš„基本知识，并æ供了如何使æœåŠ¡é©± +动程åºåœ¨PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºä¸æ³¨å†Œ/å–消注册的介ç»ã€‚ + + +什么是PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åº +================================= + +一个PCI Express端å£æ˜¯ä¸€ä¸ªé€»è¾‘çš„PCI-PCI桥结构。有两ç§ç±»åž‹çš„PCI Express端 +å£ï¼šæ ¹ç«¯å£å’Œäº¤æ¢ç«¯å£ã€‚æ ¹ç«¯å£ä»ŽPCI Expressæ ¹ç»¼åˆä½“å‘起一个PCI Express链接， +交æ¢ç«¯å£å°†PCI Express链接连接到内部逻辑PCI总线。交æ¢æœºç«¯å£ï¼Œå…¶äºŒçº§æ€»çº¿ä»£è¡¨ +交æ¢æœºçš„内部路由逻辑，被称为交æ¢æœºçš„上行端å£ã€‚交æ¢æœºçš„下行端å£æ˜¯ä»Žäº¤æ¢æœºçš„内部 +路由总线桥接到代表æ¥è‡ªPCI Express交æ¢æœºçš„下游PCI Express链接的总线。 + +一个PCI Express端å£å¯ä»¥æ供多达四个ä¸åŒçš„功能，在本文ä¸è¢«ç§°ä¸ºæœåŠ¡ï¼Œè¿™å–决于 +其端å£ç±»åž‹ã€‚PCI Express端å£çš„æœåŠ¡åŒ…括本地çƒæ‹”æ’支æŒï¼ˆHP）ã€ç”µæºç®¡ç†äº‹ä»¶æ”¯æŒï¼ˆPME）〠+高级错误报告支æŒï¼ˆAER）和虚拟通é“支æŒï¼ˆVC）。这些æœåŠ¡å¯ä»¥ç”±ä¸€ä¸ªå¤æ‚çš„é©±åŠ¨ç¨‹åº +处ç†ï¼Œä¹Ÿå¯ä»¥å•ç‹¬åˆ†å¸ƒå¹¶ç”±ç›¸åº”çš„æœåŠ¡é©±åŠ¨ç¨‹åºå¤„ç†ã€‚ + +为什么è¦ä½¿ç”¨PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºï¼Ÿ +========================================= + +在现有的Linuxå†…æ ¸ä¸ï¼ŒLinux设备驱动模型å…许一个物ç†è®¾å¤‡åªç”±ä¸€ä¸ªé©±åŠ¨å¤„ç†ã€‚ +PCI Express端å£æ˜¯ä¸€ä¸ªå…·æœ‰å¤šä¸ªä¸åŒæœåŠ¡çš„PCI-PCI桥设备。为了ä¿æŒä¸€ä¸ªå¹²å‡€å’Œç®€ +å•çš„解决方案，æ¯ä¸ªæœåŠ¡éƒ½å¯ä»¥æœ‰è‡ªå·±çš„软件æœåŠ¡é©±åŠ¨ã€‚在这ç§æƒ…å†µä¸‹ï¼Œå‡ ä¸ªæœåŠ¡é©±åŠ¨å°† +竞争一个PCI-PCI桥设备。例如，如果PCI Expressæ ¹ç«¯å£çš„本机çƒæ‹”æ’æœåŠ¡é©±åŠ¨ç¨‹åº +é¦–å…ˆè¢«åŠ è½½ï¼Œå®ƒå°±ä¼šè¦æ±‚一个PCI-PCIæ¡¥æ ¹ç«¯å£ã€‚å› æ¤ï¼Œå†…æ ¸ä¸ä¼šä¸ºè¯¥æ ¹ç«¯å£åŠ è½½å…¶ä»–æœ +务驱动。æ¢å¥è¯è¯´ï¼Œä½¿ç”¨å½“å‰çš„驱动模型，ä¸å¯èƒ½è®©å¤šä¸ªæœåŠ¡é©±åŠ¨åŒæ—¶åŠ 载并è¿è¡Œåœ¨ +PCI-PCI桥设备上。 + +为了使多个æœåŠ¡é©±åŠ¨ç¨‹åºåŒæ—¶è¿è¡Œï¼Œéœ€è¦æœ‰ä¸€ä¸ªPCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºï¼Œå®ƒç®¡ +ç†æ‰€æœ‰å¡«å……çš„PCI Express端å£ï¼Œå¹¶æ ¹æ®éœ€è¦å°†æ‰€æœ‰æ供的æœåŠ¡è¯·æ±‚分é…给相应的æœåŠ¡ +驱动程åºã€‚下é¢åˆ—出了使用PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºçš„一些关键优势: + + - å…许在一个PCI-PCI桥接端å£è®¾å¤‡ä¸ŠåŒæ—¶è¿è¡Œå¤šä¸ªæœåŠ¡é©±åŠ¨ã€‚ + + - å…许以独立的分阶段方å¼å®žæ–½æœåŠ¡é©±åŠ¨ç¨‹åºã€‚ + + - å…许一个æœåŠ¡é©±åŠ¨ç¨‹åºåœ¨å¤šä¸ªPCI-PCI桥接端å£è®¾å¤‡ä¸Šè¿è¡Œã€‚ + + - 管ç†å’Œåˆ†é…PCI-PCI桥接端å£è®¾å¤‡çš„资æºç»™è¦æ±‚çš„æœåŠ¡é©±åŠ¨ç¨‹åºã€‚ + +é…ç½®PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºä¸ŽæœåŠ¡é©±åŠ¨ç¨‹åº +============================================= + +å°†PCI Express端å£æ€»çº¿é©±åŠ¨æ”¯æŒçº³å…¥å†…æ ¸ +------------------------------------- + +包括PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºå–å†³äºŽå†…æ ¸é…ç½®ä¸æ˜¯å¦åŒ…å«PCI Express支æŒã€‚å½“å†…æ ¸ +ä¸çš„PCI Express支æŒè¢«å¯ç”¨æ—¶ï¼Œå†…æ ¸å°†è‡ªåŠ¨åŒ…å«PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºä½œä¸ºå†…æ ¸ +驱动程åºã€‚ + +å¯ç”¨æœåŠ¡é©±åŠ¨æ”¯æŒ +---------------- + +PCI设备驱动是基于Linux设备驱动模型实现的。所有的æœåŠ¡é©±åŠ¨éƒ½æ˜¯PCI设备驱动。如上所述， +ä¸€æ—¦å†…æ ¸åŠ è½½äº†PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºï¼Œå°±ä¸å¯èƒ½å†åŠ 载任何æœåŠ¡é©±åŠ¨ç¨‹åºã€‚为了满 +足PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºæ¨¡åž‹ï¼Œéœ€è¦å¯¹çŽ°æœ‰çš„æœåŠ¡é©±åŠ¨ç¨‹åºè¿›è¡Œä¸€äº›æœ€å°çš„改å˜ï¼Œå…¶ +对现有的æœåŠ¡é©±åŠ¨ç¨‹åºçš„功能没有影å“。 + +æœåŠ¡é©±åŠ¨ç¨‹åºéœ€è¦ä½¿ç”¨ä¸‹é¢æ‰€ç¤ºçš„两个API，将其æœåŠ¡æ³¨å†Œåˆ°PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹ +åºä¸ï¼ˆè§ç¬¬5.2.1å’Œ5.2.2节）。在调用这些API之å‰ï¼ŒæœåŠ¡é©±åŠ¨ç¨‹åºå¿…é¡»åˆå§‹åŒ–头文件 +/include/linux/pcieport_if.hä¸çš„pcie_port_service_driveræ•°æ®ç»“构。如果ä¸è¿™ +æ ·åšï¼Œå°†å¯¼è‡´èº«ä»½ä¸åŒ¹é…，从而使PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºæ— æ³•åŠ è½½æœåŠ¡é©±åŠ¨ç¨‹åºã€‚ + +pcie_port_service_register +~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + int pcie_port_service_register(struct pcie_port_service_driver *new) + +这个APIå–代了Linux驱动模型的 pci_register_driver API。一个æœåŠ¡é©±åŠ¨åº”该总是在模 +å—å¯åŠ¨æ—¶è°ƒç”¨ pcie_port_service_register。请注æ„，在æœåŠ¡é©±åŠ¨è¢«åŠ è½½åŽï¼Œè¯¸å¦‚ +pci_enable_device(dev) å’Œ pci_set_master(dev) 的调用ä¸å†éœ€è¦ï¼Œå› 为这些调用由 +PCI端å£æ€»çº¿é©±åŠ¨æ‰§è¡Œã€‚ + +pcie_port_service_unregister +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + void pcie_port_service_unregister(struct pcie_port_service_driver *new) + +pcie_port_service_unregisterå–代了Linux驱动模型的pci_unregister_driver。当一 +个模å—退出时，它总是被æœåŠ¡é©±åŠ¨è°ƒç”¨ã€‚ + +示例代ç +~~~~~~~~ + +下é¢æ˜¯æœåŠ¡é©±åŠ¨ä»£ç 示例，用于åˆå§‹åŒ–端å£æœåŠ¡çš„驱动程åºæ•°æ®ç»“构。 +:: + + static struct pcie_port_service_id service_id[] = { { + .vendor = PCI_ANY_ID, + .device = PCI_ANY_ID, + .port_type = PCIE_RC_PORT, + .service_type = PCIE_PORT_SERVICE_AER, + }, { /* end: all zeroes */ } + }; + + static struct pcie_port_service_driver root_aerdrv = { + .name = (char *)device_name, + .id_table = &service_id[0], + + .probe = aerdrv_load, + .remove = aerdrv_unload, + + .suspend = aerdrv_suspend, + .resume = aerdrv_resume, + }; + +下é¢æ˜¯ä¸€ä¸ªæ³¨å†Œ/å–消注册æœåŠ¡é©±åŠ¨çš„示例代ç 。 +:: + + static int __init aerdrv_service_init(void) + { + int retval = 0; + + retval = pcie_port_service_register(&root_aerdrv); + if (!retval) { + /* + * FIX ME + */ + } + return retval; + } + + static void __exit aerdrv_service_exit(void) + { + pcie_port_service_unregister(&root_aerdrv); + } + + module_init(aerdrv_service_init); + module_exit(aerdrv_service_exit); + +å¯èƒ½çš„资æºå†²çª +============== + +由于PCI-PCI桥接端å£è®¾å¤‡çš„所有æœåŠ¡é©±åŠ¨è¢«å…许åŒæ—¶è¿è¡Œï¼Œä¸‹é¢åˆ—出了一些å¯èƒ½çš„资æºå†²çªå’Œ +建议的解决方案。 + +MSI å’Œ MSI-X å‘é‡èµ„æº +--------------------- + +一旦设备上的MSI或MSI-Xä¸æ–被å¯ç”¨ï¼Œå®ƒå°±ä¼šä¸€ç›´ä¿æŒè¿™ç§æ¨¡å¼ï¼Œç›´åˆ°å®ƒä»¬å†æ¬¡è¢«ç¦ç”¨ã€‚ç”±äºŽåŒ +一个PCI-PCI桥接端å£çš„æœåŠ¡é©±åŠ¨ç¨‹åºå…±äº«åŒä¸€ä¸ªç‰©ç†è®¾å¤‡ï¼Œå¦‚果一个å•ç‹¬çš„æœåŠ¡é©±åŠ¨ç¨‹åºå¯ç”¨æˆ– +ç¦ç”¨MSI/MSI-X模å¼ï¼Œå¯èƒ½ä¼šå¯¼è‡´ä¸å¯é¢„知的行为。 + +为了é¿å…è¿™ç§æƒ…况，所有的æœåŠ¡é©±åŠ¨ç¨‹åºéƒ½ä¸å…许在其设备上切æ¢ä¸æ–模å¼ã€‚PCI Expressç«¯å£ +总线驱动程åºè´Ÿè´£ç¡®å®šä¸æ–模å¼ï¼Œè¿™å¯¹æœåŠ¡é©±åŠ¨ç¨‹åºæ¥è¯´åº”该是é€æ˜Žçš„。æœåŠ¡é©±åŠ¨ç¨‹åºåªéœ€è¦çŸ¥é“ +分é…给结构体pcie_deviceçš„å—段irqçš„å‘é‡IRQ，当PCI Express端å£æ€»çº¿é©±åŠ¨ç¨‹åºæŽ¢æµ‹æ¯ +个æœåŠ¡é©±åŠ¨ç¨‹åºæ—¶ï¼Œå®ƒè¢«ä¼ 入。æœåŠ¡é©±åŠ¨åº”该使用（struct pcie_device*）dev->irqæ¥è°ƒç”¨ +request_irq/free_irq。æ¤å¤–，ä¸æ–模å¼è¢«å˜å‚¨åœ¨struct pcie_deviceçš„interrupt_mode +å—段ä¸ã€‚ + +PCI内å˜/IOæ˜ å°„çš„åŒºåŸŸ +-------------------- + +PCI Express电æºç®¡ç†ï¼ˆPME）ã€é«˜çº§é”™è¯¯æŠ¥å‘Šï¼ˆAER）ã€çƒæ’拔（HP）和虚拟通é“（VC）的æœåŠ¡ +驱动程åºè®¿é—®PCI Express端å£çš„PCIé…置空间。在所有情况下，访问的寄å˜å™¨æ˜¯ç›¸äº’独立的。这 +个补ä¸å‡å®šæ‰€æœ‰çš„æœåŠ¡é©±åŠ¨ç¨‹åºéƒ½ä¼šè¡¨çŽ°è‰¯å¥½ï¼Œä¸ä¼šè¦†ç›–其他æœåŠ¡é©±åŠ¨ç¨‹åºçš„é…置设置。 + +PCIé…置寄å˜å™¨ +------------- + +æ¯ä¸ªæœåŠ¡é©±åŠ¨éƒ½åœ¨è‡ªå·±çš„功能结构体上è¿è¡ŒPCIé…ç½®æ“作，除了PCI Express功能结构体，其ä¸æ ¹æŽ§åˆ¶ +寄å˜å™¨å’Œè®¾å¤‡æŽ§åˆ¶å¯„å˜å™¨æ˜¯åœ¨PMEå’ŒAER之间共享。这个补ä¸å‡å®šæ‰€æœ‰çš„æœåŠ¡é©±åŠ¨éƒ½ä¼šè¡¨çŽ°è‰¯å¥½ï¼Œä¸ä¼š +覆盖其他æœåŠ¡é©±åŠ¨çš„é…置设置。 diff --git a/Documentation/translations/zh_CN/PCI/sysfs-pci.rst b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst new file mode 100644 index 000000000000..0d75c2e99d52 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/sysfs-pci.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +======================== +通过sysfs访问PCIè®¾å¤‡èµ„æº +======================== + +sysfs，通常挂载在/sys，在支æŒå®ƒçš„å¹³å°ä¸Šæ供对PCI资æºçš„访问。例如，一个特定的总线å¯èƒ½çœ‹èµ· +æ¥åƒè¿™æ ·:: + + /sys/devices/pci0000:17 + |-- 0000:17:00.0 + | |-- class + | |-- config + | |-- device + | |-- enable + | |-- irq + | |-- local_cpus + | |-- remove + | |-- resource + | |-- resource0 + | |-- resource1 + | |-- resource2 + | |-- revision + | |-- rom + | |-- subsystem_device + | |-- subsystem_vendor + | `-- vendor + `-- ... + +最上é¢çš„å…ƒç´ æ述了PCI域和总线å·ç 。在这ç§æƒ…况下，域å·æ˜¯0000，总线å·æ˜¯17（两个值都是åå…进制）。 +这个总线在0å·æ’槽ä¸åŒ…å«ä¸€ä¸ªå•ä¸€åŠŸèƒ½çš„设备。为了方便起è§ï¼Œæˆ‘们å¤åˆ¶äº†åŸŸå’Œæ€»çº¿çš„ç¼–å·ã€‚在设备目录 +ä¸‹æœ‰å‡ ä¸ªæ–‡ä»¶ï¼Œæ¯ä¸ªæ–‡ä»¶éƒ½æœ‰è‡ªå·±çš„功能。 + + =================== ===================================================== + 文件 功能 + =================== ===================================================== + class PCI级别 (ascii, ro) + config PCIé…置空间 (binary, rw) + device PCI设备 (ascii, ro) + enable 设备是å¦è¢«å¯ç”¨ (ascii, rw) + irq IRQç¼–å· (ascii, ro) + local_cpus 临近CPU掩ç (cpumask, ro) + remove ä»Žå†…æ ¸çš„åˆ—è¡¨ä¸åˆ 除设备 (ascii, wo) + resource PCI资æºä¸»æœºåœ°å€ (ascii, ro) + resource0..N PCI资æºN，如果å˜åœ¨çš„è¯ (binary, mmap, rw\ [1]_) + resource0_wc..N_wc PCI WCæ˜ å°„èµ„æºN，如果å¯é¢„å–çš„è¯ (binary, mmap) + revision PCI修订版 (ascii, ro) + rom PCI ROM资æºï¼Œå¦‚æžœå˜åœ¨çš„è¯ (binary, ro) + subsystem_device PCIå系统设备 (ascii, ro) + subsystem_vendor PCIå系统供应商 (ascii, ro) + vendor PCI供应商 (ascii, ro) + =================== ===================================================== + +:: + + ro - åªè¯»æ–‡ä»¶ + rw - 文件是å¯è¯»å’Œå¯å†™çš„ + wo - åªå†™æ–‡ä»¶ + mmap - 文件是å¯ç§»åŠ¨çš„ + ascii - 文件包å«ascii文本 + binary - 文件包å«äºŒè¿›åˆ¶æ•°æ® + cpumask - 文件包å«ä¸€ä¸ªcpumask类型的 + +.. [1] rw 仅适用于 IORESOURCE_IO（I/O 端å£ï¼‰åŒºåŸŸ + +åªè¯»æ–‡ä»¶æ˜¯ä¿¡æ¯æ€§çš„，对它们的写入将被忽略，但 "rom "文件除外。å¯å†™æ–‡ä»¶å¯ä»¥ç”¨æ¥åœ¨è®¾å¤‡ä¸Šæ‰§ +è¡Œæ“作（例如，改å˜é…置空间，分离设备）。 mmapable文件å¯ä»¥é€šè¿‡å移é‡ä¸º0的文件的mmap获得， +å¯ä»¥ç”¨æ¥ä»Žç”¨æˆ·ç©ºé—´è¿›è¡Œå®žé™…的设备编程。注æ„，有些平å°ä¸æ”¯æŒæŸäº›èµ„æºçš„mmappingï¼Œæ‰€ä»¥ä¸€å®šè¦ +检查任何å°è¯•çš„mmap的返回值。其ä¸æœ€å€¼å¾—注æ„的是I/O端å£èµ„æºï¼Œå®ƒä¹Ÿæ供读/写访问。 + +enable "文件æ供了一个计数器，表明设备已ç»è¢«å¯ç”¨äº†å¤šå°‘次。如果'enable'文件目å‰è¿”回'4'， +而一个'1'被呼入它，它将返回'5'。å‘它呼入一个'0'会å‡å°‘计数。ä¸è¿‡ï¼Œå³ä½¿å®ƒè¿”回到0，一些åˆå§‹ +化å¯èƒ½ä¹Ÿä¸ä¼šè¢«é€†è½¬ã€‚ + +rom "æ–‡ä»¶å¾ˆç‰¹åˆ«ï¼Œå› ä¸ºå®ƒæ供了对设备ROM文件的åªè¯»è®¿é—®ï¼Œå¦‚果有的è¯ã€‚然而，它在默认情况下是 +ç¦ç”¨çš„，所以应用程åºåº”该在å°è¯•è¯»å–调用之å‰å°†å—符串 "1 "写入该文件以å¯ç”¨å®ƒï¼Œå¹¶åœ¨è®¿é—®ä¹‹åŽå°† +"0 "写入该文件以ç¦ç”¨å®ƒã€‚请注æ„，设备必须被å¯ç”¨ï¼Œæ‰èƒ½æˆåŠŸè¿”回数æ®ã€‚如果驱动没有被绑定到设备 +上，å¯ä»¥ä½¿ç”¨ä¸Šé¢æ到的 "enable "文件将其å¯ç”¨ã€‚ + +remove "文件是用æ¥ç§»é™¤PCI设备的，通过å‘该文件写入一个éžé›¶çš„整数。这并ä¸æ¶‰åŠä»»ä½•å½¢å¼çš„çƒæ’ +拔功能，例如关é—设备的电æºã€‚è¯¥è®¾å¤‡è¢«ä»Žå†…æ ¸çš„PCI设备列表ä¸ç§»é™¤ï¼Œå®ƒçš„sysfs目录被移除，并且该 +设备将被从任何连接到它的驱动程åºä¸ç§»é™¤ã€‚移除PCIæ ¹æ€»çº¿æ˜¯ä¸å…许的。 + +通过sysfsè®¿é—®åŽŸæœ‰èµ„æº +--------------------- + +如果底层平å°æ”¯æŒçš„è¯ï¼Œä¼ 统的I/O端å£å’ŒISA内å˜èµ„æºä¹Ÿä¼šåœ¨sysfsä¸æ供。它们ä½äºŽPCI类的层次结构 +ä¸ï¼Œä¾‹å¦‚:: + + /sys/class/pci_bus/0000:17/ + |-- bridge -> ../../../devices/pci0000:17 + |-- cpuaffinity + |-- legacy_io + `-- legacy_mem + +legacy_io文件是一个读/写文件，å¯ä»¥è¢«åº”用程åºç”¨æ¥åšä¼ 统的端å£I/O。应用程åºåº”该打开该文件，寻 +找所需的端å£ï¼ˆä¾‹å¦‚0x3e8），并进行1ã€2或4å—节的读或写。legacy_mem文件应该被mmapped，其å移 +é‡ä¸Žæ‰€éœ€çš„内å˜å移é‡ç›¸å¯¹åº”，例如0xa0000用于VGA帧缓冲器。然åŽï¼Œåº”用程åºå¯ä»¥ç®€å•åœ°è§£é™¤å¼•ç”¨è¿”回 +的指针（当然是在检查了错误之åŽï¼‰æ¥è®¿é—®é—留内å˜ç©ºé—´ã€‚ + +支æŒæ–°å¹³å°ä¸Šçš„PCI访问 +--------------------- + +为了支æŒä¸Šè¿°çš„PCI资æºæ˜ 射，Linuxå¹³å°ä»£ç 最好定义ARCH_GENERIC_PCI_MMAP_RESOURCE并使用该 +功能的通用实现。为了支æŒé€šè¿‡/proc/bus/pciä¸çš„文件实现mmap()的历å²æŽ¥å£ï¼Œå¹³å°ä¹Ÿå¯ä»¥è®¾ç½® +HAVE_PCI_MMAP。 + +å¦å¤–，设置了 HAVE_PCI_MMAP çš„å¹³å°å¯ä»¥æ供他们自己的 pci_mmap_page_range() 实现，而ä¸æ˜¯å®š +义 ARCH_GENERIC_PCI_MMAP_RESOURCE。 + +支æŒPCI资æºçš„写组åˆæ˜ å°„çš„å¹³å°å¿…须定义arch_can_pci_mmap_wc()，当写组åˆè¢«å…许时，在è¿è¡Œæ—¶åº” +评估为éžé›¶ã€‚支æŒI/O资æºæ˜ å°„çš„å¹³å°åŒæ ·å®šä¹‰arch_can_pci_mmap_io()。 + +é—留资æºç”±HAVE_PCI_LEGACY定义ä¿æŠ¤ã€‚希望支æŒé—留功能的平å°åº”该定义它并æä¾› pci_legacy_read, +pci_legacy_write å’Œ pci_mmap_legacy_page_range 函数。 diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst new file mode 100644 index 000000000000..f1849411018e --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -0,0 +1,109 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/delay-accounting.rst + +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +======== +延时计数 +======== + +任务在ç‰å¾…æŸäº›å†…æ ¸èµ„æºå¯ç”¨æ—¶ï¼Œä¼šé€ æˆå»¶æ—¶ã€‚例如一个å¯è¿è¡Œçš„任务å¯èƒ½ä¼šç‰å¾… +一个空闲CPUæ¥è¿è¡Œã€‚ + +基于æ¯ä»»åŠ¡çš„延时计数功能度é‡ç”±ä»¥ä¸‹æƒ…å†µé€ æˆçš„任务延时： + +a) ç‰å¾…一个CPU（任务为å¯è¿è¡Œï¼‰ +b) 完æˆç”±è¯¥ä»»åŠ¡å‘èµ·çš„å—I/OåŒæ¥è¯·æ±‚ +c) 页é¢äº¤æ¢ +d) 内å˜å›žæ”¶ +e) 页缓å˜æŠ–动 +f) 直接规整 + +并将这些统计信æ¯é€šè¿‡taskstats接å£æ供给用户空间。 + +这些延时信æ¯ä¸ºé€‚当的调整任务CPU优先级ã€io优先级ã€rssé™åˆ¶æä¾›å馈。é‡è¦ä»»åŠ¡ +长期延时，表示å¯èƒ½éœ€è¦æ高其相关优先级。 + +通过使用taskstats接å£ï¼Œæœ¬åŠŸèƒ½è¿˜å¯æä¾›ä¸€ä¸ªçº¿ç¨‹ç»„ï¼ˆå¯¹åº”ä¼ ç»ŸUnix进程）所有任务 +（或线程）的总延时统计信æ¯ã€‚æ¤ç±»æ±‡æ€»å¾€å¾€æ˜¯éœ€è¦çš„ï¼Œç”±å†…æ ¸æ¥å®Œæˆæ›´åŠ 高效。 + +用户空间的实体，特别是资æºç®¡ç†ç¨‹åºï¼Œå¯å°†å»¶æ—¶ç»Ÿè®¡ä¿¡æ¯æ±‡æ€»åˆ°ä»»æ„组ä¸ã€‚为实现 +这一点，任务的延时统计信æ¯åœ¨å…¶ç”Ÿå‘½å‘¨æœŸå†…和退出时皆å¯èŽ·å–，从而确ä¿å¯è¿›è¡Œ +è¿žç»ã€å®Œæ•´çš„监控。 + +æŽ¥å£ +---- + +延时计数使用taskstats接å£ï¼Œè¯¥æŽ¥å£ç”±æœ¬ç›®å½•å¦ä¸€ä¸ªå•ç‹¬çš„文档详细æ述。Taskstats +å‘用户æ€è¿”回一个通用数æ®ç»“构，对应æ¯pid或æ¯tgid的统计信æ¯ã€‚延时计数功能填写 +该数æ®ç»“构的特定å—æ®µã€‚è§ + + include/uapi/linux/taskstats.h + +å…¶æ述了延时计数相关å—段。系统通常以计数器形å¼è¿”回 CPUã€åŒæ¥å— I/Oã€äº¤æ¢ã€å†…å˜ +回收ã€é¡µç¼“å˜æŠ–动ã€ç›´æŽ¥è§„æ•´ç‰çš„累积延时。 + +å–任务æŸè®¡æ•°å™¨ä¸¤ä¸ªè¿žç»è¯»æ•°çš„差值，将得到任务在该时间间隔内ç‰å¾…对应资æºçš„总延时。 + +å½“ä»»åŠ¡é€€å‡ºæ—¶ï¼Œå†…æ ¸ä¼šå°†åŒ…å«æ¯ä»»åŠ¡çš„统计信æ¯å‘é€ç»™ç”¨æˆ·ç©ºé—´ï¼Œè€Œæ— 需é¢å¤–的命令。 +若其为线程组最åŽä¸€ä¸ªé€€å‡ºçš„ä»»åŠ¡ï¼Œå†…æ ¸è¿˜ä¼šå‘é€æ¯tgid的统计信æ¯ã€‚更多详细信æ¯è§ +taskstats接å£çš„æ述。 + +tools/accounting目录ä¸çš„用户空间程åºgetdelays.cæ供了一些简å•çš„命令，用以显示 +延时统计信æ¯ã€‚其也是使用taskstats接å£çš„示例。 + +用法 +---- + +使用以下é…ç½®ç¼–è¯‘å†…æ ¸:: + + CONFIG_TASK_DELAY_ACCT=y + CONFIG_TASKSTATS=y + +延时计数在å¯åŠ¨æ—¶é»˜è®¤å…³é—。 +若需开å¯ï¼Œåœ¨å¯åŠ¨å‚æ•°ä¸å¢žåŠ :: + + delayacct + +本文åŽç»çš„说明基于延时计数已开å¯ã€‚也å¯åœ¨ç³»ç»Ÿè¿è¡Œæ—¶ï¼Œä½¿ç”¨sysctlçš„ +kernel.task_delayacct进行开关。注æ„，åªæœ‰åœ¨å¯ç”¨å»¶æ—¶è®¡æ•°åŽå¯åŠ¨çš„ +任务æ‰ä¼šæœ‰ç›¸å…³ä¿¡æ¯ã€‚ + +系统å¯åŠ¨åŽï¼Œä½¿ç”¨ç±»ä¼¼getdelays.c的工具获å–任务或线程组（tgid）的延时信æ¯ã€‚ + +getdelayså‘½ä»¤çš„ä¸€èˆ¬æ ¼å¼:: + + getdelays [-dilv] [-t tgid] [-p pid] + +获å–pid为10的任务从系统å¯åŠ¨åŽçš„延时信æ¯:: + + # ./getdelays -d -p 10 + （输出信æ¯å’Œä¸‹ä¾‹ç›¸ä¼¼ï¼‰ + +获å–所有tgid为5的任务从系统å¯åŠ¨åŽçš„总延时信æ¯:: + + # ./getdelays -d -t 5 + print delayacct stats ON + TGID 5 + + + CPU count real total virtual total delay total delay average + 8 7000000 6872122 3382277 0.423ms + IO count delay total delay average + 0 0 0ms + SWAP count delay total delay average + 0 0 0ms + RECLAIM count delay total delay average + 0 0 0ms + THRASHING count delay total delay average + 0 0 0ms + COMPACT count delay total delay average + 0 0 0ms + +获å–pid为1çš„IO计数，它åªå’Œ-p一起使用:: + # ./getdelays -i -p 1 + printing IO accounting + linuxrc: read=65536, write=0, cancelled_write=0 + +上é¢çš„命令与-v一起使用，å¯ä»¥èŽ·å–更多调试信æ¯ã€‚ diff --git a/Documentation/translations/zh_CN/accounting/index.rst b/Documentation/translations/zh_CN/accounting/index.rst index 362e907b41f9..a34952e12a27 100644 --- a/Documentation/translations/zh_CN/accounting/index.rst +++ b/Documentation/translations/zh_CN/accounting/index.rst @@ -15,11 +15,11 @@ .. toctree:: :maxdepth: 1 + delay-accounting psi + taskstats Todolist: cgroupstats - delay-accounting - taskstats taskstats-struct diff --git a/Documentation/translations/zh_CN/accounting/taskstats.rst b/Documentation/translations/zh_CN/accounting/taskstats.rst new file mode 100644 index 000000000000..307ac5ce0e4b --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/taskstats.rst @@ -0,0 +1,145 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/taskstats.rst + +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +================ +æ¯ä»»åŠ¡çš„ç»Ÿè®¡æŽ¥å£ +================ + +Taskstats是一个基于netlink的接å£ï¼Œç”¨äºŽä»Žå†…æ ¸å‘用户空间å‘é€æ¯ä»»åŠ¡åŠæ¯è¿›ç¨‹çš„ +统计信æ¯ã€‚ + +Taskstats设计目的： + +- 在任务生命周期内和退出时高效的æä¾›ç»Ÿè®¡ä¿¡æ¯ +- 统一ä¸åŒè®¡æ•°åç³»ç»Ÿçš„æŽ¥å£ +- 支æŒæœªæ¥è®¡æ•°ç³»ç»Ÿçš„扩展 + +æœ¯è¯ +---- + +“pidâ€ã€â€œtidâ€ã€â€œä»»åŠ¡â€äº’æ¢ä½¿ç”¨ï¼Œç”¨äºŽæè¿°ç”±struct task_structå®šä¹‰çš„æ ‡å‡† +Linux任务。“æ¯pid的统计数æ®â€ç‰ä»·äºŽâ€œæ¯ä»»åŠ¡çš„统计数æ®â€ã€‚ + +“tgidâ€ã€â€œè¿›ç¨‹â€ã€â€œçº¿ç¨‹ç»„â€äº’æ¢ä½¿ç”¨ï¼Œç”¨äºŽæ述共享mm_struct的任务集， +ä¹Ÿå°±æ˜¯ä¼ ç»Ÿçš„Unix进程。尽管使用了tgid这个è¯ï¼Œå³ä½¿ä¸€ä¸ªä»»åŠ¡æ˜¯çº¿ç¨‹ç»„组长， +对它的处ç†ä¹Ÿæ²¡æœ‰ä»€ä¹ˆä¸åŒã€‚åªè¦ä¸€ä¸ªè¿›ç¨‹è¿˜æœ‰ä»»ä½•å½’属它的任务，它就被认为 +æ´»ç€ã€‚ + +用法 +---- + +为了在任务生命周期内获得统计信æ¯ï¼Œç”¨æˆ·ç©ºé—´éœ€æ‰“开一个å•æ’çš„netlinkå¥—æŽ¥å— +（NETLINK_GENERICæ—）然åŽå‘é€æŒ‡å®špid或tgid的命令。å“应消æ¯ä¸åŒ…å«å•ä¸ª +任务的统计信æ¯ï¼ˆè‹¥æŒ‡å®šäº†pid）或进程所有任务汇总的统计信æ¯ï¼ˆè‹¥æŒ‡å®šäº†tgid）。 + +为了在任务退出时获å–统计信æ¯ï¼Œç”¨æˆ·ç©ºé—´çš„监å¬è€…å‘é€ä¸€ä¸ªæŒ‡å®šcpu掩ç 的注册命令。 +cpu掩ç 内的cpu上有任务退出时，æ¯pid的统计信æ¯å°†å‘é€ç»™æ³¨å†ŒæˆåŠŸçš„监å¬è€…。使用 +cpu掩ç å¯ä»¥é™åˆ¶ä¸€ä¸ªç›‘å¬è€…收到的数æ®ï¼Œå¹¶æœ‰åŠ©äºŽå¯¹netlink接å£è¿›è¡Œæµé‡æŽ§åˆ¶ï¼ŒåŽæ–‡ +将进行更详细的解释。 + +如果æ£åœ¨é€€å‡ºçš„任务是线程组ä¸æœ€åŽä¸€ä¸ªé€€å‡ºçš„线程，é¢å¤–一æ¡åŒ…å«æ¯tgid统计信æ¯çš„ +记录也将å‘é€ç»™ç”¨æˆ·ç©ºé—´ã€‚åŽè€…包å«çº¿ç¨‹ç»„ä¸æ‰€æœ‰çº¿ç¨‹ï¼ˆåŒ…括过去和现在）的æ¯pid统计 +ä¿¡æ¯æ€»å’Œã€‚ + +getdelays.c是一个简å•çš„示例，用以演示如何使用taskstats接å£èŽ·å–延迟统计信æ¯ã€‚ +用户å¯æ³¨å†Œcpu掩ç ã€å‘é€å‘½ä»¤å’Œå¤„ç†å“应ã€ç›‘å¬æ¯tid/tgid退出数æ®ã€å°†æ”¶åˆ°çš„æ•°æ® +写入文件ã€é€šè¿‡å¢žå¤§æŽ¥æ”¶ç¼“冲区进行基本的æµé‡æŽ§åˆ¶ã€‚ + +æŽ¥å£ +---- + +å†…æ ¸ç”¨æˆ·æŽ¥å£å°è£…在include/linux/taskstats.h。 + +为é¿å…本文档éšç€æŽ¥å£çš„演进而过期，本文仅给出当å‰ç‰ˆæœ¬çš„概è¦ã€‚当本文与taskstats.h +ä¸ä¸€è‡´æ—¶ï¼Œä»¥taskstats.h为准。 + +struct taskstats是æ¯pidå’Œæ¯tgidæ•°æ®å…±ç”¨çš„计数结构体。它是版本化的，å¯åœ¨å†…æ ¸æ–°å¢ž +计数å系统时进行扩展。taskstats.hä¸å®šä¹‰äº†å„å—段åŠè¯ä¹‰ã€‚ + +用户ã€å†…æ ¸ç©ºé—´çš„æ•°æ®äº¤æ¢æ˜¯å±žäºŽNETLINK_GENERICæ—çš„netlink消æ¯ï¼Œä½¿ç”¨netlink属性 +接å£ã€‚消æ¯æ ¼å¼å¦‚下:: + + +----------+- - -+-------------+-------------------+ + | nlmsghdr | Pad | genlmsghdr | taskstats payload | + +----------+- - -+-------------+-------------------+ + +Taskstatsè½½è·æœ‰ä¸‰ç§ç±»åž‹ï¼š + +1. 命令：由用户å‘é€ç»™å†…æ ¸ã€‚èŽ·å–指定pid/tgidæ•°æ®çš„命令包å«ä¸€ä¸ªç±»åž‹ä¸º +TASKSTATS_CMD_ATTR_PID/TGID的属性，该属性包å«u32çš„pid或tgidè½½è·ã€‚ +pid/tgid指示用户空间è¦ç»Ÿè®¡çš„任务/进程。 + +注册/注销获å–指定cpu集上退出数æ®çš„命令包å«ä¸€ä¸ªç±»åž‹ä¸º +TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK的属性，该属性包å«cpu掩ç è½½è·ã€‚ +cpu掩ç 是以asciiç 表示，用逗å·åˆ†éš”çš„cpu范围。例如若需监å¬1,2,3,5,7,8å·cpuçš„ +退出数æ®ï¼Œcpu掩ç 表示为"1-3,5,7-8"。若用户空间在关é—监å¬å¥—接å—å‰å¿˜äº†æ³¨é”€ç›‘å¬ +çš„cpu集，éšç€æ—¶é—´çš„æŽ¨ç§»ï¼Œå†…æ ¸ä¼šæ¸…ç†æ¤ç›‘å¬é›†ã€‚但是，出于æ效的目的，建议明确 +执行注销。 + +2. 命令的应ç”ï¼šå†…æ ¸å‘出应ç”用户空间的命令。载è·æœ‰ä¸‰ç±»å±žæ€§ï¼š + +a) TASKSTATS_TYPE_AGGR_PID/TGID： 本属性ä¸åŒ…å«è½½è·ï¼Œç”¨ä»¥æŒ‡ç¤ºå…¶åŽä¸ºè¢«ç»Ÿè®¡å¯¹è±¡ +çš„pig/tgid。 + +b) TASKSTATS_TYPE_PID/TGID：本属性的载è·ä¸ºpig/tgid，其统计信æ¯å°†è¢«è¿”回。 + +c) TASKSTATS_TYPE_STATS：本属性的载è·ä¸ºä¸€ä¸ªstruct taskstats实例。æ¯pidå’Œ +æ¯tgid统计信æ¯å…±ç”¨è¯¥ç»“构体。 + +3. å†…æ ¸ä¼šåœ¨ä»»åŠ¡é€€å‡ºæ—¶å‘é€æ–°æ¶ˆæ¯ã€‚其载è·åŒ…å«ä¸€ç³»åˆ—以下类型的属性： + +a) TASKSTATS_TYPE_AGGR_PID：指示其åŽä¸¤ä¸ªå±žæ€§ä¸ºpid+stats。 +b) TASKSTATS_TYPE_PID：包å«é€€å‡ºä»»åŠ¡çš„pid。 +c) TASKSTATS_TYPE_STATS：包å«é€€å‡ºä»»åŠ¡çš„æ¯pidç»Ÿè®¡ä¿¡æ¯ +d) TASKSTATS_TYPE_AGGR_TGID：指示其åŽä¸¤ä¸ªå±žæ€§ä¸ºtgid+stats。 +e) TASKSTATS_TYPE_TGID：包å«ä»»åŠ¡æ‰€å±žè¿›ç¨‹çš„tgid +f) TASKSTATS_TYPE_STATS：包å«é€€å‡ºä»»åŠ¡æ‰€å±žè¿›ç¨‹çš„æ¯tgidç»Ÿè®¡ä¿¡æ¯ + +æ¯tgid的统计 +------------ + +除了æ¯ä»»åŠ¡çš„统计信æ¯ï¼Œtaskstats还æä¾›æ¯è¿›ç¨‹çš„统计信æ¯ï¼Œå› 为资æºç®¡ç†é€šå¸¸ä»¥è¿›ç¨‹ +粒度完æˆï¼Œå¹¶ä¸”仅在用户空间èšåˆä»»åŠ¡ç»Ÿè®¡ä¿¡æ¯æ•ˆçŽ‡ä½Žä¸‹ä¸”å¯èƒ½ä¸å‡†ç¡®ï¼ˆç¼ºä¹åŽŸå性）。 + +然而，除了æ¯ä»»åŠ¡ç»Ÿè®¡ä¿¡æ¯ï¼Œåœ¨å†…æ ¸ä¸ç»´æŠ¤æ¯è¿›ç¨‹ç»Ÿè®¡ä¿¡æ¯å˜åœ¨é¢å¤–的时间和空间开销。 +为解决æ¤é—®é¢˜ï¼Œtaskstats代ç 将退出任务的统计信æ¯ç´¯ç§¯åˆ°è¿›ç¨‹èŒƒå›´çš„æ•°æ®ç»“æž„ä¸ã€‚ +当进程最åŽä¸€ä¸ªä»»åŠ¡é€€å‡ºæ—¶ï¼Œç´¯ç§¯çš„进程级数æ®ä¹Ÿä¼šå‘é€åˆ°ç”¨æˆ·ç©ºé—´ï¼ˆä¸Žæ¯ä»»åŠ¡æ•°æ®ä¸€èµ·ï¼‰ã€‚ + +当用户查询æ¯tgidæ•°æ®æ—¶ï¼Œå†…æ ¸å°†æŒ‡å®šçº¿ç¨‹ç»„ä¸æ‰€æœ‰æ´»åŠ¨çº¿ç¨‹çš„统计信æ¯ç›¸åŠ ï¼Œå¹¶æ·»åŠ åˆ° +该线程组的累积总数（å«ä¹‹å‰é€€å‡ºçš„线程）。 + +扩展taskstats +------------- + +有两ç§æ–¹æ³•å¯åœ¨æœªæ¥ä¿®æ”¹å†…æ ¸æ‰©å±•taskstats接å£ï¼Œä»¥å¯¼å‡ºæ›´å¤šçš„æ¯ä»»åŠ¡/进程统计信æ¯ï¼š + +1. 在现有struct taskstatsæœ«å°¾å¢žåŠ å—段。该结构体ä¸çš„版本å·ç¡®ä¿äº†å‘åŽå…¼å®¹æ€§ã€‚ +用户空间将仅使用与其版本对应的结构体å—段。 + +2. 定义å•ç‹¬çš„统计结构体并使用netlink属性接å£è¿”回对应的数æ®ã€‚由于用户空间独立 +处ç†æ¯ä¸ªnetlink属性，所以总是å¯ä»¥å¿½ç•¥å…¶ä¸ç†è§£ç±»åž‹çš„å±žæ€§ï¼ˆå› ä¸ºä½¿ç”¨äº†æ—§ç‰ˆæœ¬æŽ¥å£ï¼‰ã€‚ + +在1.å’Œ2.之间进行选择，属于æƒè¡¡çµæ´»æ€§å’Œå¼€é”€çš„é—®é¢˜ã€‚è‹¥ä»…éœ€å¢žåŠ å°‘æ•°å—段，那么1.是 +é¦–é€‰æ–¹æ³•ï¼Œå› ä¸ºå†…æ ¸å’Œç”¨æˆ·ç©ºé—´æ— éœ€æ‰¿æ‹…å¤„ç†æ–°netlink属性的开销。但若新å—段过多的 +扩展现有结构体，导致ä¸åŒçš„用户空间计数程åºä¸å¿…è¦çš„接收大型结构体，而对结构体 +å—段并ä¸æ„Ÿå…´è¶£ï¼Œé‚£ä¹ˆ2.是值得的。 + +Taskstatsçš„æµé‡æŽ§åˆ¶ +------------------- + +当退出任务数速率å˜å¤§ï¼Œç›‘å¬è€…å¯èƒ½è·Ÿä¸ä¸Šå†…æ ¸å‘é€æ¯tid/tgid退出数æ®çš„速率，而导致 +æ•°æ®ä¸¢å¤±ã€‚taskstats结构体å˜å¤§ã€cpuæ•°é‡ä¸Šå‡ï¼Œéƒ½ä¼šå¯¼è‡´è¿™ç§å¯èƒ½æ€§å¢žåŠ 。 + +为é¿å…统计信æ¯ä¸¢å¤±ï¼Œç”¨æˆ·ç©ºé—´åº”执行以下æ“作ä¸è‡³å°‘一项： + +- 增大监å¬è€…用于接收退出数æ®çš„netlink套接å—接收缓å˜åŒºã€‚ + +- 创建更多的监å¬è€…，å‡å°‘æ¯ä¸ªç›‘å¬è€…监å¬çš„cpuæ•°é‡ã€‚æžç«¯æƒ…况下å¯ä¸ºæ¯ä¸ªcpu创建 + 一个监å¬è€…。用户还å¯è€ƒè™‘将监å¬è€…çš„cpu亲和性设置为监å¬cpuçš„å集，特别是当他们 + 仅监å¬ä¸€ä¸ªcpu。 + +尽管采å–了这些措施，若用户空间ä»æ”¶åˆ°æŒ‡ç¤ºæŽ¥æ”¶ç¼“å˜åŒºæº¢å‡ºçš„ENOBUFS错误消æ¯ï¼Œ +则应采å–其他措施处ç†æ•°æ®ä¸¢å¤±ã€‚ diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index 980eb20521cf..d20949e8bf6f 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -133,7 +133,7 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> å³ä½¿åªå‡çº§ä¸€ä¸ªå°ç‰ˆæœ¬ï¼Œä¹Ÿä¸è¦è·³è¿‡æ¤æ¥éª¤ã€‚æ¯ä¸ªç‰ˆæœ¬ä¸éƒ½ä¼šæ·»åŠ æ–°çš„é…置选项， 如果é…ç½®æ–‡ä»¶æ²¡æœ‰æŒ‰é¢„å®šè®¾ç½®ï¼Œå°±ä¼šå‡ºçŽ°å¥‡æ€ªçš„é—®é¢˜ã€‚å¦‚æžœæ‚¨æƒ³ä»¥æœ€å°‘çš„å·¥ä½œé‡ - 将现有é…ç½®å‡çº§åˆ°æ–°ç‰ˆæœ¬ï¼Œè¯·ä½¿ç”¨ ``makeoldconfig`` ，它åªä¼šè¯¢é—®æ‚¨æ–°é…ç½® + 将现有é…ç½®å‡çº§åˆ°æ–°ç‰ˆæœ¬ï¼Œè¯·ä½¿ç”¨ ``make oldconfig`` ，它åªä¼šè¯¢é—®æ‚¨æ–°é…ç½® 选项的ç”案。 - 其他é…置命令包括:: @@ -161,7 +161,7 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> "make ${PLATFORM}_defconfig" 使用arch/$arch/configs/${PLATFORM}_defconfigä¸ çš„é»˜è®¤é€‰é¡¹å€¼åˆ›å»ºä¸€ä¸ª./.config文件。 - 用“makehelpâ€æ¥èŽ·å–您体系架构ä¸æ‰€æœ‰å¯ç”¨å¹³å°çš„列表。 + 用“make helpâ€æ¥èŽ·å–您体系架构ä¸æ‰€æœ‰å¯ç”¨å¹³å°çš„列表。 "make allyesconfig" 通过尽å¯èƒ½å°†é€‰é¡¹å€¼è®¾ç½®ä¸ºâ€œyâ€ï¼Œåˆ›å»ºä¸€ä¸ª @@ -197,9 +197,10 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> "make localyesconfig" 与localmodconfig类似，åªæ˜¯å®ƒä¼šå°†æ‰€æœ‰æ¨¡å—é€‰é¡¹è½¬æ¢ ä¸ºå†…ç½®ï¼ˆ=yï¼‰ã€‚ä½ å¯ä»¥åŒæ—¶é€šè¿‡LMC_KEEPä¿ç•™æ¨¡å—。 - "make kvmconfig" 为kvmå®¢ä½“å†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 + "make kvm_guest.config" + 为kvmå®¢æˆ·æœºå†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 - "make xenconfig" 为xen dom0å®¢ä½“å†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 + "make xen.config" 为xen dom0å®¢æˆ·æœºå†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 "make tinyconfig" é…置尽å¯èƒ½å°çš„å†…æ ¸ã€‚ @@ -229,7 +230,7 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> 请注æ„，您ä»ç„¶å¯ä»¥ä½¿ç”¨æ¤å†…æ ¸è¿è¡Œa.out用户程åºã€‚ - 执行 ``make`` æ¥åˆ›å»ºåŽ‹ç¼©å†…æ ¸æ˜ åƒã€‚如果您安装了lilo以适é…å†…æ ¸makefile， - 那么也å¯ä»¥è¿›è¡Œ ``makeinstall`` ，但是您å¯èƒ½éœ€è¦å…ˆæ£€æŸ¥ç‰¹å®šçš„lilo设置。 + 那么也å¯ä»¥è¿›è¡Œ ``make install`` ，但是您å¯èƒ½éœ€è¦å…ˆæ£€æŸ¥ç‰¹å®šçš„lilo设置。 实际安装必须以root身份执行，但任何æ£å¸¸æž„建都ä¸éœ€è¦ã€‚ æ— é¡»å¾’ç„¶ä½¿ç”¨root身份。 diff --git a/Documentation/translations/zh_CN/admin-guide/cputopology.rst b/Documentation/translations/zh_CN/admin-guide/cputopology.rst new file mode 100644 index 000000000000..544d42f8f3fa --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/cputopology.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/cputopology.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========================== +如何通过sysfså°†CPU拓扑导出 +========================== + +CPU拓扑信æ¯é€šè¿‡sysfs导出。显示的项（属性）和æŸäº›æž¶æž„çš„/proc/cpuinfo输出相似。它们ä½äºŽ +/sys/devices/system/cpu/cpuX/topology/。请阅读ABI文件： +Documentation/ABI/stable/sysfs-devices-system-cpu。 + +drivers/base/topology.c是体系结构ä¸æ€§çš„，它导出了这些属性。然而，dieã€clusterã€book〠+draw这些层次结构相关的文件仅在体系结构æ供了下文æè¿°çš„å®çš„æ¡ä»¶ä¸‹è¢«åˆ›å»ºã€‚ + +对于支æŒè¿™ä¸ªç‰¹æ€§çš„体系结构，它必须在include/asm-XXX/topology.hä¸å®šä¹‰è¿™äº›å®ä¸çš„一部分:: + + #define topology_physical_package_id(cpu) + #define topology_die_id(cpu) + #define topology_cluster_id(cpu) + #define topology_core_id(cpu) + #define topology_book_id(cpu) + #define topology_drawer_id(cpu) + #define topology_sibling_cpumask(cpu) + #define topology_core_cpumask(cpu) + #define topology_cluster_cpumask(cpu) + #define topology_die_cpumask(cpu) + #define topology_book_cpumask(cpu) + #define topology_drawer_cpumask(cpu) + +``**_id macros`` 的类型是int。 +``**_cpumask macros`` 的类型是 ``(const) struct cpumask *`` 。åŽè€…å’Œæ°å½“çš„ +``**_siblings`` sysfs属性对应（除了topology_sibling_cpumask()，它和thread_siblings +对应）。 + +为了在所有体系结构上ä¿æŒä¸€è‡´ï¼Œinclude/linux/topology.hæ供了上述所有å®çš„默认定义，以防 +它们未在include/asm-XXX/topology.hä¸å®šä¹‰: + +1) topology_physical_package_id: -1 +2) topology_die_id: -1 +3) topology_cluster_id: -1 +4) topology_core_id: 0 +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: ä»…å…¥å‚CPU +8) topology_core_cpumask: ä»…å…¥å‚CPU +9) topology_cluster_cpumask: ä»…å…¥å‚CPU +10) topology_die_cpumask: ä»…å…¥å‚CPU +11) topology_book_cpumask: ä»…å…¥å‚CPU +12) topology_drawer_cpumask: ä»…å…¥å‚CPU + +æ¤å¤–，CPU拓扑信æ¯ç”±/sys/devices/system/cpuæ供，包å«ä¸‹è¿°æ–‡ä»¶ã€‚输出对应的内部数æ®æºæ”¾åœ¨ +方括å·ï¼ˆ"[]"）ä¸ã€‚ + + =========== ================================================================== + kernel_max: å†…æ ¸é…ç½®å…许的最大CPUä¸‹æ ‡å€¼ã€‚[NR_CPUS-1] + + offline: 由于çƒæ’æ‹”ç§»é™¤æˆ–è€…è¶…è¿‡å†…æ ¸å…许的CPU上é™ï¼ˆä¸Šæ–‡æè¿°çš„kernel_max） + 导致未上线的CPU。[~cpu_online_mask + cpus >= NR_CPUS] + + online: 在线的CPU，å¯ä¾›è°ƒåº¦ä½¿ç”¨ã€‚[cpu_online_mask] + + possible: 已被分é…资æºçš„CPU，如果它们CPU实际å˜åœ¨ï¼Œå¯ä»¥ä¸Šçº¿ã€‚ + [cpu_possible_mask] + + present: 被系统识别实际å˜åœ¨çš„CPU。[cpu_present_mask] + =========== ================================================================== + +ä¸Šè¿°è¾“å‡ºçš„æ ¼å¼å’Œcpulist_parse()兼容[å‚è§ <linux/cpumask.h>]。下é¢ç»™äº›ä¾‹å。 + +在本例ä¸ï¼Œç³»ç»Ÿä¸æœ‰64个CPU，但是CPU 32-63超过了kernel_maxå€¼ï¼Œå› ä¸ºNR_CPUSé…置项是32， +å–值范围被é™åˆ¶ä¸º0..31。æ¤å¤–注æ„CPU2å’Œ4-31未上线，但是å¯ä»¥ä¸Šçº¿ï¼Œå› 为它们åŒæ—¶å˜åœ¨äºŽ +presentå’Œpossible:: + + kernel_max: 31 + offline: 2,4-31,32-63 + online: 0-1,3 + possible: 0-31 + present: 0-31 + +在本例ä¸ï¼ŒNR_CPUSé…置项是128ï¼Œä½†å†…æ ¸å¯åŠ¨æ—¶è®¾ç½®possible_cpus=144。系统ä¸æœ‰4个CPU， +CPU2被手动设置下线（也是唯一一个å¯ä»¥ä¸Šçº¿çš„CPU）:: + + kernel_max: 127 + offline: 2,4-127,128-143 + online: 0-1,3 + possible: 0-127 + present: 0-3 + +阅读Documentation/core-api/cpu_hotplug.rstå¯äº†è§£å¼€æœºå‚æ•°possible_cpus=NUM，åŒæ—¶è¿˜ +å¯ä»¥äº†è§£å„ç§cpumaskçš„ä¿¡æ¯ã€‚ diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 83db84282562..be535ffaf4b0 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -20,15 +20,15 @@ Linux å†…æ ¸ç”¨æˆ·å’Œç®¡ç†å‘˜æŒ‡å— Todolist: - kernel-parameters - devices - sysctl/index +* kernel-parameters +* devices +* sysctl/index 本节介ç»CPUæ¼æ´žåŠå…¶ç¼“解措施。 Todolist: - hw-vuln/index +* hw-vuln/index 下é¢çš„一组文档，针对的是试图跟踪问题和bug的用户。 @@ -44,18 +44,18 @@ Todolist: Todolist: - reporting-bugs - ramoops - dynamic-debug-howto - kdump/index - perf/index +* reporting-bugs +* ramoops +* dynamic-debug-howto +* kdump/index +* perf/index 这是应用程åºå¼€å‘äººå‘˜æ„Ÿå…´è¶£çš„ç« èŠ‚çš„å¼€å§‹ã€‚å¯ä»¥åœ¨è¿™é‡Œæ‰¾åˆ°æ¶µç›–å†…æ ¸ABIå„个 æ–¹é¢çš„文档。 Todolist: - sysfs-rules +* sysfs-rules 本手册的其余部分包括å„ç§æŒ‡å—，介ç»å¦‚ä½•æ ¹æ®æ‚¨çš„喜好é…ç½®å†…æ ¸çš„ç‰¹å®šè¡Œä¸ºã€‚ @@ -65,65 +65,65 @@ Todolist: clearing-warn-once cpu-load + cputopology lockup-watchdogs unicode sysrq + mm/index Todolist: - acpi/index - aoe/index - auxdisplay/index - bcache - binderfs - binfmt-misc - blockdev/index - bootconfig - braille-console - btmrvl - cgroup-v1/index - cgroup-v2 - cifs/index - cputopology - dell_rbu - device-mapper/index - edid - efi-stub - ext4 - nfs/index - gpio/index - highuid - hw_random - initrd - iostats - java - jfs - kernel-per-CPU-kthreads - laptops/index - lcd-panel-cgram - ldm - LSM/index - md - media/index - mm/index - module-signing - mono - namespaces/index - numastat - parport - perf-security - pm/index - pnp - rapidio - ras - rtc - serial-console - svga - thunderbolt - ufs - vga-softcursor - video-output - xfs +* acpi/index +* aoe/index +* auxdisplay/index +* bcache +* binderfs +* binfmt-misc +* blockdev/index +* bootconfig +* braille-console +* btmrvl +* cgroup-v1/index +* cgroup-v2 +* cifs/index +* dell_rbu +* device-mapper/index +* edid +* efi-stub +* ext4 +* nfs/index +* gpio/index +* highuid +* hw_random +* initrd +* iostats +* java +* jfs +* kernel-per-CPU-kthreads +* laptops/index +* lcd-panel-cgram +* ldm +* LSM/index +* md +* media/index +* module-signing +* mono +* namespaces/index +* numastat +* parport +* perf-security +* pm/index +* pnp +* rapidio +* ras +* rtc +* serial-console +* svga +* thunderbolt +* ufs +* vga-softcursor +* video-output +* xfs .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst new file mode 100644 index 000000000000..0c8276109fc0 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +============ +监测数æ®è®¿é—® +============ + +:doc:`DAMON </vm/damon/index>` å…许轻é‡çº§çš„æ•°æ®è®¿é—®ç›‘测。使用DAMON， +用户å¯ä»¥åˆ†æžä»–们系统的内å˜è®¿é—®æ¨¡å¼ï¼Œå¹¶ä¼˜åŒ–它们。 + +.. toctree:: + :maxdepth: 2 + + start + usage + reclaim + + + + diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst new file mode 100644 index 000000000000..9e541578f38d --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/reclaim.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +=============== +基于DAMON的回收 +=============== + +基于DAMON的回收（DAMON_RECLAIM）是一个é™æ€çš„å†…æ ¸æ¨¡å—，旨在用于轻度内å˜åŽ‹åŠ›ä¸‹çš„主动和轻 +é‡çº§çš„回收。它的目的ä¸æ˜¯å–代基于LRU列表的页é¢å›žæ”¶ï¼Œè€Œæ˜¯æœ‰é€‰æ‹©åœ°ç”¨äºŽä¸åŒç¨‹åº¦çš„内å˜åŽ‹åŠ›å’Œè¦ +求。 + +哪些地方需è¦ä¸»åŠ¨å›žæ”¶ï¼Ÿ +====================== + +在一般的内å˜è¶…é‡ä½¿ç”¨ï¼ˆover-committed systems，虚拟化相关术è¯ï¼‰çš„系统上，主动回收冷页 +有助于节çœå†…å˜å’Œå‡å°‘延迟高峰，这些延迟是由直接回收进程或kswapdçš„CPU消耗引起的，åŒæ—¶åªäº§ +生最å°çš„æ€§èƒ½ä¸‹é™ [1]_ [2]_ 。 + +基于空闲页报告 [3]_ 的内å˜è¿‡åº¦æ‰¿è¯ºçš„虚拟化系统就是很好的例åã€‚åœ¨è¿™æ ·çš„ç³»ç»Ÿä¸ï¼Œå®¢æˆ·æœº +å‘主机报告他们的空闲内å˜ï¼Œè€Œä¸»æœºåˆ™å°†æŠ¥å‘Šçš„内å˜é‡æ–°åˆ†é…ç»™å…¶ä»–å®¢æˆ·ã€‚å› æ¤ï¼Œç³»ç»Ÿçš„内å˜å¾—到了充 +分的利用。然而，客户å¯èƒ½ä¸é‚£ä¹ˆèŠ‚çœå†…å˜ï¼Œä¸»è¦æ˜¯å› ä¸ºä¸€äº›å†…æ ¸å系统和用户空间应用程åºè¢«è®¾è®¡ä¸º +使用尽å¯èƒ½å¤šçš„内å˜ã€‚然åŽï¼Œå®¢æˆ·æœºå¯èƒ½åªå‘主机报告少é‡çš„内å˜æ˜¯ç©ºé—²çš„，导致系统的内å˜åˆ©ç”¨çŽ‡ä¸‹é™ã€‚ +在客户ä¸è¿è¡Œä¸»åŠ¨å›žæ”¶å¯ä»¥ç¼“解这个问题。 + +它是如何工作的？ +================ + +DAMON_RECLAIM找到在特定时间内没有被访问的内å˜åŒºåŸŸå¹¶åˆ†é¡µã€‚为了é¿å…它在分页æ“作ä¸æ¶ˆè€—过多 +çš„CPU，å¯ä»¥é…置一个速度é™åˆ¶ã€‚在这个速度é™åˆ¶ä¸‹ï¼Œå®ƒé¦–先分页出那些没有被访问过的内å˜åŒºåŸŸã€‚ç³» +统管ç†å‘˜è¿˜å¯ä»¥é…置在什么情况下这个方案应该自动激活和åœç”¨ä¸‰ä¸ªå†…å˜åŽ‹åŠ›æ°´ä½ã€‚ + +接å£: 模å—å‚æ•° +============== + +è¦ä½¿ç”¨è¿™ä¸ªåŠŸèƒ½ï¼Œä½ 首先è¦ç¡®ä¿ä½ 的系统è¿è¡Œåœ¨ä¸€ä¸ªä»¥ ``CONFIG_DAMON_RECLAIM=y`` 构建的内 +æ ¸ä¸Šã€‚ + +为了让系统管ç†å‘˜å¯ç”¨æˆ–ç¦ç”¨å®ƒï¼Œå¹¶ä¸ºç»™å®šçš„系统进行调整，DAMON_RECLAIM利用了模å—å‚数。也就 +æ˜¯è¯´ï¼Œä½ å¯ä»¥æŠŠ ``damon_reclaim.<parameter>=<value>`` æ”¾åœ¨å†…æ ¸å¯åŠ¨å‘½ä»¤è¡Œä¸Šï¼Œæˆ–者把 +适当的值写入 ``/sys/modules/damon_reclaim/parameters/<parameter>`` 文件。 + +注æ„，除 ``å¯ç”¨`` 外的å‚数值åªåœ¨DAMON_RECLAIMå¯åŠ¨æ—¶åº”ç”¨ã€‚å› æ¤ï¼Œå¦‚æžœä½ æƒ³åœ¨è¿è¡Œæ—¶åº”用新 +çš„å‚数值，而DAMON_RECLAIMå·²ç»è¢«å¯ç”¨ï¼Œä½ 应该通过 ``å¯ç”¨`` çš„å‚数文件ç¦ç”¨å’Œé‡æ–°å¯ç”¨å®ƒã€‚ +在é‡æ–°å¯ç”¨ä¹‹å‰ï¼Œåº”将新的å‚数值写入适当的å‚数值ä¸ã€‚ + +下é¢æ˜¯æ¯ä¸ªå‚æ•°çš„æ述。 + +enable +------ + +å¯ç”¨æˆ–ç¦ç”¨DAMON_RECLAIM。 + +ä½ å¯ä»¥é€šè¿‡æŠŠè¿™ä¸ªå‚数的值设置为 ``Y`` æ¥å¯ç”¨DAMON_RCLAIM，把它设置为 ``N`` å¯ä»¥ç¦ç”¨ +DAMON_RECLAIM。注æ„，由于基于水ä½çš„激活æ¡ä»¶ï¼ŒDAMON_RECLAIMä¸èƒ½è¿›è¡ŒçœŸæ£çš„监测和回收。 +这一点请å‚考下é¢å…³äºŽæ°´ä½å‚æ•°çš„æ述。 + +min_age +------- + +识别冷内å˜åŒºåŸŸçš„时间阈值，å•ä½æ˜¯å¾®ç§’。 + +如果一个内å˜åŒºåŸŸåœ¨è¿™ä¸ªæ—¶é—´æˆ–更长的时间内没有被访问，DAMON_RECLAIM会将该区域识别为冷的， +并回收它。 + +默认为120秒。 + +quota_ms +-------- + +回收的时间é™åˆ¶ï¼Œä»¥æ¯«ç§’为å•ä½ã€‚ + +DAMON_RECLAIM 试图在一个时间窗å£ï¼ˆquota_reset_interval_ms）内åªä½¿ç”¨åˆ°è¿™ä¸ªæ—¶é—´ï¼Œä»¥ +å°è¯•å›žæ”¶å†·é¡µã€‚è¿™å¯ä»¥ç”¨æ¥é™åˆ¶DAMON_RECLAIMçš„CPU消耗。如果该值为零，则该é™åˆ¶è¢«ç¦ç”¨ã€‚ + +默认为10ms。 + +quota_sz +-------- + +回收的内å˜å¤§å°é™åˆ¶ï¼Œå•ä½ä¸ºå—节。 + +DAMON_RECLAIM 收å–在一个时间窗å£ï¼ˆquota_reset_interval_ms）内试图回收的内å˜é‡ï¼Œå¹¶ +使其ä¸è¶…过这个é™åˆ¶ã€‚è¿™å¯ä»¥ç”¨æ¥é™åˆ¶CPUå’ŒIO的消耗。如果该值为零，则é™åˆ¶è¢«ç¦ç”¨ã€‚ + +默认情况下是128 MiB。 + +quota_reset_interval_ms +----------------------- + +时间/大å°é…é¢æ”¶å–é‡ç½®é—´éš”，å•ä½ä¸ºæ¯«ç§’。 + +时间（quota_ms）和大å°ï¼ˆquota_sz）的é…é¢çš„ç›®æ ‡é‡ç½®é—´éš”。也就是说，DAMON_RECLAIM在 +å°è¯•å›žæ”¶â€˜ä¸â€™è¶…过quota_ms毫秒或quota_szå—节的内å˜ã€‚ + +默认为1秒。 + +wmarks_interval +--------------- + +当DAMON_RECLAIM被å¯ç”¨ä½†ç”±äºŽå…¶æ°´ä½è§„则而ä¸æ´»è·ƒæ—¶ï¼Œåœ¨æ£€æŸ¥æ°´ä½ä¹‹å‰çš„最å°ç‰å¾…时间。 + +wmarks_high +----------- + +高水ä½çš„å¯ç”¨å†…å˜çŽ‡ï¼ˆæ¯åƒå—节）。 + +如果系统的å¯ç”¨å†…å˜ï¼ˆä»¥æ¯åƒå—节为å•ä½ï¼‰é«˜äºŽè¿™ä¸ªæ•°å€¼ï¼ŒDAMON_RECLAIM就会å˜å¾—ä¸æ´»è·ƒï¼Œæ‰€ä»¥ +它什么也ä¸åšï¼Œåªæ˜¯å®šæœŸæ£€æŸ¥æ°´ä½ã€‚ + +wmarks_mid +---------- + +ä¸é—´æ°´ä½çš„å¯ç”¨å†…å˜çŽ‡ï¼ˆæ¯åƒå—节）。 + +如果系统的空闲内å˜ï¼ˆä»¥æ¯åƒå—节为å•ä½ï¼‰åœ¨è¿™ä¸ªå’Œä½Žæ°´ä½çº¿ä¹‹é—´ï¼ŒDAMON_RECLAIM就会被激活， +å› æ¤å¼€å§‹ç›‘测和回收。 + +wmarks_low +---------- + +低水ä½çš„å¯ç”¨å†…å˜çŽ‡ï¼ˆæ¯åƒå—节）。 + +如果系统的空闲内å˜ï¼ˆä»¥æ¯åƒå—节为å•ä½ï¼‰ä½ŽäºŽè¿™ä¸ªæ•°å€¼ï¼ŒDAMON_RECLAIM就会å˜å¾—ä¸æ´»è·ƒï¼Œæ‰€ä»¥ +它除了定期检查水ä½å¤–什么都ä¸åšã€‚在这ç§æƒ…况下，系统会退回到基于LRU列表的页é¢ç²’度回收逻辑。 + +sample_interval +--------------- + +ç›‘æµ‹çš„é‡‡æ ·é—´éš”ï¼Œå•ä½æ˜¯å¾®ç§’。 + +DAMON用于监测冷内å˜çš„é‡‡æ ·é—´éš”ã€‚æ›´å¤šç»†èŠ‚è¯·å‚考DAMON文档 (:doc:`usage`) 。 + +aggr_interval +------------- + +监测的èšé›†é—´éš”，å•ä½æ˜¯å¾®ç§’。 + +DAMON对冷内å˜ç›‘测的èšé›†é—´éš”。更多细节请å‚考DAMON文档 (:doc:`usage`)。 + +min_nr_regions +-------------- + +监测区域的最å°æ•°é‡ã€‚ + +DAMON用于冷内å˜ç›‘测的最å°ç›‘测区域数。这å¯ä»¥ç”¨æ¥è®¾ç½®ç›‘测质é‡çš„下é™ã€‚但是，设 +置的太高å¯èƒ½ä¼šå¯¼è‡´ç›‘æµ‹å¼€é”€çš„å¢žåŠ ã€‚æ›´å¤šç»†èŠ‚è¯·å‚考DAMON文档 (:doc:`usage`) 。 + +max_nr_regions +-------------- + +监测区域的最大数é‡ã€‚ + +DAMON用于冷内å˜ç›‘测的最大监测区域数。这å¯ä»¥ç”¨æ¥è®¾ç½®ç›‘测开销的上é™å€¼ã€‚但是， +设置得太低å¯èƒ½ä¼šå¯¼è‡´ç›‘测质é‡ä¸å¥½ã€‚更多细节请å‚考DAMON文档 (:doc:`usage`) 。 + +monitor_region_start +-------------------- + +ç›®æ ‡å†…å˜åŒºåŸŸçš„物ç†åœ°å€èµ·ç‚¹ã€‚ + +DAMON_RECLAIM将对其进行工作的内å˜åŒºåŸŸçš„起始物ç†åœ°å€ã€‚也就是说，DAMON_RECLAIM +将在这个区域ä¸æ‰¾åˆ°å†·çš„内å˜åŒºåŸŸå¹¶è¿›è¡Œå›žæ”¶ã€‚默认情况下，该区域使用最大系统内å˜åŒºã€‚ + +monitor_region_end +------------------ + +ç›®æ ‡å†…å˜åŒºåŸŸçš„结æŸç‰©ç†åœ°å€ã€‚ + +DAMON_RECLAIM将对其进行工作的内å˜åŒºåŸŸçš„末端物ç†åœ°å€ã€‚也就是说，DAMON_RECLAIMå°† +在这个区域内找到冷的内å˜åŒºåŸŸå¹¶è¿›è¡Œå›žæ”¶ã€‚默认情况下，该区域使用最大系统内å˜åŒºã€‚ + +kdamond_pid +----------- + +DAMON线程的PID。 + +如果DAMON_RECLAIM被å¯ç”¨ï¼Œè¿™å°†æˆä¸ºå·¥ä½œçº¿ç¨‹çš„PID。å¦åˆ™ï¼Œä¸º-1。 + +nr_reclaim_tried_regions +------------------------ + +试图通过DAMON_RECLAIM回收的内å˜åŒºåŸŸçš„æ•°é‡ã€‚ + +bytes_reclaim_tried_regions +--------------------------- + +试图通过DAMON_RECLAIM回收的内å˜åŒºåŸŸçš„总å—节数。 + +nr_reclaimed_regions +-------------------- + +通过DAMON_RECLAIMæˆåŠŸå›žæ”¶çš„内å˜åŒºåŸŸçš„æ•°é‡ã€‚ + +bytes_reclaimed_regions +----------------------- + +通过DAMON_RECLAIMæˆåŠŸå›žæ”¶çš„内å˜åŒºåŸŸçš„总å—节数。 + +nr_quota_exceeds +---------------- + +超过时间/空间é…é¢é™åˆ¶çš„次数。 + +例å +==== + +下é¢çš„è¿è¡Œç¤ºä¾‹å‘½ä»¤ä½¿DAMON_RECLAIM找到30秒或更长时间没有访问的内å˜åŒºåŸŸå¹¶â€œå›žæ”¶â€ï¼Ÿ +为了é¿å…DAMON_RECLAIM在分页æ“作ä¸æ¶ˆè€—过多的CPU时间，回收被é™åˆ¶åœ¨æ¯ç§’1GiB以内。 +它还è¦æ±‚DAMON_RECLAIM在系统的å¯ç”¨å†…å˜çŽ‡è¶…过50%æ—¶ä¸åšä»»ä½•äº‹æƒ…，但如果它低于40%æ—¶ +就开始真æ£çš„工作。如果DAMON_RECLAIM没有å–å¾—è¿›å±•ï¼Œå› æ¤ç©ºé—²å†…å˜çŽ‡ä½ŽäºŽ20%，它会è¦æ±‚ +DAMON_RECLAIMå†æ¬¡ä»€ä¹ˆéƒ½ä¸åšï¼Œè¿™æ ·æˆ‘们就å¯ä»¥é€€å›žåˆ°åŸºäºŽLRU列表的页é¢ç²’度回收了:: + + # cd /sys/modules/damon_reclaim/parameters + # echo 30000000 > min_age + # echo $((1 * 1024 * 1024 * 1024)) > quota_sz + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + +.. [1] https://research.google/pubs/pub48551/ +.. [2] https://lwn.net/Articles/787611/ +.. [3] https://www.kernel.org/doc/html/latest/vm/free_page_reporting.html diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst new file mode 100644 index 000000000000..67d1b49481dc --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/start.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======== +å…¥é—¨æŒ‡å— +======== + +本文通过演示DAMON的默认用户空间工具，简è¦åœ°ä»‹ç»äº†å¦‚何使用DAMON。请注æ„ï¼Œä¸ºäº†ç®€æ´ +èµ·è§ï¼Œæœ¬æ–‡æ¡£åªæ述了它的部分功能。更多细节请å‚考该工具的使用文档。 +`doc <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ . + + +å‰ææ¡ä»¶ +======== + +å†…æ ¸ +---- + +é¦–å…ˆï¼Œä½ è¦ç¡®ä¿ä½ 当å‰ç³»ç»Ÿä¸è·‘çš„å†…æ ¸æž„å»ºæ—¶é€‰å®šäº†è¿™ä¸ªåŠŸèƒ½é€‰é¡¹ ``CONFIG_DAMON_*=y``. + + +用户空间工具 +------------ + +在演示ä¸ï¼Œæˆ‘们将使用DAMON的默认用户空间工具，称为DAMON Operator（DAMO）。它å¯ä»¥åœ¨ +https://github.com/awslabs/damo找到。下é¢çš„例åå‡è®¾DAMOåœ¨ä½ çš„$PATH上。当然，但 +这并ä¸æ˜¯å¼ºåˆ¶æ€§çš„。 + +å› ä¸ºDAMO使用的是DAMONçš„debugfs接å£(详情请å‚考 :doc:`usage` ä¸çš„使用方法) ä½ åº”è¯¥ +ç¡®ä¿debugfs被挂载。手动挂载它，如下所示:: + + # mount -t debugfs none /sys/kernel/debug/ + +æˆ–è€…åœ¨ä½ çš„ ``/etc/fstab`` 文件ä¸æ·»åŠ ä»¥ä¸‹ä¸€è¡Œï¼Œè¿™æ ·ä½ çš„ç³»ç»Ÿå°±å¯ä»¥åœ¨å¯åŠ¨æ—¶è‡ªåŠ¨æŒ‚è½½ +debugfs了:: + + debugfs /sys/kernel/debug debugfs defaults 0 0 + + +记录数æ®è®¿é—®æ¨¡å¼ +================ + +下é¢çš„命令记录了一个程åºçš„内å˜è®¿é—®æ¨¡å¼ï¼Œå¹¶å°†ç›‘测结果ä¿å˜åˆ°æ–‡ä»¶ä¸ã€‚ :: + + $ git clone https://github.com/sjp38/masim + $ cd masim; make; ./masim ./configs/zigzag.cfg & + $ sudo damo record -o damon.data $(pidof masim) + +命令的å‰ä¸¤è¡Œä¸‹è½½äº†ä¸€ä¸ªäººå·¥å†…å˜è®¿é—®ç”Ÿæˆå™¨ç¨‹åºå¹¶åœ¨åŽå°è¿è¡Œã€‚生æˆå™¨å°†é‡å¤åœ°é€ä¸€è®¿é—®ä¸¤ä¸ª +100 MiB大å°çš„内å˜åŒºåŸŸã€‚ä½ å¯ä»¥ç”¨ä½ 的真实工作负载æ¥ä»£æ›¿å®ƒã€‚最åŽä¸€è¡Œè¦æ±‚ ``damo`` å°† +访问模å¼è®°å½•åœ¨ ``damon.data`` 文件ä¸ã€‚ + + +将记录的模å¼å¯è§†åŒ– +================== + +ä½ å¯ä»¥åœ¨heatmapä¸ç›´è§‚地看到这ç§æ¨¡å¼ï¼Œæ˜¾ç¤ºå“ªä¸ªå†…å˜åŒºåŸŸï¼ˆX轴）何时被访问（Y轴）以åŠè®¿ +问的频率（数å—）。:: + + $ sudo damo report heats --heatmap stdout + 22222222222222222222222222222222222222211111111111111111111111111111111111111100 + 44444444444444444444444444444444444444434444444444444444444444444444444444443200 + 44444444444444444444444444444444444444433444444444444444444444444444444444444200 + 33333333333333333333333333333333333333344555555555555555555555555555555555555200 + 33333333333333333333333333333333333344444444444444444444444444444444444444444200 + 22222222222222222222222222222222222223355555555555555555555555555555555555555200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 33333333333333333333333333333333333333355555555555555555555555555555555555555200 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 33333333333333333333333333333333333333444444444444444444444444444444444444443200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + [...] + # access_frequency: 0 1 2 3 4 5 6 7 8 9 + # x-axis: space (139728247021568-139728453431248: 196.848 MiB) + # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) + # resolution: 80x40 (2.461 MiB and 1.758 s for each character) + +ä½ ä¹Ÿå¯ä»¥ç›´è§‚地看到工作集的大å°åˆ†å¸ƒï¼ŒæŒ‰å¤§å°æŽ’åºã€‚:: + + $ sudo damo report wss --range 0 101 10 + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 0 B | | + 10 95.328 MiB |**************************** | + 20 95.332 MiB |**************************** | + 30 95.340 MiB |**************************** | + 40 95.387 MiB |**************************** | + 50 95.387 MiB |**************************** | + 60 95.398 MiB |**************************** | + 70 95.398 MiB |**************************** | + 80 95.504 MiB |**************************** | + 90 190.703 MiB |********************************************************* | + 100 196.875 MiB |***********************************************************| + +在上述命令ä¸ä½¿ç”¨ ``--sortby`` 选项，å¯ä»¥æ˜¾ç¤ºå·¥ä½œé›†çš„大å°æ˜¯å¦‚何按时间顺åºå˜åŒ–的。:: + + $ sudo damo report wss --range 0 101 10 --sortby time + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 3.051 MiB | | + 10 190.703 MiB |***********************************************************| + 20 95.336 MiB |***************************** | + 30 95.328 MiB |***************************** | + 40 95.387 MiB |***************************** | + 50 95.332 MiB |***************************** | + 60 95.320 MiB |***************************** | + 70 95.398 MiB |***************************** | + 80 95.398 MiB |***************************** | + 90 95.340 MiB |***************************** | + 100 95.398 MiB |***************************** | + + +æ•°æ®è®¿é—®æ¨¡å¼æ„ŸçŸ¥çš„内å˜ç®¡ç† +========================== + +以下三个命令使æ¯ä¸€ä¸ªå¤§å°>=4K的内å˜åŒºåŸŸåœ¨ä½ 的工作负载ä¸æ²¡æœ‰è¢«è®¿é—®>=60秒，就会被æ¢æŽ‰ã€‚ :: + + $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme + $ echo "4K max 0 0 60s max pageout" >> test_scheme + $ damo schemes -c test_scheme <pid of your workload> diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst new file mode 100644 index 000000000000..5d7533347216 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -0,0 +1,286 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/usage.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======== +详细用法 +======== + +DAMON 为ä¸åŒçš„用户æ供了下é¢ä¸‰ç§æŽ¥å£ã€‚ + +- *DAMON用户空间工具。* + `è¿™ <https://github.com/awslabs/damo>`_ 为有这特æƒçš„人， 如系统管ç†å‘˜ï¼Œå¸Œæœ›æœ‰ä¸€ä¸ªåˆšå¥½ + å¯ä»¥å·¥ä½œçš„人性化界é¢ã€‚ + 使用它，用户å¯ä»¥ä»¥äººæ€§åŒ–çš„æ–¹å¼ä½¿ç”¨DAMON的主è¦åŠŸèƒ½ã€‚ä¸è¿‡ï¼Œå®ƒå¯èƒ½ä¸ä¼šä¸ºç‰¹æ®Šæƒ…况进行高度调整。 + 它åŒæ—¶æ”¯æŒè™šæ‹Ÿå’Œç‰©ç†åœ°å€ç©ºé—´çš„监测。更多细节，请å‚考它的 `使用文档 + <https://github.com/awslabs/damo/blob/next/USAGE.md>`_。 +- *debugfs接å£ã€‚* + :ref:`è¿™ <debugfs_interface>` 是为那些希望更高级的使用DAMON的特æƒç”¨æˆ·ç©ºé—´ç¨‹åºå‘˜å‡†å¤‡çš„。 + 使用它，用户å¯ä»¥é€šè¿‡è¯»å–和写入特殊的debugfs文件æ¥ä½¿ç”¨DAMON的主è¦åŠŸèƒ½ã€‚å› æ¤ï¼Œä½ å¯ä»¥ç¼–写和使 + ç”¨ä½ ä¸ªæ€§åŒ–çš„DAMON debugfs包装程åºï¼Œä»£æ›¿ä½ 读/写debugfs文件。 `DAMON用户空间工具 + <https://github.com/awslabs/damo>`_ 就是这ç§ç¨‹åºçš„一个例å 它åŒæ—¶æ”¯æŒè™šæ‹Ÿå’Œç‰©ç†åœ°å€ + 空间的监测。注æ„，这个界é¢åªæ供简å•çš„监测结果 :ref:`统计 <damos_stats>`。对于详细的监测 + 结果，DAMONæ供了一个:ref:`跟踪点 <tracepoint>`。 + +- *å†…æ ¸ç©ºé—´ç¼–ç¨‹æŽ¥å£ã€‚* + :doc:`This </vm/damon/api>` è¿™æ˜¯ä¸ºå†…æ ¸ç©ºé—´ç¨‹åºå‘˜å‡†å¤‡çš„。使用它，用户å¯ä»¥é€šè¿‡ä¸ºä½ 编写内 + æ ¸ç©ºé—´çš„DAMON应用程åºï¼Œæœ€çµæ´»æœ‰æ•ˆåœ°åˆ©ç”¨DAMONçš„æ¯ä¸€ä¸ªåŠŸèƒ½ã€‚ä½ ç”šè‡³å¯ä»¥ä¸ºå„ç§åœ°å€ç©ºé—´æ‰©å±•DAMON。 + 详细情况请å‚è€ƒæŽ¥å£ :doc:`文件 </vm/damon/api>`。 + + +debugfsæŽ¥å£ +=========== + +DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, +``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` å’Œ +``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. + + +属性 +---- + +用户å¯ä»¥é€šè¿‡è¯»å–和写入 ``attrs`` 文件获得和设置 ``é‡‡æ ·é—´éš”`` 〠``èšé›†é—´éš”`` 〠``区域更新间隔`` +以åŠç›‘æµ‹ç›®æ ‡åŒºåŸŸçš„æœ€å°/最大数é‡ã€‚è¦è¯¦ç»†äº†è§£ç›‘测属性，请å‚考 `:doc:/vm/damon/design` 。例如， +下é¢çš„命令将这些值设置为5msã€100msã€1000msã€10å’Œ1000，然åŽå†æ¬¡æ£€æŸ¥:: + + # cd <debugfs>/damon + # echo 5000 100000 1000000 10 1000 > attrs + # cat attrs + 5000 100000 1000000 10 1000 + + +ç›®æ ‡ID +------ + +一些类型的地å€ç©ºé—´æ”¯æŒå¤šä¸ªç›‘æµ‹ç›®æ ‡ã€‚ä¾‹å¦‚ï¼Œè™šæ‹Ÿå†…å˜åœ°å€ç©ºé—´çš„监测å¯ä»¥æœ‰å¤šä¸ªè¿›ç¨‹ä½œä¸ºç›‘æµ‹ç›®æ ‡ã€‚ç”¨æˆ· +å¯ä»¥é€šè¿‡å†™å…¥ç›®æ ‡çš„相关id值æ¥è®¾ç½®ç›®æ ‡ï¼Œå¹¶é€šè¿‡è¯»å– ``target_ids`` 文件æ¥èŽ·å¾—当å‰ç›®æ ‡çš„id。在监 +测虚拟地å€ç©ºé—´çš„æƒ…å†µä¸‹ï¼Œè¿™äº›å€¼åº”è¯¥æ˜¯ç›‘æµ‹ç›®æ ‡è¿›ç¨‹çš„pid。例如，下é¢çš„命令将pid为42å’Œ4242的进程设 +ä¸ºç›‘æµ‹ç›®æ ‡ï¼Œå¹¶å†æ¬¡æ£€æŸ¥:: + + # cd <debugfs>/damon + # echo 42 4242 > target_ids + # cat target_ids + 42 4242 + +用户还å¯ä»¥é€šè¿‡åœ¨æ–‡ä»¶ä¸å†™å…¥ä¸€ä¸ªç‰¹æ®Šçš„å…³é”®å— "paddr\n" æ¥ç›‘测系统的物ç†å†…å˜åœ°å€ç©ºé—´ã€‚å› ä¸ºç‰©ç†åœ° +å€ç©ºé—´ç›‘测ä¸æ”¯æŒå¤šä¸ªç›®æ ‡ï¼Œè¯»å–文件会显示一个å‡å€¼ï¼Œå³ ``42`` ，如下图所示:: + + # cd <debugfs>/damon + # echo paddr > target_ids + # cat target_ids + 42 + +请注æ„ï¼Œè®¾ç½®ç›®æ ‡ID并ä¸å¯åŠ¨ç›‘测。 + + +åˆå§‹ç›‘æµ‹ç›®æ ‡åŒºåŸŸ +---------------- + +在虚拟地å€ç©ºé—´ç›‘测的情况下，DAMONè‡ªåŠ¨è®¾ç½®å’Œæ›´æ–°ç›‘æµ‹çš„ç›®æ ‡åŒºåŸŸï¼Œè¿™æ ·å°±å¯ä»¥è¦†ç›–ç›®æ ‡è¿›ç¨‹çš„æ•´ä¸ª +内å˜æ˜ 射。然而，用户å¯èƒ½å¸Œæœ›å°†ç›‘测区域é™åˆ¶åœ¨ç‰¹å®šçš„地å€èŒƒå›´å†…ï¼Œå¦‚å †ã€æ ˆæˆ–ç‰¹å®šçš„æ–‡ä»¶æ˜ å°„åŒºåŸŸã€‚ +或者，一些用户å¯ä»¥çŸ¥é“他们工作负载的åˆå§‹è®¿é—®æ¨¡å¼ï¼Œå› æ¤å¸Œæœ›ä¸ºâ€œè‡ªé€‚应区域调整â€è®¾ç½®æœ€ä½³åˆå§‹åŒºåŸŸã€‚ + +相比之下，DAMON在物ç†å†…å˜ç›‘测的情况下ä¸ä¼šè‡ªåŠ¨è®¾ç½®å’Œæ›´æ–°ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚å› æ¤ï¼Œç”¨æˆ·åº”该自己设置 +ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚ + +在这ç§æƒ…况下，用户å¯ä»¥é€šè¿‡åœ¨ ``init_regions`` 文件ä¸å†™å…¥é€‚当的值，明确地设置他们想è¦çš„åˆ +å§‹ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚è¾“å…¥çš„æ¯ä¸€è¡Œåº”代表一个区域，形å¼å¦‚下:: + + <target idx> <start address> <end address> + +ç›®æ ‡idx应该是 ``target_ids`` 文件ä¸ç›®æ ‡çš„索引，从 ``0`` 开始，区域应该按照地å€é¡ºåºä¼ 递。 +例如，下é¢çš„å‘½ä»¤å°†è®¾ç½®å‡ ä¸ªåœ°å€èŒƒå›´ï¼Œ ``1-100`` å’Œ ``100-200`` 作为pid 42çš„åˆå§‹ç›‘æµ‹ç›®æ ‡ +区域，这是 ``target_ids`` ä¸çš„第一个（索引 ``0`` ），å¦å¤–å‡ ä¸ªåœ°å€èŒƒå›´ï¼Œ ``20-40`` å’Œ +``50-100`` 作为pid 4242的地å€ï¼Œè¿™æ˜¯ ``target_ids`` ä¸çš„第二个（索引 ``1`` ）:: + + # cd <debugfs>/damon + # cat target_ids + 42 4242 + # echo "0 1 100 + 0 100 200 + 1 20 40 + 1 50 100" > init_regions + +请注æ„，这åªæ˜¯è®¾ç½®äº†åˆå§‹çš„ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚åœ¨è™šæ‹Ÿå†…å˜ç›‘测的情况下，DAMON会在一个 ``区域更新间隔`` +åŽè‡ªåŠ¨æ›´æ–°åŒºåŸŸçš„è¾¹ç•Œã€‚å› æ¤ï¼Œåœ¨è¿™ç§æƒ…况下，如果用户ä¸å¸Œæœ›æ›´æ–°çš„è¯ï¼Œåº”该把 ``区域的更新间隔`` 设 +置得足够大。 + + +方案 +---- + +对于通常的基于DAMONçš„æ•°æ®è®¿é—®æ„ŸçŸ¥çš„内å˜ç®¡ç†ä¼˜åŒ–，用户åªæ˜¯å¸Œæœ›ç³»ç»Ÿå¯¹ç‰¹å®šè®¿é—®æ¨¡å¼çš„内å˜åŒºåŸŸåº”用内 +å˜ç®¡ç†æ“作。DAMON从用户那里接收这ç§å½¢å¼åŒ–çš„æ“ä½œæ–¹æ¡ˆï¼Œå¹¶å°†è¿™äº›æ–¹æ¡ˆåº”ç”¨åˆ°ç›®æ ‡è¿›ç¨‹ä¸ã€‚ + +用户å¯ä»¥é€šè¿‡è¯»å–和写入 ``scheme`` debugfs文件æ¥èŽ·å¾—和设置这些方案。读å–该文件还å¯ä»¥æ˜¾ç¤ºæ¯ä¸ª +方案的统计数æ®ã€‚在文件ä¸ï¼Œæ¯ä¸€ä¸ªæ–¹æ¡ˆéƒ½åº”该在æ¯ä¸€è¡Œä¸ä»¥ä¸‹åˆ—å½¢å¼è¡¨ç¤ºå‡ºæ¥:: + + <target access pattern> <action> <quota> <watermarks> + +ä½ å¯ä»¥é€šè¿‡ç®€å•åœ°åœ¨æ–‡ä»¶ä¸å†™å…¥ä¸€ä¸ªç©ºå—符串æ¥ç¦ç”¨æ–¹æ¡ˆã€‚ + +ç›®æ ‡è®¿é—®æ¨¡å¼ +~~~~~~~~~~~~ + +``<ç›®æ ‡è®¿é—®æ¨¡å¼>`` 是由三个范围构æˆçš„，形å¼å¦‚下:: + + min-size max-size min-acc max-acc min-age max-age + +具体æ¥è¯´ï¼ŒåŒºåŸŸå¤§å°çš„å—节数（ `min-size` å’Œ `max-size` ），访问频率的æ¯èšåˆåŒºé—´çš„监测访问次 +数（ `min-acc` å’Œ `max-acc` ），区域年龄的èšåˆåŒºé—´æ•°ï¼ˆ `min-age` å’Œ `max-age` ）都被指定。 +请注æ„，这些范围是å°é—区间。 + +动作 +~~~~ + +``<action>`` 是一个预定义的内å˜ç®¡ç†åŠ¨ä½œçš„整数，DAMONå°†åº”ç”¨äºŽå…·æœ‰ç›®æ ‡è®¿é—®æ¨¡å¼çš„åŒºåŸŸã€‚æ”¯æŒ +çš„æ•°å—和它们的å«ä¹‰å¦‚下:: + + - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` + - 1: Call ``madvise()`` for the region with ``MADV_COLD`` + - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` + - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` + - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` + - 5: Do nothing but count the statistics + +é…é¢ +~~~~ + +æ¯ä¸ª ``动作`` 的最佳 ``ç›®æ ‡è®¿é—®æ¨¡å¼`` å–决于工作负载，所以ä¸å®¹æ˜“找到。更糟糕的是，将æŸä¸ª +动作的方案设置得过于激进会导致严é‡çš„开销。为了é¿å…è¿™ç§å¼€é”€ï¼Œç”¨æˆ·å¯ä»¥é€šè¿‡ä¸‹é¢è¡¨æ ¼ä¸çš„ ``<quota>`` +æ¥é™åˆ¶æ–¹æ¡ˆçš„时间和大å°é…é¢:: + + <ms> <sz> <reset interval> <priority weights> + +这使得DAMON在 ``<reset interval>`` 毫秒内，尽é‡åªç”¨ ``<ms>`` 毫秒的时间对 ``ç›®æ ‡è®¿ +问模å¼`` 的内å˜åŒºåŸŸåº”用动作，并在 ``<reset interval>`` 内åªå¯¹æœ€å¤š<sz>å—节的内å˜åŒºåŸŸåº” +用动作。将 ``<ms>`` å’Œ ``<sz>`` 都设置为零，å¯ä»¥ç¦ç”¨é…é¢é™åˆ¶ã€‚ + +当预计超过é…é¢é™åˆ¶æ—¶ï¼ŒDAMONä¼šæ ¹æ® ``ç›®æ ‡è®¿é—®æ¨¡å¼`` 的大å°ã€è®¿é—®é¢‘率和年龄，对å‘çŽ°çš„å†…å˜ +区域进行优先排åºã€‚为了实现个性化的优先级，用户å¯ä»¥åœ¨ ``<优先级æƒé‡>`` ä¸è®¾ç½®è¿™ä¸‰ä¸ªå±žæ€§çš„ +æƒé‡ï¼Œå…·ä½“å½¢å¼å¦‚下:: + + <size weight> <access frequency weight> <age weight> + +æ°´ä½ +~~~~ + +有些方案需è¦æ ¹æ®ç³»ç»Ÿç‰¹å®šæŒ‡æ ‡çš„当å‰å€¼æ¥è¿è¡Œï¼Œå¦‚自由内å˜æ¯”率。对于这ç§æƒ…况，用户å¯ä»¥ä¸ºè¯¥æ¡ +件指定水ä½ã€‚:: + + <metric> <check interval> <high mark> <middle mark> <low mark> + +``<metric>`` 是一个预定义的整数，用于è¦æ£€æŸ¥çš„度é‡ã€‚支æŒçš„æ•°å—和它们的å«ä¹‰å¦‚下。 + + - 0: å¿½è§†æ°´ä½ + - 1: 系统空闲内å˜çŽ‡ (åƒåˆ†æ¯”) + +æ¯éš” ``<检查间隔>`` 微秒检查一次公制的值。 + +如果该值高于 ``<é«˜æ ‡>`` 或低于 ``<ä½Žæ ‡>`` ，该方案被åœç”¨ã€‚如果该值低于 ``<ä¸æ ‡>`` ， +该方案将被激活。 + +ç»Ÿè®¡æ•°æ® +~~~~~~~~ + +它还统计æ¯ä¸ªæ–¹æ¡ˆè¢«å°è¯•åº”用的区域的总数é‡å’Œå—节数，æ¯ä¸ªæ–¹æ¡ˆè¢«æˆåŠŸåº”用的区域的两个数é‡ï¼Œä»¥ +åŠè¶…过é…é¢é™åˆ¶çš„总数é‡ã€‚这些统计数æ®å¯ç”¨äºŽåœ¨çº¿åˆ†æžæˆ–调整方案。 + +统计数æ®å¯ä»¥é€šè¿‡è¯»å–方案文件æ¥æ˜¾ç¤ºã€‚读å–è¯¥æ–‡ä»¶å°†æ˜¾ç¤ºä½ åœ¨æ¯ä¸€è¡Œä¸è¾“入的æ¯ä¸ª ``方案`` ， +统计的五个数å—å°†è¢«åŠ åœ¨æ¯ä¸€è¡Œçš„末尾。 + +例å +~~~~ + +下é¢çš„命令应用了一个方案：â€å¦‚果一个大å°ä¸º[4KiB, 8KiB]的内å˜åŒºåŸŸåœ¨[10, 20]çš„èšåˆæ—¶é—´ +间隔内显示出æ¯ä¸€ä¸ªèšåˆæ—¶é—´é—´éš”[0, 5]的访问é‡ï¼Œè¯·åˆ†é¡µå‡ºè¯¥åŒºåŸŸã€‚对于分页，æ¯ç§’最多åªèƒ½ä½¿ +用10ms，而且æ¯ç§’分页ä¸èƒ½è¶…过1GiB。在这一é™åˆ¶ä¸‹ï¼Œé¦–先分页出具有较长年龄的内å˜åŒºåŸŸã€‚å¦å¤–， +æ¯5秒钟检查一次系统的å¯ç”¨å†…å˜çŽ‡ï¼Œå½“å¯ç”¨å†…å˜çŽ‡ä½ŽäºŽ50%时开始监测和分页，但如果å¯ç”¨å†…å˜çŽ‡ +大于60%，或低于30%，则åœæ¢ç›‘测“:: + + # cd <debugfs>/damon + # scheme="4096 8192 0 5 10 20 2" # target access pattern and action + # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas + # scheme+=" 0 0 100" # prioritization weights + # scheme+=" 1 5000000 600 500 300" # watermarks + # echo "$scheme" > schemes + + +开关 +---- + +除éžä½ 明确地å¯åŠ¨ç›‘测，å¦åˆ™å¦‚上所述的文件设置ä¸ä¼šäº§ç”Ÿæ•ˆæžœã€‚ä½ å¯ä»¥é€šè¿‡å†™å…¥å’Œè¯»å– ``monitor_on`` +文件æ¥å¯åŠ¨ã€åœæ¢å’Œæ£€æŸ¥ç›‘测的当å‰çŠ¶æ€ã€‚写入 ``on`` 该文件å¯ä»¥å¯åŠ¨å¯¹æœ‰å±žæ€§çš„ç›®æ ‡çš„ç›‘æµ‹ã€‚å†™å…¥ +``off`` 该文件则åœæ¢è¿™äº›ç›®æ ‡ã€‚如果æ¯ä¸ªç›®æ ‡è¿›ç¨‹è¢«ç»ˆæ¢ï¼ŒDAMON也会åœæ¢ã€‚下é¢çš„示例命令开å¯ã€å…³ +é—和检查DAMON的状æ€:: + + # cd <debugfs>/damon + # echo on > monitor_on + # echo off > monitor_on + # cat monitor_on + off + +请注æ„，当监测开å¯æ—¶ï¼Œä½ ä¸èƒ½å†™åˆ°ä¸Šè¿°çš„debugfsæ–‡ä»¶ã€‚å¦‚æžœä½ åœ¨DAMONè¿è¡Œæ—¶å†™åˆ°è¿™äº›æ–‡ä»¶ï¼Œå°†ä¼šè¿” +回一个错误代ç ，如 ``-EBUSY`` 。 + + +监测线程PID +----------- + +DAMON通过一个å«åškdamondçš„å†…æ ¸çº¿ç¨‹æ¥è¿›è¡Œè¯·æ±‚ç›‘æµ‹ã€‚ä½ å¯ä»¥é€šè¿‡è¯»å– ``kdamond_pid`` 文件获 +得该线程的 ``pid`` 。当监测被 ``å…³é—`` 时，读å–该文件ä¸ä¼šè¿”回任何信æ¯:: + + # cd <debugfs>/damon + # cat monitor_on + off + # cat kdamond_pid + none + # echo on > monitor_on + # cat kdamond_pid + 18594 + + +使用多个监测线程 +---------------- + +æ¯ä¸ªç›‘测上下文都会创建一个 ``kdamond`` çº¿ç¨‹ã€‚ä½ å¯ä»¥ä½¿ç”¨ ``mk_contexts`` å’Œ ``rm_contexts`` +文件为多个 ``kdamond`` 需è¦çš„ç”¨ä¾‹åˆ›å»ºå’Œåˆ é™¤ç›‘æµ‹ä¸Šä¸‹æ–‡ã€‚ + +将新上下文的å称写入 ``mk_contexts`` 文件，在 ``DAMON debugfs`` 目录上创建一个该å称的目录。 +该目录将有该上下文的 ``DAMON debugfs`` 文件:: + + # cd <debugfs>/damon + # ls foo + # ls: cannot access 'foo': No such file or directory + # echo foo > mk_contexts + # ls foo + # attrs init_regions kdamond_pid schemes target_ids + +如果ä¸å†éœ€è¦ä¸Šä¸‹æ–‡ï¼Œä½ å¯ä»¥é€šè¿‡æŠŠä¸Šä¸‹æ–‡çš„åå—放到 ``rm_contexts`` 文件ä¸æ¥åˆ 除它和相应的目录:: + + # echo foo > rm_contexts + # ls foo + # ls: cannot access 'foo': No such file or directory + +注æ„， ``mk_contexts`` 〠``rm_contexts`` å’Œ ``monitor_on`` 文件åªåœ¨æ ¹ç›®å½•ä¸‹ã€‚ + + +监测结果的监测点 +================ + +DAMON通过一个tracepoint ``damon:damon_aggregated`` æ供监测结果. 当监测开å¯æ—¶ï¼Œä½ å¯ +以记录追踪点事件，并使用追踪点支æŒå·¥å…·å¦‚perf显示结果。比如说:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script diff --git a/Documentation/translations/zh_CN/admin-guide/mm/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/index.rst new file mode 100644 index 000000000000..702271c5b683 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/index.rst @@ -0,0 +1,49 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/index.rst + +:翻译: + + å¾é‘« xu xin <xu.xin16@zte.com.cn> + + +======== +内å˜ç®¡ç† +======== + +Linux内å˜ç®¡ç†å系统，顾åæ€ä¹‰ï¼Œæ˜¯è´Ÿè´£ç³»ç»Ÿä¸çš„内å˜ç®¡ç†ã€‚它包括了虚拟内å˜ä¸Žè¯·æ±‚ +åˆ†é¡µçš„å®žçŽ°ï¼Œå†…æ ¸å†…éƒ¨ç»“æž„å’Œç”¨æˆ·ç©ºé—´ç¨‹åºçš„内å˜åˆ†é…ã€å°†æ–‡ä»¶æ˜ 射到进程地å€ç©ºé—´ä»¥ +åŠè®¸å¤šå…¶ä»–很酷的事情。 + +Linux内å˜ç®¡ç†æ˜¯ä¸€ä¸ªå…·æœ‰è®¸å¤šå¯é…置设置的å¤æ‚系统, 且这些设置ä¸çš„大多数都å¯ä»¥é€š +过 ``/proc`` 文件系统获得，并且å¯ä»¥ä½¿ç”¨ ``sysctl`` 进行查询和调整。这些API接 +å£è¢«æ述在Documentation/admin-guide/sysctl/vm.rst文件和 `man 5 proc`_ ä¸ã€‚ + +.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html + +Linux内å˜ç®¡ç†æœ‰å®ƒè‡ªå·±çš„术è¯ï¼Œå¦‚æžœä½ è¿˜ä¸ç†Ÿæ‚‰å®ƒï¼Œè¯·è€ƒè™‘阅读下é¢å‚考： +:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. + +在æ¤ç›®å½•ä¸‹ï¼Œæˆ‘们详细æ述了如何与Linux内å˜ç®¡ç†ä¸çš„å„ç§æœºåˆ¶äº¤äº’。 + +.. toctree:: + :maxdepth: 1 + + damon/index + ksm + +Todolist: +* concepts +* cma_debugfs +* hugetlbpage +* idle_page_tracking +* memory-hotplug +* nommu-mmap +* numa_memory_policy +* numaperf +* pagemap +* soft-dirty +* swap_numa +* transhuge +* userfaultfd +* zswap diff --git a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst new file mode 100644 index 000000000000..4829156ef1ae --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst @@ -0,0 +1,148 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/ksm.rst + +:翻译: + + å¾é‘« xu xin <xu.xin16@zte.com.cn> + + +============ +å†…æ ¸åŒé¡µåˆå¹¶ +============ + + +概述 +==== + +KSM是一ç§èƒ½èŠ‚çœå†…å˜çš„æ•°æ®åŽ»é‡åŠŸèƒ½ï¼Œç”±CONFIG_KSM=yå¯ç”¨ï¼Œå¹¶åœ¨2.6.32版本时被添 +åŠ åˆ°Linuxå†…æ ¸ã€‚è¯¦è§ ``mm/ksm.c`` 的实现，以åŠhttp://lwn.net/Articles/306704 +å’Œhttps://lwn.net/Articles/330589 + +KSM最åˆç›®çš„是为了与KVM（å³è‘—åçš„å†…æ ¸å…±äº«å†…å˜ï¼‰ä¸€èµ·ä½¿ç”¨è€Œå¼€å‘的，通过共享虚拟机 +之间的公共数æ®ï¼Œå°†æ›´å¤šè™šæ‹Ÿæœºæ”¾å…¥ç‰©ç†å†…å˜ã€‚但它对于任何会生æˆå¤šä¸ªç›¸åŒæ•°æ®å®žä¾‹çš„ +应用程åºéƒ½æ˜¯å¾ˆæœ‰ç”¨çš„。 + +KSM的守护进程ksmd会定期扫æ那些已注册的用户内å˜åŒºåŸŸï¼ŒæŸ¥æ‰¾å†…容相åŒçš„页é¢ï¼Œè¿™äº› +页é¢å¯ä»¥è¢«å•ä¸ªå†™ä¿æŠ¤é¡µé¢æ›¿æ¢ï¼ˆå¦‚果进程以åŽæƒ³è¦æ›´æ–°å…¶å†…容，将自动å¤åˆ¶ï¼‰ã€‚使用： +引用:`sysfs intraface <ksm_sysfs>` 接å£æ¥é…ç½®KSM守护程åºåœ¨å•ä¸ªè¿‡ç¨‹ä¸æ‰€æ‰«æ的页 +数以åŠä¸¤ä¸ªè¿‡ç¨‹ä¹‹é—´çš„间隔时间。 + +KSMåªåˆå¹¶åŒ¿å（ç§æœ‰ï¼‰é¡µé¢ï¼Œä»Žä¸åˆå¹¶é¡µç¼“å˜ï¼ˆæ–‡ä»¶ï¼‰é¡µé¢ã€‚KSMçš„åˆå¹¶é¡µé¢æœ€åˆåªèƒ½è¢« +é”å®šåœ¨å†…æ ¸å†…å˜ä¸ï¼Œä½†çŽ°åœ¨å¯ä»¥å°±åƒå…¶ä»–用户页é¢ä¸€æ ·è¢«æ¢å‡ºï¼ˆä½†å½“它们被交æ¢å›žæ¥æ—¶å…± +äº«ä¼šè¢«ç ´å: ksmdå¿…é¡»é‡æ–°å‘现它们的身份并å†æ¬¡åˆå¹¶ï¼‰ã€‚ + +以madvise控制KSM +================ + +KSM仅在特定的地å€ç©ºé—´åŒºåŸŸæ—¶è¿è¡Œï¼Œå³åº”用程åºé€šè¿‡ä½¿ç”¨å¦‚下所示的madvise(2)系统调 +用æ¥è¯·æ±‚æŸå—地å€æˆä¸ºå¯èƒ½çš„åˆå¹¶å€™é€‰è€…的地å€ç©ºé—´:: + + int madvise(addr, length, MADV_MERGEABLE) + +应用程åºå½“然也å¯ä»¥é€šè¿‡è°ƒç”¨:: + + int madvise(addr, length, MADV_UNMERGEABLE) + +æ¥å–消该请求，并æ¢å¤ä¸ºéžå…±äº«é¡µé¢ï¼šæ¤æ—¶KSM将去除åˆå¹¶åœ¨è¯¥èŒƒå›´å†…的任何åˆå¹¶é¡µã€‚注æ„： +这个去除åˆå¹¶çš„调用å¯èƒ½çªç„¶éœ€è¦çš„内å˜é‡è¶…过实际å¯ç”¨çš„内å˜é‡-那么å¯èƒ½ä¼šå‡ºçŽ°EAGAIN +失败，但更å¯èƒ½ä¼šå”¤é†’OOM killer。 + +如果KSM未被é…置到æ£åœ¨è¿è¡Œçš„å†…æ ¸ä¸ï¼Œåˆ™madvise MADV_MERGEABLE å’Œ MADV_UNMERGEABLE +的调用åªä¼šä»¥EINVAL 失败。如果æ£åœ¨è¿è¡Œçš„å†…æ ¸æ˜¯ç”¨CONFIG_KSM=yæ–¹å¼æž„建的，那么这些 +调用通常会æˆåŠŸï¼šå³ä½¿KSM守护程åºå½“å‰æ²¡æœ‰è¿è¡Œï¼ŒMADV_MERGEABLE ä»ç„¶ä¼šåœ¨KSMå®ˆæŠ¤ç¨‹åº +å¯åŠ¨æ—¶æ³¨å†ŒèŒƒå›´ï¼Œå³ä½¿è¯¥èŒƒå›´ä¸èƒ½åŒ…å«KSM实际å¯ä»¥åˆå¹¶çš„任何页é¢ï¼Œå³ä½¿MADV_UNMERGEABLE +åº”ç”¨äºŽä»Žæœªæ ‡è®°ä¸ºMADV_MERGEABLE的范围。 + +如果一å—内å˜åŒºåŸŸå¿…须被拆分为至少一个新的MADV_MERGEABLE区域或MADV_UNMERGEABLE区域， +当该进程将超过 ``vm.max_map_count`` 的设定，则madviseå¯èƒ½è¿”回ENOMEM。（请å‚阅文档 +Documentation/admin-guide/sysctl/vm.rst）。 + +与其他madviseè°ƒç”¨ä¸€æ ·ï¼Œå®ƒä»¬åœ¨ç”¨æˆ·åœ°å€ç©ºé—´çš„æ˜ å°„åŒºåŸŸä¸Šä½¿ç”¨ï¼šå¦‚æžœæŒ‡å®šçš„èŒƒå›´åŒ…å«æœª +æ˜ å°„çš„é—´éš™ï¼ˆå°½ç®¡åœ¨ä¸é—´çš„æ˜ å°„åŒºåŸŸå·¥ä½œï¼‰ï¼Œå®ƒä»¬å°†æŠ¥å‘ŠENOMEM，如果没有足够的内å˜ç”¨äºŽ +内部结构，则å¯èƒ½ä¼šå› EAGAIN而失败。 + +KSM守护进程sysfsæŽ¥å£ +==================== + +KSM守护进程å¯ä»¥ç”±``/sys/kernel/mm/ksm/`` ä¸çš„sysfs文件控制，所有人都å¯ä»¥è¯»å–，但 +åªèƒ½ç”±root用户写入。å„接å£è§£é‡Šå¦‚下： + + +pages_to_scan + ksmd进程进入ç¡çœ å‰è¦æ‰«æ的页数。 + 例如， ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan`` + + 默认值：100（该值被选择用于演示目的） + +sleep_millisecs + ksmd在下次扫æå‰åº”ä¼‘çœ å¤šå°‘æ¯«ç§’ + 例如， ``echo 20 > /sys/kernel/mm/ksm/sleep_millisecs`` + + 默认值：20（该值被选择用于演示目的） + +merge_across_nodes + 指定是å¦å¯ä»¥åˆå¹¶æ¥è‡ªä¸åŒNUMA节点的页é¢ã€‚当设置为0时，ksmä»…åˆå¹¶åœ¨ç‰©ç†ä¸Šä½ + 于åŒä¸€NUMA节点的内å˜åŒºåŸŸä¸çš„页é¢ã€‚è¿™é™ä½Žäº†è®¿é—®å…±äº«é¡µé¢çš„延迟。在有明显的 + NUMAè·ç¦»ä¸Šï¼Œå…·æœ‰æ›´å¤šèŠ‚点的系统å¯èƒ½å—益于设置该值为0时的更低延迟。而对于 + 需è¦å¯¹å†…å˜ä½¿ç”¨é‡æœ€å°åŒ–的较å°ç³»ç»Ÿæ¥è¯´ï¼Œè®¾ç½®è¯¥å€¼ä¸º1（默认设置）则å¯èƒ½ä¼šå— + 益于更大共享页é¢ã€‚在决定使用哪ç§è®¾ç½®ä¹‹å‰ï¼Œæ‚¨å¯èƒ½å¸Œæœ›æ¯”较系统在æ¯ç§è®¾ç½®ä¸‹ + 的性能。 ``merge_across_nodes`` 仅当系统ä¸æ²¡æœ‰ksm共享页é¢æ—¶ï¼Œæ‰èƒ½è¢«æ›´æ”¹è®¾ + 置：首先将接å£`run` 设置为2从而对页进行去åˆå¹¶ï¼Œç„¶åŽåœ¨ä¿®æ”¹ + ``merge_across_nodes`` åŽå†å°†â€˜run’åˆè®¾ç½®ä¸º1ï¼Œä»¥æ ¹æ®æ–°è®¾ç½®æ¥é‡æ–°åˆå¹¶ã€‚ + + 默认值：1（如早期的å‘å¸ƒç‰ˆæœ¬ä¸€æ ·åˆå¹¶è·¨ç«™ç‚¹ï¼‰ + +run + * 设置为0å¯åœæ¢ksmdè¿è¡Œï¼Œä½†ä¿ç•™åˆå¹¶é¡µé¢ï¼Œ + * 设置为1å¯è¿è¡Œksmd，例如， ``echo 1 > /sys/kernel/mm/ksm/run`` ， + * 设置为2å¯åœæ¢ksmdè¿è¡Œï¼Œå¹¶ä¸”对所有目å‰å·²åˆå¹¶çš„页进行去åˆå¹¶ï¼Œä½†ä¿ç•™å¯åˆå¹¶ + 区域以供下次è¿è¡Œã€‚ + + 默认值：0（必须设置为1æ‰èƒ½æ¿€æ´»KSM，除éžç¦ç”¨äº†CONFIG_SYSFS） + +use_zero_pages + 指定是å¦åº”当特殊处ç†ç©ºé¡µï¼ˆå³é‚£äº›ä»…å«zero的已分é…页）。当该值设置为1时， + ç©ºé¡µä¸Žå†…æ ¸é›¶é¡µåˆå¹¶ï¼Œè€Œä¸æ˜¯åƒé€šå¸¸æƒ…å†µä¸‹é‚£æ ·ç©ºé¡µè‡ªèº«å½¼æ¤åˆå¹¶ã€‚è¿™å¯ä»¥æ ¹æ® + 工作负载的ä¸åŒï¼Œåœ¨å…·æœ‰ç€è‰²é›¶é¡µçš„架构上å¯ä»¥æ高性能。å¯ç”¨æ¤è®¾ç½®æ—¶åº”å°å¿ƒï¼Œ + å› ä¸ºå®ƒå¯èƒ½ä¼šé™ä½ŽæŸäº›å·¥ä½œè´Ÿè½½çš„KSM性能，比如，当待åˆå¹¶çš„候选页é¢çš„æ ¡éªŒå’Œ + 与空页é¢çš„æ ¡éªŒå’Œæ°å¥½åŒ¹é…的时候。æ¤è®¾ç½®å¯éšæ—¶æ›´æ”¹ï¼Œä»…对那些更改åŽå†åˆå¹¶ + 的页é¢æœ‰æ•ˆã€‚ + + 默认值：0（如åŒæ—©æœŸç‰ˆæœ¬çš„KSMæ£å¸¸è¡¨çŽ°ï¼‰ + +max_page_sharing + å•ä¸ªKSM页é¢å…许的最大共享站点数。这将强制执行é‡å¤æ•°æ®æ¶ˆé™¤é™åˆ¶ï¼Œä»¥é¿å…涉 + åŠé历共享KSM页é¢çš„è™šæ‹Ÿæ˜ å°„çš„è™šæ‹Ÿå†…å˜æ“作的高延迟。最å°å€¼ä¸º2ï¼Œå› ä¸ºæ–°åˆ› + 建的KSM页é¢å°†è‡³å°‘有两个共享者。该值越高，KSMåˆå¹¶å†…å˜çš„é€Ÿåº¦è¶Šå¿«ï¼ŒåŽ»é‡ + å› å也越高，但是对于任何给定的KSM页é¢ï¼Œè™šæ‹Ÿæ˜ 射的最å情况é历的速度也会 + 越慢。å‡æ…¢äº†è¿™ç§é历速度就æ„味ç€åœ¨äº¤æ¢ã€åŽ‹ç¼©ã€NUMA平衡和页é¢è¿ç§»æœŸé—´ï¼Œ + æŸäº›è™šæ‹Ÿå†…å˜æ“作将有更高的延迟，从而é™ä½Žè¿™äº›è™šæ‹Ÿå†…å˜æ“作调用者的å“应能力。 + 其他任务如果ä¸æ¶‰åŠæ‰§è¡Œè™šæ‹Ÿæ˜ å°„é历的VMæ“作，其任务调度延迟ä¸å—æ¤å‚æ•°çš„å½± + å“ï¼Œå› ä¸ºè¿™äº›é历本身是调度å‹å¥½çš„。 + +stable_node_chains_prune_millisecs + 指定KSM检查特定页é¢çš„元数æ®çš„频率（å³é‚£äº›è¾¾åˆ°è¿‡æ—¶ä¿¡æ¯æ•°æ®åŽ»é‡é™åˆ¶æ ‡å‡†çš„ + 页é¢ï¼‰å•ä½æ˜¯æ¯«ç§’。较å°çš„毫秒值将以更低的延迟æ¥é‡Šæ”¾KSM元数æ®ï¼Œä½†å®ƒä»¬å°†ä½¿ + ksmd在扫æ期间使用更多CPU。如果还没有一个KSM页é¢è¾¾åˆ° ``max_page_sharing`` + æ ‡å‡†ï¼Œé‚£å°±æ²¡æœ‰ä»€ä¹ˆç”¨ã€‚ + +KSM与MADV_MERGEABLE的工作有效性体现于 ``/sys/kernel/mm/ksm/`` 路径下的接å£ï¼š + +pages_shared + 表示多少共享页æ£åœ¨è¢«ä½¿ç”¨ +pages_sharing + 表示还有多少站点æ£åœ¨å…±äº«è¿™äº›å…±äº«é¡µï¼Œå³èŠ‚çœäº†å¤šå°‘ +pages_unshared + 表示有多少页是唯一的，但被åå¤æ£€æŸ¥ä»¥è¿›è¡Œåˆå¹¶ +pages_volatile + è¡¨ç¤ºæœ‰å¤šå°‘é¡µå› å˜åŒ–å¤ªå¿«è€Œæ— æ³•æ”¾åœ¨treeä¸ +full_scans + 表示所有å¯åˆå¹¶åŒºåŸŸå·²æ‰«æ多少次 +stable_node_chains + 达到 ``max_page_sharing`` é™åˆ¶çš„KSM页数 +stable_node_dups + é‡å¤çš„KSM页数 + +比值 ``pages_sharing/pages_shared`` 的最大值å—é™åˆ¶äºŽ ``max_page_sharing`` +的设定。è¦æƒ³å¢žåŠ 该比值，则相应地è¦å¢žåŠ ``max_page_sharing`` 的值。 diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index d10191c45cf1..26d9913fc8b6 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -42,6 +42,7 @@ kref assoc_array xarray + rbtree Todolist: @@ -49,7 +50,6 @@ Todolist: idr circular-buffers - rbtree generic-radix-tree packing bus-virt-phys-mapping diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index ab7d81889340..e45fe80d1cd8 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -292,8 +292,6 @@ block/blk-sysfs.c block/blk-settings.c -block/blk-exec.c - block/blk-flush.c block/blk-lib.c diff --git a/Documentation/translations/zh_CN/core-api/kobject.rst b/Documentation/translations/zh_CN/core-api/kobject.rst index b7c37794cc7f..0747b472fdea 100644 --- a/Documentation/translations/zh_CN/core-api/kobject.rst +++ b/Documentation/translations/zh_CN/core-api/kobject.rst @@ -258,7 +258,6 @@ kobject_put()以é¿å…错误的å‘生是一个很好的åšæ³•ã€‚ struct kobj_type { void (*release)(struct kobject *kobj); const struct sysfs_ops *sysfs_ops; - struct attribute **default_attrs; const struct attribute_group **default_groups; const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj); const void *(*namespace)(struct kobject *kobj); @@ -271,10 +270,10 @@ kobject_init()或kobject_init_and_add()时必须指定一个指å‘该结构的 指针。 当然，kobj_type结构ä¸çš„releaseå—段是指å‘è¿™ç§ç±»åž‹çš„kobjectçš„release() -方法的一个指针。å¦å¤–两个å—段（sysfs_ops å’Œ default_attrsï¼‰æŽ§åˆ¶è¿™ç§ +方法的一个指针。å¦å¤–两个å—段（sysfs_ops å’Œ default_groupsï¼‰æŽ§åˆ¶è¿™ç§ ç±»åž‹çš„å¯¹è±¡å¦‚ä½•åœ¨ sysfs ä¸è¢«è¡¨ç¤ºï¼›å®ƒä»¬è¶…出了本文的范围。 -default_attrs 指针是一个默认属性的列表，它将为任何用这个 ktype 注册 +default_groups 指针是一个默认属性的列表，它将为任何用这个 ktype 注册 çš„ kobject 自动创建。 @@ -325,10 +324,9 @@ ksets 结构体kset_uevent_opsæ¥å¤„ç†å®ƒ:: struct kset_uevent_ops { - int (* const filter)(struct kset *kset, struct kobject *kobj); - const char *(* const name)(struct kset *kset, struct kobject *kobj); - int (* const uevent)(struct kset *kset, struct kobject *kobj, - struct kobj_uevent_env *env); + int (* const filter)(struct kobject *kobj); + const char *(* const name)(struct kobject *kobj); + int (* const uevent)(struct kobject *kobj, struct kobj_uevent_env *env); }; diff --git a/Documentation/translations/zh_CN/core-api/rbtree.rst b/Documentation/translations/zh_CN/core-api/rbtree.rst new file mode 100644 index 000000000000..a3e1555cb974 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/rbtree.rst @@ -0,0 +1,391 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/rbtree.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========================= +Linuxä¸çš„çº¢é»‘æ ‘ï¼ˆrbtree） +========================= + + +:日期: 2007å¹´1月18æ—¥ +:作者: Rob Landley <rob@landley.net> + +ä½•ä¸ºçº¢é»‘æ ‘ï¼Œå®ƒä»¬æœ‰ä»€ä¹ˆç”¨ï¼Ÿ +-------------------------- + +çº¢é»‘æ ‘æ˜¯ä¸€ç§è‡ªå¹³è¡¡äºŒå‰æœç´¢æ ‘，被用æ¥å˜å‚¨å¯æŽ’åºçš„é”®/值数æ®å¯¹ã€‚è¿™ä¸ŽåŸºæ•°æ ‘ï¼ˆè¢«ç”¨æ¥é«˜æ•ˆ +å˜å‚¨ç¨€ç–æ•°ç»„ï¼Œå› æ¤ä½¿ç”¨é•¿æ•´åž‹ä¸‹æ ‡æ¥æ’å…¥/访问/åˆ é™¤ç»“ç‚¹ï¼‰å’Œå“ˆå¸Œè¡¨ï¼ˆæ²¡æœ‰ä¿æŒæŽ’åºå› è€Œæ— æ³• +容易地按åºé历，åŒæ—¶å¿…须调节其大å°å’Œå“ˆå¸Œå‡½æ•°ï¼Œç„¶è€Œçº¢é»‘æ ‘å¯ä»¥ä¼˜é›…地伸缩以便å˜å‚¨ä»»æ„ +æ•°é‡çš„键）ä¸åŒã€‚ + +çº¢é»‘æ ‘å’ŒAVLæ ‘ç±»ä¼¼ï¼Œä½†åœ¨æ’å…¥å’Œåˆ é™¤æ—¶æ供了更快的实时有界的最å情况性能（分别最多两次 +旋转和三次旋转，æ¥å¹³è¡¡æ ‘），查询时间轻微å˜æ…¢ï¼ˆä½†æ—¶é—´å¤æ‚度ä»ç„¶æ˜¯O(log n)）。 + +引用Linuxæ¯å‘¨æ–°é—»ï¼ˆLinux Weekly News）： + + å†…æ ¸ä¸æœ‰å¤šå¤„çº¢é»‘æ ‘çš„ä½¿ç”¨æ¡ˆä¾‹ã€‚æœ€åŽæœŸé™è°ƒåº¦å™¨å’Œå®Œå…¨å…¬å¹³æŽ’队（CFQ）I/O调度器利用 + çº¢é»‘æ ‘è·Ÿè¸ªè¯·æ±‚ï¼›æ•°æ®åŒ…CD/DVD驱动程åºä¹Ÿæ˜¯å¦‚æ¤ã€‚高精度时钟代ç ä½¿ç”¨ä¸€é¢—çº¢é»‘æ ‘ç»„ç»‡ + 未完æˆçš„定时器请求。ext3æ–‡ä»¶ç³»ç»Ÿç”¨çº¢é»‘æ ‘è·Ÿè¸ªç›®å½•é¡¹ã€‚è™šæ‹Ÿå†…å˜åŒºåŸŸï¼ˆVMAs）ã€epoll + 文件æ述符ã€å¯†ç å¦å¯†é’¥å’Œåœ¨â€œåˆ†å±‚令牌桶â€è°ƒåº¦å™¨ä¸çš„网络数æ®åŒ…éƒ½ç”±çº¢é»‘æ ‘è·Ÿè¸ªã€‚ + +本文档涵盖了对Linuxçº¢é»‘æ ‘å®žçŽ°çš„ä½¿ç”¨æ–¹æ³•ã€‚æ›´å¤šå…³äºŽçº¢é»‘æ ‘çš„æ€§è´¨å’Œå®žçŽ°çš„ä¿¡æ¯ï¼Œå‚è§ï¼š + + Linuxæ¯å‘¨æ–°é—»å…³äºŽçº¢é»‘æ ‘çš„æ–‡ç« + https://lwn.net/Articles/184495/ + + ç»´åŸºç™¾ç§‘çº¢é»‘æ ‘è¯æ¡ + https://en.wikipedia.org/wiki/Red-black_tree + +çº¢é»‘æ ‘çš„Linux实现 +----------------- + +Linuxçš„çº¢é»‘æ ‘å®žçŽ°åœ¨æ–‡ä»¶â€œlib/rbtree.câ€ä¸ã€‚è¦ä½¿ç”¨å®ƒï¼Œéœ€è¦â€œ#include <linux/rbtree.h>â€ã€‚ + +Linuxçš„çº¢é»‘æ ‘å®žçŽ°å¯¹é€Ÿåº¦è¿›è¡Œäº†ä¼˜åŒ–ï¼Œå› æ¤æ¯”ä¼ ç»Ÿçš„å®žçŽ°å°‘ä¸€ä¸ªé—´æŽ¥å±‚ï¼ˆæœ‰æ›´å¥½çš„ç¼“å˜å±€éƒ¨æ€§ï¼‰ã€‚ +æ¯ä¸ªrb_node结构体的实例嵌入在它管ç†çš„æ•°æ®ç»“æž„ä¸ï¼Œå› æ¤ä¸éœ€è¦é 指针æ¥åˆ†ç¦»rb_node和它 +管ç†çš„æ•°æ®ç»“æž„ã€‚ç”¨æˆ·åº”è¯¥ç¼–å†™ä»–ä»¬è‡ªå·±çš„æ ‘æœç´¢å’Œæ’入函数，æ¥è°ƒç”¨å·²æä¾›çš„çº¢é»‘æ ‘å‡½æ•°ï¼Œ +而ä¸æ˜¯ä½¿ç”¨ä¸€ä¸ªæ¯”è¾ƒå›žè°ƒå‡½æ•°æŒ‡é’ˆã€‚åŠ é”代ç ä¹Ÿç•™ç»™çº¢é»‘æ ‘çš„ç”¨æˆ·ç¼–å†™ã€‚ + +åˆ›å»ºä¸€é¢—çº¢é»‘æ ‘ +-------------- + +çº¢é»‘æ ‘ä¸çš„æ•°æ®ç»“点是包å«rb_node结构体æˆå‘˜çš„结构体:: + + struct mytype { + struct rb_node node; + char *keystring; + }; + +当处ç†ä¸€ä¸ªæŒ‡å‘内嵌rb_node结构体的指针时，包ä½rb_node的结构体å¯ç”¨æ ‡å‡†çš„container_of() +å®è®¿é—®ã€‚æ¤å¤–，个体æˆå‘˜å¯ç›´æŽ¥ç”¨rb_entry(node, type, member)访问。 + +æ¯é¢—çº¢é»‘æ ‘çš„æ ¹æ˜¯ä¸€ä¸ªrb_rootæ•°æ®ç»“构，它由以下方å¼åˆå§‹åŒ–为空: + + struct rb_root mytree = RB_ROOT; + +åœ¨ä¸€é¢—çº¢é»‘æ ‘ä¸æœç´¢å€¼ +-------------------- + +ä¸ºä½ çš„æ ‘å†™ä¸€ä¸ªæœç´¢å‡½æ•°æ˜¯ç›¸å½“简å•çš„ï¼šä»Žæ ‘æ ¹å¼€å§‹ï¼Œæ¯”è¾ƒæ¯ä¸ªå€¼ï¼Œç„¶åŽæ ¹æ®éœ€è¦ç»§ç»å‰å¾€å·¦è¾¹æˆ– +å³è¾¹çš„分支。 + +示例:: + + struct mytype *my_search(struct rb_root *root, char *string) + { + struct rb_node *node = root->rb_node; + + while (node) { + struct mytype *data = container_of(node, struct mytype, node); + int result; + + result = strcmp(string, data->keystring); + + if (result < 0) + node = node->rb_left; + else if (result > 0) + node = node->rb_right; + else + return data; + } + return NULL; + } + +åœ¨ä¸€é¢—çº¢é»‘æ ‘ä¸æ’å…¥æ•°æ® +---------------------- + +åœ¨æ ‘ä¸æ’入数æ®çš„æ¥éª¤åŒ…括：首先æœç´¢æ’入新结点的ä½ç½®ï¼Œç„¶åŽæ’å…¥ç»“ç‚¹å¹¶å¯¹æ ‘å†å¹³è¡¡ +（"recoloring"）。 + +æ’入的æœç´¢å’Œä¸Šæ–‡çš„æœç´¢ä¸åŒï¼Œå®ƒè¦æ‰¾åˆ°å«æŽ¥æ–°ç»“点的ä½ç½®ã€‚新结点也需è¦ä¸€ä¸ªæŒ‡å‘它的父节点 +的链接，以达到å†å¹³è¡¡çš„目的。 + +示例:: + + int my_insert(struct rb_root *root, struct mytype *data) + { + struct rb_node **new = &(root->rb_node), *parent = NULL; + + /* Figure out where to put new node */ + while (*new) { + struct mytype *this = container_of(*new, struct mytype, node); + int result = strcmp(data->keystring, this->keystring); + + parent = *new; + if (result < 0) + new = &((*new)->rb_left); + else if (result > 0) + new = &((*new)->rb_right); + else + return FALSE; + } + + /* Add new node and rebalance tree. */ + rb_link_node(&data->node, parent, new); + rb_insert_color(&data->node, root); + + return TRUE; + } + +åœ¨ä¸€é¢—çº¢é»‘æ ‘ä¸åˆ 除或替æ¢å·²ç»å˜åœ¨çš„æ•°æ® +-------------------------------------- + +è‹¥è¦ä»Žæ ‘ä¸åˆ 除一个已ç»å˜åœ¨çš„结点，调用:: + + void rb_erase(struct rb_node *victim, struct rb_root *tree); + +示例:: + + struct mytype *data = mysearch(&mytree, "walrus"); + + if (data) { + rb_erase(&data->node, &mytree); + myfree(data); + } + +è‹¥è¦ç”¨ä¸€ä¸ªæ–°ç»“点替æ¢æ ‘ä¸ä¸€ä¸ªå·²ç»å˜åœ¨çš„键值相åŒçš„结点，调用:: + + void rb_replace_node(struct rb_node *old, struct rb_node *new, + struct rb_root *tree); + +通过这ç§æ–¹å¼æ›¿æ¢ç»“点ä¸ä¼šå¯¹æ ‘åšé‡æŽ’åºï¼šå¦‚果新结点的键值和旧结点ä¸åŒï¼Œçº¢é»‘æ ‘å¯èƒ½è¢« +ç ´å。 + +（按排åºçš„顺åºï¼‰é历å˜å‚¨åœ¨çº¢é»‘æ ‘ä¸çš„å…ƒç´ +---------------------------------------- + +我们æ供了四个函数，用于以排åºçš„æ–¹å¼éåŽ†ä¸€é¢—çº¢é»‘æ ‘çš„å†…å®¹ã€‚è¿™äº›å‡½æ•°å¯ä»¥åœ¨ä»»æ„çº¢é»‘æ ‘ +上工作，并且ä¸éœ€è¦è¢«ä¿®æ”¹æˆ–包装（除éžåŠ é”的目的）:: + + struct rb_node *rb_first(struct rb_root *tree); + struct rb_node *rb_last(struct rb_root *tree); + struct rb_node *rb_next(struct rb_node *node); + struct rb_node *rb_prev(struct rb_node *node); + +è¦å¼€å§‹è¿ä»£ï¼Œéœ€è¦ä½¿ç”¨ä¸€ä¸ªæŒ‡å‘æ ‘æ ¹çš„æŒ‡é’ˆè°ƒç”¨rb_first()或rb_last()ï¼Œå®ƒå°†è¿”å›žä¸€ä¸ªæŒ‡å‘ +æ ‘ä¸ç¬¬ä¸€ä¸ªæˆ–最åŽä¸€ä¸ªå…ƒç´ 所包å«çš„节点结构的指针。è¦ç»§ç»çš„è¯ï¼Œå¯ä»¥åœ¨å½“å‰ç»“点上调用 +rb_next()或rb_prev()æ¥èŽ·å–下一个或上一个结点。当没有剩余的结点时，将返回NULL。 + +è¿ä»£å™¨å‡½æ•°è¿”回一个指å‘被嵌入的rb_node结构体的指针，由æ¤ï¼ŒåŒ…ä½rb_node的结构体å¯ç”¨ +æ ‡å‡†çš„container_of()å®è®¿é—®ã€‚æ¤å¤–，个体æˆå‘˜å¯ç›´æŽ¥ç”¨rb_entry(node, type, member) +访问。 + +示例:: + + struct rb_node *node; + for (node = rb_first(&mytree); node; node = rb_next(node)) + printk("key=%s\n", rb_entry(node, struct mytype, node)->keystring); + +带缓å˜çš„çº¢é»‘æ ‘ +-------------- + +计算最左边（最å°çš„）结点是二å‰æœç´¢æ ‘的一个相当常è§çš„任务，例如用于éåŽ†ï¼Œæˆ–ç”¨æˆ·æ ¹æ® +他们自己的逻辑ä¾èµ–一个特定的顺åºã€‚为æ¤ï¼Œç”¨æˆ·å¯ä»¥ä½¿ç”¨'struct rb_root_cached'æ¥ä¼˜åŒ– +时间å¤æ‚度为O(logN)çš„rb_first()的调用，以简å•åœ°èŽ·å–指针，é¿å…äº†æ½œåœ¨çš„æ˜‚è´µçš„æ ‘è¿ä»£ã€‚ +维护æ“作的é¢å¤–è¿è¡Œæ—¶é—´å¼€é”€å¯å¿½ç•¥ï¼Œä¸è¿‡å†…å˜å 用较大。 + +å’Œrb_root结构体类似，带缓å˜çš„çº¢é»‘æ ‘ç”±ä»¥ä¸‹æ–¹å¼åˆå§‹åŒ–为空:: + + struct rb_root_cached mytree = RB_ROOT_CACHED; + +带缓å˜çš„çº¢é»‘æ ‘åªæ˜¯ä¸€ä¸ªå¸¸è§„çš„rb_rootï¼ŒåŠ ä¸Šä¸€ä¸ªé¢å¤–的指针æ¥ç¼“å˜æœ€å·¦è¾¹çš„节点。这使得 +rb_root_cachedå¯ä»¥å˜åœ¨äºŽrb_rootå˜åœ¨çš„任何地方，并且åªéœ€å¢žåŠ å‡ ä¸ªæŽ¥å£æ¥æ”¯æŒå¸¦ç¼“å˜çš„ +æ ‘:: + + struct rb_node *rb_first_cached(struct rb_root_cached *tree); + void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool); + void rb_erase_cached(struct rb_node *node, struct rb_root_cached *); + +æ“ä½œå’Œåˆ é™¤ä¹Ÿæœ‰å¯¹åº”çš„å¸¦ç¼“å˜çš„æ ‘çš„è°ƒç”¨:: + + void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *, + bool, struct rb_augment_callbacks *); + void rb_erase_augmented_cached(struct rb_node *, struct rb_root_cached *, + struct rb_augment_callbacks *); + + +å¯¹å¢žå¼ºåž‹çº¢é»‘æ ‘çš„æ”¯æŒ +-------------------- + +å¢žå¼ºåž‹çº¢é»‘æ ‘æ˜¯ä¸€ç§åœ¨æ¯ä¸ªç»“点里å˜å‚¨äº†â€œä¸€äº›â€é™„åŠ æ•°æ®çš„çº¢é»‘æ ‘ï¼Œå…¶ä¸ç»“点Nçš„é™„åŠ æ•°æ® +必须是以Nä¸ºæ ¹çš„åæ ‘ä¸æ‰€æœ‰ç»“ç‚¹çš„å†…å®¹çš„å‡½æ•°ã€‚å®ƒæ˜¯å»ºç«‹åœ¨çº¢é»‘æ ‘åŸºç¡€è®¾æ–½ä¹‹ä¸Šçš„å¯é€‰ç‰¹æ€§ã€‚ +想è¦ä½¿ç”¨è¿™ä¸ªç‰¹æ€§çš„çº¢é»‘æ ‘ç”¨æˆ·ï¼Œæ’å…¥å’Œåˆ é™¤ç»“ç‚¹æ—¶å¿…é¡»è°ƒç”¨å¢žå¼ºåž‹æŽ¥å£å¹¶æ供增强型回调函数。 + +å®žçŽ°å¢žå¼ºåž‹çº¢é»‘æ ‘æ“作的C文件必须包å«<linux/rbtree_augmented.h>而ä¸æ˜¯<linux/rbtree.h>。 +注æ„，linux/rbtree_augmented.hæš´éœ²äº†ä¸€äº›çº¢é»‘æ ‘å®žçŽ°çš„ç»†èŠ‚è€Œä½ ä¸åº”ä¾èµ–它们，请åšæŒ +使用文档记录的API，并且ä¸è¦åœ¨å¤´æ–‡ä»¶ä¸åŒ…å«<linux/rbtree_augmented.h>，以最å°åŒ–ä½ çš„ +用户æ„外地ä¾èµ–这些实现细节的å¯èƒ½ã€‚ + +æ’入时，用户必须更新通往被æ’入节点的路径上的增强信æ¯ï¼Œç„¶åŽåƒå¾€å¸¸ä¸€æ ·è°ƒç”¨rb_link_node()， +然åŽæ˜¯rb_augment_inserted()而ä¸æ˜¯å¹³æ—¶çš„rb_insert_color()调用。如果 +rb_augment_inserted()å†å¹³è¡¡äº†çº¢é»‘æ ‘ï¼Œå®ƒå°†å›žè°ƒè‡³ä¸€ä¸ªç”¨æˆ·æ供的函数æ¥æ›´æ–°å—å½±å“çš„ +åæ ‘ä¸Šçš„å¢žå¼ºä¿¡æ¯ã€‚ + +åˆ é™¤ä¸€ä¸ªç»“ç‚¹æ—¶ï¼Œç”¨æˆ·å¿…é¡»è°ƒç”¨rb_erase_augmented()而ä¸æ˜¯rb_erase()。 +rb_erase_augmented()回调至一个用户æ供的函数æ¥æ›´æ–°å—å½±å“çš„åæ ‘ä¸Šçš„å¢žå¼ºä¿¡æ¯ã€‚ + +在两ç§æƒ…况下，回调都是通过rb_augment_callbacks结构体æ供的。必须定义3个回调： + +- ä¸€ä¸ªä¼ æ’回调，它更新一个给定结点和它的祖先们的增强数æ®ï¼Œç›´åˆ°ä¸€ä¸ªç»™å®šçš„åœæ¢ç‚¹ + （如果是NULLï¼Œå°†æ›´æ–°ä¸€è·¯æ›´æ–°åˆ°æ ‘æ ¹ï¼‰ã€‚ + +- 一个å¤åˆ¶å›žè°ƒï¼Œå®ƒå°†ä¸€é¢—给定åæ ‘çš„å¢žå¼ºæ•°æ®å¤åˆ¶åˆ°ä¸€ä¸ªæ–°æŒ‡å®šçš„åæ ‘æ ‘æ ¹ã€‚ + +- ä¸€ä¸ªæ ‘æ—‹è½¬å›žè°ƒï¼Œå®ƒå°†ä¸€é¢—ç»™å®šçš„åæ ‘çš„å¢žå¼ºå€¼å¤åˆ¶åˆ°æ–°æŒ‡å®šçš„åæ ‘æ ‘æ ¹ä¸Šï¼Œå¹¶é‡æ–°è®¡ç®— + å…ˆå‰çš„åæ ‘æ ‘æ ¹çš„å¢žå¼ºå€¼ã€‚ + +rb_erase_augmented()编译åŽçš„代ç å¯èƒ½ä¼šå†…è”ä¼ æ’ã€å¤åˆ¶å›žè°ƒï¼Œè¿™å°†å¯¼è‡´å‡½æ•°ä½“积更大， +å› æ¤æ¯ä¸ªå¢žå¼ºåž‹çº¢é»‘æ ‘çš„ç”¨æˆ·åº”è¯¥åªæœ‰ä¸€ä¸ªrb_erase_augmented()的调用点，以é™åˆ¶ç¼–è¯‘åŽ +的代ç 大å°ã€‚ + + +使用示例 +^^^^^^^^ + +åŒºé—´æ ‘æ˜¯å¢žå¼ºåž‹çº¢é»‘æ ‘çš„ä¸€ä¸ªä¾‹å。å‚考Cormen，Leiserson，Rivestå’ŒStein写的 +ã€Šç®—æ³•å¯¼è®ºã€‹ã€‚åŒºé—´æ ‘çš„æ›´å¤šç»†èŠ‚ï¼š + +ç»å…¸çš„çº¢é»‘æ ‘åªæœ‰ä¸€ä¸ªé”®ï¼Œå®ƒä¸èƒ½ç›´æŽ¥ç”¨æ¥å˜å‚¨åƒ[lo:hi]è¿™æ ·çš„åŒºé—´èŒƒå›´ï¼Œä¹Ÿä¸èƒ½å¿«é€ŸæŸ¥æ‰¾ +与新的lo:hié‡å 的部分，或者查找是å¦æœ‰ä¸Žæ–°çš„lo:hi完全匹é…的部分。 + +ç„¶è€Œï¼Œçº¢é»‘æ ‘å¯ä»¥è¢«å¢žå¼ºï¼Œä»¥ä¸€ç§ç»“构化的方å¼æ¥å˜å‚¨è¿™ç§åŒºé—´èŒƒå›´ï¼Œä»Žè€Œä½¿é«˜æ•ˆçš„查找和 +精确匹é…æˆä¸ºå¯èƒ½ã€‚ + +这个å˜å‚¨åœ¨æ¯ä¸ªèŠ‚点ä¸çš„“é¢å¤–ä¿¡æ¯â€æ˜¯å…¶æ‰€æœ‰åŽä»£ç»“点ä¸çš„最大hi（max_hiï¼‰å€¼ã€‚è¿™ä¸ªä¿¡æ¯ +å¯ä»¥ä¿æŒåœ¨æ¯ä¸ªç»“点上，åªéœ€æŸ¥çœ‹ä¸€ä¸‹è¯¥ç»“点和它的直系å结点们。这将被用于时间å¤æ‚度 +为O(log n)的最低匹é…查找（所有å¯èƒ½çš„匹é…ä¸æœ€ä½Žçš„起始地å€ï¼‰ï¼Œå°±åƒè¿™æ ·:: + + struct interval_tree_node * + interval_tree_first_match(struct rb_root *root, + unsigned long start, unsigned long last) + { + struct interval_tree_node *node; + + if (!root->rb_node) + return NULL; + node = rb_entry(root->rb_node, struct interval_tree_node, rb); + + while (true) { + if (node->rb.rb_left) { + struct interval_tree_node *left = + rb_entry(node->rb.rb_left, + struct interval_tree_node, rb); + if (left->__subtree_last >= start) { + /* + * Some nodes in left subtree satisfy Cond2. + * Iterate to find the leftmost such node N. + * If it also satisfies Cond1, that's the match + * we are looking for. Otherwise, there is no + * matching interval as nodes to the right of N + * can't satisfy Cond1 either. + */ + node = left; + continue; + } + } + if (node->start <= last) { /* Cond1 */ + if (node->last >= start) /* Cond2 */ + return node; /* node is leftmost match */ + if (node->rb.rb_right) { + node = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb); + if (node->__subtree_last >= start) + continue; + } + } + return NULL; /* No match */ + } + } + +æ’å…¥/åˆ é™¤æ˜¯é€šè¿‡ä»¥ä¸‹å¢žå¼ºåž‹å›žè°ƒæ¥å®šä¹‰çš„:: + + static inline unsigned long + compute_subtree_last(struct interval_tree_node *node) + { + unsigned long max = node->last, subtree_last; + if (node->rb.rb_left) { + subtree_last = rb_entry(node->rb.rb_left, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + if (node->rb.rb_right) { + subtree_last = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + return max; + } + + static void augment_propagate(struct rb_node *rb, struct rb_node *stop) + { + while (rb != stop) { + struct interval_tree_node *node = + rb_entry(rb, struct interval_tree_node, rb); + unsigned long subtree_last = compute_subtree_last(node); + if (node->__subtree_last == subtree_last) + break; + node->__subtree_last = subtree_last; + rb = rb_parent(&node->rb); + } + } + + static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new) + { + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; + } + + static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new) + { + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; + old->__subtree_last = compute_subtree_last(old); + } + + static const struct rb_augment_callbacks augment_callbacks = { + augment_propagate, augment_copy, augment_rotate + }; + + void interval_tree_insert(struct interval_tree_node *node, + struct rb_root *root) + { + struct rb_node **link = &root->rb_node, *rb_parent = NULL; + unsigned long start = node->start, last = node->last; + struct interval_tree_node *parent; + + while (*link) { + rb_parent = *link; + parent = rb_entry(rb_parent, struct interval_tree_node, rb); + if (parent->__subtree_last < last) + parent->__subtree_last = last; + if (start < parent->start) + link = &parent->rb.rb_left; + else + link = &parent->rb.rb_right; + } + + node->__subtree_last = last; + rb_link_node(&node->rb, rb_parent, link); + rb_insert_augmented(&node->rb, root, &augment_callbacks); + } + + void interval_tree_remove(struct interval_tree_node *node, + struct rb_root *root) + { + rb_erase_augmented(&node->rb, root, &augment_callbacks); + } diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst index 0c6fd447ced6..b3c095306ffe 100644 --- a/Documentation/translations/zh_CN/cpu-freq/core.rst +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -7,7 +7,9 @@ å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> -.. _cn_core.rst: +:æ ¡è¯‘: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> ==================================== CPUFreqæ ¸å¿ƒå’ŒCPUFreq通知器的通用说明 @@ -29,10 +31,10 @@ CPUFreqæ ¸å¿ƒå’ŒCPUFreq通知器的通用说明 ====================== cpufreqæ ¸å¿ƒä»£ç ä½äºŽdrivers/cpufreq/cpufreq.cä¸ã€‚这些cpufreq代ç 为CPUFreq架构的驱 -动程åºï¼ˆé‚£äº›æ“作硬件切æ¢é¢‘率的代ç ï¼‰ä»¥åŠ "通知器 "æä¾›äº†ä¸€ä¸ªæ ‡å‡†åŒ–çš„æŽ¥å£ã€‚ -这些是设备驱动程åºæˆ–需è¦äº†è§£ç–ç•¥å˜åŒ–çš„å…¶å®ƒå†…æ ¸éƒ¨åˆ†ï¼ˆå¦‚ ACPI çƒé‡ç®¡ç†ï¼‰æˆ–所有频率更改（除 -计时代ç 外），甚至需è¦å¼ºåˆ¶ç¡®å®šé€Ÿåº¦é™åˆ¶çš„通知器（如 ARM 架构上的 LCD 驱动程åºï¼‰ã€‚ -æ¤å¤–， å†…æ ¸ "常数" loops_per_jiffyä¼šæ ¹æ®é¢‘率å˜åŒ–而更新。 +动程åºï¼ˆé‚£äº›æ‰§è¡Œç¡¬ä»¶é¢‘率切æ¢çš„代ç ï¼‰ä»¥åŠ "通知器" æä¾›äº†ä¸€ä¸ªæ ‡å‡†åŒ–çš„æŽ¥å£ã€‚ +包括设备驱动程åºï¼›éœ€è¦äº†è§£ç–ç•¥å˜åŒ–（如 ACPI çƒé‡ç®¡ç†ï¼‰ï¼Œæˆ–所有频率å˜åŒ–（如计时代ç ）， +甚至需è¦å¼ºåˆ¶é™åˆ¶ä¸ºæŒ‡å®šé¢‘率（如 ARM 架构上的 LCD 驱动程åºï¼‰çš„å…¶å®ƒå†…æ ¸ç»„ä»¶ã€‚ +æ¤å¤–ï¼Œå†…æ ¸ "常数" loops_per_jiffy ä¼šæ ¹æ®é¢‘率å˜åŒ–而更新。 cpufreqç–略的引用计数由 cpufreq_cpu_get å’Œ cpufreq_cpu_put æ¥å®Œæˆï¼Œä»¥ç¡®ä¿ cpufreq 驱 动程åºè¢«æ£ç¡®åœ°æ³¨å†Œåˆ°æ ¸å¿ƒä¸ï¼Œå¹¶ä¸”驱动程åºåœ¨ cpufreq_put_cpu 被调用之å‰ä¸ä¼šè¢«å¸è½½ã€‚这也ä¿è¯ @@ -41,7 +43,7 @@ cpufreqç–略的引用计数由 cpufreq_cpu_get å’Œ cpufreq_cpu_put æ¥å®Œæˆï¼Œ 2. CPUFreq 通知器 ==================== -CPUFreq通知器符åˆæ ‡å‡†çš„å†…æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ +CPUFreq通知器éµå¾ªæ ‡å‡†çš„å†…æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ 关于通知器的细节请å‚阅 linux/include/linux/notifier.h。 这里有两个ä¸åŒçš„CPUfreq通知器 - ç–略通知器和转æ¢é€šçŸ¥å™¨ã€‚ @@ -69,20 +71,20 @@ CPUFreq通知器符åˆæ ‡å‡†çš„å†…æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ 第三个å‚数是一个包å«å¦‚下值的结构体cpufreq_freqs： -===== ==================== -cpu å—å½±å“cpuçš„ç¼–å· +====== =============================== +policy 指å‘struct cpufreq_policy的指针 old 旧频率 new 新频率 flags cpufreqé©±åŠ¨çš„æ ‡å¿— -===== ==================== +====== =============================== 3. å«æœ‰Operating Performance Point (OPP)çš„CPUFreqè¡¨çš„ç”Ÿæˆ ================================================================== 关于OPP的细节请å‚阅 Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - - 这个功能æ供了一个éšæ—¶å¯ç”¨çš„转æ¢ç¨‹åºï¼Œç”¨æ¥å°†OPP层关于å¯ç”¨é¢‘率的内部信æ¯ç¿»è¯‘æˆä¸€ç§å®¹æ˜“æ供给 - cpufreqçš„æ ¼å¼ã€‚ + 这个函数æ供了一个éšæ—¶å¯ç”¨çš„转æ¢ä¾‹ç¨‹ï¼Œç”¨æ¥å°†OPP层关于å¯ç”¨é¢‘率的内部信æ¯ç¿»è¯‘æˆä¸€ç§ + cpufreq易于处ç†çš„æ ¼å¼ã€‚ .. Warning:: diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst index 0fc5d1495789..2ca92042767b 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -8,7 +8,9 @@ å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> -.. _cn_cpu-drivers.rst: +:æ ¡è¯‘: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> ======================================= 如何实现一个新的CPUFreq处ç†å™¨é©±åŠ¨ç¨‹åºï¼Ÿ @@ -38,14 +40,14 @@ 1. 怎么åšï¼Ÿ =========== -如æ¤ï¼Œä½ 刚刚得到了一个全新的CPU/芯片组åŠå…¶æ•°æ®æ‰‹å†Œï¼Œå¹¶å¸Œæœ›ä¸ºè¿™ä¸ªCPU/èŠ¯ç‰‡ç»„æ·»åŠ cpufreq +å¦‚æžœï¼Œä½ åˆšåˆšå¾—åˆ°äº†ä¸€ä¸ªå…¨æ–°çš„CPU/芯片组åŠå…¶æ•°æ®æ‰‹å†Œï¼Œå¹¶å¸Œæœ›ä¸ºè¿™ä¸ªCPU/èŠ¯ç‰‡ç»„æ·»åŠ cpufreq 支æŒï¼Ÿå¾ˆå¥½ï¼Œè¿™é‡Œæœ‰ä¸€äº›è‡³å…³é‡è¦çš„æ示： 1.1 åˆå§‹åŒ– ---------- -首先，在__initcall_level_7 (module_init())或更é åŽçš„函数ä¸æ£€æŸ¥è¿™ä¸ªå†…æ ¸æ˜¯å¦ +首先，在 __initcall level 7 (module_init())或更é åŽçš„函数ä¸æ£€æŸ¥è¿™ä¸ªå†…æ ¸æ˜¯å¦ è¿è¡Œåœ¨æ£ç¡®çš„CPUå’Œæ£ç¡®çš„芯片组上。如果是，则使用cpufreq_register_driver()å‘ CPUfreqæ ¸å¿ƒå±‚æ³¨å†Œä¸€ä¸ªcpufreq_driver结构体。 @@ -60,11 +62,11 @@ CPUfreqæ ¸å¿ƒå±‚æ³¨å†Œä¸€ä¸ªcpufreq_driver结构体。 .setpolicy 或 .fast_switch 或 .target 或 .target_index - å·®å¼‚è§ ä¸‹æ–‡ã€‚ -并且å¯é€‰æ‹© +其它å¯é€‰æˆå‘˜ - .flags - cpufreqæ ¸çš„æ示。 + .flags - ç»™cpufreqæ ¸å¿ƒçš„æ示。 - .driver_data - cpufreq驱动程åºçš„特定数æ®ã€‚ + .driver_data - cpufreq驱动程åºçš„特有数æ®ã€‚ .get_intermediate å’Œ target_intermediate - 用于在改å˜CPU频率时切æ¢åˆ°ç¨³å®š 的频率。 @@ -73,16 +75,18 @@ CPUfreqæ ¸å¿ƒå±‚æ³¨å†Œä¸€ä¸ªcpufreq_driver结构体。 .bios_limit - 返回HW/BIOS对CPU的最大频率é™åˆ¶å€¼ã€‚ - .exit - 一个指å‘per-policy清ç†å‡½æ•°çš„指针，该函数在cpuçƒæ’拔过程的CPU_POST_DEAD + .exit - 一个指å‘per-policy清ç†å‡½æ•°çš„指针，该函数在CPUçƒæ’拔过程的CPU_POST_DEAD 阶段被调用。 .suspend - 一个指å‘per-policyæš‚åœå‡½æ•°çš„指针，该函数在关ä¸æ–且在该ç–略的调节器åœæ¢ åŽè¢«è°ƒç”¨ã€‚ - .resume - 一个指å‘per-policyæ¢å¤å‡½æ•°çš„指针，该函数在关ä¸æ–且在调节器å†ä¸€æ¬¡å¼€å§‹å‰è¢« + .resume - 一个指å‘per-policyæ¢å¤å‡½æ•°çš„指针，该函数在关ä¸æ–且在调节器å†ä¸€æ¬¡å¯åŠ¨å‰è¢« 调用。 - .attr - 一个指å‘NULL结尾的"struct freq_attr"列表的指针，该函数å…许导出值到 + .ready - 一个指å‘per-policy准备函数的指针，该函数在ç–略完全åˆå§‹åŒ–之åŽè¢«è°ƒç”¨ã€‚ + + .attr - 一个指å‘NULL结尾的"struct freq_attr"列表的指针，该列表å…许导出值到 sysfs。 .boost_enabled - 如果设置，则å¯ç”¨æå‡(boost)频率。 @@ -93,95 +97,93 @@ CPUfreqæ ¸å¿ƒå±‚æ³¨å†Œä¸€ä¸ªcpufreq_driver结构体。 1.2 Per-CPU åˆå§‹åŒ– ------------------ -æ¯å½“一个新的CPU被注册到设备模型ä¸ï¼Œæˆ–者在cpufreq驱动注册自己之åŽï¼Œå¦‚æžœæ¤CPUçš„cpufreqç– -ç•¥ä¸å˜åœ¨ï¼Œåˆ™ä¼šè°ƒç”¨per-policyçš„åˆå§‹åŒ–函数cpufreq_driver.init。请注æ„，.init()å’Œ.exit()ç¨‹åº -åªå¯¹ç–略调用一次，而ä¸æ˜¯å¯¹ç–略管ç†çš„æ¯ä¸ªCPU调用一次。它需è¦ä¸€ä¸ª ``struct cpufreq_policy +æ¯å½“一个新的CPU被注册到设备模型ä¸ï¼Œæˆ–者当cpufreq驱动注册自身之åŽï¼Œå¦‚æžœæ¤CPUçš„cpufreqç– +ç•¥ä¸å˜åœ¨ï¼Œåˆ™ä¼šè°ƒç”¨per-policyçš„åˆå§‹åŒ–函数cpufreq_driver.init。请注æ„，.init()å’Œ.exit()例程 +åªä¸ºæŸä¸ªç–略调用一次，而ä¸æ˜¯å¯¹è¯¥ç–略管ç†çš„æ¯ä¸ªCPU调用一次。它需è¦ä¸€ä¸ª ``struct cpufreq_policy *policy`` 作为å‚数。现在该怎么åšå‘¢ï¼Ÿ 如果有必è¦ï¼Œè¯·åœ¨ä½ çš„CPU上激活CPUfreq功能支æŒã€‚ -然åŽï¼Œé©±åŠ¨ç¨‹åºå¿…须填写以下数值: +然åŽï¼Œé©±åŠ¨ç¨‹åºå¿…须填写以下值: +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.min_freq å’Œ | | -|policy->cpuinfo.max_freq | 该CPU支æŒçš„最低和最高频率（kHz） | -| | | -| | | +|policy->cpuinfo.min_freqå’Œ | 该CPU支æŒçš„最低和最高频率（kHz） | +|policy->cpuinfo.max_freq | | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.transition_latency | | -| | CPU在两个频率之间切æ¢æ‰€éœ€çš„时间，以 | -| | 纳秒为å•ä½ï¼ˆå¦‚适用，å¦åˆ™æŒ‡å®š | -| | CPUFREQ_ETERNAL） | +|policy->cpuinfo.transition_latency | CPU在两个频率之间切æ¢æ‰€éœ€çš„时间，以 | +| | 纳秒为å•ä½ï¼ˆå¦‚ä¸é€‚用，设定为 | +| | CPUFREQ_ETERNAL） | +| | | +-----------------------------------+--------------------------------------+ -|policy->cur | 该CPU当å‰çš„工作频率(如适用) | -| | | +|policy->cur | 该CPU当å‰çš„工作频率(如适用) | +| | | +-----------------------------------+--------------------------------------+ -|policy->min, | | -|policy->max, | | -|policy->policy and, if necessary, | | -|policy->governor | 必须包å«è¯¥cpuçš„ “默认ç–ç•¥â€ã€‚ç¨åŽ | -| | 会用这些值调用 | -| | cpufreq_driver.verify and either | -| | cpufreq_driver.setpolicy or | -| | cpufreq_driver.target/target_index | -| | | +|policy->min, | 必须包å«è¯¥CPUçš„"默认ç–ç•¥"。ç¨åŽ | +|policy->max, | 会用这些值调用 | +|policy->policy and, if necessary, | cpufreq_driver.verify和下é¢å‡½æ•° | +|policy->governor | 之一：cpufreq_driver.setpolicy或 | +| | cpufreq_driver.target/target_index | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpus | 用与这个CPU一起åšDVFSçš„(在线+离线) | -| | CPU(å³ä¸Žå®ƒå…±äº«æ—¶é’Ÿ/电压轨)的掩ç æ›´æ–° | -| | 这个 | -| | | +|policy->cpus | 该policy通过DVFS框架影å“的全部CPU | +| | (å³ä¸Žæœ¬CPU共享"时钟/电压"对)æž„æˆ | +| | 掩ç (åŒæ—¶åŒ…å«åœ¨çº¿å’Œç¦»çº¿CPU)，用掩ç | +| | 更新本å—段 | +| | | +-----------------------------------+--------------------------------------+ -对于设置其ä¸çš„一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手å¯èƒ½ä¼šæœ‰å¸® +对于设置其ä¸çš„一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表辅助函数å¯èƒ½ä¼šæœ‰å¸® 助。关于它们的更多信æ¯ï¼Œè¯·å‚è§ç¬¬2节。 1.3 éªŒè¯ -------- -当用户决定设置一个新的ç–ç•¥(ç”± “policy,governor,min,max组æˆâ€)时，必须对这个ç–略进行验è¯ï¼Œ +当用户决定设置一个新的ç–ç•¥(ç”±"policy,governor,min,max组æˆ")时，必须对这个ç–略进行验è¯ï¼Œ ä»¥ä¾¿çº æ£ä¸å…¼å®¹çš„值。为了验è¯è¿™äº›å€¼ï¼Œcpufreq_verify_within_limits(``struct cpufreq_policy *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数å¯èƒ½ä¼šæœ‰å¸®åŠ©ã€‚ -关于频率表助手的详细内容请å‚è§ç¬¬2节。 +关于频率表辅助函数的详细内容请å‚è§ç¬¬2节。 您需è¦ç¡®ä¿è‡³å°‘有一个有效频率（或工作范围）在 policy->min å’Œ policy->max 范围内。如果有必 -è¦ï¼Œå…ˆå¢žåŠ policy->max，åªæœ‰åœ¨æ²¡æœ‰åŠžæ³•çš„情况下，æ‰å‡å°‘policy->min。 +è¦ï¼Œå…ˆå¢žå¤§policy->max，åªæœ‰åœ¨æ²¡æœ‰è§£å†³æ–¹æ¡ˆçš„情况下，æ‰å‡å°policy->min。 1.4 target 或 target_index 或 setpolicy 或 fast_switch? ------------------------------------------------------- -大多数cpufreq驱动甚至大多数cpu频率å‡é™ç®—法åªå…许将CPUé¢‘çŽ‡è®¾ç½®ä¸ºé¢„å®šä¹‰çš„å›ºå®šå€¼ã€‚å¯¹äºŽè¿™äº›ï¼Œä½ +大多数cpufreq驱动甚至大多数CPU频率å‡é™ç®—法åªå…许将CPUé¢‘çŽ‡è®¾ç½®ä¸ºé¢„å®šä¹‰çš„å›ºå®šå€¼ã€‚å¯¹äºŽè¿™äº›ï¼Œä½ å¯ä»¥ä½¿ç”¨->target()，->target_index()或->fast_switch()回调。 -有些cpufreq功能的处ç†å™¨å¯ä»¥è‡ªå·±åœ¨æŸäº›é™åˆ¶ä¹‹é—´åˆ‡æ¢é¢‘率。这些应使用->setpolicy()回调。 +有些具有硬件调频能力的处ç†å™¨å¯ä»¥è‡ªè¡Œä¾æ®æŸäº›é™åˆ¶æ¥åˆ‡æ¢CPU频率。它们应使用->setpolicy()回调。 1.5. target/target_index ------------------------ -target_index调用有两个å‚数：``struct cpufreq_policy * policy``å’Œ``unsigned int`` -索引(于列出的频率表)。 +target_index调用有两个å‚数： ``struct cpufreq_policy * policy`` å’Œ ``unsigned int`` +索引(用于索引频率表项)。 当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 -它应该总是在错误的情况下æ¢å¤åˆ°ä¹‹å‰çš„频率(å³policy->restore_freq)，å³ä½¿æˆ‘们之å‰åˆ‡æ¢åˆ°ä¸é—´é¢‘率。 +在å‘生错误的情况下总是应该æ¢å¤åˆ°ä¹‹å‰çš„频率(å³policy->restore_freq)，å³ä½¿æˆ‘们已ç»åˆ‡æ¢åˆ°äº† +ä¸é—´é¢‘率。 已弃用 ---------- -ç›®æ ‡è°ƒç”¨æœ‰ä¸‰ä¸ªå‚数。``struct cpufreq_policy * policy``, unsigned int target_frequency, +target调用有三个å‚数。``struct cpufreq_policy * policy``, unsigned int target_frequency, unsigned int relation. CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须使用以下规则æ¥ç¡®å®šã€‚ -- 紧跟 "ç›®æ ‡é¢‘çŽ‡"。 +- å°½é‡è´´è¿‘"ç›®æ ‡é¢‘çŽ‡"。 - policy->min <= new_freq <= policy->max (这必须是有效的!!!) - 如果 relation==CPUFREQ_REL_L，å°è¯•é€‰æ‹©ä¸€ä¸ªé«˜äºŽæˆ–ç‰äºŽ target_freq çš„ new_freq。("L代表 最低，但ä¸èƒ½ä½ŽäºŽ") - 如果 relation==CPUFREQ_REL_H，å°è¯•é€‰æ‹©ä¸€ä¸ªä½ŽäºŽæˆ–ç‰äºŽ target_freq çš„ new_freq。("H代表 最高，但ä¸èƒ½é«˜äºŽ") -这里，频率表助手å¯èƒ½ä¼šå¸®åŠ©ä½ --详è§ç¬¬2节。 +这里，频率表辅助函数å¯èƒ½ä¼šå¸®åŠ©ä½ -- 详è§ç¬¬2节。 1.6. fast_switch ---------------- @@ -195,42 +197,43 @@ CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须ä 1.7 setpolicy ------------- -setpolicy调用åªéœ€è¦ä¸€ä¸ª``struct cpufreq_policy * policy``作为å‚数。需è¦å°†å¤„ç†å™¨å†…或芯片组内动æ€é¢‘ +setpolicy调用åªéœ€è¦ä¸€ä¸ª ``struct cpufreq_policy * policy`` 作为å‚数。需è¦å°†å¤„ç†å™¨å†…或芯片组内动æ€é¢‘ 率切æ¢çš„下é™è®¾ç½®ä¸ºpolicy->min，上é™è®¾ç½®ä¸ºpolicy->max，如果支æŒçš„è¯ï¼Œå½“policy->policy为 -CPUFREQ_POLICY_PERFORMANCE时选择é¢å‘性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择é¢å‘çœç”µçš„设置。 +CPUFREQ_POLICY_PERFORMANCE时选择é¢å‘性能的设置，为CPUFREQ_POLICY_POWERSAVE时选择é¢å‘çœç”µçš„设置。 也å¯ä»¥æŸ¥çœ‹drivers/cpufreq/longrun.cä¸çš„å‚考实现。 1.8 get_intermediate å’Œ target_intermediate -------------------------------------------- -仅适用于 target_index() å’Œ CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 +仅适用于未设置 target_index() å’Œ CPUFREQ_ASYNC_NOTIFICATION 的驱动。 get_intermediate应该返回一个平å°æƒ³è¦åˆ‡æ¢åˆ°çš„稳定的ä¸é—´é¢‘率，target_intermediate()应该将CPU设置为 -该频率，然åŽå†è·³è½¬åˆ°'index'å¯¹åº”çš„é¢‘çŽ‡ã€‚æ ¸å¿ƒä¼šè´Ÿè´£å‘é€é€šçŸ¥ï¼Œé©±åŠ¨ä¸å¿…在target_intermediate()或 -target_index()ä¸å¤„ç†ã€‚ +该频率，然åŽå†è·³è½¬åˆ°'index'对应的频率。cpufreqæ ¸å¿ƒä¼šè´Ÿè´£å‘é€é€šçŸ¥ï¼Œé©±åŠ¨ä¸å¿…在 +target_intermediate()或target_index()ä¸å¤„ç†å®ƒä»¬ã€‚ -在驱动程åºä¸æƒ³å› 为æŸä¸ªç›®æ ‡é¢‘率切æ¢åˆ°ä¸é—´é¢‘率的情况下，它们å¯ä»¥ä»Žget_intermediate()ä¸è¿”回'0'。在这ç§æƒ…况 -ä¸‹ï¼Œæ ¸å¿ƒå°†ç›´æŽ¥è°ƒç”¨->target_index()。 +在驱动程åºä¸æƒ³ä¸ºæŸä¸ªç›®æ ‡é¢‘率切æ¢åˆ°ä¸é—´é¢‘率的情况下，它们å¯ä»¥è®©get_intermediate()返回'0'。 +在这ç§æƒ…况下，cpufreqæ ¸å¿ƒå°†ç›´æŽ¥è°ƒç”¨->target_index()。 -注æ„：->target_index()应该在失败的情况下æ¢å¤åˆ°policy->restore_freqï¼Œå› ä¸ºcore会为æ¤å‘é€é€šçŸ¥ã€‚ +注æ„：->target_index()应该在å‘生失败的情况下将频率æ¢å¤åˆ°policy->restore_freq， +å› ä¸ºcpufreqæ ¸å¿ƒä¼šä¸ºæ¤å‘é€é€šçŸ¥ã€‚ -2. 频率表助手 -============= +2. 频率表辅助函数 +================= -由于大多数cpufreq处ç†å™¨åªå…è®¸è¢«è®¾ç½®ä¸ºå‡ ä¸ªç‰¹å®šçš„é¢‘çŽ‡ï¼Œå› æ¤ï¼Œä¸€ä¸ªå¸¦æœ‰ä¸€äº›å‡½æ•°çš„ “频率表â€å¯èƒ½ä¼šè¾…助处ç†å™¨é©±åŠ¨ -程åºçš„ä¸€äº›å·¥ä½œã€‚è¿™æ ·çš„ "频率表" 由一个cpufreq_frequency_tableæ¡ç›®æž„æˆçš„数组组æˆï¼Œ"driver_data" ä¸åŒ… -å«äº†é©±åŠ¨ç¨‹åºçš„具体数值，"frequency" ä¸åŒ…å«äº†ç›¸åº”çš„é¢‘çŽ‡ï¼Œå¹¶è®¾ç½®äº†æ ‡å¿—ã€‚åœ¨è¡¨çš„æœ€åŽï¼Œéœ€è¦æ·»åŠ 一个 -cpufreq_frequency_tableæ¡ç›®ï¼Œé¢‘率设置为CPUFREQ_TABLE_END。而如果想跳过表ä¸çš„一个æ¡ç›®ï¼Œåˆ™å°†é¢‘率设置为 -CPUFREQ_ENTRY_INVALID。这些æ¡ç›®ä¸éœ€è¦æŒ‰ç…§ä»»ä½•ç‰¹å®šçš„顺åºæŽ’åºï¼Œä½†å¦‚果它们是cpufreq æ ¸å¿ƒä¼šå¯¹å®ƒä»¬è¿›è¡Œå¿«é€Ÿçš„DVFS， +由于大多数支æŒcpufreq的处ç†å™¨åªå…è®¸è¢«è®¾ç½®ä¸ºå‡ ä¸ªç‰¹å®šçš„é¢‘çŽ‡ï¼Œå› æ¤ï¼Œ"频率表"和一些相关函数å¯èƒ½ä¼šè¾…助处ç†å™¨é©±åŠ¨ +程åºçš„ä¸€äº›å·¥ä½œã€‚è¿™æ ·çš„"频率表"是一个由struct cpufreq_frequency_tableçš„æ¡ç›®æž„æˆçš„数组，"driver_data"æˆå‘˜åŒ… +å«é©±åŠ¨ç¨‹åºçš„专用值，"frequency"æˆå‘˜åŒ…å«äº†ç›¸åº”的频率，æ¤å¤–è¿˜æœ‰æ ‡å¿—æˆå‘˜ã€‚在表的最åŽï¼Œéœ€è¦æ·»åŠ 一个 +cpufreq_frequency_tableæ¡ç›®ï¼Œé¢‘率设置为CPUFREQ_TABLE_END。如果想跳过表ä¸çš„一个æ¡ç›®ï¼Œåˆ™å°†é¢‘率设置为 +CPUFREQ_ENTRY_INVALID。这些æ¡ç›®ä¸éœ€è¦æŒ‰ç…§ä»»ä½•ç‰¹å®šçš„顺åºæŽ’åºï¼Œå¦‚果排åºäº†ï¼Œcpufreqæ ¸å¿ƒæ‰§è¡ŒDVFS会更快一点， å› ä¸ºæœç´¢æœ€ä½³åŒ¹é…会更快。 -如果ç–略在其policy->freq_tableå—段ä¸åŒ…å«ä¸€ä¸ªæœ‰æ•ˆçš„指针，cpufreqè¡¨å°±ä¼šè¢«æ ¸å¿ƒè‡ªåŠ¨éªŒè¯ã€‚ +如果在policy->freq_tableå—段ä¸åŒ…å«ä¸€ä¸ªæœ‰æ•ˆçš„频率表指针，频率表就会被cpufreqæ ¸å¿ƒè‡ªåŠ¨éªŒè¯ã€‚ cpufreq_frequency_table_verify()ä¿è¯è‡³å°‘有一个有效的频率在policy->minå’Œpolicy->max范围内，并且所有其他 -æ ‡å‡†éƒ½è¢«æ»¡è¶³ã€‚è¿™å¯¹->verify调用很有帮助。 +准则都被满足。这对->verify调用很有帮助。 -cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。åªè¦æŠŠæ•°å€¼ä¼ 递给这个函数，这个函数就会返 +cpufreq_frequency_table_target()是对应于->target阶段的频率表辅助函数。åªè¦æŠŠå€¼ä¼ 递给这个函数，这个函数就会返 回包å«CPUè¦è®¾ç½®çš„频率的频率表æ¡ç›®ã€‚ 以下å®å¯ä»¥ä½œä¸ºcpufreq_frequency_tableçš„è¿ä»£å™¨ã€‚ @@ -238,8 +241,8 @@ cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。å cpufreq_for_each_entry(pos, table) - é历频率表的所有æ¡ç›®ã€‚ cpufreq_for_each_valid_entry(pos, table) - 该函数é历所有æ¡ç›®ï¼Œä¸åŒ…括CPUFREQ_ENTRY_INVALID频率。 -使用å‚æ•° "pos"-一个``cpufreq_frequency_table * `` 作为循环å˜é‡ï¼Œä½¿ç”¨å‚æ•° "table"-ä½œä¸ºä½ æƒ³è¿ä»£ -çš„``cpufreq_frequency_table * `` 。 +使用å‚æ•°"pos" -- 一个 ``cpufreq_frequency_table *`` 作为循环指针，使用å‚æ•°"table" -- ä½œä¸ºä½ æƒ³è¿ä»£ +çš„ ``cpufreq_frequency_table *`` 。 例如:: @@ -250,5 +253,5 @@ cpufreq_for_each_valid_entry(pos, table) - 该函数é历所有æ¡ç›®ï¼Œä¸åŒ…æ pos->frequency = ... } -å¦‚æžœä½ éœ€è¦åœ¨driver_freq_tableä¸å¤„ç†posçš„ä½ç½®ï¼Œä¸è¦å‡åŽ»æŒ‡é’ˆï¼Œå› 为它的代价相当高。相åï¼Œä½¿ç”¨å® +å¦‚æžœä½ éœ€è¦åœ¨driver_freq_tableä¸å¤„ç†posçš„ä½ç½®ï¼Œä¸è¦åšæŒ‡é’ˆå‡æ³•ï¼Œå› ä¸ºå®ƒçš„ä»£ä»·ç›¸å½“é«˜ã€‚ä½œä¸ºæ›¿ä»£ï¼Œä½¿ç”¨å® cpufreq_for_each_entry_idx() å’Œ cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst index f14423099d4b..e8fdba923cd5 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -8,13 +8,15 @@ å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> -.. _cn_cpufreq-stats.rst: +:æ ¡è¯‘: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> ========================================== sysfs CPUFreq Stats的一般说明 ========================================== -ç”¨æˆ·ä¿¡æ¯ +ä¸ºä½¿ç”¨è€…å‡†å¤‡çš„ä¿¡æ¯ ä½œè€…: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> @@ -29,17 +31,16 @@ sysfs CPUFreq Stats的一般说明 1. 简介 =============== -cpufreq-stats是一个为æ¯ä¸ªCPUæä¾›CPU频率统计的驱动。 -这些统计数æ®åœ¨/sysfsä¸ä»¥ä¸€å †åªè¯»æŽ¥å£çš„å½¢å¼æ供。这个接å£ï¼ˆåœ¨é…置好åŽï¼‰å°†å‡ºçŽ°åœ¨ -/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）ä¸cpufreqä¸‹çš„ä¸€ä¸ªå• -独的目录ä¸ï¼Œæ供给æ¯ä¸ªCPU。 -å„ç§ç»Ÿè®¡æ•°æ®å°†åœ¨æ¤ç›®å½•ä¸‹å½¢æˆåªè¯»æ–‡ä»¶ã€‚ +cpufreq-stats是一ç§ä¸ºæ¯ä¸ªCPUæä¾›CPU频率统计的驱动。 +这些统计数æ®ä»¥/sysfsä¸ä¸€ç³»åˆ—åªè¯»æŽ¥å£çš„å½¢å¼å‘ˆçŽ°ã€‚cpufreq-stats接å£ï¼ˆè‹¥å·²é…置）将为æ¯ä¸ªCPUç”Ÿæˆ +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）ä¸cpufreq目录下的stats目录。 +å„项统计数æ®å°†åœ¨stats目录下形æˆå¯¹åº”çš„åªè¯»æ–‡ä»¶ã€‚ -æ¤é©±åŠ¨æ˜¯ç‹¬ç«‹äºŽä»»ä½•å¯èƒ½è¿è¡Œåœ¨ä½ 所用CPU上的特定cpufreq_driverè€Œè®¾è®¡çš„ã€‚å› æ¤ï¼Œå®ƒå°†ä¸Žæ‰€æœ‰ -cpufreq_driver一起工作。 +æ¤é©±åŠ¨æ˜¯ä»¥ç‹¬ç«‹äºŽä»»ä½•å¯èƒ½è¿è¡Œåœ¨ä½ 所用CPU上的特定cpufreq_driverçš„æ–¹å¼è®¾è®¡çš„ã€‚å› æ¤ï¼Œå®ƒå°†èƒ½å’Œä»»ä½• +cpufreq_driverååŒå·¥ä½œã€‚ -2. æ供的统计数æ®(举例说明) +2. å·²æ供的统计数æ®(有例å) ===================================== cpufreq statsæ供了以下统计数æ®ï¼ˆåœ¨ä¸‹é¢è¯¦ç»†è§£é‡Šï¼‰ã€‚ @@ -48,8 +49,8 @@ cpufreq statsæ供了以下统计数æ®ï¼ˆåœ¨ä¸‹é¢è¯¦ç»†è§£é‡Šï¼‰ã€‚ - total_trans - trans_table -所有的统计数æ®å°†ä»Žç»Ÿè®¡é©±åŠ¨è¢«è½½å…¥çš„时间（或统计被é‡ç½®çš„时间）开始，到æŸä¸€ç»Ÿè®¡æ•°æ®è¢«è¯»å–的时间为æ¢ã€‚ -显然，统计驱动ä¸ä¼šæœ‰ä»»ä½•å…³äºŽç»Ÿè®¡é©±åŠ¨è½½å…¥ä¹‹å‰çš„频率转æ¢ä¿¡æ¯ã€‚ +所有统计数æ®æ¥è‡ªä»¥ä¸‹æ—¶é—´èŒƒå›´ï¼šä»Žç»Ÿè®¡é©±åŠ¨è¢«åŠ 载的时间（或统计数æ®è¢«é‡ç½®çš„时间）开始，到æŸä¸€ç»Ÿè®¡æ•°æ®è¢«è¯»å–的时间为æ¢ã€‚ +显然，统计驱动ä¸ä¼šä¿å˜å®ƒè¢«åŠ 载之å‰çš„任何频率转æ¢ä¿¡æ¯ã€‚ :: @@ -64,14 +65,14 @@ cpufreq statsæ供了以下统计数æ®ï¼ˆåœ¨ä¸‹é¢è¯¦ç»†è§£é‡Šï¼‰ã€‚ - **reset** -åªå†™å±žæ€§ï¼Œå¯ç”¨äºŽé‡ç½®ç»Ÿè®¡è®¡æ•°å™¨ã€‚这对于评估ä¸åŒè°ƒèŠ‚器下的系统行为éžå¸¸æœ‰ç”¨ï¼Œä¸”æ— éœ€é‡å¯ã€‚ +åªå†™å±žæ€§ï¼Œå¯ç”¨äºŽé‡ç½®ç»Ÿè®¡è®¡æ•°å™¨ã€‚这对于评估ä¸åŒè°ƒèŠ‚器的系统行为éžå¸¸æœ‰ç”¨ï¼Œä¸”æ— éœ€é‡å¯ã€‚ - **time_in_state** -æ¤é¡¹ç»™å‡ºäº†è¿™ä¸ªCPU所支æŒçš„æ¯ä¸ªé¢‘率所花费的时间。cat输出的æ¯ä¸€è¡Œéƒ½ä¼šæœ‰"<frequency> -<time>"对，表示这个CPU在<frequency>上花费了<time>个usertimeå•ä½çš„时间。这里的 -usertimeå•ä½æ˜¯10mS（类似于/procä¸è¾“出的其他时间）。 +æ¤æ–‡ä»¶ç»™å‡ºäº†åœ¨æœ¬CPU支æŒçš„æ¯ä¸ªé¢‘率上分别花费的时间。cat输出的æ¯ä¸€è¡Œéƒ½æ˜¯ä¸€ä¸ª"<frequency> +<time>"对，表示这个CPU在<frequency>上花费了<time>个usertimeå•ä½çš„时间。输出的æ¯ä¸€è¡Œå¯¹åº” +一个CPU支æŒçš„频率。这里usertimeå•ä½æ˜¯10mS（类似于/proc导出的其它时间）。 :: @@ -85,7 +86,7 @@ usertimeå•ä½æ˜¯10mS（类似于/procä¸è¾“出的其他时间）。 - **total_trans** -给出了这个CPU上频率转æ¢çš„总次数。cat的输出将有一个å•ä¸€çš„计数，这就是频率转æ¢çš„总数。 +æ¤æ–‡ä»¶ç»™å‡ºäº†è¿™ä¸ªCPU频率转æ¢çš„总次数。cat的输出是一个计数值，它就是频率转æ¢çš„总次数。 :: @@ -94,10 +95,10 @@ usertimeå•ä½æ˜¯10mS（类似于/procä¸è¾“出的其他时间）。 - **trans_table** -这将æ供所有CPU频率转æ¢çš„细粒度信æ¯ã€‚这里的cat输出是一个二维矩阵，其ä¸ä¸€ä¸ªæ¡ç›®<i, j>（第 +本文件æ供所有CPU频率转æ¢çš„细粒度信æ¯ã€‚这里的cat输出是一个二维矩阵，其ä¸ä¸€ä¸ªæ¡ç›®<i, j>（第 i行，第j列）代表从Freq_i到Freq_j的转æ¢æ¬¡æ•°ã€‚Freq_i行和Freq_j列éµå¾ªé©±åŠ¨æœ€åˆæ供给cpufreq -æ ¸çš„é¢‘çŽ‡è¡¨çš„æŽ’åºé¡ºåºï¼Œå› æ¤å¯ä»¥æŽ’åºï¼ˆå‡åºæˆ–é™åºï¼‰æˆ–ä¸æŽ’åºã€‚ 这里的输出也包å«äº†æ¯è¡Œæ¯åˆ—的实际 -频率值，以便更好地阅读。 +æ ¸å¿ƒçš„é¢‘çŽ‡è¡¨çš„æŽ’åˆ—é¡ºåºï¼Œå› æ¤å¯ä»¥å·²æŽ’åºï¼ˆå‡åºæˆ–é™åºï¼‰æˆ–未排åºã€‚这里的输出也包å«äº†å®žé™… +频率值，分别按行和按列显示，以便更好地阅读。 如果转æ¢è¡¨å¤§äºŽPAGE_SIZE，读å–时将返回一个-EFBIG错误。 @@ -115,7 +116,7 @@ i行，第j列）代表从Freq_i到Freq_j的转æ¢æ¬¡æ•°ã€‚Freq_i行和Freq_j列 3. é…ç½®cpufreq-stats ============================ -è¦åœ¨ä½ çš„å†…æ ¸ä¸é…ç½®cpufreq-stats:: +按以下方å¼åœ¨ä½ çš„å†…æ ¸ä¸é…ç½®cpufreq-stats:: Config Main Menu Power management options (ACPI, APM) ---> @@ -124,7 +125,7 @@ i行，第j列）代表从Freq_i到Freq_j的转æ¢æ¬¡æ•°ã€‚Freq_i行和Freq_j列 [*] CPU frequency translation statistics -"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被å¯ç”¨ä»¥é…ç½®cpufreq-stats。 +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被å¯ç”¨ï¼Œä»¥æ”¯æŒé…ç½®cpufreq-stats。 "CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)æ供了包括 time_in_stateã€total_transå’Œtrans_table的统计数æ®ã€‚ diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index 0f770b8664e9..77a8c44cdf49 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -22,13 +22,13 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst :maxdepth: 2 testing-overview + sparse gcov kasan Todolist: - coccinelle - - sparse - kcov - ubsan - kmemleak diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/dev-tools/sparse.rst index 0f444b83d639..556282437aad 100644 --- a/Documentation/translations/zh_CN/sparse.txt +++ b/Documentation/translations/zh_CN/dev-tools/sparse.rst @@ -1,34 +1,34 @@ -Chinese translated version of Documentation/dev-tools/sparse.rst +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <pavel@ucw.cz> +Copyright 2006 Bob Copeland <me@bobcopeland.com> -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Chinese maintainer: Li Yang <leoyang.li@nxp.com> ---------------------------------------------------------------------- -Documentation/dev-tools/sparse.rst çš„ä¸æ–‡ç¿»è¯‘ +:Original: Documentation/dev-tools/sparse.rst -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…。 +:翻译: -ä¸æ–‡ç‰ˆç»´æŠ¤è€…： æŽé˜³ Li Yang <leoyang.li@nxp.com> -ä¸æ–‡ç‰ˆç¿»è¯‘者： æŽé˜³ Li Yang <leoyang.li@nxp.com> + Li Yang <leoyang.li@nxp.com> +:æ ¡è¯‘: -以下为æ£æ–‡ ---------------------------------------------------------------------- + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> -Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek <pavel@ucw.cz> -Copyright 2006 Bob Copeland <me@bobcopeland.com> +.. _cn_sparse: + +Sparse +====== + +Sparse是一个C程åºçš„è¯ä¹‰æ£€æŸ¥å™¨ï¼›å®ƒå¯ä»¥ç”¨æ¥å‘çŽ°å†…æ ¸ä»£ç 的一些潜在问题。 å…³ +于sparse的概述，请å‚è§https://lwn.net/Articles/689907/ï¼›æœ¬æ–‡æ¡£åŒ…å« +ä¸€äº›é’ˆå¯¹å†…æ ¸çš„sparseä¿¡æ¯ã€‚ +关于sparse的更多信æ¯ï¼Œä¸»è¦æ˜¯å…³äºŽå®ƒçš„内部结构，å¯ä»¥åœ¨å®ƒçš„官方网页上找到： +https://sparse.docs.kernel.org。 使用 sparse 工具åšç±»åž‹æ£€æŸ¥ ~~~~~~~~~~~~~~~~~~~~~~~~~~ -"__bitwise" 是一ç§ç±»åž‹å±žæ€§ï¼Œæ‰€ä»¥ä½ åº”è¯¥è¿™æ ·ä½¿ç”¨å®ƒï¼š +"__bitwise" 是一ç§ç±»åž‹å±žæ€§ï¼Œæ‰€ä»¥ä½ åº”è¯¥è¿™æ ·ä½¿ç”¨å®ƒ:: typedef int __bitwise pm_request_t; @@ -48,7 +48,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> å¦ç™½æ¥è¯´ï¼Œä½ 并ä¸éœ€è¦ä½¿ç”¨æžšä¸¾ç±»åž‹ã€‚上é¢é‚£äº›å®žé™…都å¯ä»¥æµ“缩æˆä¸€ä¸ªç‰¹æ®Šçš„"int __bitwise"类型。 -所以更简å•çš„办法åªè¦è¿™æ ·åšï¼š +所以更简å•çš„办法åªè¦è¿™æ ·åš:: typedef int __bitwise pm_request_t; @@ -60,25 +60,42 @@ __bitwise"类型。 一个å°æ醒：常数整数"0"æ˜¯ç‰¹æ®Šçš„ã€‚ä½ å¯ä»¥ç›´æŽ¥æŠŠå¸¸æ•°é›¶å½“作ä½æ–¹å¼æ•´æ•°ä½¿ç”¨è€Œ ä¸ç”¨æ‹…心 sparse ä¼šæŠ±æ€¨ã€‚è¿™æ˜¯å› ä¸º"bitwise"（æ°å¦‚å…¶å）是用æ¥ç¡®ä¿ä¸åŒä½æ–¹ å¼ç±»åž‹ä¸ä¼šè¢«å¼„混（å°å°¾æ¨¡å¼ï¼Œå¤§å°¾æ¨¡å¼ï¼Œcpu尾模å¼ï¼Œæˆ–者其他），对他们æ¥è¯´ -常数"0"确实是特殊的。 +常数"0"确实 **是** 特殊的。 + +使用sparse进行é”检查 +-------------------- + +下é¢çš„å®å¯¹äºŽ gcc æ¥è¯´æ˜¯æœªå®šä¹‰çš„，在 sparse è¿è¡Œæ—¶å®šä¹‰ï¼Œä»¥ä½¿ç”¨sparse的“上下文†+跟踪功能，应用于é”定。 这些注释告诉 sparse 什么时候有é”，以åŠæ³¨é‡Šçš„函数的进入和 +退出。 + +__must_hold - 指定的é”在函数进入和退出时被æŒæœ‰ã€‚ + +__acquires - 指定的é”在函数退出时被æŒæœ‰ï¼Œä½†åœ¨è¿›å…¥æ—¶ä¸è¢«æŒæœ‰ã€‚ + +__releases - 指定的é”在函数进入时被æŒæœ‰ï¼Œä½†åœ¨é€€å‡ºæ—¶ä¸è¢«æŒæœ‰ã€‚ + +如果函数在ä¸æŒæœ‰é”的情况下进入和退出，在函数内部以平衡的方å¼èŽ·å–和释放é”ï¼Œåˆ™ä¸ +需è¦æ³¨é‡Šã€‚ +上é¢çš„三个注释是针对sparseå¦åˆ™ä¼šæŠ¥å‘Šä¸Šä¸‹æ–‡ä¸å¹³è¡¡çš„情况。 èŽ·å– sparse 工具 ~~~~~~~~~~~~~~~~ ä½ å¯ä»¥ä»Ž Sparse 的主页获å–最新的å‘布版本： - http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + https://www.kernel.org/pub/software/devel/sparse/dist/ æˆ–è€…ï¼Œä½ ä¹Ÿå¯ä»¥ä½¿ç”¨ git 克隆最新的 sparse å¼€å‘版本： - git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + git://git.kernel.org/pub/scm/devel/sparse/sparse.git ä¸€æ—¦ä½ ä¸‹è½½äº†æºç ，åªè¦ä»¥æ™®é€šç”¨æˆ·èº«ä»½è¿è¡Œï¼š make make install -å®ƒå°†ä¼šè¢«è‡ªåŠ¨å®‰è£…åˆ°ä½ çš„ ~/bin 目录下。 +å¦‚æžœæ˜¯æ ‡å‡†çš„ç”¨æˆ·ï¼Œå®ƒå°†ä¼šè¢«è‡ªåŠ¨å®‰è£…åˆ°ä½ çš„~/bin目录下。 使用 sparse 工具 ~~~~~~~~~~~~~~~~ diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst new file mode 100644 index 000000000000..23d0b6fccd58 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/index.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +============================= +Open Firmware å’Œ Devicetree +============================= + +è¯¥æ–‡æ¡£æ˜¯æ•´ä¸ªè®¾å¤‡æ ‘æ–‡æ¡£çš„æ€»ç›®å½•ï¼Œæ ‡é¢˜ä¸å¤šæ˜¯ä¸šå†…默认的术è¯ï¼Œåˆè§å°±ç¿»è¯‘æˆä¸æ–‡ï¼Œ +æ™¦æ¶©éš¾æ‡‚ï¼Œå› æ¤å°½é‡ä¿ç•™ï¼ŒåŽé¢ç¿»è¯‘å…¶å文档时，å¯èƒ½ä¼šæ ¹æ®è¯å¢ƒï¼Œçµæ´»åœ°ç¿»è¯‘为ä¸æ–‡ã€‚ + +å†…æ ¸Devicetree的使用 +======================= +.. toctree:: + :maxdepth: 1 + + usage-model + of_unittest + +Todolist: + +* kernel-api + +Devicetree Overlays +=================== +.. toctree:: + :maxdepth: 1 + +Todolist: + +* changesets +* dynamic-resolution-notes +* overlay-notes + +Devicetree Bindings +=================== +.. toctree:: + :maxdepth: 1 + +Todolist: + +* bindings/index diff --git a/Documentation/translations/zh_CN/devicetree/of_unittest.rst b/Documentation/translations/zh_CN/devicetree/of_unittest.rst new file mode 100644 index 000000000000..abd94e771ef8 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/of_unittest.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/of_unittest.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +================================= +Open Firmware Devicetree å•å…ƒæµ‹è¯• +================================= + +作者: Gaurav Minocha <gaurav.minocha.os@gmail.com> + +1. 概述 +======= + +本文档解释了执行 OF å•å…ƒæµ‹è¯•æ‰€éœ€çš„测试数æ®æ˜¯å¦‚何动æ€åœ°é™„åŠ åˆ°å®žæ—¶æ ‘ä¸Šçš„ï¼Œä¸Žæœºå™¨çš„æž¶æž„æ— å…³ã€‚ + +建议在继ç»è¯»ä¸‹åŽ»ä¹‹å‰ï¼Œå…ˆé˜…读以下文件。 + +(1) Documentation/devicetree/usage-model.rst +(2) http://www.devicetree.org/Device_Tree_Usage + +OF Selftest被设计用æ¥æµ‹è¯•æ供给设备驱动开å‘者的接å£ï¼ˆinclude/linux/of.h），以从未æ‰å¹³ +åŒ–çš„è®¾å¤‡æ ‘æ•°æ®ç»“æž„ä¸èŽ·å–设备信æ¯ç‰ã€‚这个接å£è¢«å¤§å¤šæ•°è®¾å¤‡é©±åŠ¨åœ¨å„ç§ä½¿ç”¨æƒ…况下使用。 + + +2. æµ‹è¯•æ•°æ® +=========== + +è®¾å¤‡æ ‘æºæ–‡ä»¶ï¼ˆdrivers/of/unittest-data/testcases.dts）包å«æ‰§è¡Œdrivers/of/unittest.c +ä¸è‡ªåŠ¨åŒ–å•å…ƒæµ‹è¯•æ‰€éœ€çš„测试数æ®ã€‚ç›®å‰ï¼Œä»¥ä¸‹è®¾å¤‡æ ‘æºåŒ…å«æ–‡ä»¶ï¼ˆ.dtsi）被包å«åœ¨testcases.dtä¸:: + + drivers/of/unittest-data/tests-interrupts.dtsi + drivers/of/unittest-data/tests-platform.dtsi + drivers/of/unittest-data/tests-phandle.dtsi + drivers/of/unittest-data/tests-match.dtsi + +å½“å†…æ ¸åœ¨å¯ç”¨OF_SELFTEST的情况下被构建时，那么下é¢çš„make规则:: + + $(obj)/%.dtb: $(src)/%.dts FORCE + $(call if_changed_dep, dtc) + +用于将DTæºæ–‡ä»¶ï¼ˆtestcases.dts）编译æˆäºŒè¿›åˆ¶blob（testcases.dtb），也被称为æ‰å¹³åŒ–çš„DT。 + +之åŽï¼Œä½¿ç”¨ä»¥ä¸‹è§„则将上述二进制blob包装æˆä¸€ä¸ªæ±‡ç¼–文件（testcases.dtb.S）:: + + $(obj)/%.dtb.S: $(obj)/%.dtb + $(call cmd, dt_S_dtb) + +汇编文件被编译æˆä¸€ä¸ªå¯¹è±¡æ–‡ä»¶ï¼ˆtestcases.dtb.oï¼‰ï¼Œå¹¶è¢«é“¾æŽ¥åˆ°å†…æ ¸é•œåƒä¸ã€‚ + + +2.1. æ·»åŠ æµ‹è¯•æ•°æ® +----------------- + +未æ‰å¹³åŒ–çš„è®¾å¤‡æ ‘ç»“æž„ä½“: + +未æ‰å¹³åŒ–çš„è®¾å¤‡æ ‘ç”±è¿žæŽ¥çš„è®¾å¤‡èŠ‚ç‚¹ç»„æˆï¼Œå…¶æ ‘状结构形å¼å¦‚下所述:: + + // following struct members are used to construct the tree + struct device_node { + ... + struct device_node *parent; + struct device_node *child; + struct device_node *sibling; + ... + }; + +图1æ述了一个机器的未æ‰å¹³åŒ–è®¾å¤‡æ ‘çš„é€šç”¨ç»“æž„ï¼Œåªè€ƒè™‘了å节点和åŒçº§æŒ‡é’ˆã€‚å˜åœ¨å¦ä¸€ä¸ªæŒ‡é’ˆï¼Œ +``*parent`` ，用于åå‘éåŽ†è¯¥æ ‘ã€‚å› æ¤ï¼Œåœ¨ä¸€ä¸ªç‰¹å®šçš„层次上，å节点和所有的兄弟å§å¦¹èŠ‚点将 +有一个指å‘å…±åŒèŠ‚点的父指针（例如，child1ã€sibling2ã€sibling3ã€sibling4çš„çˆ¶æŒ‡é’ˆæŒ‡å‘ +æ ¹èŠ‚ç‚¹ï¼‰:: + + root ('/') + | + child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | + | | | null + | | | + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + | | | null + | | | + null null child131 -> null + | + null + +Figure 1: 未æ‰å¹³åŒ–çš„è®¾å¤‡æ ‘çš„é€šç”¨ç»“æž„ + + +在执行OFå•å…ƒæµ‹è¯•ä¹‹å‰ï¼Œéœ€è¦å°†æµ‹è¯•æ•°æ®é™„åŠ åˆ°æœºå™¨çš„è®¾å¤‡æ ‘ä¸Šï¼ˆå¦‚æžœå˜åœ¨ï¼‰ã€‚å› æ¤ï¼Œå½“调用 +selftest_data_add()时，首先会读å–é€šè¿‡ä»¥ä¸‹å†…æ ¸ç¬¦å·é“¾æŽ¥åˆ°å†…æ ¸é•œåƒä¸çš„æ‰å¹³åŒ–è®¾å¤‡æ ‘ +æ•°æ®:: + + __dtb_testcases_begin - address marking the start of test data blob + __dtb_testcases_end - address marking the end of test data blob + +其次，它调用of_fdt_unflatten_tree()æ¥è§£é™¤æ‰å¹³åŒ–çš„blob。最åŽï¼Œå¦‚æžœæœºå™¨çš„è®¾å¤‡æ ‘ +（å³å®žæ—¶æ ‘）是å˜åœ¨çš„，那么它将未æ‰å¹³åŒ–的测试数æ®æ ‘é™„åŠ åˆ°å®žæ—¶æ ‘ä¸Šï¼Œå¦åˆ™å®ƒå°†è‡ªå·±ä½œä¸º +å®žæ—¶è®¾å¤‡æ ‘é™„åŠ ã€‚ + +attach_node_and_children()使用of_attach_node()å°†èŠ‚ç‚¹é™„åŠ åˆ°å®žæ—¶æ ‘ä¸Šï¼Œå¦‚ä¸‹æ‰€ +述。为了解释这一点，图2ä¸æ述的测试数æ®æ ‘è¢«é™„åŠ åˆ°å›¾1ä¸æè¿°çš„å®žæ—¶æ ‘ä¸Š:: + + root ('/') + | + testcase-data + | + test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null + | | | | + test-child01 null null null + + +Figure 2: 将测试数æ®æ ‘é™„åœ¨å®žæ—¶æ ‘ä¸Šçš„ä¾‹å。 + +æ ¹æ®ä¸Šé¢çš„æ–¹æ¡ˆï¼Œå®žæ—¶æ ‘å·²ç»å˜åœ¨ï¼Œæ‰€ä»¥ä¸éœ€è¦é™„åŠ æ ¹('/')节点。所有其他节点都是通过在 +æ¯ä¸ªèŠ‚点上调用of_attach_node()æ¥é™„åŠ çš„ã€‚ + +在函数of_attach_node()ä¸ï¼Œæ–°çš„èŠ‚ç‚¹è¢«é™„åœ¨å®žæ—¶æ ‘ä¸ç»™å®šçš„父节点的å节点上。但是，如 +果父节点已ç»æœ‰äº†ä¸€ä¸ªå©å，那么新节点就会å–代当å‰çš„å©å，并将其å˜æˆå…¶å…„弟å§å¦¹ã€‚å› æ¤ï¼Œ +当测试案例的数æ®èŠ‚点被连接到上é¢çš„å®žæ—¶æ ‘ï¼ˆå›¾1）时，最终的结构如图3所示:: + + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + (...) | | | null + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + null null | null + | + child131 -> null + | + null + ----------------------------------------------------------------------- + + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + | (...) (...) (...) null + | + test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null + | | | | + null null null test-child01 + + +Figure 3: é™„åŠ æµ‹è¯•æ¡ˆä¾‹æ•°æ®åŽçš„å®žæ—¶è®¾å¤‡æ ‘ç»“æž„ã€‚ + + +èªæ˜Žçš„读者会注æ„到，与先å‰çš„结构相比，test-child0节点æˆä¸ºæœ€åŽä¸€ä¸ªå…„弟å§å¦¹ï¼ˆå›¾2）。 +在连接了第一个test-child0节点之åŽï¼Œåˆè¿žæŽ¥äº†test-sibling1节点，该节点推动å节点 +（å³test-child0）æˆä¸ºå…„弟å§å¦¹ï¼Œå¹¶ä½¿è‡ªå·±æˆä¸ºå节点，如上所述。 + +如果å‘现一个é‡å¤çš„节点（å³å¦‚果一个具有相åŒfull_name属性的节点已ç»å˜åœ¨äºŽå®žæ—¶æ ‘ä¸ï¼‰ï¼Œ +那么该节点ä¸ä¼šè¢«é™„åŠ ï¼Œè€Œæ˜¯é€šè¿‡è°ƒç”¨å‡½æ•°update_node_properties()将其属性更新到活 +æ ‘çš„èŠ‚ç‚¹ä¸ã€‚ + + +2.2. åˆ é™¤æµ‹è¯•æ•°æ® +----------------- + +一旦测试用例执行完，selftest_data_remove被调用，以移除最åˆè¿žæŽ¥çš„设备节点（首先是 +å¶å节点被分离，然åŽå‘上移动父节点被移除，最åŽæ˜¯æ•´ä¸ªæ ‘）。selftest_data_remove() +调用detach_node_and_children()，使用of_detach_node()å°†èŠ‚ç‚¹ä»Žå®žæ—¶è®¾å¤‡æ ‘ä¸Šåˆ†ç¦»ã€‚ + +为了分离一个节点，of_detach_node()è¦ä¹ˆå°†ç»™å®šèŠ‚点的父节点的å节点指针更新为其åŒçº§èŠ‚ +点，è¦ä¹ˆæ ¹æ®æƒ…况将å‰ä¸€ä¸ªåŒçº§èŠ‚点附在给定节点的åŒçº§èŠ‚ç‚¹ä¸Šã€‚å°±è¿™æ ·å§ã€‚ :) diff --git a/Documentation/translations/zh_CN/devicetree/usage-model.rst b/Documentation/translations/zh_CN/devicetree/usage-model.rst new file mode 100644 index 000000000000..318a3c6a0114 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/usage-model.rst @@ -0,0 +1,330 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/usage-model.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +=================== +Linux å’Œ Devicetree +=================== + +Linuxå¯¹è®¾å¤‡æ ‘æ•°æ®çš„使用模型 + +:作者: Grant Likely <grant.likely@secretlab.ca> + +è¿™ç¯‡æ–‡ç« æ述了Linuxå¦‚ä½•ä½¿ç”¨è®¾å¤‡æ ‘ã€‚å…³äºŽè®¾å¤‡æ ‘æ•°æ®æ ¼å¼çš„概述å¯ä»¥åœ¨ +devicetree.org\ [1]_ çš„è®¾å¤‡æ ‘ä½¿ç”¨é¡µé¢ä¸Šæ‰¾åˆ°ã€‚ + +.. [1] https://www.devicetree.org/specifications/ + +"Open Firmware Device Tree"，或简称为Devicetree（DT），是一ç§ç”¨äºŽæ述硬 +件的数æ®ç»“æž„å’Œè¯è¨€ã€‚更确切地说，它是一ç§æ“作系统å¯è¯»çš„硬件æè¿°ï¼Œè¿™æ ·æ“ä½œç³»ç»Ÿå°±ä¸ +需è¦å¯¹æœºå™¨çš„细节进行硬编ç 。 + +从结构上看，DTæ˜¯ä¸€æ£µæ ‘ï¼Œæˆ–è€…è¯´æ˜¯å¸¦æœ‰å‘½åèŠ‚ç‚¹çš„æ— çŽ¯å›¾ï¼ŒèŠ‚ç‚¹å¯ä»¥æœ‰ä»»æ„æ•°é‡çš„命å +属性æ¥å°è£…ä»»æ„çš„æ•°æ®ã€‚还å˜åœ¨ä¸€ç§æœºåˆ¶ï¼Œå¯ä»¥åœ¨è‡ªç„¶çš„æ ‘çŠ¶ç»“æž„ä¹‹å¤–åˆ›å»ºä»Žä¸€ä¸ªèŠ‚ç‚¹åˆ° +å¦ä¸€ä¸ªèŠ‚点的任æ„链接。 + +从概念上讲，一套通用的使用惯例，称为 "bindings"（åŽæ–‡è¯‘ä¸ºç»‘å®šï¼‰ï¼Œè¢«å®šä¹‰ä¸ºæ•°æ® +åº”è¯¥å¦‚ä½•å‡ºçŽ°åœ¨æ ‘ä¸ï¼Œä»¥æ述典型的硬件特性，包括数æ®æ€»çº¿ã€ä¸æ–线ã€GPIO连接和外围 +设备。 + +å°½å¯èƒ½ä½¿ç”¨çŽ°æœ‰çš„绑定æ¥æ述硬件，以最大é™åº¦åœ°åˆ©ç”¨çŽ°æœ‰çš„支æŒä»£ç ，但由于属性和节 +点å称是简å•çš„文本å—符串，通过定义新的节点和属性æ¥æ‰©å±•çŽ°æœ‰çš„绑定或创建新的绑定 +很容易。然而，è¦è¦æƒ•çš„是，在创建一个新的绑定之å‰ï¼Œæœ€å¥½å…ˆå¯¹å·²ç»å˜åœ¨çš„东西åšä¸€äº› +功课。目å‰æœ‰ä¸¤ç§ä¸åŒçš„ã€ä¸å…¼å®¹çš„i2cæ€»çº¿çš„ç»‘å®šï¼Œè¿™æ˜¯å› ä¸ºåœ¨åˆ›å»ºæ–°çš„ç»‘å®šæ—¶æ²¡æœ‰äº‹å…ˆ +调查i2c设备在现有系统ä¸æ˜¯å¦‚何被枚举的。 + +1. åŽ†å² +------- +DT最åˆæ˜¯ç”±Open Firmware创建的，作为将数æ®ä»ŽOpen Firmwareä¼ é€’ç»™å®¢æˆ·ç¨‹åº +ï¼ˆå¦‚ä¼ é€’ç»™æ“作系统）的通信方法的一部分。æ“ä½œç³»ç»Ÿä½¿ç”¨è®¾å¤‡æ ‘åœ¨è¿è¡Œæ—¶æŽ¢æµ‹ç¡¬ä»¶çš„æ‹“ +扑结构，从而在没有硬编ç ä¿¡æ¯çš„情况下支æŒå¤§å¤šæ•°å¯ç”¨çš„硬件（å‡è®¾æ‰€æœ‰è®¾å¤‡çš„驱动程 +åºéƒ½å¯ç”¨ï¼‰ã€‚ + +由于Open Firmware通常在PowerPCå’ŒSPARCå¹³å°ä¸Šä½¿ç”¨ï¼Œé•¿æœŸä»¥æ¥ï¼Œå¯¹è¿™äº›æž¶æž„çš„ +Linux支æŒä¸€ç›´ä½¿ç”¨è®¾å¤‡æ ‘。 + +2005年，当PowerPC Linux开始大规模清ç†å¹¶åˆå¹¶32ä½å’Œ64ä½æ”¯æŒæ—¶ï¼Œå†³å®šåœ¨æ‰€æœ‰ +Powerpcå¹³å°ä¸Šè¦æ±‚DT支æŒï¼Œæ— 论它们是å¦ä½¿ç”¨Open Firmware。为了åšåˆ°è¿™ä¸€ç‚¹ï¼Œ +我们创建了一个å«åšæ‰å¹³åŒ–è®¾å¤‡æ ‘ï¼ˆFDT）的DT表示法，它å¯ä»¥ä½œä¸ºä¸€ä¸ªäºŒè¿›åˆ¶çš„blob +ä¼ é€’ç»™å†…æ ¸ï¼Œè€Œä¸éœ€è¦çœŸæ£çš„Open Firmware实现。U-Bootã€kexecå’Œå…¶ä»–å¼•å¯¼ç¨‹åº +被修改，以支æŒä¼ é€’è®¾å¤‡æ ‘äºŒè¿›åˆ¶ï¼ˆdtb）和在引导时修改dtb。DTä¹Ÿè¢«æ·»åŠ åˆ°PowerPC +引导包装器（arch/powerpc/boot/\*）ä¸ï¼Œè¿™æ ·dtbå°±å¯ä»¥è¢«åŒ…è£¹åœ¨å†…æ ¸é•œåƒä¸ï¼Œä»¥ +支æŒå¼•å¯¼çŽ°æœ‰çš„éžDT察觉的固件。 + +一段时间åŽï¼ŒFDT基础架构被普åŠåˆ°äº†æ‰€æœ‰çš„架构ä¸ã€‚åœ¨å†™è¿™ç¯‡æ–‡ç« çš„æ—¶å€™ï¼Œ6个主线架 +构（armã€microblazeã€mipsã€powerpcã€sparcå’Œx86）和1个éžä¸»çº¿æž¶æž„（ios） +有æŸç§ç¨‹åº¦çš„DT支æŒã€‚ + +1. æ•°æ®æ¨¡åž‹ +----------- +å¦‚æžœä½ è¿˜æ²¡æœ‰è¯»è¿‡è®¾å¤‡æ ‘ç”¨æ³•\ [1]_页，那么现在就去读å§ã€‚没关系，我ç‰ç€.... + +2.1 高层次视角 +-------------- +最é‡è¦çš„是è¦æ˜Žç™½ï¼ŒDTåªæ˜¯ä¸€ä¸ªæ述硬件的数æ®ç»“构。它没有什么神奇之处，也ä¸ä¼šç¥ž +奇地让所有的硬件é…置问题消失。它所åšçš„是æ供一ç§è¯è¨€ï¼Œå°†ç¡¬ä»¶é…置与Linuxå†…æ ¸ +（或任何其他æ“作系统）ä¸çš„æ¿å¡å’Œè®¾å¤‡é©±åŠ¨æ”¯æŒè§£è€¦ã€‚使用它å¯ä»¥ä½¿æ¿å¡å’Œè®¾å¤‡æ”¯æŒ +å˜æˆæ•°æ®é©±åŠ¨ï¼›æ ¹æ®ä¼ é€’åˆ°å†…æ ¸çš„æ•°æ®åšå‡ºè®¾ç½®å†³å®šï¼Œè€Œä¸æ˜¯æ ¹æ®æ¯å°æœºå™¨çš„硬编ç 选 +择。 + +ç†æƒ³æƒ…况下，数æ®é©±åŠ¨çš„å¹³å°è®¾ç½®åº”该导致更少的代ç é‡å¤ï¼Œå¹¶ä½¿å…¶æ›´å®¹æ˜“ç”¨ä¸€ä¸ªå†…æ ¸ +é•œåƒæ”¯æŒå„ç§ç¡¬ä»¶ã€‚ + +Linux使用DTæ•°æ®æœ‰ä¸‰ä¸ªä¸»è¦ç›®çš„: + +1) å¹³å°è¯†åˆ«ã€‚ +2) è¿è¡Œæ—¶é…ç½®ï¼Œä»¥åŠ +3) 设备数é‡ã€‚ + +2.2 å¹³å°è¯†åˆ« +------------ +é¦–å…ˆï¼Œå†…æ ¸å°†ä½¿ç”¨DTä¸çš„æ•°æ®æ¥è¯†åˆ«ç‰¹å®šçš„机器。在一个ç†æƒ³çš„世界里，具体的平å°å¯¹ +å†…æ ¸æ¥è¯´å¹¶ä¸é‡è¦ï¼Œå› 为所有的平å°ç»†èŠ‚éƒ½ä¼šè¢«è®¾å¤‡æ ‘ä»¥ä¸€è‡´å’Œå¯é çš„æ–¹å¼å®Œç¾Žæ述。 +但是，硬件并ä¸å®Œç¾Žï¼Œæ‰€ä»¥å†…æ ¸å¿…é¡»åœ¨æ—©æœŸå¯åŠ¨æ—¶è¯†åˆ«æœºå™¨ï¼Œä»¥ä¾¿æœ‰æœºä¼šè¿è¡Œç‰¹å®šäºŽæœº +器的修å¤ç¨‹åºã€‚ + +在大多数情况下，机器的身份是ä¸ç›¸å…³çš„ï¼Œè€Œå†…æ ¸å°†æ ¹æ®æœºå™¨çš„æ ¸å¿ƒCPU或SoCæ¥é€‰æ‹© +设置代ç 。例如，在ARM上，arch/arm/kernel/setup.cä¸çš„setup_arch()将调 +用arch/arm/kernel/devtree.cä¸çš„setup_machine_fdt()，它通过 +machine_desc表æœç´¢å¹¶é€‰æ‹©ä¸Žè®¾å¤‡æ ‘æ•°æ®æœ€åŒ¹é…çš„machine_descã€‚å®ƒé€šè¿‡æŸ¥çœ‹æ ¹ +è®¾å¤‡æ ‘èŠ‚ç‚¹ä¸çš„'compatible'属性，并将其与struct machine_descä¸çš„ +dt_compatåˆ—è¡¨ï¼ˆå¦‚æžœä½ å¥½å¥‡ï¼Œè¯¥åˆ—è¡¨å®šä¹‰åœ¨arch/arm/include/asm/mach/arch.h +ä¸ï¼‰è¿›è¡Œæ¯”较，从而确定最佳匹é…。 + +“compatible†属性包å«ä¸€ä¸ªæŽ’åºçš„å—符串列表，以机器的确切å称开始，åŽé¢æ˜¯ +一个å¯é€‰çš„与之兼容的æ¿å列表，从最兼容到最ä¸å…¼å®¹æŽ’åºã€‚例如，TI BeagleBoard +和它的åŽç»§è€…BeagleBoard xMæ¿çš„æ ¹å…¼å®¹å±žæ€§å¯èƒ½çœ‹èµ·æ¥åˆ†åˆ«ä¸º:: + + compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3"; + compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3"; + +å…¶ä¸ "ti,map3-beagleboard-xm "指定了确切的型å·ï¼Œå®ƒè¿˜å£°ç§°å®ƒä¸ŽOMAP 3450 SoC +以åŠä¸€èˆ¬çš„OMP3系列SoCå…¼å®¹ã€‚ä½ ä¼šæ³¨æ„到，该列表从最具体的（确切的æ¿å）到最 +ä¸å…·ä½“的（SoC系列）进行排åºã€‚ + +èªæ˜Žçš„读者å¯èƒ½ä¼šæŒ‡å‡ºï¼ŒBeagle xM也å¯ä»¥å£°ç§°ä¸ŽåŽŸBeagleæ¿å…¼å®¹ã€‚然而，我们应 +该当心在æ¿çº§ä¸Šè¿™æ ·åšï¼Œå› 为通常情况下，å³ä½¿åœ¨åŒä¸€äº§å“系列ä¸ï¼Œæ¯å—æ¿éƒ½æœ‰å¾ˆé«˜ +çš„å˜åŒ–，而且当一å—æ¿å£°ç§°ä¸Žå¦ä¸€å—æ¿å…¼å®¹æ—¶ï¼Œå¾ˆéš¾ç¡®å®šåˆ°åº•æ˜¯ä»€ä¹ˆæ„æ€ã€‚对于高层 +æ¥è¯´ï¼Œæœ€å¥½æ˜¯è°¨æ…Žè¡Œäº‹ï¼Œä¸è¦å£°ç§°ä¸€å—æ¿å与å¦ä¸€å—æ¿å兼容。值得注æ„的例外是， +当一å—æ¿å是å¦ä¸€å—æ¿å的载体时，例如CPU模å—连接到一个载体æ¿ä¸Šã€‚ + +关于兼容值还有一个注æ„事项。在兼容属性ä¸ä½¿ç”¨çš„任何å—符串都必须有文件说明它 +表示什么。在Documentation/devicetree/bindingsä¸æ·»åŠ 兼容å—符串的文档。 + +åŒæ ·åœ¨ARM上，对于æ¯ä¸ªmachine_descï¼Œå†…æ ¸ä¼šæŸ¥çœ‹æ˜¯å¦æœ‰ä»»ä½•dt_compatåˆ—è¡¨æ¡ +目出现在兼容属性ä¸ã€‚如果有，那么该机器_desc就是驱动该机器的候选者。在æœç´¢ +了整个machine_descs表之åŽï¼Œsetup_machine_fdt()æ ¹æ®æ¯ä¸ªmachine_desc +在兼容属性ä¸åŒ¹é…çš„æ¡ç›®ï¼Œè¿”回 “最兼容†的machine_descã€‚å¦‚æžœæ²¡æœ‰æ‰¾åˆ°åŒ¹é… +çš„machine_desc，那么它将返回NULL。 + +这个方案背åŽçš„åŽŸå› æ˜¯è§‚å¯Ÿåˆ°ï¼Œåœ¨å¤§å¤šæ•°æƒ…å†µä¸‹ï¼Œå¦‚æžœå®ƒä»¬éƒ½ä½¿ç”¨ç›¸åŒçš„SoCæˆ–ç›¸åŒ +系列的SoC，一个机器_descå¯ä»¥æ”¯æŒå¤§é‡çš„电路æ¿ã€‚然而，ä¸å¯é¿å…地会有一些例 +外情况，å³ç‰¹å®šçš„æ¿å需è¦ç‰¹æ®Šçš„设置代ç ，这在一般情况下是没有用的。特殊情况 +å¯ä»¥é€šè¿‡åœ¨é€šç”¨è®¾ç½®ä»£ç ä¸æ˜Žç¡®æ£€æŸ¥æœ‰é—®é¢˜çš„æ¿åæ¥å¤„ç†ï¼Œä½†å¦‚æžœè¶…è¿‡å‡ ä¸ªæƒ…å†µä¸‹ï¼Œ +è¿™æ ·åšå¾ˆå¿«å°±ä¼šå˜å¾—很难看和/æˆ–æ— æ³•ç»´æŠ¤ã€‚ + +相å，兼容列表å…许通用机器_desc通过在dt_compat列表ä¸æŒ‡å®šâ€œä¸å¤ªå…¼å®¹â€çš„值 +æ¥æ供对广泛的通用æ¿çš„支æŒã€‚在上é¢çš„例åä¸ï¼Œé€šç”¨æ¿æ”¯æŒå¯ä»¥å£°ç§°ä¸Žâ€œti,ompa3†+或“ti,ompa3450â€å…¼å®¹ã€‚如果在最åˆçš„beagleboard上å‘现了一个bug，需è¦åœ¨ +早期å¯åŠ¨æ—¶ä½¿ç”¨ç‰¹æ®Šçš„å˜é€šä»£ç ，那么å¯ä»¥æ·»åŠ 一个新的machine_desc，实现å˜é€šï¼Œ +并且åªåœ¨â€œti,omap3-beagleboardâ€ä¸ŠåŒ¹é…。 + +PowerPC使用了一个ç¨å¾®ä¸åŒçš„方案，它从æ¯ä¸ªæœºå™¨_descä¸è°ƒç”¨.probe()é’©å， +并使用第一个返回TRUEçš„é’©å。然而，这ç§æ–¹æ³•æ²¡æœ‰è€ƒè™‘到兼容列表的优先级，对于 +新的架构支æŒå¯èƒ½åº”该é¿å…。 + +2.3 è¿è¡Œæ—¶é…ç½® +-------------- +在大多数情况下，DT是将数æ®ä»Žå›ºä»¶ä¼ é€’ç»™å†…æ ¸çš„å”¯ä¸€æ–¹æ³•ï¼Œæ‰€ä»¥ä¹Ÿè¢«ç”¨æ¥ä¼ 递è¿è¡Œ +时和é…置数æ®ï¼Œå¦‚å†…æ ¸å‚æ•°å—符串和initrdé•œåƒçš„ä½ç½®ã€‚ + +这些数æ®å¤§éƒ¨åˆ†éƒ½åŒ…å«åœ¨/chosen节点ä¸ï¼Œå½“å¯åŠ¨Linux时，它看起æ¥å°±åƒè¿™æ ·:: + + chosen { + bootargs = "console=ttyS0,115200 loglevel=8"; + initrd-start = <0xc8000000>; + initrd-end = <0xc8200000>; + }; + +bootargs属性包å«å†…æ ¸å‚数，initrd-\*属性定义initrd blob的地å€å’Œå¤§å°ã€‚注 +æ„initrd-end是initrdæ˜ åƒåŽçš„第一个地å€ï¼Œæ‰€ä»¥è¿™ä¸Žç»“构体资æºçš„通常è¯ä¹‰ä¸ä¸€ +致。选择的节点也å¯ä»¥é€‰æ‹©åŒ…å«ä»»æ„æ•°é‡çš„é¢å¤–属性，用于平å°ç‰¹å®šçš„é…置数æ®ã€‚ + +在早期å¯åŠ¨è¿‡ç¨‹ä¸ï¼Œæž¶æž„设置代ç 通过ä¸åŒçš„辅助回调函数多次调用 +of_scan_flat_dt()æ¥è§£æžè®¾å¤‡æ ‘æ•°æ®ï¼Œç„¶åŽè¿›è¡Œåˆ†é¡µè®¾ç½®ã€‚of_scan_flat_dt() +代ç 扫æè®¾å¤‡æ ‘ï¼Œå¹¶ä½¿ç”¨è¾…åŠ©å‡½æ•°æ¥æå–早期å¯åŠ¨æœŸé—´æ‰€éœ€çš„ä¿¡æ¯ã€‚通常情况下， +early_init_dt_scan_chosen()辅助函数用于解æžæ‰€é€‰èŠ‚ç‚¹ï¼ŒåŒ…æ‹¬å†…æ ¸å‚数， +early_init_dt_scan_root()用于åˆå§‹åŒ–DT地å€ç©ºé—´æ¨¡åž‹ï¼Œearly_init_dt_scan_memory() +用于确定å¯ç”¨RAM的大å°å’Œä½ç½®ã€‚ + +在ARM上，函数setup_machine_fdt()负责在选择支æŒæ¿åçš„æ£ç¡®machine_desc +åŽï¼Œå¯¹è®¾å¤‡æ ‘进行早期扫æ。 + +2.4 è®¾å¤‡æ•°é‡ +------------ +在电路æ¿è¢«è¯†åˆ«åŽï¼Œåœ¨æ—©æœŸé…置数æ®è¢«è§£æžåŽï¼Œå†…æ ¸åˆå§‹åŒ–å¯ä»¥ä»¥æ£å¸¸æ–¹å¼è¿›è¡Œã€‚在 +这个过程ä¸çš„æŸä¸ªæ—¶åˆ»ï¼Œunflatten_device_tree()被调用以将数æ®è½¬æ¢æˆæ›´æœ‰ +效的è¿è¡Œæ—¶è¡¨ç¤ºã€‚这也是调用机器特定设置钩å的时候，比如ARM上的machine_desc +.init_early()ã€.init_irq()å’Œ.init_machine()é’©å。本节的其余部分使用 +了ARM实现的例å，但所有架构在使用DT时都会åšå‡ 乎相åŒçš„事情。 + +从å称上å¯ä»¥çŒœåˆ°ï¼Œ.init_early()用于在å¯åŠ¨è¿‡ç¨‹æ—©æœŸéœ€è¦æ‰§è¡Œçš„任何机器特定设 +置，而.init_irq()则用于设置ä¸æ–处ç†ã€‚使用DT并ä¸ä¼šå®žè´¨æ€§åœ°æ”¹å˜è¿™ä¸¤ä¸ªå‡½æ•°çš„ +行为。如果æ供了DT，那么.init_early()å’Œ.init_irq()都能调用任何一个DT查 +询函数（of_* in include/linux/of*.h），以获得关于平å°çš„é¢å¤–æ•°æ®ã€‚ + +DT上下文ä¸æœ€æœ‰è¶£çš„é’©å是.init_machine()，它主è¦è´Ÿè´£å°†å¹³å°çš„æ•°æ®å¡«å……到 +Linux设备模型ä¸ã€‚历å²ä¸Šï¼Œè¿™åœ¨åµŒå…¥å¼å¹³å°ä¸Šæ˜¯é€šè¿‡åœ¨æ¿å¡support .c文件ä¸å®š +义一组é™æ€æ—¶é’Ÿç»“æž„ã€platform_devices和其他数æ®ï¼Œå¹¶åœ¨.init_machine()ä¸ +大é‡æ³¨å†Œæ¥å®žçŽ°çš„。当使用DT时，就ä¸ç”¨ä¸ºæ¯ä¸ªå¹³å°çš„é™æ€è®¾å¤‡è¿›è¡Œç¡¬ç¼–ç ，å¯ä»¥é€šè¿‡ +解æžDT获得设备列表，并动æ€åˆ†é…设备结构体。 + +最简å•çš„情况是，.init_machine()åªè´Ÿè´£æ³¨å†Œä¸€ä¸ªplatform_devices。 +platform_device是Linux使用的一个概念，用于ä¸èƒ½è¢«ç¡¬ä»¶æ£€æµ‹åˆ°çš„内å˜æˆ–I/Oæ˜ +射的设备，以åŠâ€œå¤åˆâ€æˆ– “虚拟â€è®¾å¤‡ï¼ˆåŽé¢ä¼šè¯¦ç»†ä»‹ç»ï¼‰ã€‚虽然DT没有“平å°è®¾å¤‡â€çš„ +术è¯ï¼Œä½†å¹³å°è®¾å¤‡å¤§è‡´å¯¹åº”äºŽæ ‘æ ¹çš„è®¾å¤‡èŠ‚ç‚¹å’Œç®€å•å†…å˜æ˜ 射总线节点的å节点。 + +现在是举例说明的好时机。下é¢æ˜¯NVIDIA Tegraæ¿çš„è®¾å¤‡æ ‘çš„ä¸€éƒ¨åˆ†:: + + /{ + compatible = "nvidia,harmony", "nvidia,tegra20"; + #address-cells = <1>; + #size-cells = <1>; + interrupt-parent = <&intc>; + + chosen { }; + aliases { }; + + memory { + device_type = "memory"; + reg = <0x00000000 0x40000000>; + }; + + soc { + compatible = "nvidia,tegra20-soc", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + intc: interrupt-controller@50041000 { + compatible = "nvidia,tegra20-gic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x50041000 0x1000>, < 0x50040100 0x0100 >; + }; + + serial@70006300 { + compatible = "nvidia,tegra20-uart"; + reg = <0x70006300 0x100>; + interrupts = <122>; + }; + + i2s1: i2s@70002800 { + compatible = "nvidia,tegra20-i2s"; + reg = <0x70002800 0x100>; + interrupts = <77>; + codec = <&wm8903>; + }; + + i2c@7000c000 { + compatible = "nvidia,tegra20-i2c"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x7000c000 0x100>; + interrupts = <70>; + + wm8903: codec@1a { + compatible = "wlf,wm8903"; + reg = <0x1a>; + interrupts = <347>; + }; + }; + }; + + sound { + compatible = "nvidia,harmony-sound"; + i2s-controller = <&i2s1>; + i2s-codec = <&wm8903>; + }; + }; + +在.init_machine()时，Tegraæ¿æ”¯æŒä»£ç 将需è¦æŸ¥çœ‹è¿™ä¸ªDT，并决定为哪些节点 +创建platform_devicesã€‚ç„¶è€Œï¼Œçœ‹ä¸€ä¸‹è¿™ä¸ªæ ‘ï¼Œå¹¶ä¸èƒ½ç«‹å³çœ‹å‡ºæ¯ä¸ªèŠ‚点代表什么 +类型的设备，甚至ä¸èƒ½çœ‹å‡ºä¸€ä¸ªèŠ‚点是å¦ä»£è¡¨ä¸€ä¸ªè®¾å¤‡ã€‚/chosenã€/aliaseså’Œ +/memory节点是信æ¯èŠ‚点，并ä¸æ述设备（尽管å¯ä»¥è¯´å†…å˜å¯ä»¥è¢«è®¤ä¸ºæ˜¯ä¸€ä¸ªè®¾å¤‡ï¼‰ã€‚ +/soc节点的å节点是内å˜æ˜ 射的设备，但是codec@1a是一个i2c设备，而sound节 +点代表的ä¸æ˜¯ä¸€ä¸ªè®¾å¤‡ï¼Œè€Œæ˜¯å…¶ä»–设备是如何连接在一起以创建音频å系统的。我知 +é“æ¯ä¸ªè®¾å¤‡æ˜¯ä»€ä¹ˆï¼Œå› 为我熟悉电路æ¿çš„è®¾è®¡ï¼Œä½†æ˜¯å†…æ ¸æ€Žä¹ˆçŸ¥é“æ¯ä¸ªèŠ‚点该怎么åšï¼Ÿ + +诀çªåœ¨äºŽï¼Œå†…æ ¸ä»Žæ ‘çš„æ ¹éƒ¨å¼€å§‹ï¼Œå¯»æ‰¾å…·æœ‰â€œå…¼å®¹â€å±žæ€§çš„节点。首先，一般认为任何 +具有“兼容â€å±žæ€§çš„节点都代表æŸç§è®¾å¤‡ï¼›å…¶æ¬¡ï¼Œå¯ä»¥è®¤ä¸ºæ ‘æ ¹çš„ä»»ä½•èŠ‚ç‚¹è¦ä¹ˆç›´æŽ¥è¿ž +接到处ç†å™¨æ€»çº¿ä¸Šï¼Œè¦ä¹ˆæ˜¯æ— 法用其他方å¼æè¿°çš„æ‚项系统设备。对于这些节点ä¸çš„ +æ¯ä¸€ä¸ªï¼ŒLinux都会分é…和注册一个platform_device，它åˆå¯èƒ½è¢«ç»‘定到一个 +platform_driver。 + +为什么为这些节点使用platform_device是一个安全的å‡è®¾ï¼Ÿå—¯ï¼Œå°±Linux对设备 +的建模方å¼è€Œè¨€ï¼Œå‡ 乎所有的总线类型都å‡å®šå…¶è®¾å¤‡æ˜¯æ€»çº¿æŽ§åˆ¶å™¨çš„å©åã€‚ä¾‹å¦‚ï¼Œæ¯ +个i2c_client是i2c_master的一个å节点。æ¯ä¸ªspi_device都是SPI总线的一 +个å节点。类似的还有USBã€PCIã€MDIOç‰ã€‚åŒæ ·çš„层次结构也出现在DTä¸ï¼ŒI2C设 +备节点åªä½œä¸ºI2C总线节点的å节点出现。åŒç†ï¼ŒSPIã€MDIOã€USBç‰ç‰ã€‚唯一ä¸éœ€ +è¦ç‰¹å®šç±»åž‹çš„父设备的设备是platform_devices（和amba_devices，但åŽé¢ä¼š +详细介ç»ï¼‰ï¼Œå®ƒä»¬å°†æ„‰å¿«åœ°è¿è¡Œåœ¨Linux/sys/devicesæ ‘çš„åº•éƒ¨ã€‚å› æ¤ï¼Œå¦‚果一个 +DT节点ä½äºŽæ ‘çš„æ ¹éƒ¨ï¼Œé‚£ä¹ˆå®ƒçœŸçš„å¯èƒ½æœ€å¥½æ³¨å†Œä¸ºplatform_device。 + +Linuxæ¿æ”¯æŒä»£ç 调用of_platform_populate(NULL, NULL, NULL, NULL)æ¥ +å¯åŠ¨æ ‘æ ¹çš„è®¾å¤‡å‘现。å‚数都是NULLï¼Œå› ä¸ºå½“ä»Žæ ‘çš„æ ¹éƒ¨å¼€å§‹æ—¶ï¼Œä¸éœ€è¦æ供一个起 +始节点（第一个NULL），一个父结构设备（最åŽä¸€ä¸ªNULLï¼‰ï¼Œè€Œä¸”æˆ‘ä»¬æ²¡æœ‰ä½¿ç”¨åŒ¹é… +表（尚未）。对于åªéœ€è¦æ³¨å†Œè®¾å¤‡çš„æ¿å，除了of_platform_populate()的调用， +.init_machine()å¯ä»¥å®Œå…¨ä¸ºç©ºã€‚ + +在Tegra的例åä¸ï¼Œè¿™è¯´æ˜Žäº†/socå’Œ/sound节点，但是SoC节点的å节点呢？它们 +ä¸åº”该也被注册为平å°è®¾å¤‡å—？对于Linux DT支æŒï¼Œä¸€èˆ¬çš„行为是å设备在驱动 +.probe()æ—¶è¢«çˆ¶è®¾å¤‡é©±åŠ¨æ³¨å†Œã€‚å› æ¤ï¼Œä¸€ä¸ªi2c总线设备驱动程åºå°†ä¸ºæ¯ä¸ªå节点 +注册一个i2c_client，一个SPI总线驱动程åºå°†æ³¨å†Œå…¶spi_deviceå节点，其他 +总线类型也是如æ¤ã€‚æ ¹æ®è¯¥æ¨¡åž‹ï¼Œå¯ä»¥ç¼–写一个与SoC节点绑定的驱动程åºï¼Œå¹¶ç®€å• +地为其æ¯ä¸ªå节点注册platform_device。æ¿å¡æ”¯æŒä»£ç 将分é…和注册一个SoC设 +备，一个（ç†è®ºä¸Šçš„）SoC设备驱动程åºå¯ä»¥ç»‘定到SoC设备，并在其.probe()é’© +ä¸ä¸º/soc/interruptcontrollerã€/soc/serialã€/soc/i2så’Œ/soc/i2c注 +册platform_devices。很简å•ï¼Œå¯¹å—？ + +实际上，事实è¯æ˜Žï¼Œå°†ä¸€äº›platform_deviceçš„å设备注册为更多的platform_device +是一ç§å¸¸è§çš„模å¼ï¼Œè®¾å¤‡æ ‘支æŒä»£ç åæ˜ äº†è¿™ä¸€ç‚¹ï¼Œå¹¶ä½¿ä¸Šè¿°ä¾‹å更简å•ã€‚ +of_platform_populate()的第二个å‚数是一个of_device_id表，任何与该表 +ä¸çš„æ¡ç›®ç›¸åŒ¹é…的节点也将获得其å节点的注册。在Tegra的例åä¸ï¼Œä»£ç å¯ä»¥æ˜¯ +è¿™æ ·çš„:: + + static void __init harmony_init_machine(void) + { + /* ... */ + of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL); + } + +“simple-busâ€åœ¨Devicetree规范ä¸è¢«å®šä¹‰ä¸ºä¸€ä¸ªå±žæ€§ï¼Œæ„味ç€ä¸€ä¸ªç®€å•çš„内å˜æ˜ å°„ +的总线，所以of_platform_populate()代ç å¯ä»¥è¢«å†™æˆåªæ˜¯å‡è®¾ç®€å•æ€»çº¿å…¼å®¹çš„节 +点将总是被é历。然而，我们把它作为一个å‚æ•°ä¼ å…¥ï¼Œä»¥ä¾¿ç”µè·¯æ¿æ”¯æŒä»£ç å¯ä»¥éšæ—¶è¦† +盖默认行为。 + +[需è¦æ·»åŠ å…³äºŽæ·»åŠ i2c/spi/etcå设备的讨论] 。 + +附录A：AMBA设备 +--------------- + +ARM Primecell是连接到ARM AMBA总线的æŸç§è®¾å¤‡ï¼Œå®ƒåŒ…括对硬件检测和电æºç®¡ç† +的一些支æŒã€‚在Linuxä¸ï¼Œamba_deviceå’Œamba_bus_type结构体被用æ¥è¡¨ç¤º +Primecell设备。然而，棘手的一点是，AMBA总线上的所有设备并éžéƒ½æ˜¯Primecell， +而且对于Linuxæ¥è¯´ï¼Œå…¸åž‹çš„情况是amba_deviceå’Œplatform_deviceå®žä¾‹éƒ½æ˜¯åŒ +一总线段的åŒä¹‰è¯ã€‚ + +当使用DT时，这给of_platform_populate()带æ¥äº†é—®é¢˜ï¼Œå› 为它必须决定是å¦å°† +æ¯ä¸ªèŠ‚点注册为platform_device或amba_device。ä¸å¹¸çš„是，这使设备创建模型 +å˜å¾—有点å¤æ‚，但解决方案原æ¥å¹¶ä¸æ˜¯å¤ªå…·æœ‰ä¾µç•¥æ€§ã€‚如果一个节点与“arm,amba-primecell†+兼容，那么of_platform_populate()将把它注册为amba_device而ä¸æ˜¯ +platform_device。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index a34e58733ac8..88d8df957a78 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -5,7 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginSC + \kerneldocBeginSC{ .. _linux_doc_zh: @@ -23,6 +23,11 @@ å¦å¤–，éšæ—¶æ¬¢è¿Žæ‚¨å¯¹å†…æ ¸æ–‡æ¡£è¿›è¡Œæ”¹è¿›ï¼›å¦‚æžœæ‚¨æƒ³æä¾›å¸®åŠ©ï¼Œè¯·åŠ å…¥vger.kernel.org 上的linux-doc邮件列表。 +顺便说下，ä¸æ–‡æ–‡æ¡£ä¹Ÿéœ€è¦éµå®ˆå†…æ ¸ç¼–ç é£Žæ ¼ï¼Œé£Žæ ¼ä¸ä¸æ–‡å’Œè‹±æ–‡çš„主è¦ä¸åŒå°±æ˜¯ä¸æ–‡ +çš„å—ç¬¦æ ‡ç‚¹å 用两个英文å—符宽度， 所以，当英文è¦æ±‚ä¸è¦è¶…过æ¯è¡Œ100个å—符时， +ä¸æ–‡å°±ä¸è¦è¶…过50个å—符。å¦å¤–，也è¦æ³¨æ„'-'，'=' ç‰ç¬¦å·ä¸Žç›¸å…³æ ‡é¢˜çš„对é½ã€‚在将 +è¡¥ä¸æ交到社区之å‰ï¼Œä¸€å®šè¦è¿›è¡Œå¿…è¦çš„checkpatch.pl检查和编译测试。 + 许å¯è¯æ–‡æ¡£ ---------- @@ -51,10 +56,14 @@ TODOList: 下列文档æè¿°äº†å†…æ ¸éœ€è¦çš„å¹³å°å›ºä»¶ç›¸å…³ä¿¡æ¯ã€‚ +.. toctree:: + :maxdepth: 2 + + devicetree/index + TODOList: * firmware-guide/index -* devicetree/index 应用程åºå¼€å‘人员文档 -------------------- @@ -99,13 +108,17 @@ TODOList: :maxdepth: 2 core-api/index + accounting/index cpu-freq/index iio/index + infiniband/index + power/index + virt/index sound/index filesystems/index - virt/index - infiniband/index - accounting/index + scheduler/index + vm/index + peci/index TODOList: @@ -123,7 +136,6 @@ TODOList: * netlabel/index * networking/index * pcmcia/index -* power/index * target/index * timers/index * spi/index @@ -134,13 +146,11 @@ TODOList: * gpu/index * security/index * crypto/index -* vm/index * bpf/index * usb/index * PCI/index * scsi/index * misc-devices/index -* scheduler/index * mhi/index ä½“ç³»ç»“æž„æ— å…³æ–‡æ¡£ @@ -193,4 +203,4 @@ TODOList: .. raw:: latex - \kerneldocEndSC + }\kerneldocEndSC diff --git a/Documentation/translations/zh_CN/peci/index.rst b/Documentation/translations/zh_CN/peci/index.rst new file mode 100644 index 000000000000..4f6694c828fa --- /dev/null +++ b/Documentation/translations/zh_CN/peci/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/peci/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +================= +Linux PECI å系统 +================= + +.. toctree:: + + + peci + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/peci/peci.rst b/Documentation/translations/zh_CN/peci/peci.rst new file mode 100644 index 000000000000..a3b4f99b994c --- /dev/null +++ b/Documentation/translations/zh_CN/peci/peci.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/peci/peci.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +==== +概述 +==== + +å¹³å°çŽ¯å¢ƒæŽ§åˆ¶æŽ¥å£ï¼ˆPECI）是英特尔处ç†å™¨å’Œç®¡ç†æŽ§åˆ¶å™¨ï¼ˆå¦‚底æ¿ç®¡ç†æŽ§åˆ¶å™¨ï¼ŒBMC） +之间的一个通信接å£ã€‚PECIæ供的æœåŠ¡å…许管ç†æŽ§åˆ¶å™¨é€šè¿‡è®¿é—®å„ç§å¯„å˜å™¨æ¥é…ç½®ã€ç›‘ +控和调试平å°ã€‚它定义了一个专门的命令å议，管ç†æŽ§åˆ¶å™¨ä½œä¸ºPECIçš„å‘起者，处ç†å™¨ +作为PECIçš„å“应者。PECIå¯ä»¥ç”¨äºŽåŸºäºŽå•å¤„ç†å™¨å’Œå¤šå¤„ç†å™¨çš„系统ä¸ã€‚ + +注æ„：英特尔PECI规范没有作为专门的文件å‘布，而是作为英特尔CPU的外部设计规范 +（EDS）的一部分。外部设计规范通常是ä¸å…¬å¼€çš„。 + +PECI 线 +--------- + +PECI线接å£ä½¿ç”¨å•çº¿è¿›è¡Œè‡ªé”和数æ®ä¼ 输。它ä¸éœ€è¦ä»»ä½•é¢å¤–的控制线--物ç†å±‚是一个 +自é”çš„å•çº¿æ€»çº¿ä¿¡å·ï¼Œæ¯ä¸€ä¸ªæ¯”特都从接近零ä¼çš„空闲状æ€å¼€å§‹é©±åŠ¨ã€ä¸Šå‡è¾¹ç¼˜ã€‚驱动高 +电平信å·çš„æŒç»æ—¶é—´å¯ä»¥ç¡®å®šä½å€¼æ˜¯é€»è¾‘ “0†还是逻辑 “1â€ã€‚PECI线还包括与æ¯ä¸ªä¿¡ +æ¯å»ºç«‹çš„å¯å˜æ•°æ®é€ŸçŽ‡ã€‚ + +对于PECI线，æ¯ä¸ªå¤„ç†å™¨åŒ…将在一个定义的范围内利用唯一的ã€å›ºå®šçš„地å€ï¼Œè¯¥åœ°å€åº” +该与处ç†å™¨æ’座ID有固定的关系--如果其ä¸ä¸€ä¸ªå¤„ç†å™¨è¢«ç§»é™¤ï¼Œå®ƒä¸ä¼šå½±å“其余处ç†å™¨ +的地å€ã€‚ + +PECIå系统代ç 内嵌文档 +------------------------ + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/peci.h + +drivers/peci/internal.h + +drivers/peci/core.c + +drivers/peci/request.c + +PECI CPU 驱动 API +------------------- + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/peci/cpu.c diff --git a/Documentation/translations/zh_CN/power/energy-model.rst b/Documentation/translations/zh_CN/power/energy-model.rst new file mode 100644 index 000000000000..c7da1b6aefee --- /dev/null +++ b/Documentation/translations/zh_CN/power/energy-model.rst @@ -0,0 +1,190 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/energy-model.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============ +设备能é‡æ¨¡åž‹ +============ + +1. 概述 +------- + +能é‡æ¨¡åž‹ï¼ˆEM）框架是一ç§é©±åŠ¨ç¨‹åºä¸Žå†…æ ¸å系统之间的接å£ã€‚å…¶ä¸é©±åŠ¨ç¨‹åºäº†è§£ä¸åŒ +æ€§èƒ½å±‚çº§çš„è®¾å¤‡æ‰€æ¶ˆè€—çš„åŠŸçŽ‡ï¼Œè€Œå†…æ ¸å系统愿æ„使用该信æ¯åšå‡ºèƒ½é‡æ„ŸçŸ¥å†³ç–。 + +设备所消耗的功率的信æ¯æ¥æºåœ¨ä¸åŒçš„å¹³å°ä¸Šå¯èƒ½æœ‰å¾ˆå¤§çš„ä¸åŒã€‚这些功率æˆæœ¬åœ¨æŸäº› +情况下å¯ä»¥ä½¿ç”¨è®¾å¤‡æ ‘æ•°æ®æ¥ä¼°ç®—。在其它情况下，固件会更清楚。或者，用户空间å¯èƒ½ +是最清楚的。以æ¤ç±»æŽ¨ã€‚为了é¿å…æ¯ä¸€ä¸ªå®¢æˆ·ç«¯å系统对æ¯ä¸€ç§å¯èƒ½çš„ä¿¡æ¯æºè‡ªå·±é‡æ–° +实现支æŒï¼ŒEMæ¡†æž¶ä½œä¸ºä¸€ä¸ªæŠ½è±¡å±‚ä»‹å…¥ï¼Œå®ƒåœ¨å†…æ ¸ä¸å¯¹åŠŸçŽ‡æˆæœ¬è¡¨çš„æ ¼å¼è¿›è¡Œæ ‡å‡†åŒ–， +å› æ¤èƒ½å¤Ÿé¿å…多余的工作。 + +功率值å¯ä»¥ç”¨æ¯«ç“¦æˆ–“抽象刻度â€è¡¨ç¤ºã€‚多个å系统å¯èƒ½ä½¿ç”¨EM，由系统集æˆå•†æ¥æ£€æŸ¥ +功率值刻度类型的è¦æ±‚是å¦æ»¡è¶³ã€‚å¯ä»¥åœ¨èƒ½é‡æ„ŸçŸ¥è°ƒåº¦å™¨çš„文档ä¸æ‰¾åˆ°ä¸€ä¸ªä¾‹å +Documentation/scheduler/sched-energy.rst。对于一些å系统，比如çƒèƒ½æˆ– +powercap，用“抽象刻度â€æ述功率值å¯èƒ½ä¼šå¯¼è‡´é—®é¢˜ã€‚这些å系统对过去使用的功率的 +ä¼°ç®—å€¼æ›´æ„Ÿå…´è¶£ï¼Œå› æ¤å¯èƒ½éœ€è¦çœŸå®žçš„毫瓦。这些è¦æ±‚的一个例åå¯ä»¥åœ¨æ™ºèƒ½åŠŸçŽ‡åˆ†é… +Documentation/driver-api/thermal/power_allocator.rst文档ä¸æ‰¾åˆ°ã€‚ + +å†…æ ¸å系统å¯èƒ½ï¼ˆåŸºäºŽEMå†…éƒ¨æ ‡å¿—ä½ï¼‰å®žçŽ°äº†å¯¹EM注册设备是å¦å…·æœ‰ä¸ä¸€è‡´åˆ»åº¦çš„自动 +检查。è¦è®°ä½çš„é‡è¦äº‹æƒ…是，当功率值以“抽象刻度â€è¡¨ç¤ºæ—¶ï¼Œä»Žä¸æŽ¨å¯¼ä»¥æ¯«ç„¦è€³ä¸ºå•ä½ +的真实能é‡æ¶ˆè€—是ä¸å¯èƒ½çš„。 + +下图æ述了一个驱动的例å（这里是针对Arm的，但该方法适用于任何体系结构），它 +å‘EM框架æ供了功率æˆæœ¬ï¼Œæ„Ÿå…´è¶£çš„客户端å¯ä»Žä¸è¯»å–æ•°æ®:: + + +---------------+ +-----------------+ +---------------+ + | Thermal (IPA) | | Scheduler (EAS) | | Other | + +---------------+ +-----------------+ +---------------+ + | | em_cpu_energy() | + | | em_cpu_get() | + +---------+ | +---------+ + | | | + v v v + +---------------------+ + | Energy Model | + | Framework | + +---------------------+ + ^ ^ ^ + | | | em_dev_register_perf_domain() + +----------+ | +---------+ + | | | + +---------------+ +---------------+ +--------------+ + | cpufreq-dt | | arm_scmi | | Other | + +---------------+ +---------------+ +--------------+ + ^ ^ ^ + | | | + +--------------+ +---------------+ +--------------+ + | Device Tree | | Firmware | | ? | + +--------------+ +---------------+ +--------------+ + +对于CPU设备，EM框架管ç†ç€ç³»ç»Ÿä¸æ¯ä¸ªâ€œæ€§èƒ½åŸŸâ€çš„功率æˆæœ¬è¡¨ã€‚一个性能域是一组 +性能一起伸缩的CPU。性能域通常与CPUFreqç–略具有1对1æ˜ å°„ã€‚ä¸€ä¸ªæ€§èƒ½åŸŸä¸çš„ +所有CPUè¦æ±‚具有相åŒçš„微架构。ä¸åŒæ€§èƒ½åŸŸä¸çš„CPUå¯ä»¥æœ‰ä¸åŒçš„微架构。 + + +2. æ ¸å¿ƒAPI +---------- + +2.1 é…置选项 +^^^^^^^^^^^^ + +必须使能CONFIG_ENERGY_MODELæ‰èƒ½ä½¿ç”¨EM框架。 + + +2.2 性能域的注册 +^^^^^^^^^^^^^^^^ + +“高级â€EM的注册 +~~~~~~~~~~~~~~~~ + +“高级â€EMå› å®ƒå…许驱动æ供更精确的功率模型而得å。它并ä¸å—é™äºŽæ¡†æž¶ä¸çš„一些已 +实现的数å¦å…¬å¼ï¼ˆå°±åƒâ€œç®€å•â€EMé‚£æ ·ï¼‰ã€‚å®ƒå¯ä»¥æ›´å¥½åœ°åæ˜ æ¯ä¸ªæ€§èƒ½çŠ¶æ€çš„实际功率 +测é‡ã€‚å› æ¤ï¼Œåœ¨EMé™æ€åŠŸçŽ‡ï¼ˆæ¼ç”µæµåŠŸçŽ‡ï¼‰æ˜¯é‡è¦çš„情况下，应该首选这ç§æ³¨å†Œæ–¹å¼ã€‚ + +驱动程åºåº”通过以下API将性能域注册到EM框架ä¸:: + + int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, + struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + +驱动程åºå¿…é¡»æ供一个回调函数，为æ¯ä¸ªæ€§èƒ½çŠ¶æ€è¿”回<频率,功率>å…ƒç»„ã€‚é©±åŠ¨ç¨‹åº +æ供的回调函数å¯ä»¥è‡ªç”±åœ°ä»Žä»»ä½•ç›¸å…³ä½ç½®ï¼ˆDTã€å›ºä»¶......）以åŠä»¥ä»»ä½•è¢«è®¤ä¸ºæ˜¯ +å¿…è¦çš„æ–¹å¼èŽ·å–æ•°æ®ã€‚åªæœ‰å¯¹äºŽCPU设备，驱动程åºå¿…须使用cpumask指定性能域的CPU。 +对于CPU以外的其他设备，最åŽä¸€ä¸ªå‚数必须被设置为NULL。 + +最åŽä¸€ä¸ªå‚数“milliwattsâ€ï¼ˆæ¯«ç“¦ï¼‰è®¾ç½®æˆæ£ç¡®çš„值是很é‡è¦çš„，使用EMçš„å†…æ ¸ +å系统å¯èƒ½ä¼šä¾èµ–è¿™ä¸ªæ ‡å¿—æ¥æ£€æŸ¥æ‰€æœ‰çš„EM设备是å¦ä½¿ç”¨ç›¸åŒçš„刻度。如果有ä¸åŒçš„ +刻度，这些å系统å¯èƒ½å†³å®šï¼šè¿”回è¦å‘Š/错误，åœæ¢å·¥ä½œæˆ–崩溃（panic）。 + +关于实现这个回调函数的驱动程åºçš„例å，å‚è§ç¬¬3节。或者在第2.4节阅读这个API +的更多文档。 + + +“简å•â€EM的注册 +~~~~~~~~~~~~~~~~ + +“简å•â€EM是用框架的辅助函数cpufreq_register_em_with_opp()注册的。它实现了 +一个和以下数å¦å…¬å¼ç´§å¯†ç›¸å…³çš„功率模型:: + + Power = C * V^2 * f + +使用这ç§æ–¹æ³•æ³¨å†Œçš„EMå¯èƒ½æ— 法æ£ç¡®åæ˜ çœŸå®žè®¾å¤‡çš„ç‰©ç†ç‰¹æ€§ï¼Œä¾‹å¦‚当é™æ€åŠŸçŽ‡ +（æ¼ç”µæµåŠŸçŽ‡ï¼‰å¾ˆé‡è¦æ—¶ã€‚ + + +2.3 访问性能域 +^^^^^^^^^^^^^^ + +有两个API函数æ供对能é‡æ¨¡åž‹çš„访问。em_cpu_get()以CPU id为å‚数，em_pd_get() +以设备指针为å‚数。使用哪个接å£å–决于å系统，但对于CPU设备æ¥è¯´ï¼Œè¿™ä¸¤ä¸ªå‡½æ•°éƒ½è¿” +回相åŒçš„性能域。 + +对CPU的能é‡æ¨¡åž‹æ„Ÿå…´è¶£çš„å系统å¯ä»¥é€šè¿‡em_cpu_get() API检索它。在创建性能域时 +分é…一次能é‡æ¨¡åž‹è¡¨ï¼Œå®ƒä¿å˜åœ¨å†…å˜ä¸ä¸è¢«ä¿®æ”¹ã€‚ + +一个性能域所消耗的能é‡å¯ä»¥ä½¿ç”¨em_cpu_energy() APIæ¥ä¼°ç®—。该估算å‡å®šCPU设备 +使用的CPUfreq监管器是schedutil。当å‰è¯¥è®¡ç®—ä¸èƒ½æ供给其它类型的设备。 + +关于上述API的更多细节å¯ä»¥åœ¨ ``<linux/energy_model.h>`` 或第2.4节ä¸æ‰¾åˆ°ã€‚ + + +2.4 API的细节æè¿° +^^^^^^^^^^^^^^^^^ +å‚è§ include/linux/energy_model.h å’Œ kernel/power/energy_model.c çš„kernel doc。 + +3. 驱动示例 +----------- + +CPUFreq框架支æŒä¸“用的回调函数，用于为指定的CPU（们）注册EM： +cpufreq_driver::register_em()。这个回调必须为æ¯ä¸ªç‰¹å®šçš„驱动程åºæ£ç¡®å®žçŽ°ï¼Œ +å› ä¸ºæ¡†æž¶ä¼šåœ¨è®¾ç½®è¿‡ç¨‹ä¸é€‚时地调用它。本节æ供了一个简å•çš„例å，展示CPUFreq驱动 +在能é‡æ¨¡åž‹æ¡†æž¶ä¸ä½¿ç”¨ï¼ˆå‡çš„）“fooâ€å议注册性能域。该驱动实现了一个est_power() +函数æ供给EM框架:: + + -> drivers/cpufreq/foo_cpufreq.c + + 01 static int est_power(unsigned long *mW, unsigned long *KHz, + 02 struct device *dev) + 03 { + 04 long freq, power; + 05 + 06 /* 使用“fooâ€åè®®è®¾ç½®é¢‘çŽ‡ä¸Šé™ */ + 07 freq = foo_get_freq_ceil(dev, *KHz); + 08 if (freq < 0); + 09 return freq; + 10 + 11 /* 估算相关频率下设备的功率æˆæœ¬ */ + 12 power = foo_estimate_power(dev, freq); + 13 if (power < 0); + 14 return power; + 15 + 16 /* 将这些值返回给EM框架 */ + 17 *mW = power; + 18 *KHz = freq; + 19 + 20 return 0; + 21 } + 22 + 23 static void foo_cpufreq_register_em(struct cpufreq_policy *policy) + 24 { + 25 struct em_data_callback em_cb = EM_DATA_CB(est_power); + 26 struct device *cpu_dev; + 27 int nr_opp; + 28 + 29 cpu_dev = get_cpu_device(cpumask_first(policy->cpus)); + 30 + 31 /* 查找该ç–略支æŒçš„OPPæ•°é‡ */ + 32 nr_opp = foo_get_nr_opp(policy); + 33 + 34 /* 并注册新的性能域 */ + 35 em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus, + 36 true); + 37 } + 38 + 39 static struct cpufreq_driver foo_cpufreq_driver = { + 40 .register_em = foo_cpufreq_register_em, + 41 }; diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst new file mode 100644 index 000000000000..bc54983ba515 --- /dev/null +++ b/Documentation/translations/zh_CN/power/index.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/index.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +======== +电æºç®¡ç† +======== + +.. toctree:: + :maxdepth: 1 + + energy-model + opp + +TODOList: + + * apm-acpi + * basic-pm-debugging + * charger-manager + * drivers-testing + * freezing-of-tasks + * pci + * pm_qos_interface + * power_supply_class + * runtime_pm + * s2ram + * suspend-and-cpuhotplug + * suspend-and-interrupts + * swsusp-and-swap-files + * swsusp-dmcrypt + * swsusp + * video + * tricks + + * userland-swsusp + + * powercap/powercap + * powercap/dtpm + + * regulator/consumer + * regulator/design + * regulator/machine + * regulator/overview + * regulator/regulator + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/power/opp.rst b/Documentation/translations/zh_CN/power/opp.rst new file mode 100644 index 000000000000..8d6e3f6f6202 --- /dev/null +++ b/Documentation/translations/zh_CN/power/opp.rst @@ -0,0 +1,341 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/opp.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +====================== +æ“作性能值（OPP）库 +====================== + +(C) 2009-2010 Nishanth Menon <nm@ti.com>, å¾·å·žä»ªå™¨å…¬å¸ + +.. 目录 + + 1. 简介 + 2. OPP链表åˆå§‹æ³¨å†Œ + 3. OPPæœç´¢å‡½æ•° + 4. OPPå¯ç”¨æ€§æŽ§åˆ¶å‡½æ•° + 5. OPPæ•°æ®æ£€ç´¢å‡½æ•° + 6. æ•°æ®ç»“æž„ + +1. 简介 +======= + +1.1 何为æ“作性能值（OPP）？ +------------------------------ + +当今å¤æ‚çš„å•ç‰‡ç³»ç»Ÿï¼ˆSoC）由多个å模å—组æˆï¼Œè¿™äº›å模å—会è”åˆå·¥ä½œã€‚在一个执行ä¸åŒç”¨ä¾‹ +çš„æ“作系统ä¸ï¼Œå¹¶ä¸æ˜¯SoCä¸çš„所有模å—都需è¦ä¸€ç›´ä»¥æœ€é«˜é¢‘率工作。为了促æˆè¿™ä¸€ç‚¹ï¼ŒSoCä¸ +çš„å模å—被分组为ä¸åŒåŸŸï¼Œå…许一些域以较低的电压和频率è¿è¡Œï¼Œè€Œå…¶å®ƒåŸŸåˆ™ä»¥è¾ƒé«˜çš„“电压/ +频率对â€è¿è¡Œã€‚ + +设备按域支æŒçš„由频率电压对组æˆçš„离散的元组的集åˆï¼Œè¢«ç§°ä¸ºæ“作性能值（组），或OPPs。 + +举例æ¥è¯´ï¼š + +让我们考虑一个支æŒä¸‹è¿°é¢‘率ã€ç”µåŽ‹å€¼çš„内å˜ä¿æŠ¤å•å…ƒï¼ˆMPU）设备： +{300MHz，最低电压为1V}, {800MHz，最低电压为1.2V}, {1GHz，最低电压为1.3V} + +我们能将它们表示为3个OPP，如下述{Hz, uV}元组（译注：频率的å•ä½æ˜¯èµ«å…¹ï¼Œç”µåŽ‹çš„å•ä½æ˜¯ +å¾®ä¼ï¼‰ã€‚ + +- {300000000, 1000000} +- {800000000, 1200000} +- {1000000000, 1300000} + +1.2 æ“作性能值库 +---------------- + +OPP库æ供了一组辅助函数æ¥ç»„织和查询OPPä¿¡æ¯ã€‚该库ä½äºŽdrivers/opp/目录下，其头文件 +ä½äºŽinclude/linux/pm_opp.hä¸ã€‚OPP库å¯ä»¥é€šè¿‡å¼€å¯CONFIG_PM_OPPæ¥å¯ç”¨ã€‚æŸäº›SoC， +如德州仪器的OMAP框架å…许在ä¸éœ€è¦cpufreq的情况下å¯é€‰åœ°åœ¨æŸä¸€OPP下å¯åŠ¨ã€‚ + +OPP库的典型用法如下:: + + （用户） -> 注册一个默认的OPPé›†åˆ -> （库） + （SoC框架） -> 在必è¦çš„情况下，对æŸäº›OPP进行修改 -> OPP layer + -> æœç´¢/检索信æ¯çš„查询 -> + +OPP层期望æ¯ä¸ªåŸŸç”±ä¸€ä¸ªå”¯ä¸€çš„设备指针æ¥è¡¨ç¤ºã€‚SoC框架在OPP层为æ¯ä¸ªè®¾å¤‡æ³¨å†Œäº†ä¸€ç»„åˆå§‹ +OPP。这个链表的长度被期望是一个最优化的å°æ•°å—，通常æ¯ä¸ªè®¾å¤‡å¤§çº¦5个。åˆå§‹é“¾è¡¨åŒ…å«äº† +一个OPP集åˆï¼Œè¿™ä¸ªé›†åˆè¢«æœŸæœ›èƒ½åœ¨ç³»ç»Ÿä¸å®‰å…¨ä½¿èƒ½ã€‚ + +关于OPPå¯ç”¨æ€§çš„说明 +^^^^^^^^^^^^^^^^^^^ + +éšç€ç³»ç»Ÿçš„è¿è¡Œï¼ŒSoC框架å¯èƒ½ä¼šåŸºäºŽå„ç§å¤–éƒ¨å› ç´ é€‰æ‹©è®©æŸäº›OPP在æ¯ä¸ªè®¾å¤‡ä¸Šå¯ç”¨æˆ–ä¸å¯ç”¨ï¼Œ +示例：温度管ç†æˆ–其它异常场景ä¸ï¼ŒSoC框架å¯èƒ½ä¼šé€‰æ‹©ç¦ç”¨ä¸€ä¸ªè¾ƒé«˜é¢‘率的OPPä»¥å®‰å…¨åœ°ç»§ç» +è¿è¡Œï¼Œç›´åˆ°è¯¥OPP被é‡æ–°å¯ç”¨ï¼ˆå¦‚æžœå¯èƒ½ï¼‰ã€‚ + +OPP库在它的实现ä¸è¾¾æˆäº†è¿™ä¸ªæ¦‚念。以下æ“作函数åªèƒ½å¯¹å¯ç”¨çš„OPP使用： +dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, +dev_pm_opp_get_freq, dev_pm_opp_get_opp_count。 + +dev_pm_opp_find_freq_exact是用æ¥æŸ¥æ‰¾OPP指针的，该指针å¯è¢«ç”¨åœ¨dev_pm_opp_enable/ +disable函数，使一个OPP在被需è¦æ—¶å˜ä¸ºå¯ç”¨ã€‚ + +è¦å‘Šï¼šå¦‚果对一个设备调用dev_pm_opp_enable/disable函数，OPP库的用户应该使用 +dev_pm_opp_get_opp_countæ¥åˆ·æ–°OPPçš„å¯ç”¨æ€§è®¡æ•°ã€‚触å‘这些的具体机制，或者对有ä¾èµ–çš„ +å系统（比如cpufreq）的通知机制，都是由使用OPP库的SoC特定框架酌情处ç†çš„。在这些æ“作 +ä¸ï¼ŒåŒæ ·éœ€è¦æ³¨æ„刷新cpufreq表。 + +2. OPP链表åˆå§‹æ³¨å†Œ +================== +SoC的实现会è¿ä»£è°ƒç”¨dev_pm_opp_add函数æ¥å¢žåŠ æ¯ä¸ªè®¾å¤‡çš„OPP。预期SoC框架将以最优的 +æ–¹å¼æ³¨å†ŒOPPæ¡ç›® - 典型的数å—范围å°äºŽ5。通过注册OPP生æˆçš„OPP链表，在整个设备è¿è¡Œè¿‡ç¨‹ +ä¸ç”±OPP库维护。SoC框架éšåŽå¯ä»¥ä½¿ç”¨dev_pm_opp_enable / disable函数动æ€åœ° +控制OPPçš„å¯ç”¨æ€§ã€‚ + +dev_pm_opp_add + 为设备指针所指å‘çš„ç‰¹å®šåŸŸæ·»åŠ ä¸€ä¸ªæ–°çš„OPP。OPPæ˜¯ç”¨é¢‘çŽ‡å’Œç”µåŽ‹å®šä¹‰çš„ã€‚ä¸€æ—¦å®Œæˆ + æ·»åŠ ï¼ŒOPP被认为是å¯ç”¨çš„，å¯ä»¥ç”¨dev_pm_opp_enable/disable函数æ¥æŽ§åˆ¶å…¶å¯ç”¨æ€§ã€‚ + OPP库内部用dev_pm_opp结构体å˜å‚¨å¹¶ç®¡ç†è¿™äº›ä¿¡æ¯ã€‚这个函数å¯ä»¥è¢«SoCæ¡†æž¶æ ¹æ®SoC + 的使用环境的需求æ¥å®šä¹‰ä¸€ä¸ªæœ€ä¼˜é“¾è¡¨ã€‚ + + è¦å‘Šï¼š + ä¸è¦åœ¨ä¸æ–上下文使用这个函数。 + + 示例:: + + soc_pm_init() + { + /* åšä¸€äº›äº‹æƒ… */ + r = dev_pm_opp_add(mpu_dev, 1000000, 900000); + if (!r) { + pr_err("%s: unable to register mpu opp(%d)\n", r); + goto no_cpufreq; + } + /* åšä¸€äº›å’Œcpufreq相关的事情 */ + no_cpufreq: + /* åšå‰©ä½™çš„事情 */ + } + +3. OPPæœç´¢å‡½æ•° +============== +cpufreqç‰é«˜å±‚框架对频率进行æ“ä½œï¼Œä¸ºäº†å°†é¢‘çŽ‡æ˜ å°„åˆ°ç›¸åº”çš„OPP，OPP库æ供了便利的函数 +æ¥æœç´¢OPP库内部管ç†çš„OPP链表。这些æœç´¢å‡½æ•°å¦‚果找到匹é…çš„OPP，将返回指å‘该OPP的指针， +å¦åˆ™è¿”å›žé”™è¯¯ã€‚è¿™äº›é”™è¯¯é¢„è®¡ç”±æ ‡å‡†çš„é”™è¯¯æ£€æŸ¥ï¼Œå¦‚IS_ERR()æ¥å¤„ç†ï¼Œå¹¶ç”±è°ƒç”¨è€…采å–适当的 +行动。 + +这些函数的调用者应在使用完OPPåŽè°ƒç”¨dev_pm_opp_put()。å¦åˆ™ï¼ŒOPP的内å˜å°†æ°¸è¿œä¸ä¼š +被释放，并导致内å˜æ³„露。 + +dev_pm_opp_find_freq_exact + æ ¹æ® *精确的* 频率和å¯ç”¨æ€§æ¥æœç´¢OPP。这个函数对默认ä¸å¯ç”¨çš„OPP特别有用。 + 例å：在SoC框架检测到更高频率å¯ç”¨çš„情况下，它å¯ä»¥ä½¿ç”¨è¿™ä¸ªå‡½æ•°åœ¨è°ƒç”¨ + dev_pm_opp_enable之å‰æ‰¾åˆ°OPP:: + + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); + dev_pm_opp_put(opp); + /* ä¸è¦æ“作指针.. åªæ˜¯åšæœ‰æ•ˆæ€§æ£€æŸ¥.. */ + if (IS_ERR(opp)) { + pr_err("frequency not disabled!\n"); + /* 触å‘åˆé€‚çš„æ“作.. */ + } else { + dev_pm_opp_enable(dev,1000000000); + } + + 注æ„： + 这是唯一一个å¯ä»¥æœç´¢ä¸å¯ç”¨OPP的函数。 + +dev_pm_opp_find_freq_floor + æœç´¢ä¸€ä¸ª *最多* æ供指定频率的å¯ç”¨OPP。这个函数在æœç´¢è¾ƒå°çš„匹é…或按频率 + 递å‡çš„顺åºæ“作OPPä¿¡æ¯æ—¶å¾ˆæœ‰ç”¨ã€‚ + 例å：è¦æ‰¾çš„一个设备的最高OPP:: + + freq = ULONG_MAX; + opp = dev_pm_opp_find_freq_floor(dev, &freq); + dev_pm_opp_put(opp); + +dev_pm_opp_find_freq_ceil + æœç´¢ä¸€ä¸ª *最少* æ供指定频率的å¯ç”¨OPP。这个函数在æœç´¢è¾ƒå¤§çš„匹é…或按频率 + 递增的顺åºæ“作OPPä¿¡æ¯æ—¶å¾ˆæœ‰ç”¨ã€‚ + 例1：找到一个设备最å°çš„OPP:: + + freq = 0; + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + dev_pm_opp_put(opp); + + 例: 一个SoCçš„cpufreq_driver->target的简易实现:: + + soc_cpufreq_target(..) + { + /* åšç–略检查ç‰æ“作 */ + /* 找到和请求最接近的频率 */ + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + dev_pm_opp_put(opp); + if (!IS_ERR(opp)) + soc_switch_to_freq_voltage(freq); + else + /* 当ä¸èƒ½æ»¡è¶³è¯·æ±‚时，è¦åšçš„事 */ + /* åšå…¶å®ƒäº‹ */ + } + +4. OPPå¯ç”¨æ€§æŽ§åˆ¶å‡½æ•° +==================== +在OPP库ä¸æ³¨å†Œçš„默认OPPé“¾è¡¨ä¹Ÿè®¸æ— æ³•æ»¡è¶³æ‰€æœ‰å¯èƒ½çš„场景。OPP库æ供了一套函数æ¥ä¿®æ”¹ +OPP链表ä¸çš„æŸä¸ªOPPçš„å¯ç”¨æ€§ã€‚这使得SoC框架能够精细地动æ€æŽ§åˆ¶å“ªä¸€ç»„OPP是å¯ç”¨äºŽæ“作 +的。设计这些函数的目的是在诸如考虑温度时 *暂时地* åˆ é™¤æŸä¸ªOPPï¼ˆä¾‹å¦‚ï¼Œåœ¨æ¸©åº¦ä¸‹é™ +之å‰ä¸è¦ä½¿ç”¨æŸOPP）。 + +è¦å‘Šï¼š + ä¸è¦åœ¨ä¸æ–上下文使用这些函数。 + +dev_pm_opp_enable + 使一个OPPå¯ç”¨äºŽæ“作。 + 例å：å‡è®¾1GHzçš„OPPåªæœ‰åœ¨SoC温度低于æŸä¸ªé˜ˆå€¼æ—¶æ‰å¯ç”¨ã€‚SoC框架的实现å¯èƒ½ + 会选择åšä»¥ä¸‹äº‹æƒ…:: + + if (cur_temp < temp_low_thresh) { + /* è‹¥1GHz未使能，则使能 */ + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); + dev_pm_opp_put(opp); + /* 仅仅是错误检查 */ + if (!IS_ERR(opp)) + ret = dev_pm_opp_enable(dev, 1000000000); + else + goto try_something_else; + } + +dev_pm_opp_disable + 使一个OPPä¸å¯ç”¨äºŽæ“作。 + 例å：å‡è®¾1GHzçš„OPPåªæœ‰åœ¨SoC温度高于æŸä¸ªé˜ˆå€¼æ—¶æ‰å¯ç”¨ã€‚SoC框架的实现å¯èƒ½ + 会选择åšä»¥ä¸‹äº‹æƒ…:: + + if (cur_temp > temp_high_thresh) { + /* è‹¥1GHzå·²ä½¿èƒ½ï¼Œåˆ™å…³é— */ + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true); + dev_pm_opp_put(opp); + /* 仅仅是错误检查 */ + if (!IS_ERR(opp)) + ret = dev_pm_opp_disable(dev, 1000000000); + else + goto try_something_else; + } + +5. OPPæ•°æ®æ£€ç´¢å‡½æ•° +================== +由于OPP库对OPPä¿¡æ¯è¿›è¡Œäº†æŠ½è±¡åŒ–处ç†ï¼Œå› æ¤éœ€è¦ä¸€ç»„函数æ¥ä»Ždev_pm_opp结构体ä¸æå– +ä¿¡æ¯ã€‚一旦使用æœç´¢å‡½æ•°æ£€ç´¢åˆ°ä¸€ä¸ªOPP指针，以下函数就å¯ä»¥è¢«SoC框架用æ¥æ£€ç´¢OPP层 +内部æè¿°çš„ä¿¡æ¯ã€‚ + +dev_pm_opp_get_voltage + 检索OPP指针æ述的电压。 + 例å: 当cpufreq切æ¢åˆ°åˆ°ä¸åŒé¢‘率时，SoC框架需è¦ç”¨ç¨³åŽ‹å™¨æ¡†æž¶å°†OPPæè¿° + 的电压设置到æ供电压的电æºç®¡ç†èŠ¯ç‰‡ä¸:: + + soc_switch_to_freq_voltage(freq) + { + /* åšä¸€äº›äº‹æƒ… */ + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + v = dev_pm_opp_get_voltage(opp); + dev_pm_opp_put(opp); + if (v) + regulator_set_voltage(.., v); + /* åšå…¶å®ƒäº‹ */ + } + +dev_pm_opp_get_freq + 检索OPP指针æ述的频率。 + 例å：比方说，SoCæ¡†æž¶ä½¿ç”¨äº†å‡ ä¸ªè¾…åŠ©å‡½æ•°ï¼Œé€šè¿‡è¿™äº›å‡½æ•°ï¼Œæˆ‘ä»¬å¯ä»¥å°†OPP + æŒ‡é’ˆä¼ å…¥ï¼Œè€Œä¸æ˜¯ä¼ å…¥é¢å¤–çš„å‚数，用æ¥å¤„ç†ä¸€ç³»åˆ—æ•°æ®å‚æ•°:: + + soc_cpufreq_target(..) + { + /* åšä¸€äº›äº‹æƒ….. */ + max_freq = ULONG_MAX; + max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq); + requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq); + if (!IS_ERR(max_opp) && !IS_ERR(requested_opp)) + r = soc_test_validity(max_opp, requested_opp); + dev_pm_opp_put(max_opp); + dev_pm_opp_put(requested_opp); + /* åšå…¶å®ƒäº‹ */ + } + soc_test_validity(..) + { + if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp)) + return -EINVAL; + if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp)) + return -EINVAL; + /* åšä¸€äº›äº‹æƒ….. */ + } + +dev_pm_opp_get_opp_count + 检索æŸä¸ªè®¾å¤‡å¯ç”¨çš„OPPæ•°é‡ã€‚ + 例å：å‡è®¾SoCä¸çš„一个å处ç†å™¨éœ€è¦çŸ¥é“æŸä¸ªè¡¨ä¸çš„å¯ç”¨é¢‘率，主处ç†å™¨å¯ä»¥ + 按如下方å¼å‘出通知:: + + soc_notify_coproc_available_frequencies() + { + /* åšä¸€äº›äº‹æƒ… */ + num_available = dev_pm_opp_get_opp_count(dev); + speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); + /* 按å‡åºå¡«å……表 */ + freq = 0; + while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { + speeds[i] = freq; + freq++; + i++; + dev_pm_opp_put(opp); + } + + soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available); + /* åšå…¶å®ƒäº‹ */ + } + +6. æ•°æ®ç»“æž„ +=========== +通常，一个SoC包å«å¤šä¸ªå¯å˜ç”µåŽ‹åŸŸã€‚æ¯ä¸ªåŸŸç”±ä¸€ä¸ªè®¾å¤‡æŒ‡é’ˆæ述。和OPP之间的关系å¯ä»¥ +按以下方å¼æè¿°:: + + SoC + |- device 1 + | |- opp 1 (availability, freq, voltage) + | |- opp 2 .. + ... ... + | `- opp n .. + |- device 2 + ... + `- device m + +OPP库维护ç€ä¸€ä¸ªå†…部链表，SoC框架使用上文æè¿°çš„å„个函数æ¥å¡«å……和访问。然而，æè¿° +真实OPP和域的结构体是OPP库自身的内部组æˆï¼Œä»¥å…许åˆé€‚的抽象在ä¸åŒç³»ç»Ÿä¸å¾—到å¤ç”¨ã€‚ + +struct dev_pm_opp + OPP库的内部数æ®ç»“构，用于表示一个OPP。除了频率ã€ç”µåŽ‹ã€å¯ç”¨æ€§ä¿¡æ¯å¤–， + 它还包å«OPP库è¿è¡Œæ‰€éœ€çš„内部统计信æ¯ã€‚指å‘这个结构体的指针被æ供给 + 用户（比如SoC框架）使用，在与OPP层的交互ä¸ä½œä¸ºOPPçš„æ ‡è¯†ç¬¦ã€‚ + + è¦å‘Šï¼š + 结构体dev_pm_opp的指针ä¸åº”该由用户解æžæˆ–修改。一个实例的默认值由 + dev_pm_opp_add填充，但OPPçš„å¯ç”¨æ€§ç”±dev_pm_opp_enable/disable函数 + 修改。 + +struct device + 这用于å‘OPPå±‚æ ‡è¯†ä¸€ä¸ªåŸŸã€‚è®¾å¤‡çš„æ€§è´¨å’Œå®ƒçš„å®žçŽ°æ˜¯ç”±OPP库的用户决定的， + 如SoC框架。 + +总体æ¥è¯´ï¼Œä»¥ä¸€ä¸ªç®€åŒ–的视角看，对数æ®ç»“æž„çš„æ“作å¯ä»¥æ述为下é¢å„图:: + + åˆå§‹åŒ– / 修改: + +-----+ /- dev_pm_opp_enable + dev_pm_opp_add --> | opp | <------- + | +-----+ \- dev_pm_opp_disable + \-------> domain_info(device) + + æœç´¢å‡½æ•°: + /-- dev_pm_opp_find_freq_ceil ---\ +-----+ + domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | + \-- dev_pm_opp_find_freq_floor ---/ +-----+ + + 检索函数: + +-----+ /- dev_pm_opp_get_voltage + | opp | <--- + +-----+ \- dev_pm_opp_get_freq + + domain_info <- dev_pm_opp_get_opp_count diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 3f1683cd4727..a9570165582a 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -254,29 +254,6 @@ Linus Torvalds 是决定改动能å¦è¿›å…¥ Linux å†…æ ¸çš„æœ€ç»ˆè£å†³è€…。他ç 手册页补ä¸ï¼Œæˆ–至少å‘é€æ›´æ”¹é€šçŸ¥ï¼Œä»¥ä¾¿ä¸€äº›ä¿¡æ¯è¿›å…¥æ‰‹å†Œé¡µã€‚还应将用户空间API 更改å¤åˆ¶åˆ° linux-api@vger.kernel.org。 -对于å°çš„è¡¥ä¸ï¼Œä½ 也许会CC到æœé›†ç碎补ä¸çš„邮件列表(Trivial Patch Monkey) -trivial@kernel.org，那里专门收集ç碎的补ä¸ã€‚下é¢è¿™æ ·çš„è¡¥ä¸ä¼šè¢«çœ‹ä½œâ€œç碎的†-è¡¥ä¸ï¼š - - - 文档的拼写修æ£ã€‚ - - ä¿®æ£ä¼šå½±å“到 grep(1) 的拼写。 - - è¦å‘Šä¿¡æ¯ä¿®æ£(频ç¹çš„打å°æ— 用的è¦å‘Šæ˜¯ä¸å¥½çš„。) - - 编译错误修æ£ï¼ˆä»£ç 逻辑的确是对的，åªæ˜¯ç¼–译有问题。） - - è¿è¡Œæ—¶ä¿®æ£ï¼ˆåªè¦çœŸçš„ä¿®æ£äº†é”™è¯¯ã€‚） - - 移除使用了被废弃的函数/å®çš„代ç (例如 check_region。) - - è”系方å¼å’Œæ–‡æ¡£ä¿®æ£ã€‚ - - 用å¯ç§»æ¤çš„代ç 替æ¢ä¸å¯ç§»æ¤çš„代ç （å³ä½¿åœ¨ä½“系结构相关的代ç ä¸ï¼Œæ—¢ç„¶æœ‰ - - 人拷è´ï¼Œåªè¦å®ƒæ˜¯ç碎的） - - 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在é‡ä¼ 模å¼ä¸‹ï¼‰ - -(译注，关于“ç碎补ä¸â€çš„ä¸€äº›è¯´æ˜Žï¼šå› ä¸ºåŽŸæ–‡çš„è¿™ä¸€éƒ¨åˆ†å†™å¾—æ¯”è¾ƒç®€å•ï¼Œæ‰€ä»¥ä¸å¾—ä¸ -è¿ä¾‹å†™ä¸€ä¸‹è¯‘注。"trivial"这个英文å•è¯çš„本æ„是“ç碎的，ä¸é‡è¦çš„。â€ä½†æ˜¯åœ¨è¿™é‡Œ -有ç¨å¾®æœ‰ä¸€äº›å˜åŒ–，例如对一些明显的NULL指针的修æ£ï¼Œå±žäºŽè¿è¡Œæ—¶ä¿®æ£ï¼Œä¼šè¢«å½’ç±» -到ç碎补ä¸é‡Œã€‚虽然NULL指针的修æ£å¾ˆé‡è¦ï¼Œä½†æ˜¯è¿™æ ·çš„ä¿®æ£å¾€å¾€å¾ˆå°è€Œä¸”很容易得到 -检验，所以也被归入ç碎补ä¸ã€‚ç碎补ä¸æ›´ç²¾ç¡®çš„归类应该是 -“simple, localized & easy to verifyâ€ï¼Œä¹Ÿå°±æ˜¯è¯´ç®€å•çš„，局部的和易于检验的。 -trivial@kernel.orgé‚®ä»¶åˆ—è¡¨çš„ç›®çš„æ˜¯é’ˆå¯¹è¿™æ ·çš„è¡¥ä¸ï¼Œä¸ºæ交者æ供一个ä¸å¿ƒï¼Œæ¥ -é™ä½Žæ交的门槛。) 6) 没有 MIME ç¼–ç ，没有链接，没有压缩，没有附件，åªæœ‰çº¯æ–‡æœ¬ ----------------------------------------------------------- diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst index bbf5d7b3777a..614cde0c0997 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -18,6 +18,7 @@ RISC-V 体系结构 :maxdepth: 1 boot-image-header + vm-layout pmu patch-acceptance diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/riscv/vm-layout.rst new file mode 100644 index 000000000000..585cb89317a3 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/vm-layout.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/riscv/vm-layout.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +============================ +RISC-V Linux上的虚拟内å˜å¸ƒå±€ +============================ + +:作者: Alexandre Ghiti <alex@ghiti.fr> +:日期: 12 February 2021 + +这份文件æ述了RISC-V Linuxå†…æ ¸ä½¿ç”¨çš„è™šæ‹Ÿå†…å˜å¸ƒå±€ã€‚ + +32ä½ RISC-V Linux å†…æ ¸ +====================== + +RISC-V Linux Kernel SV32 +------------------------ + +TODO + +64ä½ RISC-V Linux å†…æ ¸ +====================== + +RISC-V特æƒæž¶æž„文档指出，64ä½åœ°å€ "必须使第63-48ä½å€¼éƒ½ç‰äºŽç¬¬47ä½ï¼Œå¦åˆ™å°†å‘生缺页异常。"：这将虚 +拟地å€ç©ºé—´åˆ†æˆä¸¤åŠï¼Œä¸é—´æœ‰ä¸€ä¸ªéžå¸¸å¤§çš„洞，下åŠéƒ¨åˆ†æ˜¯ç”¨æˆ·ç©ºé—´æ‰€åœ¨çš„地方，上åŠéƒ¨åˆ†æ˜¯RISC-V Linux +å†…æ ¸æ‰€åœ¨çš„åœ°æ–¹ã€‚ + +RISC-V Linux Kernel SV39 +------------------------ + +:: + + ======================================================================================================================== + å¼€å§‹åœ°å€ | å移 | 结æŸåœ°å€ | å¤§å° | 虚拟内å˜åŒºåŸŸæè¿° + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 0000003fffffffff | 256 GB | 用户空间虚拟内å˜ï¼Œæ¯ä¸ªå†…å˜ç®¡ç†å™¨ä¸åŒ + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... 巨大的ã€å‡ 乎64ä½å®½çš„ç›´åˆ°å†…æ ¸æ˜ å°„çš„-256GB地方 + | | | | 开始å移的éžç»å…¸è™šæ‹Ÿå†…å˜åœ°å€ç©ºæ´žã€‚ + | | | | + __________________|____________|__________________|_________|___________________________________________________________ + | + | å†…æ ¸ç©ºé—´çš„è™šæ‹Ÿå†…å˜ï¼Œåœ¨æ‰€æœ‰è¿›ç¨‹ä¹‹é—´å…±äº«: + ____________________________________________________________|___________________________________________________________ + | | | | + ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB | fixmap + ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB | PCI io + ffffffc700000000 | -228 GB | ffffffc7ffffffff | 4 GB | vmemmap + ffffffc800000000 | -224 GB | ffffffd7ffffffff | 64 GB | vmalloc/ioremap space + ffffffd800000000 | -160 GB | fffffff6ffffffff | 124 GB | ç›´æŽ¥æ˜ å°„æ‰€æœ‰ç‰©ç†å†…å˜ + fffffff700000000 | -36 GB | fffffffeffffffff | 32 GB | kasan + __________________|____________|__________________|_________|____________________________________________________________ + | + | + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ diff --git a/Documentation/translations/zh_CN/scheduler/completion.rst b/Documentation/translations/zh_CN/scheduler/completion.rst new file mode 100644 index 000000000000..bc8218514e0a --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/completion.rst @@ -0,0 +1,256 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/completion.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +======================================= +å®Œæˆ - "ç‰å¾…完æˆ" å±éšœåº”用程åºæŽ¥å£(API) +======================================= + +简介: +----- + +å¦‚æžœä½ æœ‰ä¸€ä¸ªæˆ–å¤šä¸ªçº¿ç¨‹å¿…é¡»ç‰å¾…æŸäº›å†…æ ¸æ´»åŠ¨è¾¾åˆ°æŸä¸ªç‚¹æˆ–æŸä¸ªç‰¹å®šçš„状æ€ï¼Œå®Œæˆå¯ä»¥ä¸ºè¿™ +个问题æä¾›ä¸€ä¸ªæ— ç«žäº‰çš„è§£å†³æ–¹æ¡ˆã€‚ä»Žè¯ä¹‰ä¸Šè®²ï¼Œå®ƒä»¬æœ‰ç‚¹åƒpthread_barrier()，并且使 +用的案例类似 + +完æˆæ˜¯ä¸€ç§ä»£ç åŒæ¥æœºåˆ¶ï¼Œå®ƒæ¯”任何滥用é”/ä¿¡å·é‡å’Œå¿™ç‰å¾…循环的行为都è¦å¥½ã€‚å½“ä½ æƒ³ç”¨yield() +或一些å¤æ€ªçš„msleep(1)循环æ¥å…许其它代ç 继ç»è¿è¡Œæ—¶ï¼Œä½ å¯èƒ½æƒ³ç”¨wait_for_completion*() +调用和completion()æ¥ä»£æ›¿ã€‚ + +使用“完æˆâ€çš„好处是，它们有一个良好定义ã€èšç„¦çš„ç›®æ ‡ï¼Œè¿™ä¸ä»…使得我们很容易ç†è§£ä»£ç çš„æ„图， +而且它们也会生æˆæ›´é«˜æ•ˆçš„代ç ï¼Œå› ä¸ºæ‰€æœ‰çº¿ç¨‹éƒ½å¯ä»¥ç»§ç»æ‰§è¡Œï¼Œç›´åˆ°çœŸæ£éœ€è¦ç»“æžœçš„æ—¶åˆ»ã€‚è€Œä¸”ç‰ +待和信å·éƒ½é«˜æ•ˆçš„使用了低层调度器的ç¡çœ /唤醒设施。 + +完æˆæ˜¯å»ºç«‹åœ¨Linux调度器的ç‰å¾…队列和唤醒基础设施之上的。ç‰å¾…队列ä¸çš„线程所ç‰å¾…çš„ +事件被简化为 ``struct completion`` ä¸çš„一个简å•æ ‡å¿—，被æ°å¦‚å…¶å地称为‘done’。 + +由于完æˆä¸Žè°ƒåº¦æœ‰å…³ï¼Œä»£ç å¯ä»¥åœ¨kernel/sched/completion.cä¸æ‰¾åˆ°ã€‚ + + +用法: +----- + +使用完æˆéœ€è¦ä¸‰ä¸ªä¸»è¦éƒ¨åˆ†: + + - 'struct completion' åŒæ¥å¯¹è±¡çš„åˆå§‹åŒ– + - 通过调用wait_for_completion()的一个å˜ä½“æ¥å®žçŽ°ç‰å¾…部分。 + - 通过调用complete()或complete_all()实现å‘信端。 + +也有一些辅助函数用于检查完æˆçš„状æ€ã€‚请注æ„，虽然必须先åšåˆå§‹åŒ–，但ç‰å¾…和信å·éƒ¨åˆ†å¯ä»¥ +按任何时间顺åºå‡ºçŽ°ã€‚也就是说，一个线程在å¦ä¸€ä¸ªçº¿ç¨‹æ£€æŸ¥æ˜¯å¦éœ€è¦ç‰å¾…它之å‰ï¼Œå·²ç»å°†ä¸€ä¸ª +完æˆæ ‡è®°ä¸º "done"，这是完全æ£å¸¸çš„。 + +è¦ä½¿ç”¨å®ŒæˆAPIï¼Œä½ éœ€è¦#include <linux/completion.h>并创建一个é™æ€æˆ–动æ€çš„ +``struct completion`` 类型的å˜é‡ï¼Œå®ƒåªæœ‰ä¸¤ä¸ªå—段:: + + struct completion { + unsigned int done; + wait_queue_head_t wait; + }; + +结构体æ供了->waitç‰å¾…队列æ¥æ”¾ç½®ä»»åŠ¡è¿›è¡Œç‰å¾…（如果有的è¯ï¼‰ï¼Œä»¥åŠ->done完æˆæ ‡å¿—æ¥è¡¨æ˜Žå®ƒ +是å¦å®Œæˆã€‚ + +完æˆçš„命å应当与æ£åœ¨è¢«åŒæ¥çš„事件å一致。一个好的例å是:: + + wait_for_completion(&early_console_added); + + complete(&early_console_added); + +好的ã€ç›´è§‚的命å（一如既往地）有助于代ç çš„å¯è¯»æ€§ã€‚将一个完æˆå‘½å为 ``complete`` +是没有帮助的，除éžå…¶ç›®çš„是超级明显的... + + +åˆå§‹åŒ–完æˆ: +----------- + +动æ€åˆ†é…的完æˆå¯¹è±¡æœ€å¥½è¢«åµŒå…¥åˆ°æ•°æ®ç»“æž„ä¸ï¼Œä»¥ç¡®ä¿åœ¨å‡½æ•°/驱动的生命周期内å˜æ´»ï¼Œä»¥é˜² +æ¢ä¸Žå¼‚æ¥complete()调用å‘生竞争。 + +在使用wait_for_completion()çš„_timeout()或_killable()/_interruptible()å˜ä½“ +时应特别å°å¿ƒï¼Œå› 为必须ä¿è¯åœ¨æ‰€æœ‰ç›¸å…³æ´»åŠ¨ï¼ˆcomplete()或reinit_completion()）å‘生 +之å‰ä¸ä¼šå‘生内å˜è§£é™¤åˆ†é…，å³ä½¿è¿™äº›ç‰å¾…函数由于超时或信å·è§¦å‘而过早返回。 + +动æ€åˆ†é…的完æˆå¯¹è±¡çš„åˆå§‹åŒ–是通过调用init_completion()æ¥å®Œæˆçš„:: + + init_completion(&dynamic_object->done); + +在这个调用ä¸ï¼Œæˆ‘们åˆå§‹åŒ– waitqueue 并将 ->done 设置为 0，å³â€œnot completedâ€æˆ– +“not doneâ€ã€‚ + +é‡æ–°åˆå§‹åŒ–函数reinit_completion()，åªæ˜¯å°†->doneå—段é‡ç½®ä¸º0（“not doneâ€ï¼‰ï¼Œè€Œ +ä¸è§¦åŠç‰å¾…队列。这个函数的调用者必须确ä¿æ²¡æœ‰ä»»ä½•ä»¤äººè®¨åŽŒçš„wait_for_completion() +调用在并行进行。 + +在åŒä¸€ä¸ªå®Œæˆå¯¹è±¡ä¸Šè°ƒç”¨init_completion()两次很å¯èƒ½æ˜¯ä¸€ä¸ªbugï¼Œå› ä¸ºå®ƒå°†é˜Ÿåˆ—é‡æ–°åˆå§‹ +化为一个空队列，已排队的任务å¯èƒ½ä¼šâ€œä¸¢å¤±â€--在这ç§æƒ…况下使用reinit_completion()，但 +è¦æ³¨æ„其他竞争。 + +对于é™æ€å£°æ˜Žå’Œåˆå§‹åŒ–，å¯ä»¥ä½¿ç”¨å®ã€‚ + +对于文件范围内的é™æ€ï¼ˆæˆ–å…¨å±€ï¼‰å£°æ˜Žï¼Œä½ å¯ä»¥ä½¿ç”¨ DECLARE_COMPLETION():: + + static DECLARE_COMPLETION(setup_done); + DECLARE_COMPLETION(setup_done); + +注æ„，在这ç§æƒ…况下，完æˆåœ¨å¯åŠ¨æ—¶ï¼ˆæˆ–模å—åŠ è½½æ—¶ï¼‰è¢«åˆå§‹åŒ–为“not doneâ€ï¼Œä¸éœ€è¦è°ƒç”¨ +init_completion()。 + +当完æˆè¢«å£°æ˜Žä¸ºä¸€ä¸ªå‡½æ•°ä¸çš„局部å˜é‡æ—¶ï¼Œé‚£ä¹ˆåº”该总是明确地使用 +DECLARE_COMPLETION_ONSTACK()æ¥åˆå§‹åŒ–，这ä¸ä»…仅是为了让lockdepæ£ç¡®è¿è¡Œï¼Œä¹Ÿæ˜¯æ˜Žç¡®è¡¨ +å它有é™çš„使用范围是有æ„为之并被仔细考虑的:: + + DECLARE_COMPLETION_ONSTACK(setup_done) + +请注æ„，当使用完æˆå¯¹è±¡ä½œä¸ºå±€éƒ¨å˜é‡æ—¶ï¼Œä½ å¿…é¡»æ•é”地æ„è¯†åˆ°å‡½æ•°å †æ ˆçš„çŸæš‚生命期：在所有 +活动（如ç‰å¾…的线程）åœæ¢å¹¶ä¸”完æˆå¯¹è±¡å®Œå…¨æœªè¢«ä½¿ç”¨ä¹‹å‰ï¼Œå‡½æ•°ä¸å¾—返回到调用上下文。 + +å†æ¬¡å¼ºè°ƒè¿™ä¸€ç‚¹ï¼šç‰¹åˆ«æ˜¯åœ¨ä½¿ç”¨ä¸€äº›å…·æœ‰æ›´å¤æ‚结果的ç‰å¾…APIå˜ä½“æ—¶ï¼Œæ¯”å¦‚è¶…æ—¶æˆ–ä¿¡å· +（_timeout(), _killable()å’Œ_interruptible()）å˜ä½“，ç‰å¾…å¯èƒ½ä¼šæå‰å®Œæˆï¼Œè€Œå¯¹è±¡å¯ +能ä»åœ¨è¢«å…¶ä»–线程使用 - 从wait_on_completion*()调用者函数的返回会å–消分é…å‡½æ•°æ ˆï¼Œå¦‚ +æžœcomplete()在其它æŸçº¿ç¨‹ä¸å®Œæˆè°ƒç”¨ï¼Œä¼šå¼•èµ·å¾®å°çš„æ•°æ®æŸå。简å•çš„测试å¯èƒ½ä¸ä¼šè§¦å‘è¿™ +些类型的竞争。 + +如果ä¸ç¡®å®šçš„è¯ï¼Œä½¿ç”¨åŠ¨æ€åˆ†é…的完æˆå¯¹è±¡ï¼Œ 最好是嵌入到其它一些生命周期长的对象ä¸ï¼Œé•¿åˆ° +超过使用完æˆå¯¹è±¡çš„任何辅助线程的生命周期，或者有一个é”或其他åŒæ¥æœºåˆ¶æ¥ç¡®ä¿complete() +ä¸ä¼šåœ¨ä¸€ä¸ªè¢«é‡Šæ”¾çš„对象ä¸è°ƒç”¨ã€‚ + +åœ¨å †æ ˆä¸Šå•çº¯åœ°è°ƒç”¨DECLARE_COMPLETION()会触å‘一个lockdepè¦å‘Šã€‚ + +ç‰å¾…完æˆ: +--------- + +对于一个线程æ¥è¯´ï¼Œè¦ç‰å¾…一些并å‘活动的完æˆï¼Œå®ƒè¦åœ¨åˆå§‹åŒ–的完æˆç»“构体上调用 +wait_for_completion():: + + void wait_for_completion(struct completion *done) + +一个典型的使用场景是:: + + CPU#1 CPU#2 + + struct completion setup_done; + + init_completion(&setup_done); + initialize_work(...,&setup_done,...); + + /* run non-dependent code */ /* do setup */ + + wait_for_completion(&setup_done); complete(setup_done); + +这并ä¸æ„味ç€è°ƒç”¨wait_for_completion()å’Œcomplete()有任何特定的时间顺åº--如果调 +用complete()å‘生在调用wait_for_completion()之å‰ï¼Œé‚£ä¹ˆç‰å¾…方将立å³ç»§ç»æ‰§è¡Œï¼Œå› 为 +所有的ä¾èµ–都得到了满足；如果没有，它将阻塞，直到complete()å‘出完æˆçš„ä¿¡å·ã€‚ + +注æ„，wait_for_completion()是在调用spin_lock_irq()/spin_unlock_irq()，所以 +åªæœ‰å½“ä½ çŸ¥é“ä¸æ–被å¯ç”¨æ—¶æ‰èƒ½å®‰å…¨åœ°è°ƒç”¨å®ƒã€‚从IRQs-off的原å上下文ä¸è°ƒç”¨å®ƒå°†å¯¼è‡´éš¾ä»¥æ£€ +测的错误的ä¸æ–å¯ç”¨ã€‚ + +默认行为是ä¸å¸¦è¶…时的ç‰å¾…ï¼Œå¹¶å°†ä»»åŠ¡æ ‡è®°ä¸ºâ€œUNINTERRUPTIBLEâ€çŠ¶æ€ã€‚wait_for_completion() +åŠå…¶å˜ä½“åªæœ‰åœ¨è¿›ç¨‹ä¸Šä¸‹æ–‡ä¸æ‰æ˜¯å®‰å…¨çš„ï¼ˆå› ä¸ºå®ƒä»¬å¯ä»¥ä¼‘çœ ï¼‰ï¼Œä½†åœ¨åŽŸå上下文ã€ä¸æ–上下文ã€IRQ +被ç¦ç”¨æˆ–抢å 被ç¦ç”¨çš„情况下是ä¸å®‰å…¨çš„--关于在原å/ä¸æ–上下文ä¸å¤„ç†å®Œæˆçš„问题，还请看下é¢çš„ +try_wait_for_completion()。 + +由于wait_for_completion()的所有å˜ä½“都å¯èƒ½ï¼ˆå¾ˆæ˜Žæ˜¾ï¼‰é˜»å¡žå¾ˆé•¿æ—¶é—´ï¼Œè¿™å–å†³äºŽå®ƒä»¬æ‰€ç‰ +å¾…çš„æ´»åŠ¨çš„æ€§è´¨ï¼Œæ‰€ä»¥åœ¨å¤§å¤šæ•°æƒ…å†µä¸‹ï¼Œä½ å¯èƒ½ä¸æƒ³åœ¨æŒæœ‰mutexé”的情况下调用它。 + + +wait_for_completion*()å¯ç”¨çš„å˜ä½“: +--------------------------------- + +下é¢çš„å˜ä½“都会返回状æ€ï¼Œåœ¨å¤§å¤šæ•°(/所有)情况下都应该检查这个状æ€--在故æ„ä¸æ£€æŸ¥çŠ¶æ€çš„情 +å†µä¸‹ï¼Œä½ å¯èƒ½è¦åšä¸€ä¸ªè¯´æ˜Ž(例如，è§arch/arm/kernel/smp.c:__cpu_up())。 + +一个常è§çš„问题是ä¸å‡†ç¡®çš„返回类型赋值，所以è¦æ³¨æ„将返回值赋值给适当类型的å˜é‡ã€‚ + +检查返回值的具体å«ä¹‰ä¹Ÿå¯èƒ½è¢«å‘现是相当ä¸å‡†ç¡®çš„，例如，åƒè¿™æ ·çš„æž„é€ :: + + if (!wait_for_completion_interruptible_timeout(...)) + +...会在æˆåŠŸå®Œæˆå’Œä¸æ–的情况下执行相åŒçš„代ç 路径--è¿™å¯èƒ½ä¸æ˜¯ä½ 想è¦çš„结果:: + + int wait_for_completion_interruptible(struct completion *done) + +这个函数在任务ç‰å¾…æ—¶æ ‡è®°ä¸ºTASK_INTERRUPTIBLE。如果在ç‰å¾…期间收到信å·ï¼Œå®ƒå°†è¿”回 +-ERESTARTSYSï¼›å¦åˆ™ä¸º0:: + + unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout) + +è¯¥ä»»åŠ¡è¢«æ ‡è®°ä¸ºTASK_UNINTERRUPTIBLE，并将最多超时ç‰å¾…“timeoutâ€ä¸ªjiffies。如果超时å‘生，则 +返回0，å¦åˆ™è¿”回剩余的时间（但至少是1）。 + +超时最好用msecs_to_jiffies()或usecs_to_jiffies()计算，以使代ç 在很大程度上ä¸å— +HZçš„å½±å“。 + +如果返回的超时值被故æ„å¿½ç•¥ï¼Œé‚£ä¹ˆæ³¨é‡Šåº”è¯¥è§£é‡ŠåŽŸå› +（例如，è§drivers/mfd/wm8350-core.c wm8350_read_auxadc():: + + long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout) + +è¿™ä¸ªå‡½æ•°ä¼ é€’ä¸€ä¸ªä»¥jiffies为å•ä½çš„è¶…æ—¶ï¼Œå¹¶å°†ä»»åŠ¡æ ‡è®°ä¸ºTASK_INTERRUPTIBLE。如果收到 +ä¿¡å·ï¼Œåˆ™è¿”回-ERESTARTSYSï¼›å¦åˆ™ï¼Œå¦‚果完æˆè¶…时，则返回0；如果完æˆäº†ï¼Œåˆ™è¿”回剩余的时间 +（jiffies）。 + +更多的å˜ä½“包括_killable，它使用TASK_KILLABLE作为指定的任务状æ€ï¼Œå¦‚果它被ä¸æ–，将返 +回-ERESTARTSYS，如果完æˆäº†ï¼Œåˆ™è¿”回0。它也有一个_timeoutå˜ä½“:: + + long wait_for_completion_killable(struct completion *done) + long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout) + +wait_for_completion_io()çš„_ioå˜ä½“的行为与éž_ioå˜ä½“相åŒï¼Œåªæ˜¯å°†ç‰å¾…时间计为“IOç‰å¾…â€ï¼Œ +这对任务在调度/IO统计ä¸çš„计算方å¼æœ‰å½±å“:: + + void wait_for_completion_io(struct completion *done) + unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout) + + +对完æˆå‘ä¿¡å·: +------------- + +一个线程想è¦å‘出信å·é€šçŸ¥ç»§ç»çš„æ¡ä»¶å·²ç»è¾¾åˆ°ï¼Œå°±ä¼šè°ƒç”¨complete()，å‘å…¶ä¸ä¸€ä¸ªç‰å¾…者å‘出信 +å·è¡¨æ˜Žå®ƒå¯ä»¥ç»§ç»:: + + void complete(struct completion *done) + +... or calls complete_all() to signal all current and future waiters:: + + void complete_all(struct completion *done) + +å³ä½¿åœ¨çº¿ç¨‹å¼€å§‹ç‰å¾…之å‰å°±å‘出了完æˆçš„ä¿¡å·ï¼Œä¿¡å·ä¼ 递也会继ç»è¿›è¡Œã€‚这是通过ç‰å¾…者 +“consumingâ€ï¼ˆé€’å‡ï¼‰â€œstruct completion†的完æˆå—段æ¥å®žçŽ°çš„。ç‰å¾…çš„çº¿ç¨‹å”¤é†’çš„é¡ºåº +与它们被排队的顺åºç›¸åŒï¼ˆFIFO顺åºï¼‰ã€‚ + +如果多次调用complete()，那么这将å…许该数é‡çš„ç‰å¾…者继ç»è¿›è¡Œ--æ¯æ¬¡è°ƒç”¨complete()å°† +简å•åœ°å¢žåŠ 已完æˆçš„å—段。但多次调用complete_all()是一个错误。complete()å’Œ +complete_all()都å¯ä»¥åœ¨IRQ/atomic上下文ä¸å®‰å…¨è°ƒç”¨ã€‚ + +在任何时候，åªèƒ½æœ‰ä¸€ä¸ªçº¿ç¨‹åœ¨ä¸€ä¸ªç‰¹å®šçš„ “struct completionâ€ä¸Šè°ƒç”¨ complete() 或 +complete_all() - 通过ç‰å¾…队列自旋é”进行åºåˆ—化。任何对 complete() 或 +complete_all() 的并å‘调用都å¯èƒ½æ˜¯ä¸€ä¸ªè®¾è®¡é”™è¯¯ã€‚ + +从IRQ上下文ä¸å‘出完æˆä¿¡å· 是å¯è¡Œçš„ï¼Œå› ä¸ºå®ƒå°†æ£ç¡®åœ°ç”¨ +spin_lock_irqsave()/spin_unlock_irqrestore()执行é”æ“作 + + +try_wait_for_completion()/completion_done(): +-------------------------------------------- + +try_wait_for_completion()函数ä¸ä¼šå°†çº¿ç¨‹æ”¾åœ¨ç‰å¾…队列ä¸ï¼Œè€Œæ˜¯åœ¨éœ€è¦æŽ’队（阻塞）线 +程时返回false，å¦åˆ™ä¼šæ¶ˆè€—一个已å‘布的完æˆå¹¶è¿”回true:: + + bool try_wait_for_completion(struct completion *done) + +最åŽï¼Œä¸ºäº†åœ¨ä¸ä»¥ä»»ä½•æ–¹å¼æ”¹å˜å®Œæˆçš„情况下检查完æˆçš„状æ€ï¼Œå¯ä»¥è°ƒç”¨completion_done()， +如果没有å‘布的完æˆå°šæœªè¢«ç‰å¾…者消耗，则返回false（æ„味ç€å˜åœ¨ç‰å¾…者），å¦åˆ™è¿”回true:: + + bool completion_done(struct completion *done) + +try_wait_for_completion()å’Œcompletion_done()都å¯ä»¥åœ¨IRQ或原å上下文ä¸å®‰å…¨è°ƒç”¨ã€‚ diff --git a/Documentation/translations/zh_CN/scheduler/index.rst b/Documentation/translations/zh_CN/scheduler/index.rst new file mode 100644 index 000000000000..12bf3bd02ccf --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/index.rst @@ -0,0 +1,43 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +:æ ¡è¯‘: + + + +=============== +Linux调度器 +=============== + +.. toctree:: + :maxdepth: 1 + + completion + sched-arch + sched-bwc + sched-design-CFS + sched-domains + sched-capacity + sched-energy + sched-nice-design + sched-stats + +TODOList: + + sched-deadline + sched-rt-group + + text_files + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/scheduler/sched-arch.rst b/Documentation/translations/zh_CN/scheduler/sched-arch.rst new file mode 100644 index 000000000000..754a15c6b60f --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-arch.rst @@ -0,0 +1,76 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-arch.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +=============================== +架构特定代ç çš„CPU调度器实现æ示 +=============================== + + Nick Piggin, 2005 + +ä¸Šä¸‹æ–‡åˆ‡æ¢ +========== +1. è¿è¡Œé˜Ÿåˆ—é” +默认情况下，switch_to arch函数在调用时é”定了è¿è¡Œé˜Ÿåˆ—。这通常ä¸æ˜¯ä¸€ä¸ªé—®é¢˜ï¼Œé™¤éž +switch_toå¯èƒ½éœ€è¦èŽ·å–è¿è¡Œé˜Ÿåˆ—é”。这通常是由于上下文切æ¢ä¸çš„唤醒æ“ä½œé€ æˆçš„ã€‚è§ +arch/ia64/include/asm/switch_to.h的例å。 + +为了è¦æ±‚调度器在è¿è¡Œé˜Ÿåˆ—解é”的情况下调用switch_toï¼Œä½ å¿…é¡»åœ¨å¤´æ–‡ä»¶ +ä¸`#define __ARCH_WANT_UNLOCKED_CTXSW`(通常是定义switch_to的那个文件）。 + +在CONFIG_SMP的情况下，解é”的上下文切æ¢å¯¹æ ¸å¿ƒè°ƒåº¦å™¨çš„实现åªå¸¦æ¥äº†éžå¸¸å°çš„æ€§èƒ½æŸ +失。 + +CPU空转 +======= +ä½ çš„cpu_idle程åºéœ€è¦éµå®ˆä»¥ä¸‹è§„则： + +1. 现在抢å 应该在空闲的例程上ç¦ç”¨ã€‚应该åªåœ¨è°ƒç”¨schedule()æ—¶å¯ç”¨ï¼Œç„¶åŽå†ç¦ç”¨ã€‚ + +2. need_resched/TIF_NEED_RESCHED åªä¼šè¢«è®¾ç½®ï¼Œå¹¶ä¸”在è¿è¡Œä»»åŠ¡è°ƒç”¨ schedule() + 之å‰æ°¸è¿œä¸ä¼šè¢«æ¸…除。空闲线程åªéœ€è¦æŸ¥è¯¢need_resched，并且永远ä¸ä¼šè®¾ç½®æˆ–清除它。 + +3. 当cpu_idleå‘现（need_resched() == 'true'），它应该调用schedule()。å¦åˆ™ + 它ä¸åº”该调用schedule()。 + +4. 在检查need_resched时，唯一需è¦ç¦ç”¨ä¸æ–的情况是，我们è¦è®©å¤„ç†å™¨ä¼‘çœ åˆ°ä¸‹ä¸€ä¸ªä¸ + æ–（这并ä¸å¯¹need_reschedæ供任何ä¿æŠ¤ï¼Œå®ƒå¯ä»¥é˜²æ¢ä¸¢å¤±ä¸€ä¸ªä¸æ–）: + + 4a. è¿™ç§ç¡çœ 类型的常è§é—®é¢˜ä¼¼ä¹Žæ˜¯:: + + local_irq_disable(); + if (!need_resched()) { + local_irq_enable(); + *** resched interrupt arrives here *** + __asm__("sleep until next interrupt"); + } + +5. 当need_reschedå˜ä¸ºé«˜ç”µå¹³æ—¶ï¼ŒTIF_POLLING_NRFLAGå¯ä»¥ç”±ä¸éœ€è¦ä¸æ–æ¥å”¤é†’它们 + 的空闲程åºè®¾ç½®ã€‚æ¢å¥è¯è¯´ï¼Œå®ƒä»¬å¿…须定期轮询need_resched，尽管åšä¸€äº›åŽå°å·¥ä½œæˆ– + 进入低CPU优先级å¯èƒ½æ˜¯åˆç†çš„。 + + - 5a. 如果TIF_POLLING_NRFLAG被设置，而我们确实决定进入一个ä¸æ–ç¡çœ ，那 + 么需è¦æ¸…除它，然åŽå‘出一个内å˜å±éšœï¼ˆæŽ¥ç€æµ‹è¯•need_resched，ç¦ç”¨ä¸æ–，如3ä¸è§£é‡Šï¼‰ã€‚ + +arch/x86/kernel/process.c有轮询和ç¡çœ 空闲函数的例å。 + + +å¯èƒ½å‡ºçŽ°çš„arch/问题 +=================== + +我å‘现的å¯èƒ½çš„arch问题（并试图解决或没有解决）。: + +ia64 - safe_halt的调用与ä¸æ–相比，是å¦å¾ˆè’谬？ (它ç¡çœ 了å—) (å‚考 #4a) + +sh64 - ç¡çœ 与ä¸æ–相比，是å¦å¾ˆè’谬？ (å‚考 #4a) + +sparc - 在这一点上，IRQ是开ç€çš„（？），把local_irq_save改为_disable。 + - 待办事项: 需è¦ç¬¬äºŒä¸ªCPUæ¥ç¦ç”¨æŠ¢å (å‚考 #1) diff --git a/Documentation/translations/zh_CN/scheduler/sched-bwc.rst b/Documentation/translations/zh_CN/scheduler/sched-bwc.rst new file mode 100644 index 000000000000..90e931f4ceed --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-bwc.rst @@ -0,0 +1,204 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-bwc.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + + +============ +CFS 带宽控制 +============ + +.. note:: + 本文åªè®¨è®ºäº†SCHED_NORMALçš„CPU带宽控制。 + SCHED_RT的情况在Documentation/scheduler/sched-rt-group.rstä¸æœ‰æ¶‰åŠã€‚ + +CFS带宽控制是一个CONFIG_FAIR_GROUP_SCHED扩展，它å…许指定一个组或层次的最大CPU带宽。 + +一个组å…许的带宽是用é…é¢å’Œå‘¨æœŸæŒ‡å®šçš„。在æ¯ä¸ªç»™å®šçš„â€å‘¨æœŸâ€œï¼ˆå¾®ç§’）内，一个任务组被分é…多 +达“é…é¢â€å¾®ç§’çš„CPU时间。当cgroupä¸çš„线程å¯è¿è¡Œæ—¶ï¼Œè¯¥é…é¢ä»¥æ—¶é—´ç‰‡æ®µçš„æ–¹å¼è¢«åˆ†é…到æ¯ä¸ªcpu +è¿è¡Œé˜Ÿåˆ—ä¸ã€‚一旦所有的é…é¢è¢«åˆ†é…，任何é¢å¤–çš„é…é¢è¯·æ±‚将导致这些线程被é™æµã€‚被é™æµçš„çº¿ç¨‹å°†ä¸ +能å†æ¬¡è¿è¡Œï¼Œç›´åˆ°ä¸‹ä¸€ä¸ªæ—¶æœŸçš„é…é¢å¾—到补充。 + +一个组的未分é…é…é¢æ˜¯å…¨å±€è·Ÿè¸ªçš„，在æ¯ä¸ªå‘¨æœŸè¾¹ç•Œè¢«åˆ·æ–°ä¸ºcfs_quotaå•å…ƒã€‚当线程消耗这个带宽时， +它以需求为基础被转移到cpu-local“ç’仓â€ï¼Œåœ¨æ¯æ¬¡æ›´æ–°ä¸è½¬ç§»çš„æ•°é‡æ˜¯å¯è°ƒæ•´çš„，被æ述为“片“（时 +间片）。 + +çªå‘特性 +-------- +现在这个功能借æ¥çš„时间是用于防范我们对未æ¥çš„ä½Žä¼°ï¼Œä»£ä»·æ˜¯å¯¹å…¶ä»–ç³»ç»Ÿç”¨æˆ·çš„å¹²æ‰°å¢žåŠ ã€‚æ‰€æœ‰è¿™äº›éƒ½ +有很好的é™åˆ¶ã€‚ + +ä¼ ç»Ÿçš„ï¼ˆUP-EDFï¼‰å¸¦å®½æŽ§åˆ¶æ˜¯è¿™æ ·çš„: + + (U = \Sum u_i) <= 1 + +这既ä¿è¯äº†æ¯ä¸ªæœ€åŽæœŸé™çš„实现，也ä¿è¯äº†ç³»ç»Ÿçš„稳定。毕竟，如果U>1，那么æ¯ä¸€ç§’é’Ÿçš„å£é’Ÿæ—¶é—´ï¼Œæˆ‘ +们就必须è¿è¡Œè¶…过一秒钟的程åºæ—¶é—´ï¼Œæ˜¾ç„¶ä¼šé”™è¿‡æˆ‘们的最åŽæœŸé™ï¼Œä½†ä¸‹ä¸€ä¸ªæœ€åŽæœŸé™ä¼šæ›´è¿œï¼Œæ°¸è¿œæ²¡æœ‰ +æ—¶é—´èµ¶ä¸Šï¼Œæ— è¾¹æ— ç•Œçš„å¤±è´¥ã€‚ + +çªå‘特性观察到工作负载并ä¸æ€»æ˜¯æ‰§è¡Œå…¨éƒ¨é…é¢ï¼›è¿™ä½¿å¾—人们å¯ä»¥å°†u_iæ述为一个统计分布。 + +例如，让u_i = {x,e}_i，其ä¸x是p(95)å’Œx+e p(100)ï¼ˆä¼ ç»Ÿçš„WCET）。这实际上å…许uæ›´å°ï¼Œæ +高了效率（我们å¯ä»¥åœ¨ç³»ç»Ÿä¸æ‰“包更多的任务），但代价是当所有的概率都一致时，会错过最åŽæœŸé™ã€‚然 +而，它确实ä¿æŒäº†ç¨³å®šæ€§ï¼Œå› 为åªè¦æˆ‘们的x高于平å‡æ°´å¹³ï¼Œæ¯ä¸€æ¬¡è¶…é™éƒ½å¿…须与低估相匹é…。 + +也就是说，å‡è®¾æˆ‘们有两个任务，都指定了一个p(95)值，那么我们有一个p(95)*p(95)=90.25%的机 +会，两个任务都在他们的é…é¢å†…，一切都很好。åŒæ—¶ï¼Œæˆ‘们有一个p(5)p(5)=0.25%çš„æœºä¼šï¼Œä¸¤ä¸ªä»»åŠ¡åŒ +时超过他们的é…é¢ï¼ˆä¿è¯æœ€åŽæœŸé™å¤±è´¥ï¼‰ã€‚在这两者之间有一个阈值，其ä¸ä¸€ä¸ªè¶…过了，而å¦ä¸€ä¸ªæ²¡æœ‰ä¸è¶³ï¼Œ +æ— æ³•è¡¥å¿ï¼›è¿™å–决于具体的CDFs。 + +åŒæ—¶ï¼Œæˆ‘们å¯ä»¥è¯´ï¼Œæœ€å的情况下的截æ¢æ—¥æœŸå¤±è´¥ï¼Œå°†æ˜¯Sum e_iï¼›ä¹Ÿå°±æ˜¯è¯´ï¼Œæœ‰ä¸€ä¸ªæœ‰ç•Œçš„è¿Ÿå»¶ï¼ˆåœ¨å‡ +设x+e确实是WCET的情况下）。 + +使用çªå‘时的干扰是由错过最åŽæœŸé™çš„å¯èƒ½æ€§å’Œå¹³å‡WCETæ¥è¯„价的。测试结果表明，当有许多cgroup或 +CPU未被充分利用时，干扰是有é™çš„。更多的细节显示在： +https://lore.kernel.org/lkml/5371BD36-55AE-4F71-B9D7-B86DC32E3D2B@linux.alibaba.com/ + +ç®¡ç† +---- +é…é¢ã€å‘¨æœŸå’Œçªå‘是在cpuå系统内通过cgroupfs管ç†çš„。 + +.. note:: + 本节æè¿°çš„cgroupfs文件åªé€‚用于cgroup v1.对于cgroup v2，请å‚阅Control Group v2。 + :ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2-cpu>`. + +- cpu.cfs_quota_us：在一个时期内补充的è¿è¡Œæ—¶é—´ï¼ˆå¾®ç§’）。 +- cpu.cfs_period_us：一个周期的长度（微秒）。 +- cpu.stat: 输出节æµç»Ÿè®¡æ•°æ®[下é¢è¿›ä¸€æ¥è§£é‡Š] +- cpu.cfs_burst_us：最大累积è¿è¡Œæ—¶é—´ï¼ˆå¾®ç§’）。 + +默认值是:: + + cpu.cfs_period_us=100ms + cpu.cfs_quota_us=-1 + cpu.cfs_burst_us=0 + +cpu.cfs_quota_us的值为-1表示该组没有任何带宽é™åˆ¶ï¼Œè¿™æ ·çš„组被æè¿°ä¸ºæ— é™åˆ¶çš„带宽组。这代表 +了CFSçš„ä¼ ç»Ÿå·¥ä½œä¿æŠ¤è¡Œä¸ºã€‚ + +写入ä¸å°äºŽcpu.cfs_burst_us的任何（有效的）æ£å€¼å°†é…å‘指定的带宽é™åˆ¶ã€‚该é…é¢æˆ–周期å…许的最 +å°é…é¢æ˜¯1ms。周期长度也有一个1s的上é™ã€‚当带宽é™åˆ¶ä»¥åˆ†å±‚æ–¹å¼ä½¿ç”¨æ—¶ï¼Œå˜åœ¨é¢å¤–çš„é™åˆ¶ï¼Œè¿™äº›åœ¨ä¸‹ +é¢æœ‰æ›´è¯¦ç»†çš„解释。 + +å‘cpu.cfs_quota_us写入任何负值都会移除带宽é™åˆ¶ï¼Œå¹¶ä½¿ç»„å†æ¬¡å›žåˆ°æ— é™åˆ¶çš„状æ€ã€‚ + +cpu.cfs_burst_us的值为0表示该组ä¸èƒ½ç§¯ç´¯ä»»ä½•æœªä½¿ç”¨çš„带宽。它使得CFSçš„ä¼ ç»Ÿå¸¦å®½æŽ§åˆ¶è¡Œä¸ºæ²¡æœ‰ +改å˜ã€‚å°†ä¸å¤§äºŽ cpu.cfs_quota_us 的任何(有效的)æ£å€¼å†™å…¥ cpu.cfs_burst_us å°†é…å‘未使用 +带宽累积的上é™ã€‚ + +如果一个组处于å—é™çŠ¶æ€ï¼Œå¯¹è¯¥ç»„å¸¦å®½è§„æ ¼çš„ä»»ä½•æ›´æ–°éƒ½å°†å¯¼è‡´å…¶æˆä¸ºæ— é™æµçŠ¶æ€ã€‚ + +系统范围设置 +------------ +为了æ高效率，è¿è¡Œæ—¶é—´åœ¨å…¨å±€æ± å’ŒCPU本地“ç’仓â€ä¹‹é—´ä»¥æ‰¹å¤„ç†æ–¹å¼è½¬ç§»ã€‚这大大å‡å°‘了大型系统的全 +å±€æ ¸ç®—åŽ‹åŠ›ã€‚æ¯æ¬¡éœ€è¦è¿›è¡Œè¿™ç§æ›´æ–°æ—¶ï¼Œä¼ 输的数é‡è¢«æ述为 "片"。 + +这是å¯ä»¥é€šè¿‡procfs调整的:: + + /proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms) + +较大的时间片段值将å‡å°‘ä¼ è¾“å¼€é”€ï¼Œè€Œè¾ƒå°çš„值则å…许更精细的消费。 + +统计 +---- +一个组的带宽统计数æ®é€šè¿‡cpu.statçš„5个å—段导出。 + +cpu.stat: + +- nr_periods：已ç»è¿‡åŽ»çš„执行间隔的数é‡ã€‚ +- nr_throttled: 该组已被节æµ/é™åˆ¶çš„次数。 +- throttled_time: 该组的实体被é™æµçš„总时间长度（纳秒）。 +- nr_bursts：çªå‘å‘生的周期数。 +- burst_time: 任何CPU在å„个时期使用超过é…é¢çš„累计å£é’Ÿæ—¶é—´ï¼ˆçº³ç§’）。 + +这个接å£æ˜¯åªè¯»çš„。 + +分层考虑 +-------- +该接å£å¼ºåˆ¶è¦æ±‚å•ä¸ªå®žä½“的带宽总是å¯ä»¥è¾¾åˆ°çš„，å³ï¼šmax(c_i) <= C。然而，在总体情况下，是明确 +å…许过度订阅的，以便在一个层次结构ä¸å®žçŽ°å·¥ä½œä¿æŠ¤è¯ä¹‰: + + 例如，Sum (c_i)å¯èƒ½è¶…过C + +[ å…¶ä¸C是父方的带宽，c_i是其å方的带宽。 ] + +.. note:: + 译文ä¸çš„父亲/å©å指的是cgroup parent, cgroup children。 + +有两ç§æ–¹å¼å¯ä»¥ä½¿ä¸€ä¸ªç»„å˜å¾—é™æµ: + + a. 它在一段时期内完全消耗自己的é…é¢ + b. 父方的é…é¢åœ¨å…¶æœŸé—´å†…全部用完 + +在上述b)情况下，å³ä½¿å©åå¯èƒ½æœ‰å‰©ä½™çš„è¿è¡Œæ—¶é—´ï¼Œå®ƒä¹Ÿä¸ä¼šè¢«å…许，直到父亲的è¿è¡Œæ—¶é—´è¢«åˆ·æ–°ã€‚ + +CFS带宽é…é¢çš„注æ„事项 +--------------------- +一旦一个片æ–被分é…给一个cpu，它就ä¸ä¼šè¿‡æœŸã€‚然而，如果该cpuä¸Šçš„æ‰€æœ‰çº¿ç¨‹éƒ½æ— æ³•è¿è¡Œï¼Œé‚£ä¹ˆé™¤äº† +1ms以外的所有时间片都å¯ä»¥è¿”å›žåˆ°å…¨å±€æ± ä¸ã€‚这是在编译时由min_cfs_rq_runtimeå˜é‡é…置的。这 +是一个性能调整，有助于防æ¢å¯¹å…¨å±€é”çš„é¢å¤–争夺。 + +cpu-local分片ä¸ä¼šè¿‡æœŸçš„事实导致了一些有趣的罕è§æ¡ˆä¾‹ï¼Œåº”该被ç†è§£ã€‚ + +对于cgroup cpué™åˆ¶çš„应用程åºæ¥è¯´ï¼Œè¿™æ˜¯ä¸€ä¸ªç›¸å¯¹æœ‰æ„ä¹‰çš„é—®é¢˜ï¼Œå› ä¸ºä»–ä»¬è‡ªç„¶ä¼šæ¶ˆè€—ä»–ä»¬çš„å…¨éƒ¨é… +é¢ï¼Œä»¥åŠæ¯ä¸ªcpu-本地片在æ¯ä¸ªæ—¶æœŸçš„å…¨éƒ¨ã€‚å› æ¤ï¼Œé¢„计nr_periods大致ç‰äºŽnr_throttled，并且 +cpuacct.用é‡çš„å¢žåŠ å¤§è‡´ç‰äºŽcfs_quota_us在æ¯ä¸ªå‘¨æœŸçš„å¢žåŠ ã€‚ + +对于高线程ã€éžcpu绑定的应用程åºï¼Œè¿™ç§éžè¿‡æœŸçš„细微差别å…许应用程åºçŸæš‚地çªç ´ä»–们的é…é¢é™åˆ¶ï¼Œ +å³ä»»åŠ¡ç»„æ£åœ¨è¿è¡Œçš„æ¯ä¸ªcpu上未使用的片æ–é‡ï¼ˆé€šå¸¸æ¯ä¸ªcpu最多1ms或由min_cfs_rq_runtime定 +义）。这ç§è½»å¾®çš„çªå‘åªé€‚用于é…é¢å·²ç»åˆ†é…ç»™cpu，然åŽæ²¡æœ‰å®Œå…¨ä½¿ç”¨æˆ–在以å‰çš„时期返回。这个çªå‘ +é‡ä¸ä¼šåœ¨æ ¸å¿ƒä¹‹é—´è½¬ç§»ã€‚å› æ¤ï¼Œè¿™ç§æœºåˆ¶ä»ç„¶ä¸¥æ ¼é™åˆ¶ä»»åŠ¡ç»„çš„é…é¢å¹³å‡ä½¿ç”¨é‡ï¼Œå°½ç®¡æ˜¯åœ¨æ¯”å•ä¸€æ—¶æœŸæ›´ +长的时间窗å£ã€‚这也é™åˆ¶äº†çªå‘能力，æ¯ä¸ªcpuä¸è¶…过1msã€‚è¿™ä¸ºåœ¨é«˜æ ¸æ•°æœºå™¨ä¸Šæœ‰å°é…é¢é™åˆ¶çš„高线程 +应用æ供了更好的更å¯é¢„测的用户体验。它还消除了在使用低于é…é¢çš„cpu时对这些应用进行节æµçš„倾å‘。 +å¦ä¸€ç§è¯´æ³•æ˜¯ï¼Œé€šè¿‡å…许一个片æ–的未使用部分在ä¸åŒæ—¶æœŸä¿æŒæœ‰æ•ˆï¼Œæˆ‘们å‡å°‘了在ä¸éœ€è¦æ•´ä¸ªç‰‡æ–çš„cpu +时间的cpu-local ç’仓上浪费é…é¢çš„å¯èƒ½æ€§ã€‚ + +绑定cpuå’Œéžç»‘定cpu的交互å¼åº”用之间的互动也应该被考虑，特别是当å•æ ¸ä½¿ç”¨çŽ‡è¾¾åˆ°100%æ—¶ã€‚å¦‚æžœä½ +给了这些应用程åºä¸€åŠçš„cpu-core，并且它们都被安排在åŒä¸€ä¸ªCPU上，ç†è®ºä¸Šéžcpu绑定的应用程åºæœ‰ +å¯èƒ½åœ¨æŸäº›æ—¶æœŸä½¿ç”¨å¤šè¾¾1msçš„é¢å¤–é…é¢ï¼Œä»Žè€Œé˜»æ¢cpu绑定的应用程åºå®Œå…¨ä½¿ç”¨å…¶é…é¢ï¼Œè¿™ä¹Ÿæ˜¯åŒæ ·çš„æ•° +é‡ã€‚在这些情况下，将由CFS算法（è§CFS调度器）æ¥å†³å®šé€‰æ‹©å“ªä¸ªåº”用程åºæ¥è¿è¡Œï¼Œå› 为它们都是å¯è¿è¡Œ +的，并且有剩余的é…é¢ã€‚这个è¿è¡Œæ—¶é—´çš„差异将在接下æ¥çš„交互å¼åº”用程åºç©ºé—²æœŸé—´å¾—到弥补。 + +例å +---- +1. é™åˆ¶ä¸€ä¸ªç»„çš„è¿è¡Œæ—¶é—´ä¸º1个CPU的价值:: + + 如果周期是250ms，é…é¢ä¹Ÿæ˜¯250ms，那么该组将æ¯250ms获得价值1个CPUçš„è¿è¡Œæ—¶é—´ã€‚ + + # echo 250000 > cpu.cfs_quota_us /* quota = 250ms */ + # echo 250000 > cpu.cfs_period_us /* period = 250ms */ + +2. 在多CPU机器上，将一个组的è¿è¡Œæ—¶é—´é™åˆ¶ä¸º2个CPU的价值 + + 在500ms周期和1000msé…é¢çš„情况下，该组æ¯500mså¯ä»¥èŽ·å¾—2个CPUçš„è¿è¡Œæ—¶é—´:: + + # echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */ + # echo 500000 > cpu.cfs_period_us /* period = 500ms */ + + 这里较大的周期å…è®¸å¢žåŠ çªå‘能力。 + +3. 将一个组é™åˆ¶åœ¨1个CPUçš„20%。 + + 在50ms周期内，10msé…é¢å°†ç›¸å½“于1个CPUçš„20%。:: + + # echo 10000 > cpu.cfs_quota_us /* quota = 10ms */ + # echo 50000 > cpu.cfs_period_us /* period = 50ms */ + + 通过在这里使用一个å°çš„周期，我们以牺牲çªå‘容é‡ä¸ºä»£ä»·æ¥ç¡®ä¿ç¨³å®šçš„延迟å“应。 + +4. 将一个组é™åˆ¶åœ¨1个CPUçš„40%，并å…许累积到1个CPUçš„20%，如果已ç»ç´¯ç§¯äº†çš„è¯ã€‚ + + 在50ms周期内，20msé…é¢å°†ç›¸å½“于1个CPUçš„40%。而10毫秒的çªå‘将相当于1个 + CPUçš„20%:: + + # echo 20000 > cpu.cfs_quota_us /* quota = 20ms */ + # echo 50000 > cpu.cfs_period_us /* period = 50ms */ + # echo 10000 > cpu.cfs_burst_us /* burst = 10ms */ + + 较大的缓冲区设置（ä¸å¤§äºŽé…é¢ï¼‰å…许更大的çªå‘容é‡ã€‚ diff --git a/Documentation/translations/zh_CN/scheduler/sched-capacity.rst b/Documentation/translations/zh_CN/scheduler/sched-capacity.rst new file mode 100644 index 000000000000..3a52053c29dc --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-capacity.rst @@ -0,0 +1,390 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-capacity.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +:æ ¡è¯‘: + + 时奎亮 Alex Shi <alexs@kernel.org> + +============= +算力感知调度 +============= + +1. CPU算力 +========== + +1.1 简介 +-------- + +一般æ¥è¯´ï¼ŒåŒæž„çš„SMPå¹³å°ç”±å®Œå…¨ç›¸åŒçš„CPUæž„æˆã€‚异构的平å°åˆ™ç”±æ€§èƒ½ç‰¹å¾ä¸åŒçš„CPUæž„æˆï¼Œåœ¨è¿™æ ·çš„ +å¹³å°ä¸ï¼ŒCPUä¸èƒ½è¢«è®¤ä¸ºæ˜¯ç›¸åŒçš„。 + +我们引入CPU算力（capacity）的概念æ¥æµ‹é‡æ¯ä¸ªCPU能达到的性能，它的值相对系统ä¸æ€§èƒ½æœ€å¼ºçš„CPU +åšè¿‡å½’一化处ç†ã€‚异构系统也被称为éžå¯¹ç§°CPUç®—åŠ›ç³»ç»Ÿï¼Œå› ä¸ºå®ƒä»¬ç”±ä¸åŒç®—力的CPU组æˆã€‚ + +最大å¯è¾¾æ€§èƒ½ï¼ˆæ¢è¨€ä¹‹ï¼Œæœ€å¤§CPU算力）的差异有两个主è¦æ¥æº: + +- ä¸æ˜¯æ‰€æœ‰CPU的微架构都相åŒã€‚ +- 在动æ€ç”µåŽ‹é¢‘率å‡é™ï¼ˆDynamic Voltage and Frequency Scaling，DVFS）框架ä¸ï¼Œä¸æ˜¯æ‰€æœ‰çš„CPU都 + èƒ½è¾¾åˆ°ä¸€æ ·é«˜çš„æ“作性能值（Operating Performance Points，OPP。译注，也就是“频率-电压â€å¯¹ï¼‰ã€‚ + +Arm大å°æ ¸ï¼ˆbig.LITTLE）系统是åŒæ—¶å…·æœ‰ä¸¤ç§å·®å¼‚的一个例å。相较å°æ ¸ï¼Œå¤§æ ¸é¢å‘性能（拥有更多的 +æµæ°´çº¿å±‚级，更大的缓å˜ï¼Œæ›´æ™ºèƒ½çš„分支预测器ç‰ï¼‰ï¼Œé€šå¸¸å¯ä»¥è¾¾åˆ°æ›´é«˜çš„æ“作性能值。 + +CPU性能通常由æ¯ç§’百万指令（Millions of Instructions Per Second，MIPS）表示，也å¯è¡¨ç¤ºä¸º +per Hz能执行的指令数，故:: + + capacity(cpu) = work_per_hz(cpu) * max_freq(cpu) + +1.2 è°ƒåº¦å™¨æœ¯è¯ +-------------- + +调度器使用了两ç§ä¸åŒçš„算力值。CPUçš„ ``capacity_orig`` 是它的最大å¯è¾¾ç®—力，å³æœ€å¤§å¯è¾¾æ€§èƒ½ç‰çº§ã€‚ +CPUçš„ ``capacity`` 是 ``capacity_orig`` 扣除了一些性能æŸå¤±ï¼ˆæ¯”如处ç†ä¸æ–的耗时）的值。 + +注æ„CPUçš„ ``capacity`` 仅仅被设计用于CFS调度类，而 ``capacity_orig`` 是ä¸æ„ŸçŸ¥è°ƒåº¦ç±»çš„。为 +简æ´èµ·è§ï¼Œæœ¬æ–‡æ¡£çš„剩余部分将ä¸åŠ åŒºåˆ†çš„ä½¿ç”¨æœ¯è¯ ``capacity`` å’Œ ``capacity_orig`` 。 + +1.3 å¹³å°ç¤ºä¾‹ +------------ + +1.3.1 æ“ä½œæ€§èƒ½å€¼ç›¸åŒ +~~~~~~~~~~~~~~~~~~~~ + +考虑一个å‡æƒ³çš„åŒæ ¸éžå¯¹ç§°CPUç®—åŠ›ç³»ç»Ÿï¼Œå…¶ä¸ + +- work_per_hz(CPU0) = W +- work_per_hz(CPU1) = W/2 +- 所有CPU以相åŒçš„固定频率è¿è¡Œ + +æ ¹æ®ä¸Šæ–‡å¯¹ç®—力的定义: + +- capacity(CPU0) = C +- capacity(CPU1) = C/2 + +若这是Arm大å°æ ¸ç³»ç»Ÿï¼Œé‚£ä¹ˆCPU0æ˜¯å¤§æ ¸ï¼Œè€ŒCPU1是å°æ ¸ã€‚ + +考虑一ç§å‘¨æœŸæ€§äº§ç”Ÿå›ºå®šå·¥ä½œé‡çš„å·¥ä½œè´Ÿè½½ï¼Œä½ å°†ä¼šå¾—åˆ°ç±»ä¼¼ä¸‹å›¾çš„æ‰§è¡Œè½¨è¿¹:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +CPU0在系统ä¸å…·æœ‰æœ€é«˜ç®—力（C），它使用T个å•ä½æ—¶é—´å®Œæˆå›ºå®šå·¥ä½œé‡W。å¦ä¸€æ–¹é¢ï¼ŒCPU1åªæœ‰CPU0ä¸€åŠ +ç®—åŠ›ï¼Œå› æ¤åœ¨T个å•ä½æ—¶é—´å†…仅完æˆå·¥ä½œé‡W/2。 + +1.3.2 最大æ“作性能值ä¸åŒ +~~~~~~~~~~~~~~~~~~~~~~~~ + +具有ä¸åŒç®—力值的CPU，通常æ¥è¯´æœ€å¤§æ“作性能值也ä¸åŒã€‚考虑上一å°èŠ‚æ到的CPU（也就是说， +work_per_hz()相åŒï¼‰: + +- max_freq(CPU0) = F +- max_freq(CPU1) = 2/3 * F + +这将推出： + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +执行1.3.1节æ述的工作负载，æ¯ä¸ªCPU按最大频率è¿è¡Œï¼Œç»“果为:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + workload on CPU1 + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +1.4 关于计算方å¼çš„注æ„事项 +-------------------------- + +需è¦æ³¨æ„的是，使用å•ä¸€å€¼æ¥è¡¨ç¤ºCPU性能的差异是有些争议的。两个ä¸åŒçš„微架构的相对性能差异应该 +æ述为：X%æ•´æ•°è¿ç®—差异，Y%浮点数è¿ç®—差异，Z%分支跳转差异，ç‰ç‰ã€‚尽管如æ¤ï¼Œä½¿ç”¨ç®€å•è®¡ç®—æ–¹å¼ +的结果目å‰è¿˜æ˜¯ä»¤äººæ»¡æ„的。 + +2. 任务使用率 +============= + +2.1 简介 +-------- + +算力感知调度è¦æ±‚æ述任务需求，æè¿°æ–¹å¼è¦å’ŒCPU算力相关。æ¯ä¸ªè°ƒåº¦ç±»å¯ä»¥ç”¨ä¸åŒçš„æ–¹å¼æ述它。 +任务使用率是CFS独有的æè¿°æ–¹å¼ï¼Œä¸è¿‡åœ¨è¿™é‡Œä»‹ç»å®ƒæœ‰åŠ©äºŽå¼•å…¥æ›´å¤šä¸€èˆ¬æ€§çš„概念。 + +任务使用率是一ç§ç”¨ç™¾åˆ†æ¯”æ¥æ述任务åžå率需求的方å¼ã€‚一个简å•çš„近似是任务的å 空比，也就是说:: + + task_util(p) = duty_cycle(p) + +在频率固定的SMP系统ä¸ï¼Œ100%的利用率æ„味ç€ä»»åŠ¡æ˜¯å¿™ç‰å¾…循环。å之，10%的利用率暗示这是一个 +å°å‘¨æœŸä»»åŠ¡ï¼Œå®ƒåœ¨ç¡çœ 上花费的时间比执行更多。 + +2.2 频率ä¸å˜æ€§ +-------------- + +一个需è¦è€ƒè™‘的议题是，工作负载的å 空比å—CPUæ£åœ¨è¿è¡Œçš„æ“作性能值直接影å“。考虑以给定的频率F +执行周期性工作负载:: + + CPU work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +å¯ä»¥ç®—出 duty_cycle(p) == 25%。 + +现在，考虑以给定频率F/2执行 *åŒä¸€ä¸ª* 工作负载:: + + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +å¯ä»¥ç®—出 duty_cycle(p) == 50%，尽管两次执行ä¸ï¼Œä»»åŠ¡çš„è¡Œä¸ºå®Œå…¨ä¸€è‡´ï¼ˆä¹Ÿå°±æ˜¯è¯´ï¼Œæ‰§è¡Œçš„å·¥ä½œé‡ +相åŒï¼‰ã€‚ + +任务利用率信å·å¯æŒ‰ä¸‹é¢å…¬å¼å¤„ç†æˆé¢‘率ä¸å˜çš„（译注：这里的术è¯ç”¨åˆ°äº†ä¿¡å·ä¸Žç³»ç»Ÿçš„概念）:: + + task_util_freq_inv(p) = duty_cycle(p) * (curr_frequency(cpu) / max_frequency(cpu)) + +对上é¢ä¸¤ä¸ªä¾‹åè¿ç”¨è¯¥å…¬å¼ï¼Œå¯ä»¥ç®—出频率ä¸å˜çš„任务利用率å‡ä¸º25%。 + +2.3 CPUä¸å˜æ€§ +------------- + +CPU算力与任务利用率具有类型的效应，在算力ä¸åŒçš„CPU上执行完全相åŒçš„工作负载，将算出ä¸åŒçš„ +å 空比。 + +考虑1.3.2节æ到的系统，也就是说:: + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +æ¯ä¸ªCPU按最大频率执行指定周期性工作负载，结果为:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +也就是说， + +- duty_cycle(p) == 25%，如果任务p在CPU0上按最大频率è¿è¡Œã€‚ +- duty_cycle(p) == 75%，如果任务p在CPU1上按最大频率è¿è¡Œã€‚ + +任务利用率信å·å¯æŒ‰ä¸‹é¢å…¬å¼å¤„ç†æˆCPU算力ä¸å˜çš„:: + + task_util_cpu_inv(p) = duty_cycle(p) * (capacity(cpu) / max_capacity) + +å…¶ä¸ ``max_capacity`` 是系统ä¸æœ€é«˜çš„CPU算力。对上é¢çš„例åè¿ç”¨è¯¥å…¬å¼ï¼Œå¯ä»¥ç®—出CPU算力ä¸å˜ +的任务利用率å‡ä¸º25%。 + +2.4 任务利用率ä¸å˜é‡ +-------------------- + +频率和CPU算力ä¸å˜æ€§éƒ½éœ€è¦è¢«åº”用到任务利用率的计算ä¸ï¼Œä»¥ä¾¿æ±‚出真æ£çš„ä¸å˜ä¿¡å·ã€‚ +任务利用率的伪计算公å¼æ˜¯åŒæ—¶å…·å¤‡CPU和频率ä¸å˜æ€§çš„，也就是说，对于指定任务p:: + + curr_frequency(cpu) capacity(cpu) + task_util_inv(p) = duty_cycle(p) * ------------------- * ------------- + max_frequency(cpu) max_capacity + +也就是说，任务利用率ä¸å˜é‡å‡å®šä»»åŠ¡åœ¨ç³»ç»Ÿä¸æœ€é«˜ç®—力CPU上以最高频率è¿è¡Œï¼Œä»¥æ¤æ述任务的行为。 + +在接下æ¥çš„ç« èŠ‚ä¸æ到的任何任务利用率，å‡æ˜¯ä¸å˜é‡çš„å½¢å¼ã€‚ + +2.5 利用率估算 +-------------- + +由于预测未æ¥çš„水晶çƒä¸å˜åœ¨ï¼Œå½“任务第一次å˜æˆå¯è¿è¡Œæ—¶ï¼Œä»»åŠ¡çš„行为和任务利用率å‡ä¸èƒ½è¢«å‡†ç¡®é¢„测。 +CFS调度类基于实体负载跟踪机制（Per-Entity Load Tracking, PELT）维护了少é‡CPU和任务信å·ï¼Œ +å…¶ä¸ä¹‹ä¸€å¯ä»¥ç®—出平å‡åˆ©ç”¨çŽ‡ï¼ˆä¸Žçž¬æ—¶ç›¸å）。 + +è¿™æ„味ç€ï¼Œå°½ç®¡è¿ç”¨â€œçœŸå®žçš„â€ä»»åŠ¡åˆ©ç”¨çŽ‡ï¼ˆå‡å€Ÿæ°´æ™¶çƒï¼‰å†™å‡ºç®—力感知调度的准则，但是它的实现将åªèƒ½ +用任务利用率的估算值。 + +3. 算力感知调度的需求 +===================== + +3.1 CPU算力 +----------- + +当å‰ï¼ŒLinuxæ— æ³•å‡è‡ªèº«ç®—出CPUç®—åŠ›ï¼Œå› æ¤å¿…é¡»è¦æœ‰æŠŠè¿™ä¸ªä¿¡æ¯ä¼ 递给Linuxçš„æ–¹å¼ã€‚æ¯ä¸ªæž¶æž„å¿…é¡»ä¸ºæ¤ +定义arch_scale_cpu_capacity()函数。 + +armå’Œarm64架构直接把这个信æ¯æ˜ 射到arch_topology驱动的CPU scalingæ•°æ®ä¸ï¼ˆè¯‘注：å‚考 +arch_topology.hçš„percpuå˜é‡cpu_scale），它是从capacity-dmips-mhz CPU bindingä¸è¡ç”Ÿè®¡ç®— +出æ¥çš„。å‚è§Documentation/devicetree/bindings/arm/cpu-capacity.txt。 + +3.2 频率ä¸å˜æ€§ +-------------- + +如2.2节所述，算力感知调度需è¦é¢‘率ä¸å˜çš„任务利用率。æ¯ä¸ªæž¶æž„必须为æ¤å®šä¹‰ +arch_scale_freq_capacity(cpu)函数。 + +实现该函数è¦æ±‚计算出æ¯ä¸ªCPU当å‰ä»¥ä»€ä¹ˆé¢‘率在è¿è¡Œã€‚实现它的一ç§æ–¹å¼æ˜¯åˆ©ç”¨ç¡¬ä»¶è®¡æ•°å™¨ï¼ˆx86çš„ +APERF/MPERF，arm64çš„AMU），它能按CPU当å‰é¢‘率动æ€å¯æ‰©å±•åœ°å‡é™é€’增计数器的速率。å¦ä¸€ç§æ–¹å¼æ˜¯ +在cpufreq频率å˜åŒ–时直接使用钩åå‡½æ•°ï¼Œå†…æ ¸æ¤æ—¶æ„ŸçŸ¥åˆ°å°†è¦è¢«åˆ‡æ¢çš„频率（也被arm/arm64实现了）。 + +4. 调度器拓扑结构 +================= + +在构建调度域时，调度器将会å‘现系统是å¦è¡¨çŽ°ä¸ºéžå¯¹ç§°CPU算力。如果是，那么： + +- sched_asym_cpucapacityé™æ€é”®ï¼ˆstatic key）将使能。 +- SD_ASYM_CPUCAPACITY_FULLæ ‡å¿—ä½å°†åœ¨å°½é‡æœ€ä½Žè°ƒåº¦åŸŸå±‚级ä¸è¢«è®¾ç½®ï¼ŒåŒæ—¶è¦æ»¡è¶³æ¡ä»¶ï¼šè°ƒåº¦åŸŸæ°å¥½ + 完整包å«æŸä¸ªCPU算力值的全部CPU。 +- SD_ASYM_CPUCAPACITYæ ‡å¿—å°†åœ¨æ‰€æœ‰åŒ…å«éžå¯¹ç§°CPU的调度域ä¸è¢«è®¾ç½®ã€‚ + +sched_asym_cpucapacityé™æ€é”®çš„设计æ„图是，ä¿æŠ¤ä¸ºéžå¯¹ç§°CPU算力系统所准备的代ç 。ä¸è¿‡è¦æ³¨æ„çš„ +是，这个键是系统范围å¯è§çš„。想象下é¢ä½¿ç”¨äº†cpusetçš„æ¥éª¤:: + + capacity C/2 C + ________ ________ + / \ / \ + CPUs 0 1 2 3 4 5 6 7 + \__/ \______________/ + cpusets cs0 cs1 + +å¯ä»¥é€šè¿‡ä¸‹é¢çš„æ–¹å¼åˆ›å»ºï¼š + +.. code-block:: sh + + mkdir /sys/fs/cgroup/cpuset/cs0 + echo 0-1 > /sys/fs/cgroup/cpuset/cs0/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs0/cpuset.mems + + mkdir /sys/fs/cgroup/cpuset/cs1 + echo 2-7 > /sys/fs/cgroup/cpuset/cs1/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs1/cpuset.mems + + echo 0 > /sys/fs/cgroup/cpuset/cpuset.sched_load_balance + +由于“这是â€éžå¯¹ç§°CPU算力系统，sched_asym_cpucapacityé™æ€é”®å°†ä½¿èƒ½ã€‚然而，CPU 0--1对应的 +调度域层级，算力值仅有一个，该层级ä¸SD_ASYM_CPUCAPACITY未被设置，它æ述的是一个SMP区域，也 +应该被以æ¤å¤„ç†ã€‚ + +å› æ¤ï¼Œâ€œå…¸åž‹çš„â€ä¿æŠ¤éžå¯¹ç§°CPU算力代ç 路径的代ç 模å¼æ˜¯ï¼š + +- 检查sched_asym_cpucapacityé™æ€é”® +- 如果它被使能，接ç€æ£€æŸ¥è°ƒåº¦åŸŸå±‚级ä¸SD_ASYM_CPUCAPACITYæ ‡å¿—ä½æ˜¯å¦å‡ºçŽ° + +5. 算力感知调度的实现 +===================== + +5.1 CFS +------- + +5.1.1 算力适应性（fitness） +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CFS最主è¦çš„算力调度准则是:: + + task_util(p) < capacity(task_cpu(p)) + +它通常被称为算力适应性准则。也就是说，CFSå¿…é¡»ä¿è¯ä»»åŠ¡â€œé€‚åˆâ€åœ¨æŸä¸ªCPU上è¿è¡Œã€‚如果准则被è¿å， +任务将è¦æ›´é•¿åœ°æ¶ˆè€—该CPU，任务是CPUå—é™çš„（CPU-bound）。 + +æ¤å¤–，uclampå…许用户空间指定任务的最å°å’Œæœ€å¤§åˆ©ç”¨çŽ‡ï¼Œè¦ä¹ˆä»¥sched_setattr()çš„æ–¹å¼ï¼Œè¦ä¹ˆä»¥ +cgroup接å£çš„æ–¹å¼ï¼ˆå‚阅Documentation/admin-guide/cgroup-v2.rst）。如其åå—所暗示，uclamp +å¯ä»¥è¢«ç”¨åœ¨å‰ä¸€æ¡å‡†åˆ™ä¸é™åˆ¶task_util()。 + +5.1.2 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +CFS任务唤醒的CPU选择，éµå¾ªä¸Šé¢æ述的算力适应性准则。在æ¤ä¹‹ä¸Šï¼Œuclamp被用æ¥é™åˆ¶ä»»åŠ¡åˆ©ç”¨çŽ‡ï¼Œ +这令用户空间对CFS任务的CPU选择有更多的控制。也就是说，CFS被唤醒任务的CPU选择，æœç´¢æ»¡è¶³ä»¥ä¸‹ +æ¡ä»¶çš„CPU:: + + clamp(task_util(p), task_uclamp_min(p), task_uclamp_max(p)) < capacity(cpu) + +通过使用uclamp，举例æ¥è¯´ï¼Œç”¨æˆ·ç©ºé—´å¯ä»¥å…许忙ç‰å¾…循环（100%使用率）在任æ„CPU上è¿è¡Œï¼Œåªè¦ç»™ +它设置低的uclamp.max值。相å，uclamp能强制一个å°çš„周期性任务（比如，10%利用率）在最高性能 +çš„CPU上è¿è¡Œï¼Œåªè¦ç»™å®ƒè®¾ç½®é«˜çš„uclamp.min值。 + +.. note:: + + CFS的被唤醒的任务的CPU选择，å¯è¢«èƒ½è€—感知调度（Energy Aware Scheduling，EAS）覆盖，在 + Documentation/scheduler/sched-energy.rstä¸æ述。 + +5.1.3 è´Ÿè½½å‡è¡¡ +~~~~~~~~~~~~~~ + +被唤醒任务的CPU选择的一个病ç†æ€§çš„例åæ˜¯ï¼Œä»»åŠ¡å‡ ä¹Žä¸ç¡çœ ï¼Œé‚£ä¹ˆä¹Ÿå‡ ä¹Žä¸å‘生唤醒。考虑:: + + w == wakeup event + + capacity(CPU0) = C + capacity(CPU1) = C / 3 + + workload on CPU0 + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + w w w + + workload on CPU1 + CPU work ^ + | ____________________________________________ + | | + +----+----+----+----+----+----+----+----+----+----+-> + w + +该工作负载应该在CPU0上è¿è¡Œï¼Œä¸è¿‡å¦‚果任务满足以下æ¡ä»¶ä¹‹ä¸€ï¼š + +- 一开始å‘生ä¸åˆé€‚的调度（ä¸å‡†ç¡®çš„åˆå§‹åˆ©ç”¨çŽ‡ä¼°è®¡ï¼‰ +- 一开始调度æ£ç¡®ï¼Œä½†çªç„¶éœ€è¦æ›´å¤šçš„处ç†å™¨åŠŸçŽ‡ + +则任务å¯èƒ½å˜ä¸ºCPUå—é™çš„，也就是说 ``task_util(p) > capacity(task_cpu(p))`` ï¼›CPU算力 +调度准则被è¿å，将ä¸ä¼šæœ‰ä»»ä½•å”¤é†’事件æ¥ä¿®å¤è¿™ä¸ªé”™è¯¯çš„CPU选择。 + +è¿™ç§åœºæ™¯ä¸‹çš„任务被称为“ä¸åˆé€‚çš„â€ï¼ˆmisfit）任务，处ç†è¿™ä¸ªåœºæ™¯çš„机制åŒæ ·ä¹Ÿä»¥æ¤å‘½å。Misfit +任务è¿ç§»å€ŸåŠ©CFSè´Ÿè½½å‡è¡¡å™¨ï¼Œæ›´æ˜Žç¡®çš„说，是主动负载å‡è¡¡çš„部分（用æ¥è¿ç§»æ£åœ¨è¿è¡Œçš„任务）。 +当å‘生负载å‡è¡¡æ—¶ï¼Œå¦‚果一个misfit任务å¯ä»¥è¢«è¿ç§»åˆ°ä¸€ä¸ªç›¸è¾ƒå½“å‰è¿è¡Œçš„CPU具有更高算力的CPU上， +那么misfit任务的主动负载å‡è¡¡å°†è¢«è§¦å‘。 + +5.2 实时调度 +------------ + +5.2.1 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +实时任务唤醒时的CPU选择，æœç´¢æ»¡è¶³ä»¥ä¸‹æ¡ä»¶çš„CPU:: + + task_uclamp_min(p) <= capacity(task_cpu(cpu)) + +åŒæ—¶ä»ç„¶å…许接ç€ä½¿ç”¨å¸¸è§„的优先级é™åˆ¶ã€‚如果没有CPUèƒ½æ»¡è¶³è¿™ä¸ªç®—åŠ›å‡†åˆ™ï¼Œé‚£ä¹ˆå°†ä½¿ç”¨åŸºäºŽä¸¥æ ¼ +优先级的调度，CPU算力将被忽略。 + +5.3 最åŽæœŸé™è°ƒåº¦ +---------------- + +5.3.1 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +最åŽæœŸé™ä»»åŠ¡å”¤é†’时的CPU选择，æœç´¢æ»¡è¶³ä»¥ä¸‹æ¡ä»¶çš„CPU:: + + task_bandwidth(p) < capacity(task_cpu(p)) + +åŒæ—¶ä»ç„¶å…许接ç€ä½¿ç”¨å¸¸è§„的带宽和截æ¢æœŸé™é™åˆ¶ã€‚如果没有CPU能满足这个算力准则，那么任务ä¾ç„¶ +在当å‰CPU队列ä¸ã€‚ diff --git a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst new file mode 100644 index 000000000000..26b0f36f793d --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-design-CFS.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +=============== +完全公平调度器 +=============== + + +1. 概述 +======= + +CFS表示“完全公平调度器â€ï¼Œå®ƒæ˜¯ä¸ºæ¡Œé¢æ–°è®¾è®¡çš„进程调度器，由Ingo Molnar实现并åˆå…¥Linux +2.6.23。它替代了之å‰åŽŸå§‹è°ƒåº¦å™¨ä¸SCHED_OTHERç–略的交互å¼ä»£ç 。 + +CFS 80%的设计å¯ä»¥æ€»ç»“为一å¥è¯ï¼šCFS在真实硬件上建模了一个“ç†æƒ³çš„，精确的多任务CPUâ€ã€‚ + +“ç†æƒ³çš„多任务CPUâ€æ˜¯ä¸€ç§ï¼ˆä¸å˜åœ¨çš„ :-)）具有100%物ç†ç®—力的CPU，它能让æ¯ä¸ªä»»åŠ¡ç²¾ç¡®åœ°ä»¥ +相åŒçš„速度并行è¿è¡Œï¼Œé€Ÿåº¦å‡ä¸º1/nr_running。举例æ¥è¯´ï¼Œå¦‚果有两个任务æ£åœ¨è¿è¡Œï¼Œé‚£ä¹ˆæ¯ä¸ª +任务获得50%物ç†ç®—力。 --- 也就是说，真æ£çš„并行。 + +在真实的硬件上，一次åªèƒ½è¿è¡Œä¸€ä¸ªä»»åŠ¡ï¼Œæ‰€ä»¥æˆ‘们需è¦ä»‹ç»â€œè™šæ‹Ÿè¿è¡Œæ—¶é—´â€çš„概念。任务的虚拟 +è¿è¡Œæ—¶é—´è¡¨æ˜Žï¼Œå®ƒçš„下一个时间片将在上文æè¿°çš„ç†æƒ³å¤šä»»åŠ¡CPU上开始执行。在实践ä¸ï¼Œä»»åŠ¡çš„ +虚拟è¿è¡Œæ—¶é—´ç”±å®ƒçš„真实è¿è¡Œæ—¶é—´ç›¸è¾ƒæ£åœ¨è¿è¡Œçš„任务总数归一化计算得到。 + + + +2. 一些实现细节 +=============== + +在CFSä¸ï¼Œè™šæ‹Ÿè¿è¡Œæ—¶é—´ç”±æ¯ä¸ªä»»åŠ¡çš„p->se.vruntime（å•ä½ä¸ºçº³ç§’ï¼‰çš„å€¼è¡¨è¾¾å’Œè·Ÿè¸ªã€‚å› æ¤ï¼Œ +精确地计时和测é‡ä¸€ä¸ªä»»åŠ¡åº”得的“预期的CPU时间â€æ˜¯å¯èƒ½çš„。 + + 一些细节：在“ç†æƒ³çš„â€ç¡¬ä»¶ä¸Šï¼Œæ‰€æœ‰çš„ä»»åŠ¡åœ¨ä»»ä½•æ—¶åˆ»éƒ½åº”è¯¥å…·æœ‰ä¸€æ ·çš„p->se.vruntime值， + --- 也就是说，任务应当åŒæ—¶æ‰§è¡Œï¼Œæ²¡æœ‰ä»»åŠ¡ä¼šåœ¨â€œç†æƒ³çš„â€CPU分时ä¸å˜å¾—“ä¸å¹³è¡¡â€ã€‚ + +CFS的任务选择逻辑基于p->se.vruntimeçš„å€¼ï¼Œå› æ¤éžå¸¸ç®€å•ï¼šæ€»æ˜¯è¯•å›¾é€‰æ‹©p->se.vruntime值 +最å°çš„任务è¿è¡Œï¼ˆä¹Ÿå°±æ˜¯è¯´ï¼Œè‡³ä»Šæ‰§è¡Œæ—¶é—´æœ€å°‘的任务）。CFS总是尽å¯èƒ½å°è¯•æŒ‰â€œç†æƒ³å¤šä»»åŠ¡ç¡¬ä»¶â€ +é‚£æ ·å°†CPU时间在å¯è¿è¡Œä»»åŠ¡ä¸å‡åˆ†ã€‚ + +CFS剩下的其它设计，一般脱离了这个简å•çš„æ¦‚å¿µï¼Œé™„åŠ çš„è®¾è®¡åŒ…æ‹¬nice级别，多处ç†ï¼Œä»¥åŠå„ç§ +用æ¥è¯†åˆ«å·²ç¡çœ 任务的算法å˜ä½“。 + + + +3. çº¢é»‘æ ‘ +========= + +CFS的设计éžå¸¸æ¿€è¿›ï¼šå®ƒä¸ä½¿ç”¨è¿è¡Œé˜Ÿåˆ—的旧数æ®ç»“构，而是使用按时间排åºçš„çº¢é»‘æ ‘ï¼Œæž„å»ºå‡º +任务未æ¥æ‰§è¡Œçš„“时间线â€ã€‚å› æ¤æ²¡æœ‰ä»»ä½•â€œæ•°ç»„切æ¢â€çš„旧包袱（之å‰çš„原始调度器和RSDL/SD都 +被它影å“）。 + +CFSåŒæ ·ç»´æŠ¤äº†rq->cfs.min_vruntime值，它是å•è°ƒé€’增的，跟踪è¿è¡Œé˜Ÿåˆ—ä¸çš„æ‰€æœ‰ä»»åŠ¡çš„æœ€å° +虚拟è¿è¡Œæ—¶é—´å€¼ã€‚系统åšçš„全部工作是：使用min_vruntime跟踪，然åŽç”¨å®ƒçš„值将新激活的调度 +实体尽å¯èƒ½åœ°æ”¾åœ¨çº¢é»‘æ ‘çš„å·¦ä¾§ã€‚ + +è¿è¡Œé˜Ÿåˆ—ä¸æ£åœ¨è¿è¡Œçš„任务的总数由rq->cfs.load计数，它是è¿è¡Œé˜Ÿåˆ—ä¸çš„任务的æƒå€¼ä¹‹å’Œã€‚ + +CFS维护了一个按时间排åºçš„çº¢é»‘æ ‘ï¼Œæ‰€æœ‰å¯è¿è¡Œä»»åŠ¡ä»¥p->se.vruntime为键值排åºã€‚CFS从这颗 +æ ‘ä¸Šé€‰æ‹©â€œæœ€å·¦ä¾§â€çš„任务并è¿è¡Œã€‚系统继ç»è¿è¡Œï¼Œè¢«æ‰§è¡Œè¿‡çš„任务越æ¥è¶Šè¢«æ”¾åˆ°æ ‘çš„å³ä¾§ --- 缓慢， +但很明确æ¯ä¸ªä»»åŠ¡éƒ½æœ‰æˆä¸ºâ€œæœ€å·¦ä¾§ä»»åŠ¡â€çš„æœºä¼šï¼Œå› æ¤ä»»åŠ¡å°†ç¡®å®šæ€§åœ°èŽ·å¾—一定é‡CPU时间。 + +总结一下，CFS工作方å¼åƒè¿™æ ·ï¼šå®ƒè¿è¡Œä¸€ä¸ªä»»åŠ¡ä¸€ä¼šå„¿ï¼Œå½“任务å‘ç”Ÿè°ƒåº¦ï¼ˆæˆ–è€…è°ƒåº¦å™¨æ—¶é’Ÿæ»´ç” +tick产生），就会考虑任务的CPU使用率：任务刚刚花在物ç†CPU上的（少é‡ï¼‰æ—¶é—´è¢«åŠ 到 +p->se.vruntime。一旦p->se.vruntimeå˜å¾—足够大，其它的任务将æˆä¸ºæŒ‰æ—¶é—´æŽ’åºçš„çº¢é»‘æ ‘çš„ +“最左侧任务â€ï¼ˆç›¸è¾ƒæœ€å·¦ä¾§çš„任务，还è¦åŠ 上一个很å°çš„“粒度â€é‡ï¼Œä½¿å¾—我们ä¸ä¼šå¯¹ä»»åŠ¡è¿‡åº¦è°ƒåº¦ï¼Œ +导致缓å˜é¢ 簸），然åŽæ–°çš„最左侧任务将被选ä¸ï¼Œå½“å‰ä»»åŠ¡è¢«æŠ¢å 。 + + + + +4. CFSçš„ä¸€äº›ç‰¹å¾ +================ + +CFS使用纳秒粒度的计时，ä¸ä¾èµ–于任何jiffies或HZçš„ç»†èŠ‚ã€‚å› æ¤CFS并ä¸åƒä¹‹å‰çš„è°ƒåº¦å™¨é‚£æ · +有“时间片â€çš„概念，也没有任何å¯å‘å¼çš„设计。唯一å¯è°ƒçš„å‚æ•°ï¼ˆä½ éœ€è¦æ‰“å¼€CONFIG_SCHED_DEBUG）是： + + /proc/sys/kernel/sched_min_granularity_ns + +它å¯ä»¥ç”¨æ¥å°†è°ƒåº¦å™¨ä»Žâ€œæ¡Œé¢â€æ¨¡å¼ï¼ˆä¹Ÿå°±æ˜¯ä½Žæ—¶å»¶ï¼‰è°ƒèŠ‚为“æœåŠ¡å™¨â€ï¼ˆä¹Ÿå°±æ˜¯é«˜æ‰¹å¤„ç†ï¼‰æ¨¡å¼ã€‚ +它的默认设置是适åˆæ¡Œé¢çš„工作负载。SCHED_BATCH也被CFS调度器模å—处ç†ã€‚ + +CFS的设计ä¸æ˜“å—到当å‰å˜åœ¨çš„任何针对stock调度器的“攻击â€çš„å½±å“，包括fiftyp.c，thud.c， +chew.c，ring-test.c，massive_intr.c，它们都能很好地è¿è¡Œï¼Œä¸ä¼šå½±å“交互性，将产生 +符åˆé¢„期的行为。 + +CFS调度器处ç†nice级别和SCHED_BATCH的能力比之å‰çš„原始调度器更强：两ç§ç±»åž‹çš„工作负载 +都被更激进地隔离了。 + +SMPè´Ÿè½½å‡è¡¡è¢«é‡åš/清ç†è¿‡ï¼šé历è¿è¡Œé˜Ÿåˆ—çš„å‡è®¾å·²ç»ä»Žè´Ÿè½½å‡è¡¡çš„代ç ä¸ç§»é™¤ï¼Œä½¿ç”¨è°ƒåº¦æ¨¡å— +çš„è¿ä»£å™¨ã€‚结果是，负载å‡è¡¡ä»£ç å˜å¾—简å•ä¸å°‘。 + + + +5. 调度ç–ç•¥ +=========== + +CFS实现了三ç§è°ƒåº¦ç–略： + + - SCHED_NORMALï¼šï¼ˆä¼ ç»Ÿè¢«ç§°ä¸ºSCHED_OTHER）：该调度ç–略用于普通任务。 + + - SCHED_BATCH：抢å ä¸åƒæ™®é€šä»»åŠ¡é‚£æ ·é¢‘ç¹ï¼Œå› æ¤å…许任务è¿è¡Œæ›´é•¿æ—¶é—´ï¼Œæ›´å¥½åœ°åˆ©ç”¨ç¼“å˜ï¼Œ + ä¸è¿‡è¦ä»¥äº¤äº’性为代价。它很适åˆæ‰¹å¤„ç†å·¥ä½œã€‚ + + - SCHED_IDLE：它比nice 19更弱，ä¸è¿‡å®ƒä¸æ˜¯çœŸæ£çš„idleå®šæ—¶å™¨è°ƒåº¦å™¨ï¼Œå› ä¸ºè¦é¿å…给机器 + 带æ¥æ»é”的优先级å转问题。 + +SCHED_FIFO/_RR被实现在sched/rt.cä¸ï¼Œå®ƒä»¬ç”±POSIX具体说明。 + +util-linux-ng 2.13.1.1ä¸çš„chrt命令å¯ä»¥è®¾ç½®ä»¥ä¸Šæ‰€æœ‰ç–略，除了SCHED_IDLE。 + + + +6. 调度类 +========= + +æ–°çš„CFS调度器被设计æˆæ”¯æŒâ€œè°ƒåº¦ç±»â€ï¼Œä¸€ç§è°ƒåº¦æ¨¡å—çš„å¯æ‰©å±•å±‚次结构。这些模å—å°è£…了调度ç–ç•¥ +ç»†èŠ‚ï¼Œç”±è°ƒåº¦å™¨æ ¸å¿ƒä»£ç 处ç†ï¼Œä¸”æ— éœ€å¯¹å®ƒä»¬åšå¤ªå¤šå‡è®¾ã€‚ + +sched/fair.c 实现了上文æè¿°çš„CFS调度器。 + +sched/rt.c 实现了SCHED_FIFOå’ŒSCHED_RRè¯ä¹‰ï¼Œä¸”比之å‰çš„原始调度器更简æ´ã€‚它使用了100个 +è¿è¡Œé˜Ÿåˆ—（总共100个实时优先级，替代了之å‰è°ƒåº¦å™¨çš„140个），且ä¸éœ€è¦è¿‡æœŸæ•°ç»„（expired +array）。 + +调度类由sched_class结构体实现，它包括一些函数钩å，当感兴趣的事件å‘生时，钩å被调用。 + +这是（部分）钩å的列表： + + - enqueue_task(...) + + 当任务进入å¯è¿è¡ŒçŠ¶æ€æ—¶ï¼Œè¢«è°ƒç”¨ã€‚å®ƒå°†è°ƒåº¦å®žä½“ï¼ˆä»»åŠ¡ï¼‰æ”¾åˆ°çº¢é»‘æ ‘ä¸ï¼Œå¢žåŠ nr_runningå˜é‡ + 的值。 + + - dequeue_task(...) + + 当任务ä¸å†å¯è¿è¡Œæ—¶ï¼Œè¿™ä¸ªå‡½æ•°è¢«è°ƒç”¨ï¼Œå¯¹åº”çš„è°ƒåº¦å®žä½“è¢«ç§»å‡ºçº¢é»‘æ ‘ã€‚å®ƒå‡å°‘nr_runningå˜é‡ + 的值。 + + - yield_task(...) + + 这个函数的行为基本上是出队，紧接ç€å…¥é˜Ÿï¼Œé™¤éžcompat_yield sysctl被开å¯ã€‚在那ç§æƒ…况下， + å®ƒå°†è°ƒåº¦å®žä½“æ”¾åœ¨çº¢é»‘æ ‘çš„æœ€å³ç«¯ã€‚ + + - check_preempt_curr(...) + + 这个函数检查进入å¯è¿è¡ŒçŠ¶æ€çš„任务能å¦æŠ¢å 当å‰æ£åœ¨è¿è¡Œçš„任务。 + + - pick_next_task(...) + + 这个函数选择接下æ¥æœ€é€‚åˆè¿è¡Œçš„任务。 + + - set_curr_task(...) + + 这个函数在任务改å˜è°ƒåº¦ç±»æˆ–改å˜ä»»åŠ¡ç»„时被调用。 + + - task_tick(...) + + 这个函数最常被时间滴ç”函数调用，它å¯èƒ½å¯¼è‡´è¿›ç¨‹åˆ‡æ¢ã€‚这驱动了è¿è¡Œæ—¶æŠ¢å 。 + + + + +7. CFS的组调度扩展 +================== + +通常，调度器æ“作粒度为任务，努力为æ¯ä¸ªä»»åŠ¡æ供公平的CPU时间。有时å¯èƒ½å¸Œæœ›å°†ä»»åŠ¡ç¼–组， +并为æ¯ä¸ªç»„æ供公平的CPU时间。举例æ¥è¯´ï¼Œå¯èƒ½é¦–先希望为系统ä¸çš„æ¯ä¸ªç”¨æˆ·æ供公平的CPU +时间，接下æ¥æ‰æ˜¯æŸä¸ªç”¨æˆ·çš„æ¯ä¸ªä»»åŠ¡ã€‚ + +CONFIG_CGROUP_SCHED 力求实现它。它将任务编组，并为这些组公平地分é…CPU时间。 + +CONFIG_RT_GROUP_SCHED å…许将实时（也就是说，SCHED_FIFOå’ŒSCHED_RR）任务编组。 + +CONFIG_FAIR_GROUP_SCHED å…许将CFS（也就是说，SCHED_NORMALå’ŒSCHED_BATCH）任务编组。 + + 这些编译选项è¦æ±‚CONFIG_CGROUPS被定义，然åŽç®¡ç†å‘˜èƒ½ä½¿ç”¨cgroup伪文件系统任æ„创建任务组。 + 关于该文件系统的更多信æ¯ï¼Œå‚è§Documentation/admin-guide/cgroup-v1/cgroups.rst + +当CONFIG_FAIR_GROUP_SCHED被定义åŽï¼Œé€šè¿‡ä¼ªæ–‡ä»¶ç³»ç»Ÿï¼Œæ¯ä¸ªç»„被创建一个“cpu.sharesâ€æ–‡ä»¶ã€‚ +å‚è§ä¸‹é¢çš„例åæ¥åˆ›å»ºä»»åŠ¡ç»„，并通过“cgroupâ€ä¼ªæ–‡ä»¶ç³»ç»Ÿä¿®æ”¹å®ƒä»¬çš„CPU份é¢:: + + # mount -t tmpfs cgroup_root /sys/fs/cgroup + # mkdir /sys/fs/cgroup/cpu + # mount -t cgroup -ocpu none /sys/fs/cgroup/cpu + # cd /sys/fs/cgroup/cpu + + # mkdir multimedia # 创建 "multimedia" 任务组 + # mkdir browser # 创建 "browser" 任务组 + + # #é…ç½®multimedia组，令其获得browser组两å€CPU带宽 + + # echo 2048 > multimedia/cpu.shares + # echo 1024 > browser/cpu.shares + + # firefox & # å¯åŠ¨firefox并把它移到 "browser" 组 + # echo <firefox_pid> > browser/tasks + + # #å¯åŠ¨gmplayerï¼ˆæˆ–è€…ä½ æœ€å–œæ¬¢çš„ç”µå½±æ’放器） + # echo <movie_player_pid> > multimedia/tasks diff --git a/Documentation/translations/zh_CN/scheduler/sched-domains.rst b/Documentation/translations/zh_CN/scheduler/sched-domains.rst new file mode 100644 index 000000000000..e814d4c01141 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-domains.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-domains.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +:æ ¡è¯‘: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +====== +调度域 +====== + +æ¯ä¸ªCPU有一个“基â€è°ƒåº¦åŸŸï¼ˆstruct sched_domain）。调度域层次结构从基调度域构建而æ¥ï¼Œå¯ +通过->parent指针自下而上é历。->parent必须以NULL结尾，调度域结构体必须是per-CPU的， +å› ä¸ºå®ƒä»¬æ— é”更新。 + +æ¯ä¸ªè°ƒåº¦åŸŸç®¡è¾–数个CPU（å˜å‚¨åœ¨->spanå—段ä¸ï¼‰ã€‚一个调度域的span必须是它的å调度域spançš„ +超集（如有需求出现，这个é™åˆ¶å¯ä»¥æ”¾å®½ï¼‰ã€‚CPU i的基调度域必须至少管辖CPU i。æ¯ä¸ªCPUçš„ +顶层调度域通常将会管辖系统ä¸çš„全部CPUï¼Œå°½ç®¡ä¸¥æ ¼æ¥è¯´è¿™ä¸æ˜¯å¿…须的，å‡å¦‚æ˜¯è¿™æ ·ï¼Œä¼šå¯¼è‡´æŸäº› +CPU出现永远ä¸ä¼šè¢«æŒ‡å®šä»»åŠ¡è¿è¡Œçš„情况，直到å…许的CPU掩ç 被显å¼è®¾å®šã€‚调度域的spanå—段æ„味 +ç€â€œåœ¨è¿™äº›CPUä¸åšè¿›ç¨‹è´Ÿè½½å‡è¡¡â€ã€‚ + +æ¯ä¸ªè°ƒåº¦åŸŸå¿…须具有一个或多个CPU调度组（struct sched_group），它们以å•å‘å¾ªçŽ¯é“¾è¡¨çš„å½¢å¼ +组织，å˜å‚¨åœ¨->groups指针ä¸ã€‚这些组的CPU掩ç 的并集必须和调度域spanå—段一致。->groups +指针指å‘的这些组包å«çš„CPU，必须被调度域管辖。组包å«çš„是åªè¯»æ•°æ®ï¼Œè¢«åˆ›å»ºä¹‹åŽï¼Œå¯èƒ½è¢«å¤šä¸ª +CPU共享。任æ„两个组的CPU掩ç 的交集ä¸ä¸€å®šä¸ºç©ºï¼Œå¦‚果是这ç§æƒ…况，对应调度域的SD_OVERLAP +æ ‡å¿—ä½è¢«è®¾ç½®ï¼Œå®ƒç®¡è¾–的调度组å¯èƒ½ä¸èƒ½åœ¨å¤šä¸ªCPUä¸å…±äº«ã€‚ + +调度域ä¸çš„è´Ÿè½½å‡è¡¡å‘生在调度组ä¸ã€‚也就是说，æ¯ä¸ªç»„被视为一个实体。组的负载被定义为它 +管辖的æ¯ä¸ªCPU的负载之和。仅当组的负载ä¸å‡è¡¡åŽï¼Œä»»åŠ¡æ‰åœ¨ç»„之间å‘生è¿ç§»ã€‚ + +在kernel/sched/core.cä¸ï¼Œtrigger_load_balance()在æ¯ä¸ªCPU上通过scheduler_tick() +周期执行。在当å‰è¿è¡Œé˜Ÿåˆ—下一个定期调度å†å¹³è¡¡äº‹ä»¶åˆ°è¾¾åŽï¼Œå®ƒå¼•å‘一个软ä¸æ–。负载å‡è¡¡çœŸæ£ +的工作由run_rebalance_domains()->rebalance_domains()完æˆï¼Œåœ¨è½¯ä¸æ–上下文ä¸æ‰§è¡Œ +（SCHED_SOFTIRQ）。 + +åŽä¸€ä¸ªå‡½æ•°æœ‰ä¸¤ä¸ªå…¥å‚：当å‰CPUçš„è¿è¡Œé˜Ÿåˆ—ã€å®ƒåœ¨scheduler_tick()调用时是å¦ç©ºé—²ã€‚函数会从 +当å‰CPU所在的基调度域开始è¿ä»£æ‰§è¡Œï¼Œå¹¶æ²¿ç€parent指针链å‘上进入更高层级的调度域。在è¿ä»£ +过程ä¸ï¼Œå‡½æ•°ä¼šæ£€æŸ¥å½“å‰è°ƒåº¦åŸŸæ˜¯å¦å·²ç»è€—尽了å†å¹³è¡¡çš„时间间隔，如果是，它在该调度域è¿è¡Œ +load_balance()。接下æ¥å®ƒæ£€æŸ¥çˆ¶è°ƒåº¦åŸŸï¼ˆå¦‚æžœå˜åœ¨ï¼‰ï¼Œå†åŽæ¥çˆ¶è°ƒåº¦åŸŸçš„父调度域，以æ¤ç±»æŽ¨ã€‚ + +èµ·åˆï¼Œload_balance()查找当å‰è°ƒåº¦åŸŸä¸æœ€ç¹å¿™çš„调度组。如果æˆåŠŸï¼Œåœ¨è¯¥è°ƒåº¦ç»„管辖的全部CPU +çš„è¿è¡Œé˜Ÿåˆ—ä¸æ‰¾å‡ºæœ€ç¹å¿™çš„è¿è¡Œé˜Ÿåˆ—。如能找到，对当å‰çš„CPUè¿è¡Œé˜Ÿåˆ—和新找到的最ç¹å¿™è¿è¡Œ +队列å‡åŠ é”，并把任务从最ç¹å¿™é˜Ÿåˆ—ä¸è¿ç§»åˆ°å½“å‰CPU上。被è¿ç§»çš„任务数é‡ç‰äºŽåœ¨å…ˆå‰è¿ä»£æ‰§è¡Œ +ä¸è®¡ç®—出的该调度域的调度组的ä¸å‡è¡¡å€¼ã€‚ + +实现调度域 +========== + +基调度域会管辖CPU层次结构ä¸çš„第一层。对于超线程（SMT）而言，基调度域将会管辖åŒä¸€ä¸ªç‰©ç† +CPU的全部虚拟CPU，æ¯ä¸ªè™šæ‹ŸCPU对应一个调度组。 + +在SMPä¸ï¼ŒåŸºè°ƒåº¦åŸŸçš„父调度域将会管辖åŒä¸€ä¸ªç»“点ä¸çš„全部物ç†CPU，æ¯ä¸ªè°ƒåº¦ç»„对应一个物ç†CPU。 +接下æ¥ï¼Œå¦‚果是éžç»Ÿä¸€å†…å˜è®¿é—®ï¼ˆNUMA）系统，SMP调度域的父调度域将管辖整个机器，一个结点的 +CPU掩ç å¯¹åº”ä¸€ä¸ªè°ƒåº¦ç»„ã€‚äº¦æˆ–ï¼Œä½ å¯ä»¥ä½¿ç”¨å¤šçº§NUMA；举例æ¥è¯´Opteron处ç†å™¨ï¼Œå¯èƒ½ä»…用一个 +调度域æ¥è¦†ç›–它的一个NUMA层级。 + +实现者需è¦é˜…读include/linux/sched/sd_flags.h的注释：读SD_*æ¥äº†è§£å…·ä½“情况以åŠè°ƒåº¦åŸŸçš„ +SDæ ‡å¿—ä½è°ƒèŠ‚了哪些东西。 + +体系结构å¯ä»¥æŠŠæŒ‡å®šçš„拓扑层级的通用调度域构建器和默认的SDæ ‡å¿—ä½è¦†ç›–掉，方法是创建一个 +sched_domain_topology_level数组，并以该数组作为入å‚调用set_sched_topology()。 + +调度域调试基础设施å¯ä»¥é€šè¿‡CONFIG_SCHED_DEBUGå¼€å¯ï¼Œå¹¶åœ¨å¼€æœºå¯åŠ¨å‘½ä»¤è¡Œä¸å¢žåŠ +“sched_verboseâ€ã€‚å¦‚æžœä½ å¿˜è®°è°ƒæ•´å¼€æœºå¯åŠ¨å‘½ä»¤è¡Œäº†ï¼Œä¹Ÿå¯ä»¥æ‰“å¼€ +/sys/kernel/debug/sched/verbose开关。这将开å¯è°ƒåº¦åŸŸé”™è¯¯æ£€æŸ¥çš„解æžï¼Œå®ƒåº”该能æ•èŽ·ï¼ˆä¸Šæ–‡ +æ述过的）ç»å¤§å¤šæ•°é”™è¯¯ï¼ŒåŒæ—¶ä»¥å¯è§†åŒ–æ ¼å¼æ‰“å°è°ƒåº¦åŸŸçš„结构。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-energy.rst b/Documentation/translations/zh_CN/scheduler/sched-energy.rst new file mode 100644 index 000000000000..fdbf6cfeea93 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-energy.rst @@ -0,0 +1,351 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-energy.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============ +能é‡æ„ŸçŸ¥è°ƒåº¦ +============ + +1. 简介 +------- + +能é‡æ„ŸçŸ¥è°ƒåº¦ï¼ˆEAS）使调度器有能力预测其决ç–对CPU所消耗的能é‡çš„å½±å“。EASä¾é +一个能é‡æ¨¡åž‹ï¼ˆEM）æ¥ä¸ºæ¯ä¸ªä»»åŠ¡é€‰æ‹©ä¸€ä¸ªèŠ‚能的CPU，åŒæ—¶æœ€å°åŒ–对åžå率的影å“。 +本文档致力于介ç»ä»‹ç»EAS是如何工作的，它背åŽçš„主è¦è®¾è®¡å†³ç–是什么，以åŠä½¿å…¶è¿è¡Œ +所需的æ¡ä»¶ç»†èŠ‚。 + +在进一æ¥é˜…读之å‰ï¼Œè¯·æ³¨æ„，在撰写本文时:: + + /!\ EASä¸æ”¯æŒå¯¹ç§°CPUæ‹“æ‰‘çš„å¹³å° /!\ + +EASåªåœ¨å¼‚æž„CPU拓扑结构（如Arm大å°æ ¸ï¼Œbig.LITTLE）上è¿è¡Œã€‚å› ä¸ºåœ¨è¿™ç§æƒ…况下， +通过调度æ¥èŠ‚约能é‡çš„潜力是最大的。 + +EAS实际使用的EMä¸æ˜¯ç”±è°ƒåº¦å™¨ç»´æŠ¤çš„，而是一个专门的框架。关于这个框架的细节和 +它æ供的内容，请å‚考其文档（è§Documentation/power/energy-model.rst）。 + + +2. èƒŒæ™¯å’Œæœ¯è¯ +------------- + +从一开始就说清楚定义: + - èƒ½é‡ = [焦耳] ï¼ˆæ¯”å¦‚ä¾›ç”µè®¾å¤‡ä¸Šçš„ç”µæ± æ供的资æºï¼‰ + - 功率 = 能é‡/时间 = [焦耳/秒] = [瓦特] + + EASçš„ç›®æ ‡æ˜¯æœ€å°åŒ–能é‡æ¶ˆè€—，åŒæ—¶ä»èƒ½å°†å·¥ä½œå®Œæˆã€‚也就是说，我们è¦æœ€å¤§åŒ–:: + + 性能 [指令数/秒] + ---------------- + 功率 [瓦特] + +它ç‰æ•ˆäºŽæœ€å°åŒ–:: + + èƒ½é‡ [焦耳] + ----------- + 指令数 + +åŒæ—¶ä»ç„¶èŽ·å¾—“良好â€çš„性能。当å‰è°ƒåº¦å™¨åªè€ƒè™‘æ€§èƒ½ç›®æ ‡ï¼Œå› æ¤è¯¥å¼å本质上是一个 +å¯é€‰çš„ä¼˜åŒ–ç›®æ ‡ï¼Œå®ƒåŒæ—¶è€ƒè™‘äº†ä¸¤ä¸ªç›®æ ‡ï¼šèƒ½é‡æ•ˆçŽ‡å’Œæ€§èƒ½ã€‚ + +引入EM的想法是为了让调度器评估其决ç–çš„å½±å“，而ä¸æ˜¯ç›²ç›®åœ°åº”用å¯èƒ½ä»…在部分 +å¹³å°æœ‰æ£é¢æ•ˆæžœçš„节能技术。åŒæ—¶ï¼ŒEM必须尽å¯èƒ½çš„简å•ï¼Œä»¥æœ€å°åŒ–调度器的时延 +å½±å“。 + +简而言之，EAS改å˜äº†CFS任务分é…ç»™CPUçš„æ–¹å¼ã€‚当调度器决定一个任务应该在哪里 +è¿è¡Œæ—¶ï¼ˆåœ¨å”¤é†’期间），EM被用æ¥åœ¨ä¸æŸå®³ç³»ç»ŸåžåçŽ‡çš„æƒ…å†µä¸‹ï¼Œä»Žå‡ ä¸ªè¾ƒå¥½çš„å€™é€‰ +CPUä¸æŒ‘选一个ç»é¢„测能é‡æ¶ˆè€—最优的CPU。EAS的预测ä¾èµ–于对平å°æ‹“æ‰‘ç»“æž„ç‰¹å®šå…ƒç´ +的了解，包括CPU的“算力â€ï¼Œä»¥åŠå®ƒä»¬å„自的能é‡æˆæœ¬ã€‚ + + +3. æ‹“æ‰‘ä¿¡æ¯ +----------- + +EAS（以åŠè°ƒåº¦å™¨çš„剩余部分）使用“算力â€çš„概念æ¥åŒºåˆ†ä¸åŒè®¡ç®—åžå率的CPU。一个 +CPU的“算力â€ä»£è¡¨äº†å®ƒåœ¨æœ€é«˜é¢‘率下è¿è¡Œæ—¶èƒ½å®Œæˆçš„工作é‡ï¼Œä¸”è¿™ä¸ªå€¼æ˜¯ç›¸å¯¹ç³»ç»Ÿä¸ +算力最大的CPU而言的。算力值被归一化为1024以内，并且å¯ä¸Žç”±å®žä½“负载跟踪 +（PELT）机制算出的利用率信å·åšå¯¹æ¯”。由于有算力值和利用率值，EAS能够估计一个 +任务/CPU有多大/有多忙，并在评估性能与能é‡æ—¶å°†å…¶è€ƒè™‘在内。CPU算力由特定体系 +结构实现的arch_scale_cpu_capacity()回调函数æ供。 + +EAS使用的其余平å°ä¿¡æ¯æ˜¯ç›´æŽ¥ä»Žèƒ½é‡æ¨¡åž‹ï¼ˆEM）框架ä¸è¯»å–的。一个平å°çš„EMæ˜¯ä¸€å¼ +表，表ä¸æ¯é¡¹ä»£è¡¨ç³»ç»Ÿä¸ä¸€ä¸ªâ€œæ€§èƒ½åŸŸâ€çš„功率æˆæœ¬ã€‚（若è¦äº†è§£æ›´å¤šå…³äºŽæ€§èƒ½åŸŸçš„细节， +è§Documentation/power/energy-model.rst） + +当调度域被建立或é‡æ–°å»ºç«‹æ—¶ï¼Œè°ƒåº¦å™¨ç®¡ç†å¯¹æ‹“扑代ç ä¸EM对象的引用。对于æ¯ä¸ªæ ¹åŸŸ +（rd），调度器维护一个与当å‰rd->span相交的所有性能域的å•å‘链表。链表ä¸çš„æ¯ä¸ª +节点都包å«ä¸€ä¸ªæŒ‡å‘EM框架所æ供的结构体em_perf_domain的指针。 + +é“¾è¡¨è¢«é™„åŠ åœ¨æ ¹åŸŸä¸Šï¼Œä»¥åº”å¯¹ç‹¬å çš„cpusetçš„é…置。由于独å çš„cpuset的边界ä¸ä¸€å®šä¸Ž +性能域的边界一致，ä¸åŒæ ¹åŸŸçš„链表å¯èƒ½åŒ…å«é‡å¤çš„å…ƒç´ ã€‚ + +示例1 + 让我们考虑一个有12个CPUçš„å¹³å°ï¼Œåˆ†æˆ3个性能域，（pd0，pd4å’Œpd8），按以下 + æ–¹å¼ç»„织:: + + CPUs: 0 1 2 3 4 5 6 7 8 9 10 11 + PDs: |--pd0--|--pd4--|---pd8---| + RDs: |----rd1----|-----rd2-----| + + 现在，考虑用户空间决定将系统分æˆä¸¤ä¸ªç‹¬å çš„cpusetsï¼Œå› æ¤åˆ›å»ºäº†ä¸¤ä¸ªç‹¬ç«‹çš„æ ¹åŸŸï¼Œ + æ¯ä¸ªæ ¹åŸŸåŒ…å«6个CPUã€‚è¿™ä¸¤ä¸ªæ ¹åŸŸåœ¨ä¸Šå›¾ä¸è¢«è¡¨ç¤ºä¸ºrd1å’Œrd2。由于pd4与rd1å’Œrd2 + 都有交集，它将åŒæ—¶å‡ºçŽ°äºŽé™„åŠ åœ¨è¿™ä¸¤ä¸ªæ ¹åŸŸçš„â€œ->pdâ€é“¾è¡¨ä¸: + + * rd1->pd: pd0 -> pd4 + * rd2->pd: pd4 -> pd8 + + 请注æ„，调度器将为pd4创建两个é‡å¤çš„链表节点（æ¯ä¸ªé“¾è¡¨ä¸å„一个）。然而这 + 两个节点æŒæœ‰æŒ‡å‘åŒä¸€ä¸ªEM框架的共享数æ®ç»“构的指针。 + +由于对这些链表的访问å¯èƒ½ä¸Žçƒæ’æ‹”åŠå…¶å®ƒäº‹ä»¶å¹¶å‘å‘ç”Ÿï¼Œå› æ¤å®ƒä»¬å—RCUé”ä¿æŠ¤ï¼Œå°±åƒ +被调度器æ“控的拓扑结构体ä¸å‰©ä¸‹å—æ®µä¸€æ ·ã€‚ + +EASåŒæ ·ç»´æŠ¤äº†ä¸€ä¸ªé™æ€é”®ï¼ˆsched_energy_presentï¼‰ï¼Œå½“è‡³å°‘æœ‰ä¸€ä¸ªæ ¹åŸŸæ»¡è¶³EAS +å¯åŠ¨çš„所有æ¡ä»¶æ—¶ï¼Œè¿™ä¸ªé”®å°±ä¼šè¢«å¯åŠ¨ã€‚在第6节ä¸æ€»ç»“了这些æ¡ä»¶ã€‚ + + +4. 能é‡æ„ŸçŸ¥ä»»åŠ¡æ”¾ç½® +------------------- + +EAS覆盖了CFS的任务唤醒平衡代ç 。在唤醒平衡时，它使用平å°çš„EMå’ŒPELTä¿¡å·æ¥é€‰æ‹©èŠ‚能 +çš„ç›®æ ‡CPU。当EAS被å¯ç”¨æ—¶ï¼Œselect_task_rq_fair()调用find_energy_efficient_cpu() +æ¥åšä»»åŠ¡æ”¾ç½®å†³å®šã€‚这个函数寻找在æ¯ä¸ªæ€§èƒ½åŸŸä¸å¯»æ‰¾å…·æœ‰æœ€é«˜å‰©ä½™ç®—力（CPU算力 - CPU +利用率）的CPUï¼Œå› ä¸ºå®ƒèƒ½è®©æˆ‘ä»¬ä¿æŒæœ€ä½Žçš„频率。然åŽï¼Œè¯¥å‡½æ•°æ£€æŸ¥å°†ä»»åŠ¡æ”¾åœ¨æ–°CPU相较 +ä¾ç„¶æ”¾åœ¨ä¹‹å‰æ´»åŠ¨çš„prev_cpu是å¦å¯ä»¥èŠ‚çœèƒ½é‡ã€‚ + +如果唤醒的任务被è¿ç§»ï¼Œfind_energy_efficient_cpu()使用compute_energy()æ¥ä¼°ç®— +系统将消耗多少能é‡ã€‚compute_energy()检查å„CPU当å‰çš„利用率情况，并å°è¯•è°ƒæ•´æ¥ +“模拟â€ä»»åŠ¡è¿ç§»ã€‚EM框架æ供了API em_pd_energy()计算æ¯ä¸ªæ€§èƒ½åŸŸåœ¨ç»™å®šçš„利用率æ¡ä»¶ +下的预期能é‡æ¶ˆè€—。 + +下é¢è¯¦ç»†ä»‹ç»ä¸€ä¸ªä¼˜åŒ–能é‡æ¶ˆè€—的任务放置决ç–的例å。 + +示例2 + 让我们考虑一个有两个独立性能域的（伪）平å°ï¼Œæ¯ä¸ªæ€§èƒ½åŸŸå«æœ‰2个CPU。CPU0å’ŒCPU1 + 是å°æ ¸ï¼ŒCPU2å’ŒCPU3æ˜¯å¤§æ ¸ã€‚ + + 调度器必须决定将任务P放在哪个CPU上，这个任务的util_avg = 200（平å‡åˆ©ç”¨çŽ‡ï¼‰ï¼Œ + prev_cpu = 0（上一次è¿è¡Œåœ¨CPU0）。 + + ç›®å‰CPU的利用率情况如下图所示。CPU 0-3çš„util_avg分别为400ã€100ã€600å’Œ500。 + æ¯ä¸ªæ€§èƒ½åŸŸæœ‰ä¸‰ä¸ªæ“作性能值（OPP）。与æ¯ä¸ªOPP相关的CPU算力和功率æˆæœ¬åˆ—åœ¨èƒ½é‡ + 模型表ä¸ã€‚Pçš„util_avg在图ä¸æ˜¾ç¤ºä¸º"PP":: + + CPU util. + 1024 - - - - - - - Energy Model + +-----------+-------------+ + | Little | Big | + 768 ============= +-----+-----+------+------+ + | Cap | Pwr | Cap | Pwr | + +-----+-----+------+------+ + 512 =========== - ##- - - - - | 170 | 50 | 512 | 400 | + ## ## | 341 | 150 | 768 | 800 | + 341 -PP - - - - ## ## | 512 | 300 | 1024 | 1700 | + PP ## ## +-----+-----+------+------+ + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + Current OPP: ===== Other OPP: - - - util_avg (100 each): ## + + + find_energy_efficient_cpu()将首先在两个性能域ä¸å¯»æ‰¾å…·æœ‰æœ€å¤§å‰©ä½™ç®—力的CPU。 + 在这个例åä¸æ˜¯CPU1å’ŒCPU3。然åŽï¼Œå®ƒå°†ä¼°ç®—，当P被放在它们ä¸çš„ä»»æ„一个时，系统的 + èƒ½è€—ï¼Œå¹¶æ£€æŸ¥è¿™æ ·åšæ˜¯å¦ä¼šæ¯”把P放在CPU0上节çœä¸€äº›èƒ½é‡ã€‚EASå‡å®šOPPséµå¾ªåˆ©ç”¨çŽ‡ + （这与CPUFreq监管器schedutil的行为一致。关于这个问题的更多细节，è§ç¬¬6节）。 + + **情况1. P被è¿ç§»åˆ°CPU1**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 300 / 341 * 150 = 131 + * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1364 + 341 =========== ## ## + PP ## ## + 170 -## - - PP- ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + + **情况2. P被è¿ç§»åˆ°CPU3**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 100 / 341 * 150 = 43 + PP * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - -PP - * CPU3: 700 / 768 * 800 = 729 + ## ## => total_energy = 1485 + 341 =========== ## ## + ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + **情况3. Pä¾æ—§ç•™åœ¨prev_cpu/CPU0**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 400 / 512 * 300 = 234 + * CPU1: 100 / 512 * 300 = 58 + * CPU2: 600 / 768 * 800 = 625 + 512 =========== - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1437 + 341 -PP - - - - ## ## + PP ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + 从这些计算结果æ¥çœ‹ï¼Œæƒ…况1的总能é‡æœ€ä½Žã€‚所以从节约能é‡çš„角度看，CPU1是最佳候选 + 者。 + +å¤§æ ¸é€šå¸¸æ¯”å°æ ¸æ›´è€—ç”µï¼Œå› æ¤ä¸»è¦åœ¨ä»»åŠ¡ä¸é€‚åˆåœ¨å°æ ¸è¿è¡Œæ—¶ä½¿ç”¨ã€‚然而，å°æ ¸å¹¶ä¸æ€»æ˜¯æ¯” +å¤§æ ¸èŠ‚èƒ½ã€‚ä¸¾ä¾‹æ¥è¯´ï¼Œå¯¹äºŽæŸäº›ç³»ç»Ÿï¼Œå°æ ¸çš„高OPPå¯èƒ½æ¯”å¤§æ ¸çš„ä½ŽOPP能é‡æ¶ˆè€—æ›´é«˜ã€‚å› æ¤ï¼Œ +如果å°æ ¸åœ¨æŸä¸€ç‰¹å®šæ—¶é—´ç‚¹åˆšå¥½æœ‰è¶³å¤Ÿçš„利用率，在æ¤åˆ»è¢«å”¤é†’çš„å°ä»»åŠ¡æ”¾åœ¨å¤§æ ¸æ‰§è¡Œå¯èƒ½ +会更节能，尽管它在å°æ ¸ä¸Šè¿è¡Œä¹Ÿæ˜¯åˆé€‚的。 + +å³ä½¿åœ¨å¤§æ ¸æ‰€æœ‰OPP都ä¸å¦‚å°æ ¸OPP节能的情况下，在æŸäº›ç‰¹å®šæ¡ä»¶ä¸‹ï¼Œä»¤å°ä»»åŠ¡è¿è¡Œåœ¨å¤§æ ¸ +上ä¾ç„¶å¯èƒ½èŠ‚能。事实上，将一个任务放在一个å°æ ¸ä¸Šå¯èƒ½å¯¼è‡´æ•´ä¸ªæ€§èƒ½åŸŸçš„OPPæ高，这将 +å¢žåŠ å·²ç»åœ¨è¯¥æ€§èƒ½åŸŸè¿è¡Œçš„任务的能é‡æˆæœ¬ã€‚å¦‚æžœå”¤é†’çš„ä»»åŠ¡è¢«æ”¾åœ¨ä¸€ä¸ªå¤§æ ¸ä¸Šï¼Œå®ƒçš„æ‰§è¡Œ +æˆæœ¬å¯èƒ½æ¯”放在å°æ ¸ä¸Šæ›´é«˜ï¼Œä½†è¿™ä¸ä¼šå½±å“å°æ ¸ä¸Šçš„其它任务，这些任务将继ç»ä»¥è¾ƒä½Žçš„OPP +è¿è¡Œã€‚å› æ¤ï¼Œå½“考虑CPU消耗的总能é‡æ—¶ï¼Œåœ¨å¤§æ ¸ä¸Šè¿è¡Œä¸€ä¸ªä»»åŠ¡çš„é¢å¤–æˆæœ¬å¯èƒ½å°äºŽä¸ºæ‰€æœ‰ +其它è¿è¡Œåœ¨å°æ ¸çš„任务æ高OPPçš„æˆæœ¬ã€‚ + +上é¢çš„例åå‡ ä¹Žä¸å¯èƒ½ä»¥ä¸€ç§é€šç”¨çš„æ–¹å¼å¾—到æ£ç¡®çš„结果；åŒæ—¶ï¼Œå¯¹äºŽæ‰€æœ‰å¹³å°ï¼Œåœ¨ä¸çŸ¥é“ +系统所有CPUæ¯ä¸ªä¸åŒOPPçš„è¿è¡Œæˆæœ¬æ—¶ï¼Œä¹Ÿæ— 法得到æ£ç¡®çš„结果。得益于基于EM的设计， +EAS应该能够æ£ç¡®å¤„ç†è¿™äº›é—®é¢˜è€Œä¸ä¼šå¼•å‘太多麻烦。然而，为了确ä¿å¯¹é«˜åˆ©ç”¨çŽ‡åœºæ™¯çš„ +åžåçŽ‡é€ æˆçš„å½±å“最å°åŒ–，EASåŒæ ·å®žçŽ°äº†å¦å¤–一ç§å«â€œè¿‡åº¦åˆ©ç”¨çŽ‡â€çš„机制。 + + +5. 过度利用率 +------------- + +从一般的角度æ¥çœ‹ï¼ŒEAS能æ供最大帮助的是那些涉åŠä½Žã€ä¸CPU利用率的使用场景。æ¯å½“CPU +密集型的长任务è¿è¡Œï¼Œå®ƒä»¬å°†éœ€è¦æ‰€æœ‰çš„å¯ç”¨CPU算力，调度器将没有什么办法æ¥èŠ‚çœèƒ½é‡åŒæ—¶ +åˆä¸æŸå®³åžå率。为了é¿å…EASæŸå®³æ€§èƒ½ï¼Œä¸€æ—¦CPU被使用的算力超过80%ï¼Œå®ƒå°†è¢«æ ‡è®°ä¸ºâ€œè¿‡åº¦ +利用â€ã€‚åªè¦æ ¹åŸŸä¸æ²¡æœ‰CPU是过度利用状æ€ï¼Œè´Ÿè½½å‡è¡¡è¢«ç¦ç”¨ï¼Œè€ŒEAS将覆盖唤醒平衡代ç 。 +EAS很å¯èƒ½å°†è´Ÿè½½æ”¾ç½®åœ¨ç³»ç»Ÿä¸èƒ½é‡æ•ˆçŽ‡æœ€é«˜çš„CPU而ä¸æ˜¯å…¶å®ƒCPU上，åªè¦ä¸æŸå®³åžå率。 +å› æ¤ï¼Œè´Ÿè½½å‡è¡¡å™¨è¢«ç¦ç”¨ä»¥é˜²æ¢å®ƒæ‰“ç ´EASå‘现的节能任务放置。当系统未处于过度利用状æ€æ—¶ï¼Œ +è¿™æ ·åšæ˜¯å®‰å…¨çš„ï¼Œå› ä¸ºä½ŽäºŽ80%的临界点æ„味ç€ï¼š + + a. 所有的CPU都有一些空闲时间，所以EAS使用的利用率信å·å¾ˆå¯èƒ½å‡†ç¡®åœ°ä»£è¡¨å„ç§ä»»åŠ¡ + 的“大å°â€ã€‚ + b. 所有任务，ä¸ç®¡å®ƒä»¬çš„nice值是多大，都应该被æ供了足够多的CPU算力。 + c. 既然有多余的算力，那么所有的任务都必须定期阻塞/ä¼‘çœ ï¼Œåœ¨å”¤é†’æ—¶è¿›è¡Œå¹³è¡¡å°±è¶³å¤Ÿ + 了。 + +åªè¦ä¸€ä¸ªCPU利用率超过80%的临界点，上述三个å‡è®¾ä¸è‡³å°‘有一个是ä¸æ£ç¡®çš„。在这ç§æƒ…况下， +æ•´ä¸ªæ ¹åŸŸçš„â€œè¿‡åº¦åˆ©ç”¨â€æ ‡å¿—被设置，EAS被ç¦ç”¨ï¼Œè´Ÿè½½å‡è¡¡å™¨è¢«é‡æ–°å¯ç”¨ã€‚é€šè¿‡è¿™æ ·åšï¼Œè°ƒåº¦å™¨ +åˆå›žåˆ°äº†åœ¨CPU密集的æ¡ä»¶ä¸‹åŸºäºŽè´Ÿè½½çš„算法åšè´Ÿè½½å‡è¡¡ã€‚这更好地尊é‡äº†ä»»åŠ¡çš„nice值。 + +由于过度利用率的概念在很大程度上ä¾èµ–于检测系统ä¸æ˜¯å¦æœ‰ä¸€äº›ç©ºé—²æ—¶é—´ï¼Œæ‰€ä»¥å¿…须考虑 +（比CFS）更高优先级的调度类（以åŠä¸æ–）“窃å–â€çš„CPU算力。åƒè¿™æ ·ï¼Œå¯¹è¿‡åº¦ä½¿ç”¨çŽ‡çš„检测 +ä¸ä»…è¦è€ƒè™‘CFS任务使用的算力，还需è¦è€ƒè™‘其它调度类和ä¸æ–。 + + +6. EASçš„ä¾èµ–å’Œè¦æ±‚ +------------------ + +能é‡æ„ŸçŸ¥è°ƒåº¦ä¾èµ–系统的CPU具有特定的硬件属性，以åŠå†…æ ¸ä¸çš„其它特性被å¯ç”¨ã€‚本节列出 +了这些ä¾èµ–，并对如何满足这些ä¾èµ–æ供了æ示。 + + +6.1 - éžå¯¹ç§°CPU拓扑 +^^^^^^^^^^^^^^^^^^^ + + +如简介所æ，目å‰åªæœ‰éžå¯¹ç§°CPU拓扑结构的平å°æ”¯æŒEAS。通过在è¿è¡Œæ—¶æŸ¥è¯¢ +SD_ASYM_CPUCAPACITY_FULLæ ‡å¿—ä½æ˜¯å¦åœ¨åˆ›å»ºè°ƒåº¦åŸŸæ—¶å·²è®¾ç½®æ¥æ£€æŸ¥è¿™ä¸€è¦æ±‚是å¦æ»¡è¶³ã€‚ + +å‚阅Documentation/scheduler/sched-capacity.rst以了解在sched_domain层次结构 +ä¸è®¾ç½®æ¤æ ‡å¿—ä½æ‰€éœ€æ»¡è¶³çš„è¦æ±‚。 + +请注æ„，EAS并éžä»Žæ ¹æœ¬ä¸Šä¸ŽSMPä¸å…¼å®¹ï¼Œä½†åœ¨SMPå¹³å°ä¸Šè¿˜æ²¡æœ‰è§‚察到明显的节能。这一 +é™åˆ¶å¯ä»¥åœ¨å°†æ¥è¿›è¡Œä¿®æ”¹ï¼Œå¦‚果被è¯æ˜Žä¸æ˜¯è¿™æ ·çš„è¯ã€‚ + + +6.2 - 当å‰çš„能é‡æ¨¡åž‹ +^^^^^^^^^^^^^^^^^^^^ + +EAS使用一个平å°çš„EMæ¥ä¼°ç®—调度决ç–对能é‡çš„å½±å“ã€‚å› æ¤ï¼Œä½ çš„å¹³å°å¿…é¡»å‘EM框架æä¾› +能é‡æˆæœ¬è¡¨ï¼Œä»¥å¯åŠ¨EAS。è¦åšåˆ°è¿™ä¸€ç‚¹ï¼Œè¯·å‚阅文档 +Documentation/power/energy-model.rstä¸çš„独立EM框架部分。 + +å¦è¯·æ³¨æ„，调度域需è¦åœ¨EM注册åŽé‡å»ºï¼Œä»¥ä¾¿å¯åŠ¨EAS。 + +EAS使用EM对能é‡ä½¿ç”¨çŽ‡è¿›è¡Œé¢„测决ç–ï¼Œå› æ¤å®ƒåœ¨æ£€æŸ¥ä»»åŠ¡æ”¾ç½®çš„å¯èƒ½é€‰é¡¹æ—¶æ›´åŠ æ³¨é‡ +差异。对于EASæ¥è¯´ï¼ŒEM的功率值是以毫瓦还是以“抽象刻度â€ä¸ºå•ä½è¡¨ç¤ºå¹¶ä¸é‡è¦ã€‚ + + + +6.3 - 能é‡æ¨¡åž‹å¤æ‚度 +^^^^^^^^^^^^^^^^^^^^ + +任务唤醒路径是时延æ•æ„Ÿçš„。当一个平å°çš„EM太å¤æ‚（太多CPUï¼Œå¤ªå¤šæ€§èƒ½åŸŸï¼Œå¤ªå¤šçŠ¶æ€ +ç‰ï¼‰ï¼Œåœ¨å”¤é†’路径ä¸ä½¿ç”¨å®ƒçš„æˆæœ¬å°±ä¼šå‡é«˜åˆ°ä¸å¯æŽ¥å—。能é‡æ„ŸçŸ¥å”¤é†’算法的å¤æ‚度为： + + C = Nd * (Nc + Ns) + +å…¶ä¸ï¼šNd是性能域的数é‡ï¼›Nc是CPUçš„æ•°é‡ï¼›Ns是OPP的总数（例如：对于两个性能域， +æ¯ä¸ªåŸŸæœ‰4个OPP，则Ns = 8）。 + +当调度域建立时，å¤æ‚æ€§æ£€æŸ¥æ˜¯åœ¨æ ¹åŸŸä¸Šè¿›è¡Œçš„ã€‚å¦‚æžœä¸€ä¸ªæ ¹åŸŸçš„å¤æ‚度Cæ°å¥½é«˜äºŽå®Œå…¨ +主观设定的EM_MAX_COMPLEXITY阈值（在本文写作时，是2048），则EASä¸ä¼šåœ¨æ¤æ ¹åŸŸ +å¯åŠ¨ã€‚ + +å¦‚æžœä½ çš„å¹³å°çš„能é‡æ¨¡åž‹çš„å¤æ‚度太高，EASæ— æ³•åœ¨è¿™ä¸ªæ ¹åŸŸä¸Šä½¿ç”¨ï¼Œä½†ä½ çœŸçš„æƒ³ç”¨ï¼Œ +é‚£ä¹ˆä½ å°±åªå‰©ä¸‹ä¸¤ä¸ªå¯èƒ½çš„选择： + + 1. å°†ä½ çš„ç³»ç»Ÿæ‹†åˆ†æˆåˆ†ç¦»çš„ã€è¾ƒå°çš„ã€ä½¿ç”¨ç‹¬å cpusetçš„æ ¹åŸŸï¼Œå¹¶åœ¨æ¯ä¸ªæ ¹åŸŸå±€éƒ¨ + å¯ç”¨EAS。这个方案的好处是开箱å³ç”¨ï¼Œä½†ç¼ºç‚¹æ˜¯æ— æ³•åœ¨æ ¹åŸŸä¹‹é—´å®žçŽ°è´Ÿè½½å‡è¡¡ï¼Œ + è¿™å¯èƒ½ä¼šå¯¼è‡´æ€»ä½“系统负载ä¸å‡è¡¡ã€‚ + 2. æ交补ä¸ä»¥é™ä½ŽEAS唤醒算法的å¤æ‚度，从而使其能够在åˆç†çš„时间内处ç†æ›´å¤§ + çš„EM。 + + +6.4 - Schedutil监管器 +^^^^^^^^^^^^^^^^^^^^^ + +EAS试图预测CPU在ä¸ä¹…çš„å°†æ¥ä¼šåœ¨å“ªä¸ªOPP下è¿è¡Œï¼Œä»¥ä¼°ç®—它们的能é‡æ¶ˆè€—。为了åšåˆ° +这一点，它å‡å®šCPUçš„OPPè·ŸéšCPU利用率å˜åŒ–而å˜åŒ–。 + +尽管在实践ä¸å¾ˆéš¾å¯¹è¿™ä¸€å‡è®¾çš„准确性æ供硬性ä¿è¯ï¼ˆå› 为，举例æ¥è¯´ç¡¬ä»¶å¯èƒ½ä¸ä¼šåš +它被è¦æ±‚åšçš„事情），相对于其他CPUFreq监管器，schedutil至少_请求_使用利用率 +ä¿¡å·è®¡ç®—çš„é¢‘çŽ‡ã€‚å› æ¤ï¼Œä¸ŽEAS一起使用的唯一åˆç†çš„监管器是schedutilï¼Œå› ä¸ºå®ƒæ˜¯ +唯一一个在频率请求和能é‡é¢„测之间æä¾›æŸç§ç¨‹åº¦çš„一致性的监管器。 + +ä¸æ”¯æŒå°†EAS与schedutil之外的任何其它监管器一起使用。 + + +6.5 刻度ä¸å˜æ€§ä½¿ç”¨çŽ‡ä¿¡å· +^^^^^^^^^^^^^^^^^^^^^^^^ + +为了对ä¸åŒçš„CPU和所有的性能状æ€åšå‡ºå‡†ç¡®çš„预测，EAS需è¦é¢‘率ä¸å˜çš„å’ŒCPUä¸å˜çš„ +PELTä¿¡å·ã€‚这些信å·å¯ä»¥é€šè¿‡æ¯ä¸ªä½“系结构定义的arch_scale{cpu,freq}_capacity() +回调函数获å–。 + +ä¸æ”¯æŒåœ¨æ²¡æœ‰å®žçŽ°è¿™ä¸¤ä¸ªå›žè°ƒå‡½æ•°çš„å¹³å°ä¸Šä½¿ç”¨EAS。 + + +6.6 多线程（SMT） +^^^^^^^^^^^^^^^^^ + +当å‰å®žçŽ°çš„EAS是ä¸æ„ŸçŸ¥SMTçš„ï¼Œå› æ¤æ— 法利用多线程硬件节约能é‡ã€‚EAS认为线程是独立的 +CPU，这实际上对性能和能é‡æ¶ˆè€—都是ä¸åˆ©çš„。 + +ä¸æ”¯æŒåœ¨SMT上使用EAS。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst b/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst new file mode 100644 index 000000000000..9107f0c0b979 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-nice-design.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +===================== +调度器nice值设计 +===================== + +本文档解释了新的Linux调度器ä¸ä¿®æ”¹å’Œç²¾ç®€åŽçš„nice级别的实现æ€è·¯ã€‚ + +Linuxçš„nice级别总是éžå¸¸è„†å¼±ï¼Œäººä»¬æŒç»ä¸æ–åœ°ç¼ ç€æˆ‘们，让nice +19的任务å 用 +æ›´å°‘çš„CPU时间。 + +ä¸å¹¸çš„是，在旧的调度器ä¸ï¼Œè¿™ä¸æ˜¯é‚£ä¹ˆå®¹æ˜“实现的（å¦åˆ™æˆ‘们早就åšåˆ°äº†ï¼‰ï¼Œå› 为对 +nice级别的支æŒåœ¨åŽ†å²ä¸Šæ˜¯ä¸Žæ—¶é—´ç‰‡é•¿åº¦è€¦åˆçš„，而时间片å•ä½æ˜¯ç”±HZæ»´ç”驱动的， +所以最å°çš„时间片是1/HZ。 + +在O(1)调度器ä¸ï¼ˆ2003年），我们改å˜äº†è´Ÿçš„nice级别，使它们比2.4å†…æ ¸æ›´å¼º +（人们对这一å˜åŒ–很满æ„），而且我们还故æ„æ ¡æ£äº†çº¿æ€§æ—¶é—´ç‰‡å‡†åˆ™ï¼Œä½¿å¾—nice +19 +的级别 _æ£å¥½_ 是1 jiffy。为了让大家更好地ç†è§£å®ƒï¼Œæ—¶é—´ç‰‡çš„å›¾ä¼šæ˜¯è¿™æ ·çš„ï¼ˆè´¨é‡ +ä¸ä½³çš„ASCII艺术æ醒ï¼ï¼‰:: + + + A + \ | [timeslice length] + \ | + \ | + \ | + \ | + \|___100msecs + |^ . _ + | ^ . _ + | ^ . _ + -*----------------------------------*-----> [nice level] + -20 | +19 + | + | + +å› æ¤ï¼Œå¦‚果有人真的想renice任务，相较线性规则，+19ä¼šç»™å‡ºæ›´å¤§çš„æ•ˆæžœï¼ˆæ”¹å˜ +ABIæ¥æ‰©å±•ä¼˜å…ˆçº§çš„解决方案在早期就被放弃了）。 + +è¿™ç§æ–¹æ³•åœ¨ä¸€å®šç¨‹åº¦ä¸Šå¥æ•ˆäº†ä¸€æ®µæ—¶é—´ï¼Œä½†åŽæ¥HZ=1000时，它导致1 jiffy为 +1ms，这æ„味ç€0.1%çš„CPU使用率，我们认为这有点过度。过度 _ä¸æ˜¯_ å› ä¸ºå®ƒè¡¨ç¤º +çš„CPU使用率过å°ï¼Œè€Œæ˜¯å› 为它引å‘了过于频ç¹ï¼ˆæ¯æ¯«ç§’1次）的é‡æ–°è°ƒåº¦ï¼ˆå› æ¤ä¼š +ç ´å缓å˜ï¼Œç‰ç‰ã€‚请记ä½ï¼Œç¡¬ä»¶æ›´å¼±ã€cacheæ›´å°æ˜¯å¾ˆä¹…以å‰çš„事了，当时人们在 +nice +19级别è¿è¡Œæ•°é‡é¢‡å¤šçš„应用程åºï¼‰ã€‚ + +å› æ¤ï¼Œå¯¹äºŽHZ=1000，我们将nice +19改为5æ¯«ç§’ï¼Œå› ä¸ºè¿™æ„Ÿè§‰åƒæ˜¯æ£ç¡®çš„æœ€å° +粒度——这相当于5%çš„CPU利用率。但nice +19çš„æ ¹æœ¬çš„HZæ•æ„Ÿå±žæ€§ä¾ç„¶ä¿æŒä¸å˜ï¼Œ +我们没有收到过关于nice +19在CPU利用率方é¢å¤ª _å¼±_ 的任何抱怨，我们åªæ”¶åˆ° +过它（ä¾ç„¶ï¼‰å¤ª _强_ 的抱怨 :-)。 + +总结一下：我们一直想让niceå„级别一致性更强，但在HZå’Œjiffiesçš„é™åˆ¶ä¸‹ï¼Œä»¥åŠ +nice级别与时间片ã€è°ƒåº¦ç²’度耦åˆæ˜¯ä»¤äººè®¨åŽŒçš„è®¾è®¡ï¼Œè¿™ä¸€ç›®æ ‡å¹¶ä¸çœŸæ£å¯è¡Œã€‚ + +第二个关于Linux nice级别支æŒçš„抱怨是（ä¸é‚£ä¹ˆé¢‘ç¹ï¼Œä½†ä»ç„¶å®šæœŸå‘生），它 +在原点周围的ä¸å¯¹ç§°æ€§ï¼ˆä½ å¯ä»¥åœ¨ä¸Šé¢çš„图片ä¸çœ‹åˆ°ï¼‰ï¼Œæˆ–者更准确地说：事实上 +nice级别的行为å–决于 _ç»å¯¹çš„_ nice级别，而nice应用程åºæŽ¥å£æœ¬èº«ä»Žæ ¹æœ¬ä¸Š +说是“相对â€çš„： + + int nice(int inc); + + asmlinkage long sys_nice(int increment) + +（第一个是glibc的应用程åºæŽ¥å£ï¼Œç¬¬äºŒä¸ªæ˜¯syscall的应用程åºæŽ¥å£ï¼‰ +注æ„，“incâ€æ˜¯ç›¸å¯¹å½“å‰nice级别而言的，类似bash的“niceâ€å‘½ä»¤ç‰å·¥å…·æ˜¯è¿™ä¸ª +相对性应用程åºæŽ¥å£çš„é•œåƒã€‚ + +在旧的调度器ä¸ï¼Œä¸¾ä¾‹æ¥è¯´ï¼Œå¦‚æžœä½ ä»¥nice +1å¯åŠ¨ä¸€ä¸ªä»»åŠ¡ï¼Œå¹¶ä»¥nice +2å¯åŠ¨ +å¦ä¸€ä¸ªä»»åŠ¡ï¼Œè¿™ä¸¤ä¸ªä»»åŠ¡çš„CPU分é…å°†å–决于父外壳程åºçš„nice级别——如果它是 +nice -10，那么CPU的分é…ä¸åŒäºŽ+5或+10。 + +第三个关于Linux nice级别支æŒçš„抱怨是，负数nice级别“ä¸å¤Ÿæœ‰åŠ›â€ï¼Œä»¥å¾ˆå¤šäºº +ä¸å¾—ä¸è¯‰è¯¸äºŽå®žæ—¶è°ƒåº¦ä¼˜å…ˆçº§æ¥è¿è¡ŒéŸ³é¢‘（和其它多媒体）应用程åºï¼Œæ¯”如 +SCHED_FIFOã€‚ä½†è¿™ä¹Ÿé€ æˆäº†å…¶å®ƒé—®é¢˜ï¼šSCHED_FIFO未被è¯æ˜Žæ˜¯å…于饥饿的，一个 +有问题的SCHED_FIFO应用程åºä¹Ÿä¼šé”ä½è¿è¡Œè‰¯å¥½çš„系统。 + +v2.6.23ç‰ˆå†…æ ¸çš„æ–°è°ƒåº¦å™¨è§£å†³äº†è¿™ä¸‰ç§ç±»åž‹çš„抱怨： + +为了解决第一个抱怨（nice级别ä¸å¤Ÿâ€œæœ‰åŠ›â€ï¼‰ï¼Œè°ƒåº¦å™¨ä¸Žâ€œæ—¶é—´ç‰‡â€ã€HZ的概念 +解耦（调度粒度被处ç†æˆä¸€ä¸ªå’Œniceçº§åˆ«ç‹¬ç«‹çš„æ¦‚å¿µï¼‰ï¼Œå› æ¤æœ‰å¯èƒ½å®žçŽ°æ›´å¥½ã€ +更一致的nice +19支æŒï¼šåœ¨æ–°çš„调度器ä¸ï¼Œnice +19的任务得到一个HZæ— å…³çš„ +1.5%CPU使用率，而ä¸æ˜¯æ—§ç‰ˆè°ƒåº¦å™¨ä¸3%-5%-9%çš„å¯å˜èŒƒå›´ã€‚ + +为了解决第二个抱怨（niceå„级别ä¸ä¸€è‡´ï¼‰ï¼Œæ–°è°ƒåº¦å™¨ä»¤è°ƒç”¨nice(1)对å„任务的 +CPU利用率有相åŒçš„å½±å“ï¼Œæ— è®ºå…¶ç»å¯¹nice级别如何。所以在新调度器上，è¿è¡Œä¸€ä¸ª +nice +10和一个nice +11的任务会与è¿è¡Œä¸€ä¸ªnice -5和一个nice -4的任务的 +CPU利用率分割是相åŒçš„（一个会得到55%çš„CPU，å¦ä¸€ä¸ªä¼šå¾—到45%）。这是为什么 +nice级别被改为“乘法â€ï¼ˆæˆ–æŒ‡æ•°ï¼‰â€”â€”è¿™æ ·çš„è¯ï¼Œä¸ç®¡ä½ 从哪个级别开始，“相对†+ç»“æžœå°†æ€»æ˜¯ä¸€æ ·çš„ã€‚ + +第三个抱怨（负数nice级别ä¸å¤Ÿâ€œæœ‰åŠ›â€ï¼Œå¹¶è¿«ä½¿éŸ³é¢‘应用程åºåœ¨æ›´å±é™©çš„ +SCHED_FIFO调度ç–略下è¿è¡Œï¼‰å‡ 乎被新的调度器自动解决了：更强的负数级别 +具有é‡æ–°æ ¡æ£nice级别动æ€èŒƒå›´çš„自动化副作用。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-stats.rst b/Documentation/translations/zh_CN/scheduler/sched-stats.rst new file mode 100644 index 000000000000..1c68c3d1c283 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-stats.rst @@ -0,0 +1,156 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-stats.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============== +è°ƒåº¦å™¨ç»Ÿè®¡æ•°æ® +============== + +第15版schedstats去掉了sched_yield的一些计数器：yld_exp_empty，yld_act_empty +å’Œyld_both_empty。在其它方é¢å’Œç¬¬14版完全相åŒã€‚ + +第14版schedstats包括对sched_domains（译注：调度域）的支æŒï¼Œè¯¥ç‰¹æ€§è¿›å…¥å†…æ ¸ +主线2.6.20，ä¸è¿‡è¿™ä¸€ç‰ˆschedstats与2.6.13-2.6.19å†…æ ¸çš„ç‰ˆæœ¬12的统计数æ®æ˜¯å®Œå…¨ +相åŒçš„ï¼ˆå†…æ ¸æœªå‘布第13版）。有些计数器按æ¯ä¸ªè¿è¡Œé˜Ÿåˆ—统计是更有æ„义的，其它则 +按æ¯ä¸ªè°ƒåº¦åŸŸç»Ÿè®¡æ˜¯æ›´æœ‰æ„义的。注æ„，调度域（以åŠå®ƒä»¬çš„附属信æ¯ï¼‰ä»…åœ¨å¼€å¯ +CONFIG_SMP的机器上是相关的和å¯ç”¨çš„。 + +在第14版schedstatä¸ï¼Œæ¯ä¸ªè¢«åˆ—出的CPU至少会有一级域统计数æ®ï¼Œä¸”很å¯èƒ½æœ‰ä¸€ä¸ª +以上的域。在这个实现ä¸ï¼ŒåŸŸæ²¡æœ‰ç‰¹åˆ«çš„åå—，但是编å·æœ€é«˜çš„域通常在机器上所有的 +CPU上仲è£å¹³è¡¡ï¼Œè€Œdomain0是最紧密èšç„¦çš„域，有时仅在一对CPU之间进行平衡。æ¤æ—¶ï¼Œ +没有任何体系结构需è¦3层以上的域。域统计数æ®ä¸çš„第一个å—段是一个ä½å›¾ï¼Œè¡¨æ˜Žå“ªäº› +CPUå—该域的影å“。 + +这些å—段是计数器，而且åªèƒ½é€’增。使用这些å—段的程åºå°†éœ€è¦ä»ŽåŸºçº¿è§‚测开始，然åŽåœ¨ +åŽç»æ¯ä¸€ä¸ªè§‚测ä¸è®¡ç®—出计数器的å˜åŒ–。一个能以这ç§æ–¹å¼å¤„ç†å…¶ä¸å¾ˆå¤šå—段的perl脚本 +å¯è§ + + http://eaglet.pdxhosts.com/rick/linux/schedstat/ + +请注æ„ï¼Œä»»ä½•è¿™æ ·çš„è„šæœ¬éƒ½å¿…é¡»æ˜¯ç‰¹å®šäºŽç‰ˆæœ¬çš„ï¼Œæ”¹å˜ç‰ˆæœ¬çš„主è¦åŽŸå› æ˜¯è¾“å‡ºæ ¼å¼çš„å˜åŒ–。 +对于那些希望编写自己的脚本的人，å¯ä»¥å‚考这里æè¿°çš„å„个å—段。 + +CPUç»Ÿè®¡æ•°æ® +----------- +cpu<N> 1 2 3 4 5 6 7 8 9 + +第一个å—段是sched_yield()的统计数æ®ï¼š + + 1) sched_yield()被调用了#次 + +接下æ¥çš„三个是schedule()的统计数æ®ï¼š + + 2) 这个å—段是一个过时的数组过期计数，在O(1)调度器ä¸ä½¿ç”¨ã€‚为了ABI兼容性， + 我们ä¿ç•™äº†å®ƒï¼Œä½†å®ƒæ€»æ˜¯è¢«è®¾ç½®ä¸º0。 + 3) schedule()被调用了#次 + 4) 调用schedule()导致处ç†å™¨å˜ä¸ºç©ºé—²äº†#次 + +接下æ¥çš„两个是try_to_wake_up()的统计数æ®ï¼š + + 5) try_to_wake_up()被调用了#次 + 6) 调用try_to_wake_up()导致本地CPU被唤醒了#次 + +接下æ¥çš„三个统计数æ®æ述了调度延迟： + + 7) 本处ç†å™¨è¿è¡Œä»»åŠ¡çš„总时间，å•ä½æ˜¯jiffies + 8) 本处ç†å™¨ä»»åŠ¡ç‰å¾…è¿è¡Œçš„时间，å•ä½æ˜¯jiffies + 9) 本CPUè¿è¡Œäº†#个时间片 + +åŸŸç»Ÿè®¡æ•°æ® +---------- + +对于æ¯ä¸ªè¢«æè¿°çš„CPU，和它相关的æ¯ä¸€ä¸ªè°ƒåº¦åŸŸå‡ä¼šäº§ç”Ÿä¸‹é¢ä¸€è¡Œæ•°æ®ï¼ˆæ³¨æ„，如果 +CONFIG_SMP没有被定义，那么*没有*调度域被使用，这些行ä¸ä¼šå‡ºçŽ°åœ¨è¾“出ä¸ï¼‰ã€‚ + +domain<N> <cpumask> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 + +第一个å—段是一个ä½æŽ©ç ，表明该域在æ“作哪些CPU。 + +接下æ¥çš„24个å—段是load_balance()函数的å„个统计数æ®ï¼ŒæŒ‰ç©ºé—²ç±»åž‹åˆ†ç»„（空闲， +ç¹å¿™ï¼Œæ–°ç©ºé—²ï¼‰ï¼š + + + 1) 当CPU空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨äº†#次 + 2) 当CPU空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œä½†æ˜¯å‘çŽ°è´Ÿè½½æ— éœ€ + å‡è¡¡#次 + 3) 当CPU空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œè¯•å›¾è¿ç§»1个或更多 + 任务且失败了#次 + 4) 当CPU空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œå‘现ä¸å‡è¡¡ï¼ˆå¦‚果有） + #次 + 5) 当CPU空闲时，pull_task()在这个调度域ä¸è¢«è°ƒç”¨#次 + 6) 当CPUç©ºé—²æ—¶ï¼Œå°½ç®¡ç›®æ ‡ä»»åŠ¡æ˜¯çƒç¼“å˜çŠ¶æ€ï¼Œpull_task()ä¾ç„¶è¢«è°ƒç”¨#次 + 7) 当CPU空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œæœªèƒ½æ‰¾åˆ°æ›´ç¹å¿™çš„ + 队列#次 + 8) 当CPU空闲时，在调度域ä¸æ‰¾åˆ°äº†æ›´ç¹å¿™çš„队列，但未找到更ç¹å¿™çš„调度组 + #次 + 9) 当CPUç¹å¿™æ—¶ï¼Œload_balance()在这个调度域ä¸è¢«è°ƒç”¨äº†#次 + 10) 当CPUç¹å¿™æ—¶ï¼Œload_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œä½†æ˜¯å‘çŽ°è´Ÿè½½æ— éœ€ + å‡è¡¡#次 + 11) 当CPUç¹å¿™æ—¶ï¼Œload_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œè¯•å›¾è¿ç§»1个或更多 + 任务且失败了#次 + 12) 当CPUç¹å¿™æ—¶ï¼Œload_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œå‘现ä¸å‡è¡¡ï¼ˆå¦‚果有） + #次 + 13) 当CPUç¹å¿™æ—¶ï¼Œpull_task()在这个调度域ä¸è¢«è°ƒç”¨#次 + 14) 当CPUç¹å¿™æ—¶ï¼Œå°½ç®¡ç›®æ ‡ä»»åŠ¡æ˜¯çƒç¼“å˜çŠ¶æ€ï¼Œpull_task()ä¾ç„¶è¢«è°ƒç”¨#次 + 15) 当CPUç¹å¿™æ—¶ï¼Œload_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œæœªèƒ½æ‰¾åˆ°æ›´ç¹å¿™çš„ + 队列#次 + 16) 当CPUç¹å¿™æ—¶ï¼Œåœ¨è°ƒåº¦åŸŸä¸æ‰¾åˆ°äº†æ›´ç¹å¿™çš„队列，但未找到更ç¹å¿™çš„调度组 + #次 + 17) 当CPU新空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨äº†#次 + 18) 当CPU新空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œä½†æ˜¯å‘çŽ°è´Ÿè½½æ— éœ€ + å‡è¡¡#次 + 19) 当CPU新空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œè¯•å›¾è¿ç§»1个或更多 + 任务且失败了#次 + 20) 当CPU新空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œå‘现ä¸å‡è¡¡ï¼ˆå¦‚果有） + #次 + 21) 当CPU新空闲时，pull_task()在这个调度域ä¸è¢«è°ƒç”¨#次 + 22) 当CPUæ–°ç©ºé—²æ—¶ï¼Œå°½ç®¡ç›®æ ‡ä»»åŠ¡æ˜¯çƒç¼“å˜çŠ¶æ€ï¼Œpull_task()ä¾ç„¶è¢«è°ƒç”¨#次 + 23) 当CPU新空闲时，load_balance()在这个调度域ä¸è¢«è°ƒç”¨ï¼Œæœªèƒ½æ‰¾åˆ°æ›´ç¹å¿™çš„ + 队列#次 + 24) 当CPU新空闲时，在调度域ä¸æ‰¾åˆ°äº†æ›´ç¹å¿™çš„队列，但未找到更ç¹å¿™çš„调度组 + #次 + +接下æ¥çš„3个å—段是active_load_balance()函数的å„个统计数æ®ï¼š + + 25) active_load_balance()被调用了#次 + 26) active_load_balance()被调用，试图è¿ç§»1个或更多任务且失败了#次 + 27) active_load_balance()被调用，æˆåŠŸè¿ç§»äº†#次任务 + +接下æ¥çš„3个å—段是sched_balance_exec()函数的å„个统计数æ®ï¼š + + 28) sbe_cntä¸å†è¢«ä½¿ç”¨ + 29) sbe_balancedä¸å†è¢«ä½¿ç”¨ + 30) sbe_pushedä¸å†è¢«ä½¿ç”¨ + +接下æ¥çš„3个å—段是sched_balance_fork()函数的å„个统计数æ®ï¼š + + 31) sbf_cntä¸å†è¢«ä½¿ç”¨ + 32) sbf_balancedä¸å†è¢«ä½¿ç”¨ + 33) sbf_pushedä¸å†è¢«ä½¿ç”¨ + +接下æ¥çš„3个å—段是try_to_wake_up()函数的å„个统计数æ®ï¼š + + 34) 在这个调度域ä¸è°ƒç”¨try_to_wake_up()唤醒任务时，任务在调度域ä¸ä¸€ä¸ª + 和上次è¿è¡Œä¸åŒçš„æ–°CPU上è¿è¡Œäº†#次 + 35) 在这个调度域ä¸è°ƒç”¨try_to_wake_up()唤醒任务时，任务被è¿ç§»åˆ°å‘生唤醒 + çš„CPU次数为#ï¼Œå› ä¸ºè¯¥ä»»åŠ¡åœ¨åŽŸCPU是冷缓å˜çŠ¶æ€ + 36) 在这个调度域ä¸è°ƒç”¨try_to_wake_up()唤醒任务时，引å‘被动负载å‡è¡¡#次 + +/proc/<pid>/schedstat +--------------------- +schedstatsè¿˜æ·»åŠ äº†ä¸€ä¸ªæ–°çš„/proc/<pid>/schedstat文件，æ¥æ供一些进程级的 +相åŒä¿¡æ¯ã€‚这个文件ä¸ï¼Œæœ‰ä¸‰ä¸ªå—段与该进程相关： + + 1) 在CPU上è¿è¡ŒèŠ±è´¹çš„时间 + 2) 在è¿è¡Œé˜Ÿåˆ—上ç‰å¾…的时间 + 3) 在CPU上è¿è¡Œäº†#个时间片 + +å¯ä»¥å¾ˆå®¹æ˜“地编写一个程åºï¼Œåˆ©ç”¨è¿™äº›é¢å¤–çš„å—段æ¥æŠ¥å‘Šä¸€ä¸ªç‰¹å®šçš„进程或一组进程在 +调度器ç–ç•¥ä¸‹çš„è¡¨çŽ°å¦‚ä½•ã€‚è¿™æ ·çš„ç¨‹åºçš„一个简å•ç‰ˆæœ¬å¯åœ¨ä¸‹é¢çš„链接找到 + + http://eaglet.pdxhosts.com/rick/linux/schedstat/v12/latency.c diff --git a/Documentation/translations/zh_CN/vm/active_mm.rst b/Documentation/translations/zh_CN/vm/active_mm.rst new file mode 100644 index 000000000000..366609ea4f37 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/active_mm.rst @@ -0,0 +1,85 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/active_mm.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +========= +Active MM +========= + +这是一å°linux之父回å¤å¼€å‘者的一å°é‚®ä»¶ï¼Œæ‰€ä»¥ç¿»è¯‘时我尽é‡ä¿æŒé‚®ä»¶æ ¼å¼çš„完整。 + +:: + + List: linux-kernel + Subject: Re: active_mm + From: Linus Torvalds <torvalds () transmeta ! com> + Date: 1999-07-30 21:36:24 + + å› ä¸ºæˆ‘å¹¶ä¸ç»å¸¸å†™è§£é‡Šï¼Œæ‰€ä»¥å·²ç»æŠ„é€åˆ°linux-kernel邮件列表，而当我åšè¿™äº›ï¼Œ + 且更多的人在阅读它们时，我觉得棒æžäº†ã€‚ + + 1999å¹´7月30æ—¥ 星期五， David Mosberger 写é“： + > + > 是å¦æœ‰ä¸€ä¸ªç®€çŸçš„æ述，说明task_structä¸çš„ + > "mm" å’Œ "active_mm"应该如何使用？ (如果 + > 这个问题在邮件列表ä¸è®¨è®ºè¿‡ï¼Œæˆ‘表示æ‰æ„--我刚 + > 刚度å‡å›žæ¥ï¼Œæœ‰ä¸€æ®µæ—¶é—´æ²¡èƒ½å…³æ³¨linux-kernel了）。 + + 基本上，新的设定是： + + - 我们有“真实地å€ç©ºé—´â€å’Œâ€œåŒ¿å地å€ç©ºé—´â€ã€‚区别在于，匿å地å€ç©ºé—´æ ¹æœ¬ä¸å…³å¿ƒç”¨ + 户级页表，所以当我们åšä¸Šä¸‹æ–‡åˆ‡æ¢åˆ°åŒ¿å地å€ç©ºé—´æ—¶ï¼Œæˆ‘们åªæ˜¯è®©ä»¥å‰çš„地å€ç©ºé—´ + 处于活动状æ€ã€‚ + + 一个“匿å地å€ç©ºé—´â€çš„明显用途是任何ä¸éœ€è¦ä»»ä½•ç”¨æˆ·æ˜ 射的线程--æ‰€æœ‰çš„å†…æ ¸çº¿ + 程基本上都属于这一类，但å³ä½¿æ˜¯â€œçœŸæ£çš„â€çº¿ç¨‹ä¹Ÿå¯ä»¥æš‚æ—¶è¯´åœ¨ä¸€å®šæ—¶é—´å†…å®ƒä»¬ä¸ + 会对用户空间感兴趣，调度器ä¸å¦¨è¯•ç€é¿å…在切æ¢VM状æ€ä¸Šæµªè´¹æ—¶é—´ã€‚ç›®å‰åªæœ‰è€ + å¼çš„bdflush sync能åšåˆ°è¿™ä¸€ç‚¹ã€‚ + + - “tsk->mmâ€ æŒ‡å‘ â€œçœŸå®žåœ°å€ç©ºé—´â€ã€‚对于一个匿å进程æ¥è¯´ï¼Œtsk->mm将是NULL， + å…¶é€»è¾‘åŽŸå› æ˜¯åŒ¿åè¿›ç¨‹å®žé™…ä¸Šæ ¹æœ¬å°± “没有†真æ£çš„地å€ç©ºé—´ã€‚ + + - 然而，我们显然需è¦è·Ÿè¸ªæˆ‘ä»¬ä¸ºè¿™æ ·çš„åŒ¿å用户“å·ç”¨â€äº†å“ªä¸ªåœ°å€ç©ºé—´ã€‚为æ¤ï¼Œæˆ‘们 + 有 “tsk->active_mmâ€ï¼Œå®ƒæ˜¾ç¤ºäº†å½“å‰æ´»åŠ¨çš„地å€ç©ºé—´æ˜¯ä»€ä¹ˆã€‚ + + 规则是，对于一个有真实地å€ç©ºé—´çš„进程（å³tsk->mm是 non-NULL），active_mm + 显然必须与真实的mm相åŒã€‚ + + 对于一个匿å进程，tsk->mm == NULL，而tsk->active_mm是匿å进程è¿è¡Œæ—¶ + “借用â€çš„mm。当匿å进程被调度走时，借用的地å€ç©ºé—´è¢«è¿”回并清除。 + + 为了支æŒæ‰€æœ‰è¿™äº›ï¼Œâ€œstruct mm_structâ€çŽ°åœ¨æœ‰ä¸¤ä¸ªè®¡æ•°å™¨ï¼šä¸€ä¸ªæ˜¯ “mm_users†+ 计数器，å³æœ‰å¤šå°‘ “真æ£çš„地å€ç©ºé—´ç”¨æˆ·â€ï¼Œå¦ä¸€ä¸ªæ˜¯ “mm_countâ€è®¡æ•°å™¨ï¼Œå³ “lazy†+ 用户（å³åŒ¿å用户）的数é‡ï¼Œå¦‚果有任何真æ£çš„ç”¨æˆ·ï¼Œåˆ™åŠ 1。 + + 通常情况下，至少有一个真æ£çš„用户，但也å¯èƒ½æ˜¯çœŸæ£çš„用户在å¦ä¸€ä¸ªCPU上退出，而 + 一个lazy的用户ä»åœ¨æ´»åŠ¨ï¼Œæ‰€ä»¥ä½ å®žé™…ä¸Šå¾—åˆ°çš„æƒ…å†µæ˜¯ï¼Œä½ æœ‰ä¸€ä¸ªåœ°å€ç©ºé—´ **åª** + 被lazy的用户使用。这通常是一个çŸæš‚的生命周期状æ€ï¼Œå› 为一旦这个线程被安排给一 + 个真æ£çš„线程，这个 “僵尸†mmå°±ä¼šè¢«é‡Šæ”¾ï¼Œå› ä¸º “mm_countâ€å˜æˆäº†é›¶ã€‚ + + å¦å¤–，一个新的规则是，**没有人** å†æŠŠ “init_mm†作为一个真æ£çš„MM了。 + “init_mmâ€åº”该被认为åªæ˜¯ä¸€ä¸ª “没有其他上下文时的lazy上下文â€ï¼Œäº‹å®žä¸Šï¼Œå®ƒä¸» + è¦æ˜¯åœ¨å¯åŠ¨æ—¶ä½¿ç”¨ï¼Œå½“时还没有真æ£çš„VMè¢«åˆ›å»ºã€‚å› æ¤ï¼Œç”¨æ¥æ£€æŸ¥çš„代ç + + if (current->mm == &init_mm) + + 一般æ¥è¯´ï¼Œåº”该用 + + if (!current->mm) + + å–代上é¢çš„写法（这更有æ„义--测试基本上是 “我们是å¦æœ‰ä¸€ä¸ªç”¨æˆ·çŽ¯å¢ƒâ€ï¼Œå¹¶ä¸”通常 + 由缺页异常处ç†ç¨‹åºå’Œç±»ä¼¼çš„东西æ¥å®Œæˆï¼‰ã€‚ + + 总之，我刚æ‰åœ¨ftp.kernel.org上放了一个pre-patch-2.3.13-1ï¼Œå› ä¸ºå®ƒç¨å¾®æ”¹ + å˜äº†æŽ¥å£ä»¥é€‚é…alpha（è°ä¼šæƒ³åˆ°å‘¢ï¼Œä½†alpha体系结构上下文切æ¢ä»£ç 实际上最终是 + 最丑陋的之一--ä¸åƒå…¶ä»–架构的MM和寄å˜å™¨çŠ¶æ€æ˜¯åˆ†å¼€çš„，alphaçš„PALcode将两者 + 连接起æ¥ï¼Œä½ 需è¦åŒæ—¶åˆ‡æ¢ä¸¤è€…）。 + + (文档æ¥æº http://marc.info/?l=linux-kernel&m=93337278602211&w=2) diff --git a/Documentation/translations/zh_CN/vm/balance.rst b/Documentation/translations/zh_CN/vm/balance.rst new file mode 100644 index 000000000000..e98a47ef24a8 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/balance.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/balance.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +======== +内å˜å¹³è¡¡ +======== + +2000å¹´1月开始，作者：Kanoj Sarcar <kanoj@sgi.com> + +对于 !__GFP_HIGH å’Œ !__GFP_KSWAPD_RECLAIM 以åŠéž __GFP_IO 的分é…，需è¦è¿›è¡Œ +内å˜å¹³è¡¡ã€‚ + +调用者é¿å…å›žæ”¶çš„ç¬¬ä¸€ä¸ªåŽŸå› æ˜¯è°ƒç”¨è€…ç”±äºŽæŒæœ‰è‡ªæ—‹é”或处于ä¸æ–环境ä¸è€Œæ— 法ç¡çœ 。第二个 +åŽŸå› å¯èƒ½æ˜¯ï¼Œè°ƒç”¨è€…æ„¿æ„在ä¸äº§ç”Ÿé¡µé¢å›žæ”¶å¼€é”€çš„情况下分é…失败。这å¯èƒ½å‘生在有0阶回退 +选项的机会主义高阶分é…请求ä¸ã€‚在这ç§æƒ…况下，调用者å¯èƒ½ä¹Ÿå¸Œæœ›é¿å…唤醒kswapd。 + +__GFP_IO分é…请求是为了防æ¢æ–‡ä»¶ç³»ç»Ÿæ»é”。 + +在没有éžç¡çœ 分é…请求的情况下，åšå¹³è¡¡ä¼¼ä¹Žæ˜¯æœ‰å®³çš„。页é¢å›žæ”¶å¯ä»¥è¢«æ‡’散地å¯åŠ¨ï¼Œä¹Ÿå°±æ˜¯ +说，åªæœ‰åœ¨éœ€è¦çš„时候（也就是区域的空闲内å˜ä¸º0），而ä¸æ˜¯è®©å®ƒæˆä¸ºä¸€ä¸ªä¸»åŠ¨çš„过程。 + +ä¹Ÿå°±æ˜¯è¯´ï¼Œå†…æ ¸åº”è¯¥å°è¯•ä»Žç›´æŽ¥æ˜ å°„æ± ä¸æ»¡è¶³å¯¹ç›´æŽ¥æ˜ 射页的请求，而ä¸æ˜¯å›žé€€åˆ°dmaæ± ä¸ï¼Œ +è¿™æ ·å°±å¯ä»¥ä¿æŒdmaæ± ä¸ºdma请求（ä¸ç®¡æ˜¯ä¸æ˜¯åŽŸåçš„ï¼‰æ‰€å¡«å……ã€‚ç±»ä¼¼çš„äº‰è®ºä¹Ÿé€‚ç”¨äºŽé«˜å†…å˜ +å’Œç›´æŽ¥æ˜ å°„çš„é¡µé¢ã€‚相å，如果有很多空闲的dma页，最好是通过从dmaæ± ä¸åˆ†é…一个æ¥æ»¡è¶³ +常规的内å˜è¯·æ±‚，而ä¸æ˜¯äº§ç”Ÿå¸¸è§„区域平衡的开销。 + +在2.2ä¸ï¼Œåªæœ‰å½“空闲页总数低于总内å˜çš„1/64时，æ‰ä¼šå¯åŠ¨å†…å˜å¹³è¡¡/页é¢å›žæ”¶ã€‚如果dma +和常规内å˜çš„比例åˆé€‚，å³ä½¿dma区完全空了，也很å¯èƒ½ä¸ä¼šè¿›è¡Œå¹³è¡¡ã€‚2.2å·²ç»åœ¨ä¸åŒå†…å˜ +大å°çš„生产机器上è¿è¡Œï¼Œå³ä½¿æœ‰è¿™ä¸ªé—®é¢˜å˜åœ¨ï¼Œä¼¼ä¹Žä¹Ÿåšå¾—ä¸é”™ã€‚在2.3ä¸ï¼Œç”±äºŽHIGHMEMçš„ +å˜åœ¨ï¼Œè¿™ä¸ªé—®é¢˜å˜å¾—æ›´åŠ ä¸¥é‡ã€‚ + +在2.3ä¸ï¼ŒåŒºåŸŸå¹³è¡¡å¯ä»¥ç”¨ä¸¤ç§æ–¹å¼ä¹‹ä¸€æ¥å®Œæˆï¼šæ ¹æ®åŒºåŸŸçš„大å°ï¼ˆå¯èƒ½æ˜¯ä½Žçº§åŒºåŸŸçš„大å°ï¼‰ï¼Œ +我们å¯ä»¥åœ¨åˆå§‹åŒ–阶段决定在平衡任何区域时应该争å–多少空闲页。好的方é¢æ˜¯ï¼Œåœ¨å¹³è¡¡çš„æ—¶ +候，我们ä¸éœ€è¦çœ‹ä½Žçº§åŒºçš„大å°ï¼Œåçš„æ–¹é¢æ˜¯ï¼Œæˆ‘们å¯èƒ½ä¼šå› 为忽略低级区å¯èƒ½è¾ƒä½Žçš„使用率 +而åšè¿‡äºŽé¢‘ç¹çš„平衡。å¦å¤–，åªè¦å¯¹åˆ†é…程åºç¨ä½œä¿®æ”¹ï¼Œå°±æœ‰å¯èƒ½å°†memclass()å®ç®€åŒ–为一 +个简å•çš„ç‰å¼ã€‚ + +å¦ä¸€ä¸ªå¯èƒ½çš„解决方案是，我们åªåœ¨ä¸€ä¸ªåŒº **å’Œ** 其所有低级区的空闲内å˜ä½ŽäºŽè¯¥åŒºåŠå…¶ +低级区总内å˜çš„1/64时进行平衡。这就解决了2.2的平衡问题，并尽å¯èƒ½åœ°ä¿æŒäº†ä¸Ž2.2行为 +的接近。å¦å¤–，平衡算法在å„ç§æž¶æž„上的工作方å¼ä¹Ÿæ˜¯ä¸€æ ·çš„，这些架构有ä¸åŒæ•°é‡å’Œç±»åž‹çš„ +内å˜åŒºã€‚如果我们想å˜å¾—更花哨一点，我们å¯ä»¥åœ¨æœªæ¥ä¸ºä¸åŒåŒºåŸŸçš„自由页é¢åˆ†é…ä¸åŒçš„æƒé‡ã€‚ + +请注æ„，如果普通区的大å°ä¸Ždma区相比是巨大的，那么在决定是å¦å¹³è¡¡æ™®é€šåŒºçš„时候，考虑 +空闲的dma页就å˜å¾—ä¸é‚£ä¹ˆé‡è¦äº†ã€‚那么第一个解决方案就å˜å¾—更有å¸å¼•åŠ›ã€‚ + +所附的补ä¸å®žçŽ°äº†ç¬¬äºŒä¸ªè§£å†³æ–¹æ¡ˆã€‚它还 “修å¤â€äº†ä¸¤ä¸ªé—®é¢˜ï¼šé¦–先，在低内å˜æ¡ä»¶ä¸‹ï¼Œkswapd +被唤醒，就åƒ2.2ä¸çš„éžç¡çœ 分é…。第二，HIGHMEM区也被平衡了，以便给replace_with_highmem() +一个争å–获得HIGHMEM页的机会，åŒæ—¶ç¡®ä¿HIGHMEM分é…ä¸ä¼šè½å›žæ™®é€šåŒºã€‚这也确ä¿äº†HIGHMEM +页ä¸ä¼šè¢«æ³„露（例如，在一个HIGHMEM页在交æ¢ç¼“å˜ä¸ä½†æ²¡æœ‰è¢«ä»»ä½•äººä½¿ç”¨çš„情况下）。 + +kswapd还需è¦çŸ¥é“它应该平衡哪些区。kswapd主è¦æ˜¯åœ¨æ— 法进行平衡的情况下需è¦çš„，å¯èƒ½ +æ˜¯å› ä¸ºæ‰€æœ‰çš„åˆ†é…请求都æ¥è‡ªä¸æ–上下文，而所有的进程上下文都在ç¡çœ 。对于2.3， +kswapd并ä¸çœŸæ£éœ€è¦å¹³è¡¡é«˜å†…å˜åŒºï¼Œå› 为ä¸æ–上下文并ä¸è¯·æ±‚高内å˜é¡µã€‚kswapd看zone +结构体ä¸çš„zone_wake_kswapdå—段æ¥å†³å®šä¸€ä¸ªåŒºæ˜¯å¦éœ€è¦å¹³è¡¡ã€‚ + +如果从进程内å˜å’Œshmä¸å·å–页é¢å¯ä»¥å‡è½»è¯¥é¡µé¢èŠ‚点ä¸ä»»ä½•åŒºçš„内å˜åŽ‹åŠ›ï¼Œè€Œè¯¥åŒºçš„内å˜åŽ‹åŠ› +å·²ç»ä½ŽäºŽå…¶æ°´ä½ï¼Œåˆ™ä¼šè¿›è¡Œå·å–。 + +watemark[WMARK_MIN/WMARK_LOW/WMARK_HIGH]/low_on_memory/zone_wake_kswapd： +这些是æ¯ä¸ªåŒºçš„å—段，用于确定一个区何时需è¦å¹³è¡¡ã€‚当页é¢æ•°ä½ŽäºŽæ°´ä½[WMARK_MIN]时， +hysteric çš„å—段low_on_memory被设置。这个å—段会一直被设置，直到空闲页数å˜æˆæ°´ä½ +[WMARK_HIGH]。当low_on_memory被设置时，页é¢åˆ†é…请求将å°è¯•é‡Šæ”¾è¯¥åŒºåŸŸçš„一些页é¢ï¼ˆå¦‚æžœ +请求ä¸è®¾ç½®äº†GFP_WAIT）。与æ¤ç›¸å的是，决定唤醒kswapd以释放一些区的页。这个决定ä¸æ˜¯åŸºäºŽ +hysteresis 的，而是当空闲页的数é‡ä½ŽäºŽwatermark[WMARK_LOW]时就会进行；在这ç§æƒ…况下， +zone_wake_kswapd也被设置。 + + +我所å¬åˆ°çš„（超棒的）想法： + +1. 动æ€ç»åŽ†åº”该影å“平衡：å¯ä»¥è·Ÿè¸ªä¸€ä¸ªåŒºçš„失败请求的数é‡ï¼Œå¹¶å馈到平衡方案ä¸ï¼ˆjalvo@mbay.net）。 + +2. 实现一个类似于replace_with_highmem()çš„replace_with_regular()，以ä¿ç•™dma页é¢ã€‚ + (lkd@tantalophile.demon.co.uk) diff --git a/Documentation/translations/zh_CN/vm/damon/api.rst b/Documentation/translations/zh_CN/vm/damon/api.rst new file mode 100644 index 000000000000..21143eea4ebe --- /dev/null +++ b/Documentation/translations/zh_CN/vm/damon/api.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/vm/damon/api.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +======= +APIå‚考 +======= + +å†…æ ¸ç©ºé—´çš„ç¨‹åºå¯ä»¥ä½¿ç”¨ä¸‹é¢çš„APIæ¥ä½¿ç”¨DAMONçš„æ¯ä¸ªåŠŸèƒ½ã€‚ä½ æ‰€éœ€è¦åšçš„就是引用 ``damon.h`` ， +它ä½äºŽæºä»£ç æ ‘çš„include/linux/。 + +结构体 +====== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/damon.h + + +函数 +==== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +mm/damon/core.c diff --git a/Documentation/translations/zh_CN/vm/damon/design.rst b/Documentation/translations/zh_CN/vm/damon/design.rst new file mode 100644 index 000000000000..05f66c02740a --- /dev/null +++ b/Documentation/translations/zh_CN/vm/damon/design.rst @@ -0,0 +1,139 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/vm/damon/design.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +==== +设计 +==== + +å¯é…置的层 +========== + +DAMONæ供了数æ®è®¿é—®ç›‘控功能，åŒæ—¶ä½¿å…¶å‡†ç¡®æ€§å’Œå¼€é”€å¯æŽ§ã€‚基本的访问监控需è¦ä¾èµ–äºŽç›®æ ‡åœ°å€ç©ºé—´ +并为之优化的基元。å¦ä¸€æ–¹é¢ï¼Œä½œä¸ºDAMONçš„æ ¸å¿ƒï¼Œå‡†ç¡®æ€§å’Œå¼€é”€çš„æƒè¡¡æœºåˆ¶æ˜¯åœ¨çº¯é€»è¾‘空间ä¸ã€‚DAMON +将这两部分分离在ä¸åŒçš„层ä¸ï¼Œå¹¶å®šä¹‰äº†å®ƒçš„接å£ï¼Œä»¥å…许å„ç§ä½Žå±‚æ¬¡çš„åŸºå…ƒå®žçŽ°ä¸Žæ ¸å¿ƒé€»è¾‘çš„é…置。 + +由于这ç§åˆ†ç¦»çš„设计和å¯é…置的接å£ï¼Œç”¨æˆ·å¯ä»¥é€šè¿‡é…ç½®æ ¸å¿ƒé€»è¾‘å’Œé€‚å½“çš„ä½Žçº§åŸºå…ƒå®žçŽ°æ¥æ‰©å±•DAMONçš„ +任何地å€ç©ºé—´ã€‚如果没有æä¾›åˆé€‚的，用户å¯ä»¥è‡ªå·±å®žçŽ°åŸºå…ƒã€‚ + +例如，物ç†å†…å˜ã€è™šæ‹Ÿå†…å˜ã€äº¤æ¢ç©ºé—´ã€é‚£äº›ç‰¹å®šçš„进程ã€NUMA节点ã€æ–‡ä»¶å’Œæ”¯æŒçš„内å˜è®¾å¤‡å°†è¢«æ”¯æŒã€‚ +å¦å¤–，如果æŸäº›æž¶æž„或设备支æŒç‰¹æ®Šçš„优化访问检查基元，这些基元将很容易被é…置。 + + +特定地å€ç©ºé—´åŸºå…ƒçš„å‚考实现 +========================== + +基本访问监测的低级基元被定义为两部分。: + +1. 确定地å€ç©ºé—´çš„ç›‘æµ‹ç›®æ ‡åœ°å€èŒƒå›´ +2. ç›®æ ‡ç©ºé—´ä¸ç‰¹å®šåœ°å€èŒƒå›´çš„访问检查。 + +DAMONç›®å‰ä¸ºç‰©ç†å’Œè™šæ‹Ÿåœ°å€ç©ºé—´æ供了基元的实现。下é¢ä¸¤ä¸ªå°èŠ‚æ述了这些工作的方å¼ã€‚ + + +基于VMAçš„ç›®æ ‡åœ°å€èŒƒå›´æž„é€ +------------------------- + +这仅仅是针对虚拟地å€ç©ºé—´åŸºå…ƒçš„实现。对于物ç†åœ°å€ç©ºé—´ï¼Œåªæ˜¯è¦æ±‚ç”¨æˆ·æ‰‹åŠ¨è®¾ç½®ç›‘æŽ§ç›®æ ‡åœ°å€èŒƒå›´ã€‚ + +在进程的超级巨大的虚拟地å€ç©ºé—´ä¸ï¼Œåªæœ‰å°éƒ¨åˆ†è¢«æ˜ 射到物ç†å†…å˜å¹¶è¢«è®¿é—®ã€‚å› æ¤ï¼Œè·Ÿè¸ªæœªæ˜ 射的地 +å€åŒºåŸŸåªæ˜¯ä¸€ç§æµªè´¹ã€‚然而，由于DAMONå¯ä»¥ä½¿ç”¨è‡ªé€‚应区域调整机制æ¥å¤„ç†ä¸€å®šç¨‹åº¦çš„噪声，所以严 +æ ¼æ¥è¯´ï¼Œè·Ÿè¸ªæ¯ä¸€ä¸ªæ˜ 射并ä¸æ˜¯å¿…须的，但在æŸäº›æƒ…å†µä¸‹ç”šè‡³ä¼šäº§ç”Ÿå¾ˆé«˜çš„å¼€é”€ã€‚ä¹Ÿå°±æ˜¯è¯´ï¼Œç›‘æµ‹ç›®æ ‡ +å†…éƒ¨è¿‡äºŽå·¨å¤§çš„æœªæ˜ å°„åŒºåŸŸåº”è¯¥è¢«ç§»é™¤ï¼Œä»¥ä¸å 用自适应机制的时间。 + +å‡ºäºŽè¿™ä¸ªåŽŸå› ï¼Œè¿™ä¸ªå®žçŽ°å°†å¤æ‚çš„æ˜ å°„è½¬æ¢ä¸ºä¸‰ä¸ªä¸åŒçš„区域，覆盖地å€ç©ºé—´çš„æ¯ä¸ªæ˜ 射区域。这三个 +区域之间的两个空隙是给定地å€ç©ºé—´ä¸ä¸¤ä¸ªæœ€å¤§çš„æœªæ˜ å°„åŒºåŸŸã€‚è¿™ä¸¤ä¸ªæœ€å¤§çš„æœªæ˜ å°„åŒºåŸŸæ˜¯å †å’Œæœ€ä¸Šé¢ +çš„mmap()区域之间的间隙，以åŠåœ¨å¤§å¤šæ•°æƒ…况下最下é¢çš„mmap()åŒºåŸŸå’Œå †ä¹‹é—´çš„é—´éš™ã€‚å› ä¸ºè¿™äº›é—´éš™ +在通常的地å€ç©ºé—´ä¸æ˜¯å¼‚常巨大的，排除这些间隙就足以åšå‡ºåˆç†çš„æƒè¡¡ã€‚下é¢è¯¦ç»†è¯´æ˜Žäº†è¿™ä¸€ç‚¹:: + + <heap> + <BIG UNMAPPED REGION 1> + <uppermost mmap()-ed region> + (small mmap()-ed regions and munmap()-ed regions) + <lowermost mmap()-ed region> + <BIG UNMAPPED REGION 2> + <stack> + + +基于PTE访问ä½çš„访问检查 +----------------------- + +物ç†å’Œè™šæ‹Ÿåœ°å€ç©ºé—´çš„实现都使用PTE Accessed-bit进行基本访问检查。唯一的区别在于从地å€ä¸ +找到相关的PTE访问ä½çš„æ–¹å¼ã€‚虚拟地å€çš„实现是为该地å€çš„ç›®æ ‡ä»»åŠ¡æŸ¥æ‰¾é¡µè¡¨ï¼Œè€Œç‰©ç†åœ°å€çš„实现则 +是查找与该地å€æœ‰æ˜ 射关系的æ¯ä¸€ä¸ªé¡µè¡¨ã€‚通过这ç§æ–¹å¼ï¼Œå®žçŽ°è€…æ‰¾åˆ°å¹¶æ¸…é™¤ä¸‹ä¸€ä¸ªé‡‡æ ·ç›®æ ‡åœ°å€çš„ä½ï¼Œ +并检查该ä½æ˜¯å¦åœ¨ä¸€ä¸ªé‡‡æ ·å‘¨æœŸåŽå†æ¬¡è®¾ç½®ã€‚è¿™å¯èƒ½ä¼šå¹²æ‰°å…¶ä»–使用访问ä½çš„å†…æ ¸å系统，å³ç©ºé—²é¡µè·Ÿ +踪和回收逻辑。为了é¿å…è¿™ç§å¹²æ‰°ï¼ŒDAMON使其与空闲页é¢è·Ÿè¸ªç›¸äº’排斥，并使用 ``PG_idle`` å’Œ +``PG_young`` 页é¢æ ‡å¿—æ¥è§£å†³ä¸Žå›žæ”¶é€»è¾‘的冲çªï¼Œå°±åƒç©ºé—²é¡µé¢è·Ÿè¸ªé‚£æ ·ã€‚ + + +独立于地å€ç©ºé—´çš„æ ¸å¿ƒæœºåˆ¶ +======================== + +下é¢å››ä¸ªéƒ¨åˆ†åˆ†åˆ«æ述了DAMONçš„æ ¸å¿ƒæœºåˆ¶å’Œäº”ä¸ªç›‘æµ‹å±žæ€§ï¼Œå³ ``é‡‡æ ·é—´éš”`` 〠``èšé›†é—´éš”`` 〠+``区域更新间隔`` 〠``最å°åŒºåŸŸæ•°`` å’Œ ``最大区域数`` 。 + + +访问频率监测 +------------ + +DAMON的输出显示了在给定的时间内哪些页é¢çš„访问频率是多少。访问频率的分辨率是通过设置 +``é‡‡æ ·é—´éš”`` å’Œ ``èšé›†é—´éš”`` æ¥æŽ§åˆ¶çš„。详细地说，DAMON检查æ¯ä¸ª ``é‡‡æ ·é—´éš”`` å¯¹æ¯ +个页é¢çš„访问，并将结果汇总。æ¢å¥è¯è¯´ï¼Œè®¡ç®—æ¯ä¸ªé¡µé¢çš„访问次数。在æ¯ä¸ª ``èšåˆé—´éš”`` 过 +去åŽï¼ŒDAMON调用先å‰ç”±ç”¨æˆ·æ³¨å†Œçš„回调函数，以便用户å¯ä»¥é˜…读èšåˆçš„结果，然åŽå†æ¸…除这些结 +果。这å¯ä»¥ç”¨ä»¥ä¸‹ç®€å•çš„伪代ç æ¥æè¿°:: + + while monitoring_on: + for page in monitoring_target: + if accessed(page): + nr_accesses[page] += 1 + if time() % aggregation_interval == 0: + for callback in user_registered_callbacks: + callback(monitoring_target, nr_accesses) + for page in monitoring_target: + nr_accesses[page] = 0 + sleep(sampling interval) + +è¿™ç§æœºåˆ¶çš„监测开销将éšç€ç›®æ ‡å·¥ä½œè´Ÿè½½è§„模的增长而任æ„å¢žåŠ ã€‚ + + +åŸºäºŽåŒºåŸŸçš„æŠ½æ ·è°ƒæŸ¥ +------------------ + +为了é¿å…å¼€é”€çš„æ— é™åˆ¶å¢žåŠ ，DAMONå°†å‡å®šå…·æœ‰ç›¸åŒè®¿é—®é¢‘率的相邻页é¢å½’入一个区域。åªè¦ä¿æŒ +这个å‡è®¾ï¼ˆä¸€ä¸ªåŒºåŸŸå†…的页é¢å…·æœ‰ç›¸åŒçš„访问频率），该区域内就åªéœ€è¦æ£€æŸ¥ä¸€ä¸ªé¡µé¢ã€‚å› æ¤ï¼Œå¯¹ +于æ¯ä¸ª ``é‡‡æ ·é—´éš”`` ，DAMON在æ¯ä¸ªåŒºåŸŸä¸éšæœºæŒ‘选一个页é¢ï¼Œç‰å¾…一个 ``é‡‡æ ·é—´éš”`` ，检 +查该页é¢æ˜¯å¦åŒæ—¶è¢«è®¿é—®ï¼Œå¦‚æžœè¢«è®¿é—®åˆ™å¢žåŠ è¯¥åŒºåŸŸçš„è®¿é—®é¢‘çŽ‡ã€‚å› æ¤ï¼Œç›‘测开销是å¯ä»¥é€šè¿‡è®¾ç½® +区域的数é‡æ¥æŽ§åˆ¶çš„。DAMONå…许用户设置最å°å’Œæœ€å¤§çš„区域数é‡æ¥è¿›è¡Œæƒè¡¡ã€‚ + +然而，如果å‡è®¾æ²¡æœ‰å¾—到ä¿è¯ï¼Œè¿™ä¸ªæ–¹æ¡ˆå°±ä¸èƒ½ä¿æŒè¾“出的质é‡ã€‚ + + +适应性区域调整 +-------------- + +å³ä½¿æœ€åˆçš„ç›‘æµ‹ç›®æ ‡åŒºåŸŸè¢«å¾ˆå¥½åœ°æž„å»ºä»¥æ»¡è¶³å‡è®¾ï¼ˆåŒä¸€åŒºåŸŸå†…的页é¢å…·æœ‰ç›¸ä¼¼çš„访问频率），数 +æ®è®¿é—®æ¨¡å¼ä¹Ÿä¼šè¢«åŠ¨æ€åœ°æ”¹å˜ã€‚这将导致监测质é‡ä¸‹é™ã€‚为了尽å¯èƒ½åœ°ä¿æŒå‡è®¾ï¼ŒDAMONæ ¹æ®æ¯ä¸ª +区域的访问频率自适应地进行åˆå¹¶å’Œæ‹†åˆ†ã€‚ + +对于æ¯ä¸ª ``èšé›†åŒºé—´`` ，它比较相邻区域的访问频率，如果频率差异较å°ï¼Œå°±åˆå¹¶è¿™äº›åŒºåŸŸã€‚ +然åŽï¼Œåœ¨å®ƒæŠ¥å‘Šå¹¶æ¸…除æ¯ä¸ªåŒºåŸŸçš„èšåˆæŽ¥å…¥é¢‘率åŽï¼Œå¦‚果区域总数ä¸è¶…过用户指定的最大区域数， +它将æ¯ä¸ªåŒºåŸŸæ‹†åˆ†ä¸ºä¸¤ä¸ªæˆ–三个区域。 + +通过这ç§æ–¹å¼ï¼ŒDAMONæ供了其最佳的质é‡å’Œæœ€å°çš„开销，åŒæ—¶ä¿æŒäº†ç”¨æˆ·ä¸ºå…¶æƒè¡¡è®¾å®šçš„ç•Œé™ã€‚ + + +动æ€ç›®æ ‡ç©ºé—´æ›´æ–°å¤„ç† +-------------------- + +ç›‘æµ‹ç›®æ ‡åœ°å€èŒƒå›´å¯ä»¥åŠ¨æ€æ”¹å˜ã€‚例如，虚拟内å˜å¯ä»¥åŠ¨æ€åœ°è¢«æ˜ å°„å’Œè§£æ˜ å°„ã€‚ç‰©ç†å†…å˜å¯ä»¥è¢« +çƒæ’拔。 + +由于在æŸäº›æƒ…况下å˜åŒ–å¯èƒ½ç›¸å½“频ç¹ï¼ŒDAMON检查动æ€å†…å˜æ˜ å°„çš„å˜åŒ–，并仅在用户指定的时间 +间隔（ ``区域更新间隔`` ï¼‰å†…å°†å…¶åº”ç”¨äºŽæŠ½è±¡çš„ç›®æ ‡åŒºåŸŸã€‚ diff --git a/Documentation/translations/zh_CN/vm/damon/faq.rst b/Documentation/translations/zh_CN/vm/damon/faq.rst new file mode 100644 index 000000000000..07b4ac19407d --- /dev/null +++ b/Documentation/translations/zh_CN/vm/damon/faq.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/vm/damon/faq.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +======== +常è§é—®é¢˜ +======== + +为什么是一个新的å系统，而ä¸æ˜¯æ‰©å±•perf或其他用户空间工具？ +========================================================== + +é¦–å…ˆï¼Œå› ä¸ºå®ƒéœ€è¦å°½å¯èƒ½çš„è½»é‡çº§ï¼Œä»¥ä¾¿å¯ä»¥åœ¨çº¿ä½¿ç”¨ï¼Œæ‰€ä»¥åº”该é¿å…任何ä¸å¿…è¦çš„å¼€é”€ï¼Œå¦‚å†…æ ¸-用户 +空间的上下文切æ¢æˆæœ¬ã€‚第二，DAMONçš„ç›®æ ‡æ˜¯è¢«åŒ…æ‹¬å†…æ ¸åœ¨å†…çš„å…¶ä»–ç¨‹åºæ‰€ä½¿ç”¨ã€‚å› æ¤ï¼Œå¯¹ç‰¹å®šå·¥å…· +（如perf）的ä¾èµ–性是ä¸å¯å–的。这就是DAMONåœ¨å†…æ ¸ç©ºé—´å®žçŽ°çš„ä¸¤ä¸ªæœ€å¤§çš„åŽŸå› ã€‚ + + +“闲置页é¢è·Ÿè¸ªâ€ 或 “perf mem†å¯ä»¥æ›¿ä»£DAMONå—？ +============================================== + +闲置页跟踪是物ç†åœ°å€ç©ºé—´è®¿é—®æ£€æŸ¥çš„一个低层次的原始方法。“perf memâ€ä¹Ÿæ˜¯ç±»ä¼¼çš„，尽管它å¯ä»¥ +ä½¿ç”¨é‡‡æ ·æ¥å‡å°‘开销。å¦ä¸€æ–¹é¢ï¼ŒDAMON是一个更高层次的框架，用于监控å„ç§åœ°å€ç©ºé—´ã€‚它专注于内 +å˜ç®¡ç†ä¼˜åŒ–，并æä¾›å¤æ‚的精度/开销处ç†æœºåˆ¶ã€‚å› æ¤ï¼Œâ€œç©ºé—²é¡µé¢è·Ÿè¸ªâ€ å’Œ “perf mem†å¯ä»¥æä¾› +DAMON输出的一个å集，但ä¸èƒ½æ›¿ä»£DAMON。 + + +DAMON是å¦åªæ”¯æŒè™šæ‹Ÿå†…å˜ï¼Ÿ +========================= + +ä¸ï¼ŒDAMONçš„æ ¸å¿ƒæ˜¯ç‹¬ç«‹äºŽåœ°å€ç©ºé—´çš„。用户å¯ä»¥åœ¨DAMONæ ¸å¿ƒä¸Šå®žçŽ°å’Œé…置特定地å€ç©ºé—´çš„低级原始 +éƒ¨åˆ†ï¼ŒåŒ…æ‹¬ç›‘æµ‹ç›®æ ‡åŒºåŸŸçš„æž„é€ å’Œå®žé™…çš„è®¿é—®æ£€æŸ¥ã€‚é€šè¿‡è¿™ç§æ–¹å¼ï¼ŒDAMON用户å¯ä»¥ç”¨ä»»ä½•è®¿é—®æ£€æŸ¥æŠ€ +术æ¥ç›‘测任何地å€ç©ºé—´ã€‚ + +尽管如æ¤ï¼ŒDAMON默认为虚拟内å˜å’Œç‰©ç†å†…å˜æ供了基于vma/rmap跟踪和PTE访问ä½æ£€æŸ¥çš„地å€ç©ºé—´ +相关功能的实现，以供å‚考和方便使用。 + + +我å¯ä»¥ç®€å•åœ°ç›‘测页é¢çš„粒度å—？ +============================== + +æ˜¯çš„ï¼Œä½ å¯ä»¥é€šè¿‡è®¾ç½® ``min_nr_regions`` 属性高于工作集大å°é™¤ä»¥é¡µé¢å¤§å°çš„值æ¥å®žçŽ°ã€‚ +å› ä¸ºç›‘è§†ç›®æ ‡åŒºåŸŸçš„å¤§å°è¢«å¼ºåˆ¶ä¸º ``>=page size`` ，所以区域分割ä¸ä¼šäº§ç”Ÿä»»ä½•å½±å“。 diff --git a/Documentation/translations/zh_CN/vm/damon/index.rst b/Documentation/translations/zh_CN/vm/damon/index.rst new file mode 100644 index 000000000000..84d36d90c9b0 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/damon/index.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/vm/damon/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +========================== +DAMON:æ•°æ®è®¿é—®ç›‘视器 +========================== + +DAMON是Linuxå†…æ ¸çš„ä¸€ä¸ªæ•°æ®è®¿é—®ç›‘控框架å系统。DAMONçš„æ ¸å¿ƒæœºåˆ¶ä½¿å…¶æˆä¸º +ï¼ˆè¯¥æ ¸å¿ƒæœºåˆ¶è¯¦è§(Documentation/translations/zh_CN/vm/damon/design.rst)） + + - *准确度* （监测输出对DRAM级别的内å˜ç®¡ç†è¶³å¤Ÿæœ‰ç”¨ï¼›ä½†å¯èƒ½ä¸é€‚åˆCPU Cache级别）， + - *è½»é‡çº§* （监控开销低到å¯ä»¥åœ¨çº¿åº”ç”¨ï¼‰ï¼Œä»¥åŠ + - *å¯æ‰©å±•* ï¼ˆæ— è®ºç›®æ ‡å·¥ä½œè´Ÿè½½çš„å¤§å°ï¼Œå¼€é”€çš„上é™å€¼éƒ½åœ¨æ’定范围内）。 + +å› æ¤ï¼Œåˆ©ç”¨è¿™ä¸ªæ¡†æž¶ï¼Œå†…æ ¸çš„å†…å˜ç®¡ç†æœºåˆ¶å¯ä»¥åšå‡ºé«˜çº§å†³ç–。会导致高数æ®è®¿é—®ç›‘控开销的实 +验性内å˜ç®¡ç†ä¼˜åŒ–工作å¯ä»¥å†æ¬¡è¿›è¡Œã€‚åŒæ—¶ï¼Œåœ¨ç”¨æˆ·ç©ºé—´ï¼Œæœ‰ä¸€äº›ç‰¹æ®Šå·¥ä½œè´Ÿè½½çš„用户å¯ä»¥ç¼–写 +个性化的应用程åºï¼Œä»¥ä¾¿æ›´å¥½åœ°äº†è§£å’Œä¼˜åŒ–他们的工作负载和系统。 + +.. toctree:: + :maxdepth: 2 + + faq + design + api + diff --git a/Documentation/translations/zh_CN/vm/free_page_reporting.rst b/Documentation/translations/zh_CN/vm/free_page_reporting.rst new file mode 100644 index 000000000000..31d6c34b956b --- /dev/null +++ b/Documentation/translations/zh_CN/vm/free_page_reporting.rst @@ -0,0 +1,38 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/_free_page_reporting.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +========== +空闲页报告 +========== + +空闲页报告是一个API，设备å¯ä»¥é€šè¿‡å®ƒæ¥æ³¨å†ŒæŽ¥æ”¶ç³»ç»Ÿå½“å‰æœªä½¿ç”¨çš„页é¢åˆ—表。这在虚拟 +化的情况下是很有用的，客户机能够使用这些数æ®æ¥é€šçŸ¥ç®¡ç†å™¨å®ƒä¸å†ä½¿ç”¨å†…å˜ä¸çš„æŸäº›é¡µ +é¢ã€‚ + +对于驱动，通常是气çƒé©±åŠ¨è¦ä½¿ç”¨è¿™ä¸ªåŠŸèƒ½ï¼Œå®ƒå°†åˆ†é…å’Œåˆå§‹åŒ–一个page_reporting_dev_info +结构体。它è¦å¡«å……的结构体ä¸çš„å—段是用于处ç†æ•£ç‚¹åˆ—表的 "report" 函数指针。它还必 +é¡»ä¿è¯æ¯æ¬¡è°ƒç”¨è¯¥å‡½æ•°æ—¶èƒ½å¤„ç†è‡³å°‘相当于PAGE_REPORTING_CAPACITY的散点列表æ¡ç›®ã€‚ +å‡è®¾æ²¡æœ‰å…¶ä»–页é¢æŠ¥å‘Šè®¾å¤‡å·²ç»æ³¨å†Œï¼Œ 对page_reporting_register的调用将å‘报告框 +架注册页é¢æŠ¥å‘ŠæŽ¥å£ã€‚ + +一旦注册，页é¢æŠ¥å‘ŠAPI将开始å‘驱动报告æˆæ‰¹çš„页é¢ã€‚API将在接å£è¢«æ³¨å†ŒåŽ2秒开始报告 +页é¢ï¼Œå¹¶åœ¨ä»»ä½•è¶³å¤Ÿé«˜çš„页é¢è¢«é‡Šæ”¾ä¹‹åŽ2秒继ç»æŠ¥å‘Šã€‚ + +报告的页é¢å°†è¢«å˜å‚¨åœ¨ä¼ 递给报告函数的散列表ä¸ï¼Œæœ€åŽä¸€ä¸ªæ¡ç›®çš„结æŸä½è¢«è®¾ç½®åœ¨æ¡ç›® +nent-1ä¸ã€‚ 当页é¢è¢«æŠ¥å‘Šå‡½æ•°å¤„ç†æ—¶ï¼Œåˆ†é…å™¨å°†æ— æ³•è®¿é—®å®ƒä»¬ã€‚ä¸€æ—¦æŠ¥å‘Šå‡½æ•°å®Œæˆï¼Œè¿™äº› +页将被返回到它们所获得的自由区域。 + +在移除使用空闲页报告的驱动之å‰ï¼Œæœ‰å¿…è¦è°ƒç”¨page_reporting_unregister，以移除 +ç›®å‰è¢«ç©ºé—²é¡µæŠ¥å‘Šä½¿ç”¨çš„page_reporting_dev_infoç»“æž„ä½“ã€‚è¿™æ ·åšå°†é˜»æ¢è¿›ä¸€æ¥çš„报 +告通过该接å£å‘出。如果å¦ä¸€ä¸ªé©±åŠ¨æˆ–åŒä¸€é©±åŠ¨è¢«æ³¨å†Œï¼Œå®ƒå°±æœ‰å¯èƒ½æ¢å¤å‰ä¸€ä¸ªé©±åŠ¨åœ¨æŠ¥å‘Š +空闲页方é¢çš„工作。 + + +Alexander Duyck, 2019å¹´12月04æ—¥ diff --git a/Documentation/translations/zh_CN/vm/highmem.rst b/Documentation/translations/zh_CN/vm/highmem.rst new file mode 100644 index 000000000000..018838e58c3e --- /dev/null +++ b/Documentation/translations/zh_CN/vm/highmem.rst @@ -0,0 +1,128 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/highmem.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +========== +高内å˜å¤„ç† +========== + +作者: Peter Zijlstra <a.p.zijlstra@chello.nl> + +.. contents:: :local: + +高内å˜æ˜¯ä»€ä¹ˆï¼Ÿ +============== + +当物ç†å†…å˜çš„大å°æŽ¥è¿‘或超过虚拟内å˜çš„最大大å°æ—¶ï¼Œå°±ä¼šä½¿ç”¨é«˜å†…å˜ï¼ˆhighmem）。在这一点上，内 +æ ¸ä¸å¯èƒ½åœ¨ä»»ä½•æ—¶å€™éƒ½ä¿æŒæ‰€æœ‰å¯ç”¨çš„物ç†å†…å˜çš„æ˜ å°„ã€‚è¿™æ„味ç€å†…æ ¸éœ€è¦å¼€å§‹ä½¿ç”¨å®ƒæƒ³è®¿é—®çš„物ç†å†… +å˜çš„ä¸´æ—¶æ˜ å°„ã€‚ + +æ²¡æœ‰è¢«æ°¸ä¹…æ˜ å°„è¦†ç›–çš„é‚£éƒ¨åˆ†ï¼ˆç‰©ç†ï¼‰å†…å˜å°±æ˜¯æˆ‘们所说的 "高内å˜"。对于这个边界的确切ä½ç½®ï¼Œæœ‰ +å„ç§æž¶æž„上的é™åˆ¶ã€‚ + +例如，在i386架构ä¸ï¼Œæˆ‘ä»¬é€‰æ‹©å°†å†…æ ¸æ˜ å°„åˆ°æ¯ä¸ªè¿›ç¨‹çš„è™šæ‹Ÿç©ºé—´ï¼Œè¿™æ ·æˆ‘ä»¬å°±ä¸å¿…ä¸ºå†…æ ¸çš„è¿›å…¥/退 +出付出全部的TLB作废代价。这æ„味ç€å¯ç”¨çš„虚拟内å˜ç©ºé—´ï¼ˆi386上为4GiBï¼‰å¿…é¡»åœ¨ç”¨æˆ·å’Œå†…æ ¸ç©ºé—´ä¹‹ +间进行划分。 + +使用这ç§æ–¹æ³•çš„æž¶æž„çš„ä¼ ç»Ÿåˆ†é…æ–¹å¼æ˜¯3:1，3GiB用于用户空间，顶部的1GiBç”¨äºŽå†…æ ¸ç©ºé—´ã€‚:: + + +--------+ 0xffffffff + | Kernel | + +--------+ 0xc0000000 + | | + | User | + | | + +--------+ 0x00000000 + +è¿™æ„味ç€å†…æ ¸åœ¨ä»»ä½•æ—¶å€™æœ€å¤šå¯ä»¥æ˜ å°„1GiB的物ç†å†…å˜ï¼Œä½†æ˜¯ç”±äºŽæˆ‘们需è¦è™šæ‹Ÿåœ°å€ç©ºé—´æ¥åšå…¶ä»–事 +情--包括访问其余物ç†å†…å˜çš„ä¸´æ—¶æ˜ å°„--å®žé™…çš„ç›´æŽ¥æ˜ å°„é€šå¸¸ä¼šæ›´å°‘ï¼ˆé€šå¸¸åœ¨~896MiBå·¦å³ï¼‰ã€‚ + +其他有mmä¸Šä¸‹æ–‡æ ‡ç¾çš„TLB的架构å¯ä»¥æœ‰ç‹¬ç«‹çš„å†…æ ¸å’Œç”¨æˆ·æ˜ å°„ã€‚ç„¶è€Œï¼Œä¸€äº›ç¡¬ä»¶ï¼ˆå¦‚ä¸€äº›ARM）在使 +用mmä¸Šä¸‹æ–‡æ ‡ç¾æ—¶ï¼Œå…¶è™šæ‹Ÿç©ºé—´æœ‰é™ã€‚ + + +ä¸´æ—¶è™šæ‹Ÿæ˜ å°„ +============ + +å†…æ ¸åŒ…å«å‡ ç§åˆ›å»ºä¸´æ—¶æ˜ 射的方法。: + +* vmap(). è¿™å¯ä»¥ç”¨æ¥å°†å¤šä¸ªç‰©ç†é¡µé•¿æœŸæ˜ 射到一个连ç»çš„虚拟空间。它需è¦synchronization + æ¥è§£é™¤æ˜ 射。 + +* kmap(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡ŒçŸæœŸæ˜ 射。它需è¦synchronization，但在一定程度上被摊销。 + 当以嵌套方å¼ä½¿ç”¨æ—¶ï¼Œå®ƒä¹Ÿå¾ˆå®¹æ˜“出现æ»é”ï¼Œå› æ¤ä¸å»ºè®®åœ¨æ–°ä»£ç ä¸ä½¿ç”¨å®ƒã€‚ + +* kmap_atomic(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡Œéžå¸¸çŸçš„æ—¶é—´æ˜ å°„ã€‚ç”±äºŽæ˜ å°„è¢«é™åˆ¶åœ¨å‘布它的CPU上， + 它表现得很好，但å‘å¸ƒä»»åŠ¡å› æ¤è¢«è¦æ±‚留在该CPU上直到它完æˆï¼Œä»¥å…其他任务å–ä»£å®ƒçš„æ˜ å°„ã€‚ + + kmap_atomic() 也å¯ä»¥ç”±ä¸æ–ä¸Šä¸‹æ–‡ä½¿ç”¨ï¼Œå› ä¸ºå®ƒä¸ç¡çœ ，而且调用者å¯èƒ½åœ¨è°ƒç”¨kunmap_atomic() + 之åŽæ‰ç¡çœ 。 + + å¯ä»¥å‡è®¾k[un]map_atomic()ä¸ä¼šå¤±è´¥ã€‚ + + +使用kmap_atomic +=============== + +何时何地使用 kmap_atomic() 是很直接的。当代ç 想è¦è®¿é—®ä¸€ä¸ªå¯èƒ½ä»Žé«˜å†…å˜ï¼ˆè§__GFP_HIGHMEM） +分é…的页é¢çš„内容时，例如在页缓å˜ä¸çš„页é¢ï¼Œå°±ä¼šä½¿ç”¨å®ƒã€‚该API有两个函数，它们的使用方å¼ä¸Ž +下é¢ç±»ä¼¼:: + + /* 找到感兴趣的页é¢ã€‚ */ + struct page *page = find_get_page(mapping, offset); + + /* 获得对该页内容的访问æƒã€‚ */ + void *vaddr = kmap_atomic(page); + + /* 对该页的内容åšä¸€äº›å¤„ç†ã€‚ */ + memset(vaddr, 0, PAGE_SIZE); + + /* 解除该页é¢çš„æ˜ å°„ã€‚ */ + kunmap_atomic(vaddr); + +注æ„，kunmap_atomic()调用的是kmap_atomic()调用的结果而ä¸æ˜¯å‚数。 + +å¦‚æžœä½ éœ€è¦æ˜ 射两个页é¢ï¼Œå› ä¸ºä½ æƒ³ä»Žä¸€ä¸ªé¡µé¢å¤åˆ¶åˆ°å¦ä¸€ä¸ªé¡µé¢ï¼Œä½ 需è¦ä¿æŒkmap_atomic调用严 +æ ¼åµŒå¥—ï¼Œå¦‚:: + + vaddr1 = kmap_atomic(page1); + vaddr2 = kmap_atomic(page2); + + memcpy(vaddr1, vaddr2, PAGE_SIZE); + + kunmap_atomic(vaddr2); + kunmap_atomic(vaddr1); + + +ä¸´æ—¶æ˜ å°„çš„æˆæœ¬ +============== + +åˆ›å»ºä¸´æ—¶æ˜ å°„çš„ä»£ä»·å¯èƒ½ç›¸å½“高。体系架构必须æ“ä½œå†…æ ¸çš„é¡µè¡¨ã€æ•°æ®TLBå’Œ/或MMU的寄å˜å™¨ã€‚ + +如果CONFIG_HIGHMEMæ²¡æœ‰è¢«è®¾ç½®ï¼Œé‚£ä¹ˆå†…æ ¸ä¼šå°è¯•ç”¨ä¸€ç‚¹è®¡ç®—æ¥åˆ›å»ºæ˜ 射，将页é¢ç»“构地å€è½¬æ¢æˆ +指å‘页é¢å†…容的指针，而ä¸æ˜¯åŽ»æ£é¼“æ˜ å°„ã€‚åœ¨è¿™ç§æƒ…å†µä¸‹ï¼Œè§£æ˜ å°„æ“作å¯èƒ½æ˜¯ä¸€ä¸ªç©ºæ“作。 + +如果CONFIG_MMU没有被设置，那么就ä¸å¯èƒ½æœ‰ä¸´æ—¶æ˜ 射和高内å˜ã€‚在这ç§æƒ…况下，也将使用计算方法。 + + +i386 PAE +======== + +在æŸäº›æƒ…况下，i386 架构将å…è®¸ä½ åœ¨ 32 ä½æœºå™¨ä¸Šå®‰è£…多达 64GiB 的内å˜ã€‚但这有一些åŽæžœ: + +* Linux需è¦ä¸ºç³»ç»Ÿä¸çš„æ¯ä¸ªé¡µé¢å»ºç«‹ä¸€ä¸ªé¡µå¸§ç»“构，而且页帧需è¦é©»åœ¨æ°¸ä¹…æ˜ å°„ä¸ï¼Œè¿™æ„味ç€ï¼š + +* ä½ æœ€å¤šå¯ä»¥æœ‰896M/sizeof(struct page)页帧；由于页结构体是32å—节的，所以最终会有 + 112Gçš„é¡µï¼›ç„¶è€Œï¼Œå†…æ ¸éœ€è¦åœ¨å†…å˜ä¸å˜å‚¨æ›´å¤šçš„页帧...... + +* PAEä½¿ä½ çš„é¡µè¡¨å˜å¤§--这使系统å˜æ…¢ï¼Œå› 为更多的数æ®éœ€è¦åœ¨TLBå¡«å……ç‰æ–¹é¢è¢«è®¿é—®ã€‚一个好处 + 是，PAE有更多的PTEä½ï¼Œå¯ä»¥æä¾›åƒNXå’ŒPATè¿™æ ·çš„é«˜çº§åŠŸèƒ½ã€‚ + +ä¸€èˆ¬çš„å»ºè®®æ˜¯ï¼Œä½ ä¸è¦åœ¨32ä½æœºå™¨ä¸Šä½¿ç”¨è¶…过8GiB的空间--尽管更多的空间å¯èƒ½å¯¹ä½ å’Œä½ çš„å·¥ä½œ +é‡æœ‰ç”¨ï¼Œä½†ä½ å‡ ä¹Žæ˜¯é ä½ è‡ªå·±--ä¸è¦æŒ‡æœ›å†…æ ¸å¼€å‘者真的会很关心事情的进展情况。 diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst new file mode 100644 index 000000000000..a1d2f0356cc1 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/index.rst @@ -0,0 +1,53 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +================= +Linux内å˜ç®¡ç†æ–‡æ¡£ +================= + +这是一个关于Linux内å˜ç®¡ç†ï¼ˆmm）å系统内部的文档集，其ä¸æœ‰ä¸åŒå±‚次的细节，包括注释 +和邮件列表的回å¤ï¼Œç”¨äºŽé˜è¿°æ•°æ®ç»“æž„å’Œç®—æ³•çš„åŸºæœ¬æƒ…å†µã€‚å¦‚æžœä½ æ£åœ¨å¯»æ‰¾å…³äºŽç®€å•åˆ†é…内å˜çš„建 +议，请å‚阅(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。 +对于控制和调整指å—，请å‚阅(Documentation/admin-guide/mm/index)。 +TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ¤å¤„） + +.. toctree:: + :maxdepth: 1 + + active_mm + balance + damon/index + free_page_reporting + highmem + ksm + +TODOLIST: +* arch_pgtable_helpers +* free_page_reporting +* frontswap +* hmm +* hwpoison +* hugetlbfs_reserv +* memory-model +* mmu_notifier +* numa +* overcommit-accounting +* page_migration +* page_frags +* page_owner +* page_table_check +* remap_file_pages +* slub +* split_page_table_lock +* transhuge +* unevictable-lru +* vmalloced-kernel-stacks +* z3fold +* zsmalloc diff --git a/Documentation/translations/zh_CN/vm/ksm.rst b/Documentation/translations/zh_CN/vm/ksm.rst new file mode 100644 index 000000000000..83b0c73984da --- /dev/null +++ b/Documentation/translations/zh_CN/vm/ksm.rst @@ -0,0 +1,70 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/ksm.rst + +:翻译: + + å¾é‘« xu xin <xu.xin16@zte.com.cn> + +============ +å†…æ ¸åŒé¡µåˆå¹¶ +============ + +KSM 是一ç§èŠ‚çœå†…å˜çš„æ•°æ®åŽ»é‡åŠŸèƒ½ï¼Œç”±CONFIG_KSM=yå¯ç”¨ï¼Œå¹¶åœ¨2.6.32ç‰ˆæœ¬æ—¶è¢«æ·»åŠ +到Linuxå†…æ ¸ã€‚è¯¦è§ ``mm/ksm.c`` 的实现，以åŠhttp://lwn.net/Articles/306704å’Œ +https://lwn.net/Articles/330589 + +KSM的用户空间的接å£åœ¨Documentation/translations/zh_CN/admin-guide/mm/ksm.rst +文档ä¸æœ‰æ述。 + +设计 +==== + +概述 +---- + +概述内容请è§mm/ksm.c文档ä¸çš„“DOC: Overview†+ +é€†æ˜ å°„ +------ +KSM维护ç€ç¨³å®šæ ‘ä¸çš„KSMé¡µçš„é€†æ˜ å°„ä¿¡æ¯ã€‚ + +当KSM页é¢çš„共享数å°äºŽ ``max_page_sharing`` 的虚拟内å˜åŒºåŸŸ(VMAs)时，则代表了 +KSMé¡µçš„ç¨³å®šæ ‘å…¶ä¸çš„节点指å‘了一个rmap_item结构体类型的列表。åŒæ—¶ï¼Œè¿™ä¸ªKSM页 +çš„ ``page->mapping`` 指å‘äº†è¯¥ç¨³å®šæ ‘èŠ‚ç‚¹ã€‚ + +如果共享数超过了阈值，KSMå°†ç»™ç¨³å®šæ ‘æ·»åŠ ç¬¬äºŒä¸ªç»´åº¦ã€‚ç¨³å®šæ ‘å°±å˜æˆé“¾æŽ¥ä¸€ä¸ªæˆ–多 +ä¸ªç¨³å®šæ ‘"副本"çš„"链"。æ¯ä¸ªå‰¯æœ¬éƒ½ä¿ç•™KSMé¡µçš„é€†æ˜ å°„ä¿¡æ¯ï¼Œå…¶ä¸ ``page->mapping`` +指å‘该"副本"。 + +æ¯ä¸ªé“¾ä»¥åŠé“¾æŽ¥åˆ°è¯¥é“¾ä¸çš„所有"副本"强制ä¸å˜çš„是，它们代表了相åŒçš„写ä¿æŠ¤å†…å˜ +内容，尽管任ä¸ä¸€ä¸ª"副本"是由åŒä¸€ç‰‡å†…å˜åŒºçš„ä¸åŒçš„KSMå¤åˆ¶é¡µæ‰€æŒ‡å‘的。 + +è¿™æ ·ä¸€æ¥ï¼Œç›¸æ¯”ä¸Žæ— é™çš„é€†æ˜ å°„é“¾è¡¨ï¼Œç¨³å®šæ ‘çš„æŸ¥æ‰¾è®¡ç®—å¤æ‚性ä¸å—å½±å“ã€‚ä½†åœ¨ç¨³å®šæ ‘ +本身ä¸ä¸èƒ½æœ‰é‡å¤çš„KSM页é¢å†…容ä»ç„¶æ˜¯å¼ºåˆ¶è¦æ±‚。 + +ç”± ``max_page_sharing`` 强制决定的数æ®åŽ»é‡é™åˆ¶æ˜¯å¿…è¦çš„，以æ¤æ¥é¿å…è™šæ‹Ÿå†…å˜ +rmap链表å˜å¾—过大。rmapçš„é历具有O(N)çš„å¤æ‚度，其ä¸N是共享页é¢çš„rmap_é¡¹ï¼ˆå³ +è™šæ‹Ÿæ˜ å°„ï¼‰çš„æ•°é‡ï¼Œè€Œè¿™ä¸ªå…±äº«é¡µé¢çš„节点数é‡åˆè¢« ``max_page_sharing`` 所é™åˆ¶ã€‚ +å› æ¤ï¼Œè¿™æœ‰æ•ˆåœ°å°†çº¿æ€§O(N)计算å¤æ‚度从rmapé历ä¸åˆ†æ•£åˆ°ä¸åŒçš„KSM页é¢ä¸Šã€‚ksmdè¿› +程在稳定节点"链"上的é历也是O(N)，但这个Næ˜¯ç¨³å®šæ ‘"副本"çš„æ•°é‡ï¼Œè€Œä¸æ˜¯rmap项 +çš„æ•°é‡ï¼Œå› æ¤å®ƒå¯¹ksmd性能没有显著影å“ã€‚å®žé™…ä¸Šï¼Œæœ€ä½³ç¨³å®šæ ‘"副本"的候选节点将 +ä¿ç•™åœ¨"副本"列表的开头。 + +``max_page_sharing`` 的值设置得高了会促使更快的内å˜åˆå¹¶ï¼ˆå› 为将有更少的稳定 +æ ‘å‰¯æœ¬æŽ’é˜Ÿè¿›å…¥ç¨³å®šèŠ‚ç‚¹chain->hlist）和更高的数æ®åŽ»é‡ç³»æ•°ï¼Œä½†ä»£ä»·æ˜¯åœ¨äº¤æ¢ã€åŽ‹ +缩ã€NUMA平衡和页é¢è¿ç§»è¿‡ç¨‹ä¸å¯èƒ½å¯¼è‡´KSM页的最大rmapé历速度较慢。 + +``stable_node_dups/stable_node_chains`` çš„æ¯”å€¼è¿˜å— ``max_page_sharing`` 调控 +çš„å½±å“，高比值å¯èƒ½æ„味ç€ç¨³å®šèŠ‚点dupä¸å˜åœ¨ç¢Žç‰‡ï¼Œè¿™å¯ä»¥é€šè¿‡åœ¨ksmdä¸å¼•å…¥ç¢Žç‰‡ç®— +法æ¥è§£å†³ï¼Œè¯¥ç®—法将rmap项从一个稳定节点dupé‡å®šä½åˆ°å¦ä¸€ä¸ªç¨³å®šèŠ‚点dup，以便释放 +那些仅包å«æžå°‘rmap项的稳定节点"dup"，但这å¯èƒ½ä¼šå¢žåŠ ksmd进程的CPUä½¿ç”¨çŽ‡ï¼Œå¹¶å¯ +能会å‡æ…¢åº”用程åºåœ¨KSM页é¢ä¸Šçš„åªè¯»è®¡ç®—。 + +KSM会定期扫æ稳定节点"链"ä¸é“¾æŽ¥çš„æ‰€æœ‰ç¨³å®šæ ‘"副本"ï¼Œä»¥ä¾¿åˆ å‡è¿‡æ—¶äº†çš„稳定节点。 +è¿™ç§æ‰«æ的频率由 ``stable_node_chains_prune_millisecs`` 这个sysfs 接å£å®šä¹‰ã€‚ + +å‚考 +==== +å†…æ ¸ä»£ç 请è§mm/ksm.c。 +涉åŠçš„函数(mm_slot ksm_scan stable_node rmap_item)。 diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index f56f78ba7860..e1ce9d8c06f8 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -5,7 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginTC + \kerneldocBeginTC{ .. _linux_doc_zh_tw: @@ -174,4 +174,4 @@ TODOList: .. raw:: latex - \kerneldocEndTC + }\kerneldocEndTC diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 37eccf9e2746..c4fd48f5bd8b 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -257,30 +257,6 @@ Linus Torvalds 是決定改動能å¦é€²å…¥ Linux å…§æ ¸çš„æœ€çµ‚è£æ±ºè€…。他ç 手冊é 補ä¸ï¼Œæˆ–至少發é€æ›´æ”¹é€šçŸ¥ï¼Œä»¥ä¾¿ä¸€äº›ä¿¡æ¯é€²å…¥æ‰‹å†Šé 。還應將用戶空間API 更改複製到 linux-api@vger.kernel.org。 -å°æ–¼å°çš„補ä¸ï¼Œä½ 也許會CC到æœé›†ç‘£ç¢Žè£œä¸çš„郵件列表(Trivial Patch Monkey) -trivial@kernel.org，那裡專門收集瑣碎的補ä¸ã€‚下é¢é€™æ¨£çš„補ä¸æœƒè¢«çœ‹ä½œã€Œç‘£ç¢Žçš„〠-補ä¸ï¼š - - - 文檔的拼寫修æ£ã€‚ - - ä¿®æ£æœƒå½±éŸ¿åˆ° grep(1) 的拼寫。 - - è¦å‘Šä¿¡æ¯ä¿®æ£(é »ç¹çš„列å°ç„¡ç”¨çš„è¦å‘Šæ˜¯ä¸å¥½çš„。) - - ç·¨è¯éŒ¯èª¤ä¿®æ£ï¼ˆä»£ç¢¼é‚輯的確是å°çš„，åªæ˜¯ç·¨è¯æœ‰å•é¡Œã€‚） - - é‹è¡Œæ™‚ä¿®æ£ï¼ˆåªè¦çœŸçš„ä¿®æ£äº†éŒ¯èª¤ã€‚） - - 移除使用了被廢棄的函數/å®çš„代碼(例如 check_region。) - - è¯ç¹«æ–¹å¼å’Œæ–‡æª”ä¿®æ£ã€‚ - - 用å¯ç§»æ¤çš„代碼替æ›ä¸å¯ç§»æ¤çš„代碼（å³ä½¿åœ¨é«”ç³»çµæ§‹ç›¸é—œçš„代碼ä¸ï¼Œæ—¢ç„¶æœ‰ - - 人拷è²ï¼Œåªè¦å®ƒæ˜¯ç‘£ç¢Žçš„） - - 任何文件的作者/ç¶è·è€…å°è©²æ–‡ä»¶çš„改動（例如 patch monkey 在é‡å‚³æ¨¡å¼ä¸‹ï¼‰ - -(è¯è¨»ï¼Œé—œæ–¼ã€Œç‘£ç¢Žè£œä¸ã€çš„ä¸€äº›èªªæ˜Žï¼šå› çˆ²åŽŸæ–‡çš„é€™ä¸€éƒ¨åˆ†å¯«å¾—æ¯”è¼ƒç°¡å–®ï¼Œæ‰€ä»¥ä¸å¾—ä¸ -é•ä¾‹å¯«ä¸€ä¸‹è¯è¨»ã€‚"trivial"這個英文單詞的本æ„是「瑣碎的，ä¸é‡è¦çš„。ã€ä½†æ˜¯åœ¨é€™è£¡ -有ç¨å¾®æœ‰ä¸€äº›è®ŠåŒ–，例如å°ä¸€äº›æ˜Žé¡¯çš„NULL指é‡çš„ä¿®æ£ï¼Œå±¬æ–¼é‹è¡Œæ™‚ä¿®æ£ï¼Œæœƒè¢«æ¸é¡ž -到瑣碎補ä¸é‡Œã€‚雖然NULL指é‡çš„ä¿®æ£å¾ˆé‡è¦ï¼Œä½†æ˜¯é€™æ¨£çš„ä¿®æ£å¾€å¾€å¾ˆå°è€Œä¸”很容易得到 -檢驗，所以也被æ¸å…¥ç‘£ç¢Žè£œä¸ã€‚瑣碎補ä¸æ›´ç²¾ç¢ºçš„æ¸é¡žæ‡‰è©²æ˜¯ -「simple, localized & easy to verifyã€ï¼Œä¹Ÿå°±æ˜¯èªªç°¡å–®çš„，局部的和易於檢驗的。 -trivial@kernel.org郵件列表的目的是é‡å°é€™æ¨£çš„補ä¸ï¼Œçˆ²æ交者æ供一個ä¸å¿ƒï¼Œä¾† -é™ä½Žæ交的門檻。) - 6) 沒有 MIME 編碼，沒有連çµï¼Œæ²’有壓縮，沒有附件，åªæœ‰ç´”文本 ----------------------------------------------------------- diff --git a/Documentation/tty/index.rst b/Documentation/tty/index.rst new file mode 100644 index 000000000000..21ea0cb21e55 --- /dev/null +++ b/Documentation/tty/index.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=== +TTY +=== + +Teletypewriter (TTY) layer takes care of all those serial devices. Including +the virtual ones like pseudoterminal (PTY). + +TTY structures +============== + +There are several major TTY structures. Every TTY device in a system has a +corresponding struct tty_port. These devices are maintained by a TTY driver +which is struct tty_driver. This structure describes the driver but also +contains a reference to operations which could be performed on the TTYs. It is +struct tty_operations. Then, upon open, a struct tty_struct is allocated and +lives until the final close. During this time, several callbacks from struct +tty_operations are invoked by the TTY layer. + +Every character received by the kernel (both from devices and users) is passed +through a preselected :doc:`tty_ldisc` (in +short ldisc; in C, struct tty_ldisc_ops). Its task is to transform characters +as defined by a particular ldisc or by user too. The default one is n_tty, +implementing echoes, signal handling, jobs control, special characters +processing, and more. The transformed characters are passed further to +user/device, depending on the source. + +In-detail description of the named TTY structures is in separate documents: + +.. toctree:: + :maxdepth: 2 + + tty_driver + tty_port + tty_struct + tty_ldisc + tty_buffer + n_tty + tty_internals + +Writing TTY Driver +================== + +Before one starts writing a TTY driver, they must consider +:doc:`Serial <../driver-api/serial/driver>` and :doc:`USB Serial +<../usb/usb-serial>` layers +first. Drivers for serial devices can often use one of these specific layers to +implement a serial driver. Only special devices should be handled directly by +the TTY Layer. If you are about to write such a driver, read on. + +A *typical* sequence a TTY driver performs is as follows: + +#. Allocate and register a TTY driver (module init) +#. Create and register TTY devices as they are probed (probe function) +#. Handle TTY operations and events like interrupts (TTY core invokes the + former, the device the latter) +#. Remove devices as they are going away (remove function) +#. Unregister and free the TTY driver (module exit) + +Steps regarding driver, i.e. 1., 3., and 5. are described in detail in +:doc:`tty_driver`. For the other two (devices handling), look into +:doc:`tty_port`. diff --git a/Documentation/tty/n_tty.rst b/Documentation/tty/n_tty.rst new file mode 100644 index 000000000000..15b70faee72d --- /dev/null +++ b/Documentation/tty/n_tty.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +N_TTY +===== + +.. contents:: :local: + +The default (and fallback) :doc:`TTY line discipline <tty_ldisc>`. It tries to +handle characters as per POSIX. + +External Functions +================== + +.. kernel-doc:: drivers/tty/n_tty.c + :export: + +Internal Functions +================== + +.. kernel-doc:: drivers/tty/n_tty.c + :internal: diff --git a/Documentation/tty/tty_buffer.rst b/Documentation/tty/tty_buffer.rst new file mode 100644 index 000000000000..a39d4781e0d2 --- /dev/null +++ b/Documentation/tty/tty_buffer.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +TTY Buffer +========== + +.. contents:: :local: + +Here, we document functions for taking care of tty buffer and their flipping. +Drivers are supposed to fill the buffer by one of those functions below and +then flip the buffer, so that the data are passed to :doc:`line discipline +<tty_ldisc>` for further processing. + +Flip Buffer Management +====================== + +.. kernel-doc:: drivers/tty/tty_buffer.c + :identifiers: tty_prepare_flip_string tty_insert_flip_string_fixed_flag + tty_insert_flip_string_flags __tty_insert_flip_char + tty_flip_buffer_push tty_ldisc_receive_buf + +---- + +Other Functions +=============== + +.. kernel-doc:: drivers/tty/tty_buffer.c + :identifiers: tty_buffer_space_avail tty_buffer_set_limit + +---- + +Buffer Locking +============== + +These are used only in special circumstances. Avoid them. + +.. kernel-doc:: drivers/tty/tty_buffer.c + :identifiers: tty_buffer_lock_exclusive tty_buffer_unlock_exclusive + +---- + +Internal Functions +================== + +.. kernel-doc:: drivers/tty/tty_buffer.c + :internal: diff --git a/Documentation/tty/tty_driver.rst b/Documentation/tty/tty_driver.rst new file mode 100644 index 000000000000..cc529f863406 --- /dev/null +++ b/Documentation/tty/tty_driver.rst @@ -0,0 +1,128 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +TTY Driver and TTY Operations +============================= + +.. contents:: :local: + +Allocation +========== + +The first thing a driver needs to do is to allocate a struct tty_driver. This +is done by tty_alloc_driver() (or __tty_alloc_driver()). Next, the newly +allocated structure is filled with information. See `TTY Driver Reference`_ at +the end of this document on what actually shall be filled in. + +The allocation routines expect a number of devices the driver can handle at +most and flags. Flags are those starting ``TTY_DRIVER_`` listed and described +in `TTY Driver Flags`_ below. + +When the driver is about to be freed, tty_driver_kref_put() is called on that. +It will decrements the reference count and if it reaches zero, the driver is +freed. + +For reference, both allocation and deallocation functions are explained here in +detail: + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: __tty_alloc_driver tty_driver_kref_put + +TTY Driver Flags +---------------- + +Here comes the documentation of flags accepted by tty_alloc_driver() (or +__tty_alloc_driver()): + +.. kernel-doc:: include/linux/tty_driver.h + :doc: TTY Driver Flags + +---- + +Registration +============ + +When a struct tty_driver is allocated and filled in, it can be registered using +tty_register_driver(). It is recommended to pass ``TTY_DRIVER_DYNAMIC_DEV`` in +flags of tty_alloc_driver(). If it is not passed, *all* devices are also +registered during tty_register_driver() and the following paragraph of +registering devices can be skipped for such drivers. However, the struct +tty_port part in `Registering Devices`_ is still relevant there. + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_register_driver tty_unregister_driver + +Registering Devices +------------------- + +Every TTY device shall be backed by a struct tty_port. Usually, TTY drivers +embed tty_port into device's private structures. Further details about handling +tty_port can be found in :doc:`tty_port`. The driver is also recommended to use +tty_port's reference counting by tty_port_get() and tty_port_put(). The final +put is supposed to free the tty_port including the device's private struct. + +Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed as flags to tty_alloc_driver(), +TTY driver is supposed to register every device discovered in the system +(the latter is preferred). This is performed by tty_register_device(). Or by +tty_register_device_attr() if the driver wants to expose some information +through struct attribute_group. Both of them register ``index``'th device and +upon return, the device can be opened. There are also preferred tty_port +variants described in `Linking Devices to Ports`_ later. It is up to driver to +manage free indices and choosing the right one. The TTY layer only refuses to +register more devices than passed to tty_alloc_driver(). + +When the device is opened, the TTY layer allocates struct tty_struct and starts +calling operations from :c:member:`tty_driver.ops`, see `TTY Operations +Reference`_. + +The registration routines are documented as follows: + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_register_device tty_register_device_attr + tty_unregister_device + +---- + +Linking Devices to Ports +------------------------ +As stated earlier, every TTY device shall have a struct tty_port assigned to +it. It must be known to the TTY layer at :c:member:`tty_driver.ops.install()` +at latest. There are few helpers to *link* the two. Ideally, the driver uses +tty_port_register_device() or tty_port_register_device_attr() instead of +tty_register_device() and tty_register_device_attr() at the registration time. +This way, the driver needs not care about linking later on. + +If that is not possible, the driver still can link the tty_port to a specific +index *before* the actual registration by tty_port_link_device(). If it still +does not fit, tty_port_install() can be used from the +:c:member:`tty_driver.ops.install` hook as a last resort. The last one is +dedicated mostly for in-memory devices like PTY where tty_ports are allocated +on demand. + +The linking routines are documented here: + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_link_device tty_port_register_device + tty_port_register_device_attr + +---- + +TTY Driver Reference +==================== + +All members of struct tty_driver are documented here. The required members are +noted at the end. struct tty_operations are documented next. + +.. kernel-doc:: include/linux/tty_driver.h + :identifiers: tty_driver + +---- + +TTY Operations Reference +======================== + +When a TTY is registered, these driver hooks can be invoked by the TTY layer: + +.. kernel-doc:: include/linux/tty_driver.h + :identifiers: tty_operations + diff --git a/Documentation/tty/tty_internals.rst b/Documentation/tty/tty_internals.rst new file mode 100644 index 000000000000..d0d415820300 --- /dev/null +++ b/Documentation/tty/tty_internals.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +TTY Internals +============= + +.. contents:: :local: + +Kopen +===== + +These functions serve for opening a TTY from the kernelspace: + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_kopen_exclusive tty_kopen_shared tty_kclose + +---- + +Exported Internal Functions +=========================== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_release_struct tty_dev_name_to_number tty_get_icount + +---- + +Internal Functions +================== + +.. kernel-doc:: drivers/tty/tty_io.c + :internal: diff --git a/Documentation/tty/tty_ldisc.rst b/Documentation/tty/tty_ldisc.rst new file mode 100644 index 000000000000..5144751be804 --- /dev/null +++ b/Documentation/tty/tty_ldisc.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +TTY Line Discipline +=================== + +.. contents:: :local: + +TTY line discipline process all incoming and outgoing character from/to a tty +device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a +fallback if establishing any other discipline for a tty fails. If even N_TTY +fails, N_NULL takes over. That never fails, but also does not process any +characters -- it throws them away. + +Registration +============ + +Line disciplines are registered with tty_register_ldisc() passing the ldisc +structure. At the point of registration the discipline must be ready to use and +it is possible it will get used before the call returns success. If the call +returns an error then it won’t get called. Do not re-use ldisc numbers as they +are part of the userspace ABI and writing over an existing ldisc will cause +demons to eat your computer. You must not re-register over the top of the line +discipline even with the same data or your computer again will be eaten by +demons. In order to remove a line discipline call tty_unregister_ldisc(). + +Heed this warning: the reference count field of the registered copies of the +tty_ldisc structure in the ldisc table counts the number of lines using this +discipline. The reference count of the tty_ldisc structure within a tty counts +the number of active users of the ldisc at this instant. In effect it counts +the number of threads of execution within an ldisc method (plus those about to +enter and exit although this detail matters not). + +.. kernel-doc:: drivers/tty/tty_ldisc.c + :identifiers: tty_register_ldisc tty_unregister_ldisc + +Other Functions +=============== + +.. kernel-doc:: drivers/tty/tty_ldisc.c + :identifiers: tty_set_ldisc tty_ldisc_flush + +Line Discipline Operations Reference +==================================== + +.. kernel-doc:: include/linux/tty_ldisc.h + :identifiers: tty_ldisc_ops + +Driver Access +============= + +Line discipline methods can call the methods of the underlying hardware driver. +These are documented as a part of struct tty_operations. + +TTY Flags +========= + +Line discipline methods have access to :c:member:`tty_struct.flags` field. See +:doc:`tty_struct`. + +Locking +======= + +Callers to the line discipline functions from the tty layer are required to +take line discipline locks. The same is true of calls from the driver side +but not yet enforced. + +.. kernel-doc:: drivers/tty/tty_ldisc.c + :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref + +While these functions are slightly slower than the old code they should have +minimal impact as most receive logic uses the flip buffers and they only +need to take a reference when they push bits up through the driver. + +A caution: The :c:member:`tty_ldisc_ops.open()`, +:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()` +functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail +in this situation if used within these functions. Ldisc and driver code +calling its own functions must be careful in this case. + +Internal Functions +================== + +.. kernel-doc:: drivers/tty/tty_ldisc.c + :internal: diff --git a/Documentation/tty/tty_port.rst b/Documentation/tty/tty_port.rst new file mode 100644 index 000000000000..5cb90e954fcf --- /dev/null +++ b/Documentation/tty/tty_port.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======== +TTY Port +======== + +.. contents:: :local: + +The TTY drivers are advised to use struct tty_port helpers as much as possible. +If the drivers implement :c:member:`tty_port.ops.activate()` and +:c:member:`tty_port.ops.shutdown()`, they can use tty_port_open(), +tty_port_close(), and tty_port_hangup() in respective +:c:member:`tty_struct.ops` hooks. + +The reference and details are contained in the `TTY Port Reference`_ and `TTY +Port Operations Reference`_ sections at the bottom. + +TTY Port Functions +================== + +Init & Destroy +-------------- + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_init tty_port_destroy + tty_port_get tty_port_put + +Open/Close/Hangup Helpers +------------------------- + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_install tty_port_open tty_port_block_til_ready + tty_port_close tty_port_close_start tty_port_close_end tty_port_hangup + tty_port_shutdown + +TTY Refcounting +--------------- + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_tty_get tty_port_tty_set + +TTY Helpers +----------- + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_tty_hangup tty_port_tty_wakeup + + +Modem Signals +------------- + +.. kernel-doc:: drivers/tty/tty_port.c + :identifiers: tty_port_carrier_raised tty_port_raise_dtr_rts + tty_port_lower_dtr_rts + +---- + +TTY Port Reference +================== + +.. kernel-doc:: include/linux/tty_port.h + :identifiers: tty_port + +---- + +TTY Port Operations Reference +============================= + +.. kernel-doc:: include/linux/tty_port.h + :identifiers: tty_port_operations diff --git a/Documentation/tty/tty_struct.rst b/Documentation/tty/tty_struct.rst new file mode 100644 index 000000000000..c72f5a4293b2 --- /dev/null +++ b/Documentation/tty/tty_struct.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +TTY Struct +========== + +.. contents:: :local: + +struct tty_struct is allocated by the TTY layer upon the first open of the TTY +device and released after the last close. The TTY layer passes this structure +to most of struct tty_operation's hooks. Members of tty_struct are documented +in `TTY Struct Reference`_ at the bottom. + +Initialization +============== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_init_termios + +Name +==== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_name + +Reference counting +================== + +.. kernel-doc:: include/linux/tty.h + :identifiers: tty_kref_get + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_kref_put + +Install +======= + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_standard_install + +Read & Write +============ + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_put_char + +Start & Stop +============ + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: start_tty stop_tty + +Wakeup +====== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_wakeup + +Hangup +====== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_hangup tty_vhangup tty_hung_up_p + +Misc +==== + +.. kernel-doc:: drivers/tty/tty_io.c + :identifiers: tty_do_resize + +TTY Struct Flags +================ + +.. kernel-doc:: include/linux/tty.h + :doc: TTY Struct Flags + +TTY Struct Reference +==================== + +.. kernel-doc:: include/linux/tty.h + :identifiers: tty_struct diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index c18113077889..cbbd948c626f 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -931,7 +931,7 @@ The uac1 function provides these attributes in its function directory: p_volume_min playback volume control min value (in 1/256 dB) p_volume_max playback volume control max value (in 1/256 dB) p_volume_res playback volume control resolution (in 1/256 dB) - req_number the number of pre-allocated request for both capture + req_number the number of pre-allocated requests for both capture and playback ================ ==================================================== diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index cfe6cccf0f44..dfbc27d17ff7 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -115,6 +115,7 @@ Code Seq# Include File Comments 'B' 00-1F linux/cciss_ioctl.h conflict! 'B' 00-0F include/linux/pmu.h conflict! 'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de> +'B' 00-0F xen/xenbus_dev.h conflict! 'C' all linux/soundcard.h conflict! 'C' 01-2F linux/capi.h conflict! 'C' F0-FF drivers/net/wan/cosa.h conflict! @@ -134,6 +135,7 @@ Code Seq# Include File Comments 'F' 80-8F linux/arcfb.h conflict! 'F' DD video/sstfb.h conflict! 'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! +'G' 00-0F xen/gntalloc.h, xen/gntdev.h conflict! 'H' 00-7F linux/hiddev.h conflict! 'H' 00-0F linux/hidraw.h conflict! 'H' 01 linux/mei.h conflict! @@ -176,6 +178,7 @@ Code Seq# Include File Comments 'P' 60-6F sound/sscape_ioctl.h conflict! 'P' 00-0F drivers/usb/class/usblp.c conflict! 'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! +'P' 00-0F xen/privcmd.h conflict! 'Q' all linux/soundcard.h 'R' 00-1F linux/random.h conflict! 'R' 01 linux/rfkill.h conflict! @@ -253,7 +256,7 @@ Code Seq# Include File Comments 'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs> 'l' 40-7F linux/udf_fs_i.h in development: - <http://sourceforge.net/projects/linux-udf/> + <https://github.com/pali/udftools> 'm' 00-09 linux/mmtimer.h conflict! 'm' all linux/mtio.h conflict! 'm' all linux/soundcard.h conflict! @@ -367,6 +370,7 @@ Code Seq# Include File Comments <mailto:aherrman@de.ibm.com> 0xE5 00-3F linux/fuse.h 0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver +0xEE 00-09 uapi/linux/pfrut.h Platform Firmware Runtime Update and Telemetry 0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) <mailto:thomas@winischhofer.net> 0xF6 all LTTng Linux Trace Toolkit Next Generation diff --git a/Documentation/virt/kvm/amd-memory-encryption.rst b/Documentation/virt/kvm/amd-memory-encryption.rst index 5c081c8c7164..1c6847fff304 100644 --- a/Documentation/virt/kvm/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/amd-memory-encryption.rst @@ -85,6 +85,12 @@ guests, such as launching, running, snapshotting, migrating and decommissioning. The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform context. In a typical workflow, this command should be the first command issued. +The firmware can be initialized either by using its own non-volatile storage or +the OS can manage the NV storage for the firmware using the module parameter +``init_ex_path``. The file specified by ``init_ex_path`` must exist. To create +a new NV storage file allocate the file with 32KB bytes of 0xFF as required by +the SEV spec. + Returns: 0 on success, -negative on error 2. KVM_SEV_LAUNCH_START diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index aeeb071c7688..9f3172376ec3 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -371,6 +371,9 @@ The bits in the dirty bitmap are cleared before the ioctl returns, unless KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information, see the description of the capability. +Note that the Xen shared info page, if configured, shall always be assumed +to be dirty. KVM will not explicitly mark it such. + 4.9 KVM_SET_MEMORY_ALIAS ------------------------ @@ -1391,7 +1394,7 @@ documentation when it pops into existence). ------------------- :Capability: KVM_CAP_ENABLE_CAP -:Architectures: mips, ppc, s390 +:Architectures: mips, ppc, s390, x86 :Type: vcpu ioctl :Parameters: struct kvm_enable_cap (in) :Returns: 0 on success; -1 on error @@ -1566,6 +1569,7 @@ otherwise it will return EBUSY error. struct kvm_xsave { __u32 region[1024]; + __u32 extra[0]; }; This ioctl would copy current vcpu's xsave struct to the userspace. @@ -1574,7 +1578,7 @@ This ioctl would copy current vcpu's xsave struct to the userspace. 4.43 KVM_SET_XSAVE ------------------ -:Capability: KVM_CAP_XSAVE +:Capability: KVM_CAP_XSAVE and KVM_CAP_XSAVE2 :Architectures: x86 :Type: vcpu ioctl :Parameters: struct kvm_xsave (in) @@ -1585,9 +1589,18 @@ This ioctl would copy current vcpu's xsave struct to the userspace. struct kvm_xsave { __u32 region[1024]; + __u32 extra[0]; }; -This ioctl would copy userspace's xsave struct to the kernel. +This ioctl would copy userspace's xsave struct to the kernel. It copies +as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2), +when invoked on the vm file descriptor. The size value returned by +KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096. +Currently, it is only greater than 4096 if a dynamic feature has been +enabled with ``arch_prctl()``, but this may change in the future. + +The offsets of the state save areas in struct kvm_xsave follow the +contents of CPUID leaf 0xD on the host. 4.44 KVM_GET_XCRS @@ -1684,6 +1697,10 @@ userspace capabilities, and with user requirements (for example, the user may wish to constrain cpuid to emulate older hardware, or for feature consistency across a cluster). +Dynamically-enabled feature bits need to be requested with +``arch_prctl()`` before calling this ioctl. Feature bits that have not +been requested are excluded from the result. + Note that certain capabilities, such as KVM_CAP_X86_DISABLE_EXITS, may expose cpuid features (e.g. MONITOR) which are not supported by kvm in its default configuration. If userspace enables such capabilities, it @@ -1796,6 +1813,7 @@ No flags are specified so far, the corresponding field must be set to zero. struct kvm_irq_routing_msi msi; struct kvm_irq_routing_s390_adapter adapter; struct kvm_irq_routing_hv_sint hv_sint; + struct kvm_irq_routing_xen_evtchn xen_evtchn; __u32 pad[8]; } u; }; @@ -1805,6 +1823,7 @@ No flags are specified so far, the corresponding field must be set to zero. #define KVM_IRQ_ROUTING_MSI 2 #define KVM_IRQ_ROUTING_S390_ADAPTER 3 #define KVM_IRQ_ROUTING_HV_SINT 4 + #define KVM_IRQ_ROUTING_XEN_EVTCHN 5 flags: @@ -1856,6 +1875,20 @@ address_hi must be zero. __u32 sint; }; + struct kvm_irq_routing_xen_evtchn { + __u32 port; + __u32 vcpu; + __u32 priority; + }; + + +When KVM_CAP_XEN_HVM includes the KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL bit +in its indication of supported features, routing to Xen event channels +is supported. Although the priority field is present, only the value +KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL is supported, which means delivery by +2 level event channels. FIFO event channel support may be added in +the future. + 4.55 KVM_SET_TSC_KHZ -------------------- @@ -3235,6 +3268,7 @@ number. :Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, KVM_CAP_VCPU_ATTRIBUTES for vcpu device + KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device (no set) :Type: device ioctl, vm ioctl, vcpu ioctl :Parameters: struct kvm_device_attr :Returns: 0 on success, -1 on error @@ -3269,7 +3303,8 @@ transferred is defined by the particular attribute. ------------------------ :Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, - KVM_CAP_VCPU_ATTRIBUTES for vcpu device + KVM_CAP_VCPU_ATTRIBUTES for vcpu device + KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device :Type: device ioctl, vm ioctl, vcpu ioctl :Parameters: struct kvm_device_attr :Returns: 0 on success, -1 on error @@ -3701,7 +3736,7 @@ KVM with the currently defined set of flags. :Architectures: s390 :Type: vm ioctl :Parameters: struct kvm_s390_skeys -:Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage +:Returns: 0 on success, KVM_S390_GET_SKEYS_NONE if guest is not using storage keys, negative value on error This ioctl is used to get guest storage key values on the s390 @@ -3720,7 +3755,7 @@ you want to get. The count field is the number of consecutive frames (starting from start_gfn) whose storage keys to get. The count field must be at least 1 and the maximum -allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range +allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range will cause the ioctl to return -EINVAL. The skeydata_addr field is the address to a buffer large enough to hold count @@ -3744,7 +3779,7 @@ you want to set. The count field is the number of consecutive frames (starting from start_gfn) whose storage keys to get. The count field must be at least 1 and the maximum -allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range +allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range will cause the ioctl to return -EINVAL. The skeydata_addr field is the address to a buffer containing count bytes of @@ -5134,6 +5169,15 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO not aware of the Xen CPU id which is used as the index into the vcpu_info[] array, so cannot know the correct default location. + Note that the shared info page may be constantly written to by KVM; + it contains the event channel bitmap used to deliver interrupts to + a Xen guest, amongst other things. It is exempt from dirty tracking + mechanisms — KVM will not explicitly mark the page as dirty each + time an event channel interrupt is delivered to the guest! Thus, + userspace should always assume that the designated GFN is dirty if + any vCPU has been running or any event channel interrupts can be + routed to the guest. + KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. @@ -5503,6 +5547,34 @@ the trailing ``'\0'``, is indicated by ``name_size`` in the header. The Stats Data block contains an array of 64-bit values in the same order as the descriptors in Descriptors block. +4.134 KVM_GET_XSAVE2 +-------------------- + +:Capability: KVM_CAP_XSAVE2 +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xsave (out) +:Returns: 0 on success, -1 on error + + +:: + + struct kvm_xsave { + __u32 region[1024]; + __u32 extra[0]; + }; + +This ioctl would copy current vcpu's xsave struct to the userspace. It +copies as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) +when invoked on the vm file descriptor. The size value returned by +KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096. +Currently, it is only greater than 4096 if a dynamic feature has been +enabled with ``arch_prctl()``, but this may change in the future. + +The offsets of the state save areas in struct kvm_xsave follow the contents +of CPUID leaf 0xD on the host. + + 5. The kvm_run structure ======================== @@ -6925,6 +6997,20 @@ indicated by the fd to the VM this is called on. This is intended to support intra-host migration of VMs between userspace VMMs, upgrading the VMM process without interrupting the guest. +7.30 KVM_CAP_PPC_AIL_MODE_3 +------------------------------- + +:Capability: KVM_CAP_PPC_AIL_MODE_3 +:Architectures: ppc +:Type: vm + +This capability indicates that the kernel supports the mode 3 setting for the +"Address Translation Mode on Interrupt" aka "Alternate Interrupt Location" +resource that is controlled with the H_SET_MODE hypercall. + +This capability allows a guest kernel to use a better-performance mode for +handling interrupts and system calls. + 8. Other capabilities. ====================== @@ -7293,7 +7379,7 @@ trap and emulate MSRs that are outside of the scope of KVM as well as limit the attack surface on KVM's MSR emulation code. 8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID ------------------------------ +------------------------------------- Architectures: x86 @@ -7401,6 +7487,7 @@ PVHVM guests. Valid flags are:: #define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1) #define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2) #define KVM_XEN_HVM_CONFIG_RUNSTATE (1 << 2) + #define KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL (1 << 3) The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG ioctl is available, for the guest to set its hypercall page. @@ -7420,6 +7507,10 @@ The KVM_XEN_HVM_CONFIG_RUNSTATE flag indicates that the runstate-related features KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR/_CURRENT/_DATA/_ADJUST are supported by the KVM_XEN_VCPU_SET_ATTR/KVM_XEN_VCPU_GET_ATTR ioctls. +The KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL flag indicates that IRQ routing entries +of the type KVM_IRQ_ROUTING_XEN_EVTCHN are supported, with the priority +field set to indicate 2 level event channel delivery. + 8.31 KVM_CAP_PPC_MULTITCE ------------------------- diff --git a/Documentation/virt/kvm/mmu.rst b/Documentation/virt/kvm/mmu.rst index f60f5488e121..5b1ebad24c77 100644 --- a/Documentation/virt/kvm/mmu.rst +++ b/Documentation/virt/kvm/mmu.rst @@ -161,7 +161,7 @@ Shadow pages contain the following information: If clear, this page corresponds to a guest page table denoted by the gfn field. role.quadrant: - When role.gpte_is_8_bytes=0, the guest uses 32-bit gptes while the host uses 64-bit + When role.has_4_byte_gpte=1, the guest uses 32-bit gptes while the host uses 64-bit sptes. That means a guest page table contains more ptes than the host, so multiple shadow pages are needed to shadow one guest page. For first-level shadow pages, role.quadrant can be 0 or 1 and denotes the @@ -177,9 +177,9 @@ Shadow pages contain the following information: The page is invalid and should not be used. It is a root page that is currently pinned (by a cpu hardware register pointing to it); once it is unpinned it will be destroyed. - role.gpte_is_8_bytes: - Reflects the size of the guest PTE for which the page is valid, i.e. '1' - if 64-bit gptes are in use, '0' if 32-bit gptes are in use. + role.has_4_byte_gpte: + Reflects the size of the guest PTE for which the page is valid, i.e. '0' + if direct map or 64-bit gptes are in use, '1' if 32-bit gptes are in use. role.efer_nx: Contains the value of efer.nx for which the page is valid. role.cr0_wp: diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index 2cafd3c3c6cb..d5ad96c795f6 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -664,7 +664,11 @@ one is input, the second one output. * The fd channel - use file descriptor numbers for input/output. Example: ``con1=fd:0,fd:1.`` -* The port channel - listen on TCP port number. Example: ``con1=port:4321`` +* The port channel - start a telnet server on TCP port number. Example: + ``con1=port:4321``. The host must have /usr/sbin/in.telnetd (usually part of + a telnetd package) and the port-helper from the UML utilities (see the + information for the xterm channel below). UML will not boot until a client + connects. * The pty and pts channels - use system pty/pts. diff --git a/Documentation/vm/arch_pgtable_helpers.rst b/Documentation/vm/arch_pgtable_helpers.rst index 552567d863b8..f8b225fc9190 100644 --- a/Documentation/vm/arch_pgtable_helpers.rst +++ b/Documentation/vm/arch_pgtable_helpers.rst @@ -66,9 +66,11 @@ PTE Page Table Helpers +---------------------------+--------------------------------------------------+ | pte_mknotpresent | Invalidates a mapped PTE | +---------------------------+--------------------------------------------------+ -| ptep_get_and_clear | Clears a PTE | +| ptep_clear | Clears a PTE | +---------------------------+--------------------------------------------------+ -| ptep_get_and_clear_full | Clears a PTE | +| ptep_get_and_clear | Clears and returns PTE | ++---------------------------+--------------------------------------------------+ +| ptep_get_and_clear_full | Clears and returns PTE (batched PTE unmap) | +---------------------------+--------------------------------------------------+ | ptep_test_and_clear_young | Clears young from a PTE | +---------------------------+--------------------------------------------------+ @@ -247,12 +249,12 @@ SWAP Page Table Helpers | __swp_to_pmd_entry | Creates a mapped PMD from a swapped entry (arch) | +---------------------------+--------------------------------------------------+ | is_migration_entry | Tests a migration (read or write) swapped entry | -+---------------------------+--------------------------------------------------+ -| is_write_migration_entry | Tests a write migration swapped entry | -+---------------------------+--------------------------------------------------+ -| make_migration_entry_read | Converts into read migration swapped entry | -+---------------------------+--------------------------------------------------+ -| make_migration_entry | Creates a migration swapped entry (read or write)| -+---------------------------+--------------------------------------------------+ ++-------------------------------+----------------------------------------------+ +| is_writable_migration_entry | Tests a write migration swapped entry | ++-------------------------------+----------------------------------------------+ +| make_readable_migration_entry | Creates a read migration swapped entry | ++-------------------------------+----------------------------------------------+ +| make_writable_migration_entry | Creates a write migration swapped entry | ++-------------------------------+----------------------------------------------+ [1] https://lore.kernel.org/linux-mm/20181017020930.GN30832@redhat.com/ diff --git a/Documentation/vm/cleancache.rst b/Documentation/vm/cleancache.rst deleted file mode 100644 index 68cba9131c31..000000000000 --- a/Documentation/vm/cleancache.rst +++ /dev/null @@ -1,296 +0,0 @@ -.. _cleancache: - -========== -Cleancache -========== - -Motivation -========== - -Cleancache is a new optional feature provided by the VFS layer that -potentially dramatically increases page cache effectiveness for -many workloads in many environments at a negligible cost. - -Cleancache can be thought of as a page-granularity victim cache for clean -pages that the kernel's pageframe replacement algorithm (PFRA) would like -to keep around, but can't since there isn't enough memory. So when the -PFRA "evicts" a page, it first attempts to use cleancache code to -put the data contained in that page into "transcendent memory", memory -that is not directly accessible or addressable by the kernel and is -of unknown and possibly time-varying size. - -Later, when a cleancache-enabled filesystem wishes to access a page -in a file on disk, it first checks cleancache to see if it already -contains it; if it does, the page of data is copied into the kernel -and a disk access is avoided. - -Transcendent memory "drivers" for cleancache are currently implemented -in Xen (using hypervisor memory) and zcache (using in-kernel compressed -memory) and other implementations are in development. - -:ref:`FAQs <faq>` are included below. - -Implementation Overview -======================= - -A cleancache "backend" that provides transcendent memory registers itself -to the kernel's cleancache "frontend" by calling cleancache_register_ops, -passing a pointer to a cleancache_ops structure with funcs set appropriately. -The functions provided must conform to certain semantics as follows: - -Most important, cleancache is "ephemeral". Pages which are copied into -cleancache have an indefinite lifetime which is completely unknowable -by the kernel and so may or may not still be in cleancache at any later time. -Thus, as its name implies, cleancache is not suitable for dirty pages. -Cleancache has complete discretion over what pages to preserve and what -pages to discard and when. - -Mounting a cleancache-enabled filesystem should call "init_fs" to obtain a -pool id which, if positive, must be saved in the filesystem's superblock; -a negative return value indicates failure. A "put_page" will copy a -(presumably about-to-be-evicted) page into cleancache and associate it with -the pool id, a file key, and a page index into the file. (The combination -of a pool id, a file key, and an index is sometimes called a "handle".) -A "get_page" will copy the page, if found, from cleancache into kernel memory. -An "invalidate_page" will ensure the page no longer is present in cleancache; -an "invalidate_inode" will invalidate all pages associated with the specified -file; and, when a filesystem is unmounted, an "invalidate_fs" will invalidate -all pages in all files specified by the given pool id and also surrender -the pool id. - -An "init_shared_fs", like init_fs, obtains a pool id but tells cleancache -to treat the pool as shared using a 128-bit UUID as a key. On systems -that may run multiple kernels (such as hard partitioned or virtualized -systems) that may share a clustered filesystem, and where cleancache -may be shared among those kernels, calls to init_shared_fs that specify the -same UUID will receive the same pool id, thus allowing the pages to -be shared. Note that any security requirements must be imposed outside -of the kernel (e.g. by "tools" that control cleancache). Or a -cleancache implementation can simply disable shared_init by always -returning a negative value. - -If a get_page is successful on a non-shared pool, the page is invalidated -(thus making cleancache an "exclusive" cache). On a shared pool, the page -is NOT invalidated on a successful get_page so that it remains accessible to -other sharers. The kernel is responsible for ensuring coherency between -cleancache (shared or not), the page cache, and the filesystem, using -cleancache invalidate operations as required. - -Note that cleancache must enforce put-put-get coherency and get-get -coherency. For the former, if two puts are made to the same handle but -with different data, say AAA by the first put and BBB by the second, a -subsequent get can never return the stale data (AAA). For get-get coherency, -if a get for a given handle fails, subsequent gets for that handle will -never succeed unless preceded by a successful put with that handle. - -Last, cleancache provides no SMP serialization guarantees; if two -different Linux threads are simultaneously putting and invalidating a page -with the same handle, the results are indeterminate. Callers must -lock the page to ensure serial behavior. - -Cleancache Performance Metrics -============================== - -If properly configured, monitoring of cleancache is done via debugfs in -the `/sys/kernel/debug/cleancache` directory. The effectiveness of cleancache -can be measured (across all filesystems) with: - -``succ_gets`` - number of gets that were successful - -``failed_gets`` - number of gets that failed - -``puts`` - number of puts attempted (all "succeed") - -``invalidates`` - number of invalidates attempted - -A backend implementation may provide additional metrics. - -.. _faq: - -FAQ -=== - -* Where's the value? (Andrew Morton) - -Cleancache provides a significant performance benefit to many workloads -in many environments with negligible overhead by improving the -effectiveness of the pagecache. Clean pagecache pages are -saved in transcendent memory (RAM that is otherwise not directly -addressable to the kernel); fetching those pages later avoids "refaults" -and thus disk reads. - -Cleancache (and its sister code "frontswap") provide interfaces for -this transcendent memory (aka "tmem"), which conceptually lies between -fast kernel-directly-addressable RAM and slower DMA/asynchronous devices. -Disallowing direct kernel or userland reads/writes to tmem -is ideal when data is transformed to a different form and size (such -as with compression) or secretly moved (as might be useful for write- -balancing for some RAM-like devices). Evicted page-cache pages (and -swap pages) are a great use for this kind of slower-than-RAM-but-much- -faster-than-disk transcendent memory, and the cleancache (and frontswap) -"page-object-oriented" specification provides a nice way to read and -write -- and indirectly "name" -- the pages. - -In the virtual case, the whole point of virtualization is to statistically -multiplex physical resources across the varying demands of multiple -virtual machines. This is really hard to do with RAM and efforts to -do it well with no kernel change have essentially failed (except in some -well-publicized special-case workloads). Cleancache -- and frontswap -- -with a fairly small impact on the kernel, provide a huge amount -of flexibility for more dynamic, flexible RAM multiplexing. -Specifically, the Xen Transcendent Memory backend allows otherwise -"fallow" hypervisor-owned RAM to not only be "time-shared" between multiple -virtual machines, but the pages can be compressed and deduplicated to -optimize RAM utilization. And when guest OS's are induced to surrender -underutilized RAM (e.g. with "self-ballooning"), page cache pages -are the first to go, and cleancache allows those pages to be -saved and reclaimed if overall host system memory conditions allow. - -And the identical interface used for cleancache can be used in -physical systems as well. The zcache driver acts as a memory-hungry -device that stores pages of data in a compressed state. And -the proposed "RAMster" driver shares RAM across multiple physical -systems. - -* Why does cleancache have its sticky fingers so deep inside the - filesystems and VFS? (Andrew Morton and Christoph Hellwig) - -The core hooks for cleancache in VFS are in most cases a single line -and the minimum set are placed precisely where needed to maintain -coherency (via cleancache_invalidate operations) between cleancache, -the page cache, and disk. All hooks compile into nothingness if -cleancache is config'ed off and turn into a function-pointer- -compare-to-NULL if config'ed on but no backend claims the ops -functions, or to a compare-struct-element-to-negative if a -backend claims the ops functions but a filesystem doesn't enable -cleancache. - -Some filesystems are built entirely on top of VFS and the hooks -in VFS are sufficient, so don't require an "init_fs" hook; the -initial implementation of cleancache didn't provide this hook. -But for some filesystems (such as btrfs), the VFS hooks are -incomplete and one or more hooks in fs-specific code are required. -And for some other filesystems, such as tmpfs, cleancache may -be counterproductive. So it seemed prudent to require a filesystem -to "opt in" to use cleancache, which requires adding a hook in -each filesystem. Not all filesystems are supported by cleancache -only because they haven't been tested. The existing set should -be sufficient to validate the concept, the opt-in approach means -that untested filesystems are not affected, and the hooks in the -existing filesystems should make it very easy to add more -filesystems in the future. - -The total impact of the hooks to existing fs and mm files is only -about 40 lines added (not counting comments and blank lines). - -* Why not make cleancache asynchronous and batched so it can more - easily interface with real devices with DMA instead of copying each - individual page? (Minchan Kim) - -The one-page-at-a-time copy semantics simplifies the implementation -on both the frontend and backend and also allows the backend to -do fancy things on-the-fly like page compression and -page deduplication. And since the data is "gone" (copied into/out -of the pageframe) before the cleancache get/put call returns, -a great deal of race conditions and potential coherency issues -are avoided. While the interface seems odd for a "real device" -or for real kernel-addressable RAM, it makes perfect sense for -transcendent memory. - -* Why is non-shared cleancache "exclusive"? And where is the - page "invalidated" after a "get"? (Minchan Kim) - -The main reason is to free up space in transcendent memory and -to avoid unnecessary cleancache_invalidate calls. If you want inclusive, -the page can be "put" immediately following the "get". If -put-after-get for inclusive becomes common, the interface could -be easily extended to add a "get_no_invalidate" call. - -The invalidate is done by the cleancache backend implementation. - -* What's the performance impact? - -Performance analysis has been presented at OLS'09 and LCA'10. -Briefly, performance gains can be significant on most workloads, -especially when memory pressure is high (e.g. when RAM is -overcommitted in a virtual workload); and because the hooks are -invoked primarily in place of or in addition to a disk read/write, -overhead is negligible even in worst case workloads. Basically -cleancache replaces I/O with memory-copy-CPU-overhead; on older -single-core systems with slow memory-copy speeds, cleancache -has little value, but in newer multicore machines, especially -consolidated/virtualized machines, it has great value. - -* How do I add cleancache support for filesystem X? (Boaz Harrash) - -Filesystems that are well-behaved and conform to certain -restrictions can utilize cleancache simply by making a call to -cleancache_init_fs at mount time. Unusual, misbehaving, or -poorly layered filesystems must either add additional hooks -and/or undergo extensive additional testing... or should just -not enable the optional cleancache. - -Some points for a filesystem to consider: - - - The FS should be block-device-based (e.g. a ram-based FS such - as tmpfs should not enable cleancache) - - To ensure coherency/correctness, the FS must ensure that all - file removal or truncation operations either go through VFS or - add hooks to do the equivalent cleancache "invalidate" operations - - To ensure coherency/correctness, either inode numbers must - be unique across the lifetime of the on-disk file OR the - FS must provide an "encode_fh" function. - - The FS must call the VFS superblock alloc and deactivate routines - or add hooks to do the equivalent cleancache calls done there. - - To maximize performance, all pages fetched from the FS should - go through the do_mpag_readpage routine or the FS should add - hooks to do the equivalent (cf. btrfs) - - Currently, the FS blocksize must be the same as PAGESIZE. This - is not an architectural restriction, but no backends currently - support anything different. - - A clustered FS should invoke the "shared_init_fs" cleancache - hook to get best performance for some backends. - -* Why not use the KVA of the inode as the key? (Christoph Hellwig) - -If cleancache would use the inode virtual address instead of -inode/filehandle, the pool id could be eliminated. But, this -won't work because cleancache retains pagecache data pages -persistently even when the inode has been pruned from the -inode unused list, and only invalidates the data page if the file -gets removed/truncated. So if cleancache used the inode kva, -there would be potential coherency issues if/when the inode -kva is reused for a different file. Alternately, if cleancache -invalidated the pages when the inode kva was freed, much of the value -of cleancache would be lost because the cache of pages in cleanache -is potentially much larger than the kernel pagecache and is most -useful if the pages survive inode cache removal. - -* Why is a global variable required? - -The cleancache_enabled flag is checked in all of the frequently-used -cleancache hooks. The alternative is a function call to check a static -variable. Since cleancache is enabled dynamically at runtime, systems -that don't enable cleancache would suffer thousands (possibly -tens-of-thousands) of unnecessary function calls per second. So the -global variable allows cleancache to be enabled by default at compile -time, but have insignificant performance impact when cleancache remains -disabled at runtime. - -* Does cleanache work with KVM? - -The memory model of KVM is sufficiently different that a cleancache -backend may have less value for KVM. This remains to be tested, -especially in an overcommitted system. - -* Does cleancache work in userspace? It sounds useful for - memory hungry caches like web browsers. (Jamie Lokier) - -No plans yet, though we agree it sounds useful, at least for -apps that bypass the page cache (e.g. O_DIRECT). - -Last updated: Dan Magenheimer, April 13 2011 diff --git a/Documentation/vm/damon/design.rst b/Documentation/vm/damon/design.rst index 210f0f50efd8..0cff6fac6b7e 100644 --- a/Documentation/vm/damon/design.rst +++ b/Documentation/vm/damon/design.rst @@ -13,12 +13,13 @@ primitives that dependent on and optimized for the target address space. On the other hand, the accuracy and overhead tradeoff mechanism, which is the core of DAMON, is in the pure logic space. DAMON separates the two parts in different layers and defines its interface to allow various low level -primitives implementations configurable with the core logic. +primitives implementations configurable with the core logic. We call the low +level primitives implementations monitoring operations. Due to this separated design and the configurable interface, users can extend -DAMON for any address space by configuring the core logics with appropriate low -level primitive implementations. If appropriate one is not provided, users can -implement the primitives on their own. +DAMON for any address space by configuring the core logics with appropriate +monitoring operations. If appropriate one is not provided, users can implement +the operations on their own. For example, physical memory, virtual memory, swap space, those for specific processes, NUMA nodes, files, and backing memory devices would be supportable. @@ -26,25 +27,24 @@ Also, if some architectures or devices support special optimized access check primitives, those will be easily configurable. -Reference Implementations of Address Space Specific Primitives -============================================================== +Reference Implementations of Address Space Specific Monitoring Operations +========================================================================= -The low level primitives for the fundamental access monitoring are defined in -two parts: +The monitoring operations are defined in two parts: 1. Identification of the monitoring target address range for the address space. 2. Access check of specific address range in the target space. -DAMON currently provides the implementations of the primitives for the physical +DAMON currently provides the implementations of the operations for the physical and virtual address spaces. Below two subsections describe how those work. VMA-based Target Address Range Construction ------------------------------------------- -This is only for the virtual address space primitives implementation. That for -the physical address space simply asks users to manually set the monitoring -target address ranges. +This is only for the virtual address space monitoring operations +implementation. That for the physical address space simply asks users to +manually set the monitoring target address ranges. Only small parts in the super-huge virtual address space of the processes are mapped to the physical memory and accessed. Thus, tracking the unmapped @@ -84,9 +84,10 @@ table having a mapping to the address. In this way, the implementations find and clear the bit(s) for next sampling target address and checks whether the bit(s) set again after one sampling period. This could disturb other kernel subsystems using the Accessed bits, namely Idle page tracking and the reclaim -logic. To avoid such disturbances, DAMON makes it mutually exclusive with Idle -page tracking and uses ``PG_idle`` and ``PG_young`` page flags to solve the -conflict with the reclaim logic, as Idle page tracking does. +logic. DAMON does nothing to avoid disturbing Idle page tracking, so handling +the interference is the responsibility of sysadmins. However, it solves the +conflict with the reclaim logic using ``PG_idle`` and ``PG_young`` page flags, +as Idle page tracking does. Address Space Independent Core Mechanisms @@ -94,8 +95,8 @@ Address Space Independent Core Mechanisms Below four sections describe each of the DAMON core mechanisms and the five monitoring attributes, ``sampling interval``, ``aggregation interval``, -``regions update interval``, ``minimum number of regions``, and ``maximum -number of regions``. +``update interval``, ``minimum number of regions``, and ``maximum number of +regions``. Access Frequency Monitoring @@ -168,6 +169,8 @@ The monitoring target address range could dynamically changed. For example, virtual memory could be dynamically mapped and unmapped. Physical memory could be hot-plugged. -As the changes could be quite frequent in some cases, DAMON checks the dynamic -memory mapping changes and applies it to the abstracted target area only for -each of a user-specified time interval (``regions update interval``). +As the changes could be quite frequent in some cases, DAMON allows the +monitoring operations to check dynamic changes including memory mapping changes +and applies it to monitoring operations-related data structures such as the +abstracted monitoring target memory area only for each of a user-specified time +interval (``update interval``). diff --git a/Documentation/vm/damon/faq.rst b/Documentation/vm/damon/faq.rst index 11aea40eb328..dde7e2414ee6 100644 --- a/Documentation/vm/damon/faq.rst +++ b/Documentation/vm/damon/faq.rst @@ -31,7 +31,7 @@ Does DAMON support virtual memory only? ======================================= No. The core of the DAMON is address space independent. The address space -specific low level primitive parts including monitoring target regions +specific monitoring operations including monitoring target regions constructions and actual access checks can be implemented and configured on the DAMON core by the users. In this way, DAMON users can monitor any address space with any access check technique. diff --git a/Documentation/vm/frontswap.rst b/Documentation/vm/frontswap.rst index 1979f430c1c5..feecc5e24477 100644 --- a/Documentation/vm/frontswap.rst +++ b/Documentation/vm/frontswap.rst @@ -8,12 +8,6 @@ Frontswap provides a "transcendent memory" interface for swap pages. In some environments, dramatic performance savings may be obtained because swapped pages are saved in RAM (or a RAM-like device) instead of a swap disk. -(Note, frontswap -- and :ref:`cleancache` (merged at 3.0) -- are the "frontends" -and the only necessary changes to the core kernel for transcendent memory; -all other supporting code -- the "backends" -- is implemented as drivers. -See the LWN.net article `Transcendent memory in a nutshell`_ -for a detailed overview of frontswap and related kernel parts) - .. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/ Frontswap is so named because it can be thought of as the opposite of @@ -45,12 +39,6 @@ a disk write and, if the data is later read back, a disk read are avoided. If a store returns failure, transcendent memory has rejected the data, and the page can be written to swap as usual. -If a backend chooses, frontswap can be configured as a "writethrough -cache" by calling frontswap_writethrough(). In this mode, the reduction -in swap device writes is lost (and also a non-trivial performance advantage) -in order to allow the backend to arbitrarily "reclaim" space used to -store frontswap pages to more completely manage its memory usage. - Note that if a page is stored and the page already exists in transcendent memory (a "duplicate" store), either the store succeeds and the data is overwritten, or the store fails AND the page is invalidated. This ensures stale data may @@ -87,11 +75,9 @@ This interface is ideal when data is transformed to a different form and size (such as with compression) or secretly moved (as might be useful for write-balancing for some RAM-like devices). Swap pages (and evicted page-cache pages) are a great use for this kind of slower-than-RAM- -but-much-faster-than-disk "pseudo-RAM device" and the frontswap (and -cleancache) interface to transcendent memory provides a nice way to read -and write -- and indirectly "name" -- the pages. +but-much-faster-than-disk "pseudo-RAM device". -Frontswap -- and cleancache -- with a fairly small impact on the kernel, +Frontswap with a fairly small impact on the kernel, provides a huge amount of flexibility for more dynamic, flexible RAM utilization in various system configurations: @@ -269,19 +255,6 @@ the old data and ensure that it is no longer accessible. Since the swap subsystem then writes the new data to the read swap device, this is the correct course of action to ensure coherency. -* What is frontswap_shrink for? - -When the (non-frontswap) swap subsystem swaps out a page to a real -swap device, that page is only taking up low-value pre-allocated disk -space. But if frontswap has placed a page in transcendent memory, that -page may be taking up valuable real estate. The frontswap_shrink -routine allows code outside of the swap subsystem to force pages out -of the memory managed by frontswap and back into kernel-addressable memory. -For example, in RAMster, a "suction driver" thread will attempt -to "repatriate" pages sent to a remote machine back to the local machine; -this is driven using the frontswap_shrink mechanism when memory pressure -subsides. - * Why does the frontswap patch create the new include file swapfile.h? The frontswap code depends on some swap-subsystem-internal data diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst index 6f5ffef4b716..44365c4574a3 100644 --- a/Documentation/vm/index.rst +++ b/Documentation/vm/index.rst @@ -15,7 +15,6 @@ algorithms. If you are looking for advice on simply allocating memory, see the active_mm arch_pgtable_helpers balance - cleancache damon/index free_page_reporting frontswap @@ -31,10 +30,12 @@ algorithms. If you are looking for advice on simply allocating memory, see the page_migration page_frags page_owner + page_table_check remap_file_pages slub split_page_table_lock transhuge unevictable-lru + vmalloced-kernel-stacks z3fold zsmalloc diff --git a/Documentation/vm/overcommit-accounting.rst b/Documentation/vm/overcommit-accounting.rst index 0dd54bbe4afa..1addb0c374a4 100644 --- a/Documentation/vm/overcommit-accounting.rst +++ b/Documentation/vm/overcommit-accounting.rst @@ -34,7 +34,8 @@ The Linux kernel supports the following overcommit handling modes The overcommit policy is set via the sysctl ``vm.overcommit_memory``. The overcommit amount can be set via ``vm.overcommit_ratio`` (percentage) -or ``vm.overcommit_kbytes`` (absolute value). +or ``vm.overcommit_kbytes`` (absolute value). These only have an effect +when ``vm.overcommit_memory`` is set to 2. The current overcommit limit and amount committed are viewable in ``/proc/meminfo`` as CommitLimit and Committed_AS respectively. diff --git a/Documentation/vm/page_migration.rst b/Documentation/vm/page_migration.rst index 08810f549f70..8c5cb8147e55 100644 --- a/Documentation/vm/page_migration.rst +++ b/Documentation/vm/page_migration.rst @@ -263,15 +263,15 @@ Monitoring Migration The following events (counters) can be used to monitor page migration. 1. PGMIGRATE_SUCCESS: Normal page migration success. Each count means that a - page was migrated. If the page was a non-THP page, then this counter is - increased by one. If the page was a THP, then this counter is increased by - the number of THP subpages. For example, migration of a single 2MB THP that - has 4KB-size base pages (subpages) will cause this counter to increase by - 512. + page was migrated. If the page was a non-THP and non-hugetlb page, then + this counter is increased by one. If the page was a THP or hugetlb, then + this counter is increased by the number of THP or hugetlb subpages. + For example, migration of a single 2MB THP that has 4KB-size base pages + (subpages) will cause this counter to increase by 512. 2. PGMIGRATE_FAIL: Normal page migration failure. Same counting rules as for PGMIGRATE_SUCCESS, above: this will be increased by the number of subpages, - if it was a THP. + if it was a THP or hugetlb. 3. THP_MIGRATION_SUCCESS: A THP was migrated without being split. diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst index 9837fc8147dd..905555e3e483 100644 --- a/Documentation/vm/page_owner.rst +++ b/Documentation/vm/page_owner.rst @@ -26,9 +26,9 @@ fragmentation statistics can be obtained through gfp flag information of each page. It is already implemented and activated if page owner is enabled. Other usages are more than welcome. -page owner is disabled in default. So, if you'd like to use it, you need -to add "page_owner=on" into your boot cmdline. If the kernel is built -with page owner and page owner is disabled in runtime due to no enabling +page owner is disabled by default. So, if you'd like to use it, you need +to add "page_owner=on" to your boot cmdline. If the kernel is built +with page owner and page owner is disabled in runtime due to not enabling boot option, runtime overhead is marginal. If disabled in runtime, it doesn't require memory to store owner information, so there is no runtime memory overhead. And, page owner inserts just two unlikely branches into @@ -85,7 +85,7 @@ Usage cat /sys/kernel/debug/page_owner > page_owner_full.txt ./page_owner_sort page_owner_full.txt sorted_page_owner.txt - The general output of ``page_owner_full.txt`` is as follows: + The general output of ``page_owner_full.txt`` is as follows:: Page allocated via order XXX, ... PFN XXX ... @@ -100,7 +100,7 @@ Usage and pages of buf, and finally sorts them according to the times. See the result about who allocated each page - in the ``sorted_page_owner.txt``. General output: + in the ``sorted_page_owner.txt``. General output:: XXX times, XXX pages: Page allocated via order XXX, ... diff --git a/Documentation/vm/page_table_check.rst b/Documentation/vm/page_table_check.rst new file mode 100644 index 000000000000..1a09472f10a3 --- /dev/null +++ b/Documentation/vm/page_table_check.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _page_table_check: + +================ +Page Table Check +================ + +Introduction +============ + +Page table check allows to harden the kernel by ensuring that some types of +the memory corruptions are prevented. + +Page table check performs extra verifications at the time when new pages become +accessible from the userspace by getting their page table entries (PTEs PMDs +etc.) added into the table. + +In case of detected corruption, the kernel is crashed. There is a small +performance and memory overhead associated with the page table check. Therefore, +it is disabled by default, but can be optionally enabled on systems where the +extra hardening outweighs the performance costs. Also, because page table check +is synchronous, it can help with debugging double map memory corruption issues, +by crashing kernel at the time wrong mapping occurs instead of later which is +often the case with memory corruptions bugs. + +Double mapping detection logic +============================== + ++-------------------+-------------------+-------------------+------------------+ +| Current Mapping | New mapping | Permissions | Rule | ++===================+===================+===================+==================+ +| Anonymous | Anonymous | Read | Allow | ++-------------------+-------------------+-------------------+------------------+ +| Anonymous | Anonymous | Read / Write | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Anonymous | Named | Any | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Named | Anonymous | Any | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Named | Named | Any | Allow | ++-------------------+-------------------+-------------------+------------------+ + +Enabling Page Table Check +========================= + +Build kernel with: + +- PAGE_TABLE_CHECK=y + Note, it can only be enabled on platforms where ARCH_SUPPORTS_PAGE_TABLE_CHECK + is available. + +- Boot with 'page_table_check=on' kernel parameter. + +Optionally, build kernel with PAGE_TABLE_CHECK_ENFORCED in order to have page +table support without extra kernel parameter. diff --git a/Documentation/vm/vmalloced-kernel-stacks.rst b/Documentation/vm/vmalloced-kernel-stacks.rst new file mode 100644 index 000000000000..fc8c67833af6 --- /dev/null +++ b/Documentation/vm/vmalloced-kernel-stacks.rst @@ -0,0 +1,153 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Virtually Mapped Kernel Stack Support +===================================== + +:Author: Shuah Khan <skhan@linuxfoundation.org> + +.. contents:: :local: + +Overview +-------- + +This is a compilation of information from the code and original patch +series that introduced the `Virtually Mapped Kernel Stacks feature +<https://lwn.net/Articles/694348/>` + +Introduction +------------ + +Kernel stack overflows are often hard to debug and make the kernel +susceptible to exploits. Problems could show up at a later time making +it difficult to isolate and root-cause. + +Virtually-mapped kernel stacks with guard pages causes kernel stack +overflows to be caught immediately rather than causing difficult to +diagnose corruptions. + +HAVE_ARCH_VMAP_STACK and VMAP_STACK configuration options enable +support for virtually mapped stacks with guard pages. This feature +causes reliable faults when the stack overflows. The usability of +the stack trace after overflow and response to the overflow itself +is architecture dependent. + +.. note:: + As of this writing, arm64, powerpc, riscv, s390, um, and x86 have + support for VMAP_STACK. + +HAVE_ARCH_VMAP_STACK +-------------------- + +Architectures that can support Virtually Mapped Kernel Stacks should +enable this bool configuration option. The requirements are: + +- vmalloc space must be large enough to hold many kernel stacks. This + may rule out many 32-bit architectures. +- Stacks in vmalloc space need to work reliably. For example, if + vmap page tables are created on demand, either this mechanism + needs to work while the stack points to a virtual address with + unpopulated page tables or arch code (switch_to() and switch_mm(), + most likely) needs to ensure that the stack's page table entries + are populated before running on a possibly unpopulated stack. +- If the stack overflows into a guard page, something reasonable + should happen. The definition of "reasonable" is flexible, but + instantly rebooting without logging anything would be unfriendly. + +VMAP_STACK +---------- + +VMAP_STACK bool configuration option when enabled allocates virtually +mapped task stacks. This option depends on HAVE_ARCH_VMAP_STACK. + +- Enable this if you want the use virtually-mapped kernel stacks + with guard pages. This causes kernel stack overflows to be caught + immediately rather than causing difficult-to-diagnose corruption. + +.. note:: + + Using this feature with KASAN requires architecture support + for backing virtual mappings with real shadow memory, and + KASAN_VMALLOC must be enabled. + +.. note:: + + VMAP_STACK is enabled, it is not possible to run DMA on stack + allocated data. + +Kernel configuration options and dependencies keep changing. Refer to +the latest code base: + +`Kconfig <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/Kconfig>` + +Allocation +----------- + +When a new kernel thread is created, thread stack is allocated from +virtually contiguous memory pages from the page level allocator. These +pages are mapped into contiguous kernel virtual space with PAGE_KERNEL +protections. + +alloc_thread_stack_node() calls __vmalloc_node_range() to allocate stack +with PAGE_KERNEL protections. + +- Allocated stacks are cached and later reused by new threads, so memcg + accounting is performed manually on assigning/releasing stacks to tasks. + Hence, __vmalloc_node_range is called without __GFP_ACCOUNT. +- vm_struct is cached to be able to find when thread free is initiated + in interrupt context. free_thread_stack() can be called in interrupt + context. +- On arm64, all VMAP's stacks need to have the same alignment to ensure + that VMAP'd stack overflow detection works correctly. Arch specific + vmap stack allocator takes care of this detail. +- This does not address interrupt stacks - according to the original patch + +Thread stack allocation is initiated from clone(), fork(), vfork(), +kernel_thread() via kernel_clone(). Leaving a few hints for searching +the code base to understand when and how thread stack is allocated. + +Bulk of the code is in: +`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`. + +stack_vm_area pointer in task_struct keeps track of the virtually allocated +stack and a non-null stack_vm_area pointer serves as a indication that the +virtually mapped kernel stacks are enabled. + +:: + + struct vm_struct *stack_vm_area; + +Stack overflow handling +----------------------- + +Leading and trailing guard pages help detect stack overflows. When stack +overflows into the guard pages, handlers have to be careful not overflow +the stack again. When handlers are called, it is likely that very little +stack space is left. + +On x86, this is done by handling the page fault indicating the kernel +stack overflow on the double-fault stack. + +Testing VMAP allocation with guard pages +---------------------------------------- + +How do we ensure that VMAP_STACK is actually allocating with a leading +and trailing guard page? The following lkdtm tests can help detect any +regressions. + +:: + + void lkdtm_STACK_GUARD_PAGE_LEADING() + void lkdtm_STACK_GUARD_PAGE_TRAILING() + +Conclusions +----------- + +- A percpu cache of vmalloced stacks appears to be a bit faster than a + high-order stack allocation, at least when the cache hits. +- THREAD_INFO_IN_TASK gets rid of arch-specific thread_info entirely and + simply embed the thread_info (containing only flags) and 'int cpu' into + task_struct. +- The thread stack can be free'ed as soon as the task is dead (without + waiting for RCU) and then, if vmapped stacks are in use, cache the + entire stack for reuse on the same cpu. diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst index f498f1d36cd3..982c8af853b9 100644 --- a/Documentation/x86/index.rst +++ b/Documentation/x86/index.rst @@ -21,6 +21,7 @@ x86-specific Documentation tlb mtrr pat + intel-hfi intel-iommu intel_txt amd-memory-encryption diff --git a/Documentation/x86/intel-hfi.rst b/Documentation/x86/intel-hfi.rst new file mode 100644 index 000000000000..49dea58ea4fb --- /dev/null +++ b/Documentation/x86/intel-hfi.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================ +Hardware-Feedback Interface for scheduling on Intel Hardware +============================================================ + +Overview +-------- + +Intel has described the Hardware Feedback Interface (HFI) in the Intel 64 and +IA-32 Architectures Software Developer's Manual (Intel SDM) Volume 3 Section +14.6 [1]_. + +The HFI gives the operating system a performance and energy efficiency +capability data for each CPU in the system. Linux can use the information from +the HFI to influence task placement decisions. + +The Hardware Feedback Interface +------------------------------- + +The Hardware Feedback Interface provides to the operating system information +about the performance and energy efficiency of each CPU in the system. Each +capability is given as a unit-less quantity in the range [0-255]. Higher values +indicate higher capability. Energy efficiency and performance are reported in +separate capabilities. Even though on some systems these two metrics may be +related, they are specified as independent capabilities in the Intel SDM. + +These capabilities may change at runtime as a result of changes in the +operating conditions of the system or the action of external factors. The rate +at which these capabilities are updated is specific to each processor model. On +some models, capabilities are set at boot time and never change. On others, +capabilities may change every tens of milliseconds. For instance, a remote +mechanism may be used to lower Thermal Design Power. Such change can be +reflected in the HFI. Likewise, if the system needs to be throttled due to +excessive heat, the HFI may reflect reduced performance on specific CPUs. + +The kernel or a userspace policy daemon can use these capabilities to modify +task placement decisions. For instance, if either the performance or energy +capabilities of a given logical processor becomes zero, it is an indication that +the hardware recommends to the operating system to not schedule any tasks on +that processor for performance or energy efficiency reasons, respectively. + +Implementation details for Linux +-------------------------------- + +The infrastructure to handle thermal event interrupts has two parts. In the +Local Vector Table of a CPU's local APIC, there exists a register for the +Thermal Monitor Register. This register controls how interrupts are delivered +to a CPU when the thermal monitor generates and interrupt. Further details +can be found in the Intel SDM Vol. 3 Section 10.5 [1]_. + +The thermal monitor may generate interrupts per CPU or per package. The HFI +generates package-level interrupts. This monitor is configured and initialized +via a set of machine-specific registers. Specifically, the HFI interrupt and +status are controlled via designated bits in the IA32_PACKAGE_THERM_INTERRUPT +and IA32_PACKAGE_THERM_STATUS registers, respectively. There exists one HFI +table per package. Further details can be found in the Intel SDM Vol. 3 +Section 14.9 [1]_. + +The hardware issues an HFI interrupt after updating the HFI table and is ready +for the operating system to consume it. CPUs receive such interrupt via the +thermal entry in the Local APIC's Local Vector Table. + +When servicing such interrupt, the HFI driver parses the updated table and +relays the update to userspace using the thermal notification framework. Given +that there may be many HFI updates every second, the updates relayed to +userspace are throttled at a rate of CONFIG_HZ jiffies. + +References +---------- + +.. [1] https://www.intel.com/sdm diff --git a/Documentation/x86/sva.rst b/Documentation/x86/sva.rst index 076efd51ef1f..2e9b8b0f9a0f 100644 --- a/Documentation/x86/sva.rst +++ b/Documentation/x86/sva.rst @@ -104,18 +104,47 @@ The MSR must be configured on each logical CPU before any application thread can interact with a device. Threads that belong to the same process share the same page tables, thus the same MSR value. -PASID is cleared when a process is created. The PASID allocation and MSR -programming may occur long after a process and its threads have been created. -One thread must call iommu_sva_bind_device() to allocate the PASID for the -process. If a thread uses ENQCMD without the MSR first being populated, a #GP -will be raised. The kernel will update the PASID MSR with the PASID for all -threads in the process. A single process PASID can be used simultaneously -with multiple devices since they all share the same address space. - -One thread can call iommu_sva_unbind_device() to free the allocated PASID. -The kernel will clear the PASID MSR for all threads belonging to the process. - -New threads inherit the MSR value from the parent. +PASID Life Cycle Management +=========================== + +PASID is initialized as INVALID_IOASID (-1) when a process is created. + +Only processes that access SVA-capable devices need to have a PASID +allocated. This allocation happens when a process opens/binds an SVA-capable +device but finds no PASID for this process. Subsequent binds of the same, or +other devices will share the same PASID. + +Although the PASID is allocated to the process by opening a device, +it is not active in any of the threads of that process. It's loaded to the +IA32_PASID MSR lazily when a thread tries to submit a work descriptor +to a device using the ENQCMD. + +That first access will trigger a #GP fault because the IA32_PASID MSR +has not been initialized with the PASID value assigned to the process +when the device was opened. The Linux #GP handler notes that a PASID has +been allocated for the process, and so initializes the IA32_PASID MSR +and returns so that the ENQCMD instruction is re-executed. + +On fork(2) or exec(2) the PASID is removed from the process as it no +longer has the same address space that it had when the device was opened. + +On clone(2) the new task shares the same address space, so will be +able to use the PASID allocated to the process. The IA32_PASID is not +preemptively initialized as the PASID value might not be allocated yet or +the kernel does not know whether this thread is going to access the device +and the cleared IA32_PASID MSR reduces context switch overhead by xstate +init optimization. Since #GP faults have to be handled on any threads that +were created before the PASID was assigned to the mm of the process, newly +created threads might as well be treated in a consistent way. + +Due to complexity of freeing the PASID and clearing all IA32_PASID MSRs in +all threads in unbind, free the PASID lazily only on mm exit. + +If a process does a close(2) of the device file descriptor and munmap(2) +of the device MMIO portal, then the driver will unbind the device. The +PASID is still marked VALID in the PASID_MSR for any threads in the +process that accessed the device. But this is harmless as without the +MMIO portal they cannot submit new work to the device. Relationships ============= |
