diff options
| author | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2021-07-18 18:56:58 -0700 |
|---|---|---|
| committer | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2021-07-18 18:56:58 -0700 |
| commit | 320424c7d44f54c18df9812fd7c45f6963524002 (patch) | |
| tree | 5853aff866a321d476f5e4f2a3de5b5e90408580 /Documentation | |
| parent | f8f84af5da9ee04ef1d271528656dac42a090d00 (diff) | |
| parent | 62fb9874f5da54fdb243003b386128037319b219 (diff) | |
| download | linux-stable-320424c7d44f54c18df9812fd7c45f6963524002.tar.gz linux-stable-320424c7d44f54c18df9812fd7c45f6963524002.tar.bz2 linux-stable-320424c7d44f54c18df9812fd7c45f6963524002.zip | |
Merge tag 'v5.13' into next
Sync up with the mainline to get the latest parport API.
Diffstat (limited to 'Documentation')
880 files changed, 35956 insertions, 10140 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-class-dax b/Documentation/ABI/obsolete/sysfs-class-dax index 0faf1354cd05..5bcce27458e3 100644 --- a/Documentation/ABI/obsolete/sysfs-class-dax +++ b/Documentation/ABI/obsolete/sysfs-class-dax @@ -1,7 +1,7 @@ What: /sys/class/dax/ Date: May, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +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 diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered index 0360be39c98e..dae880b1a5d5 100644 --- a/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered +++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered @@ -1,4 +1,4 @@ -This ABI is renamed and moved to a new location /sys/kernel/fadump/registered.¬ +This ABI is renamed and moved to a new location /sys/kernel/fadump/registered. What: /sys/kernel/fadump_registered Date: Feb 2012 diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem index 6ce0b129ab12..ca2396edb5f1 100644 --- a/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem +++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem @@ -1,4 +1,4 @@ -This ABI is renamed and moved to a new location /sys/kernel/fadump/release_mem.¬ +This ABI is renamed and moved to a new location /sys/kernel/fadump/release_mem. What: /sys/kernel/fadump_release_mem Date: Feb 2012 diff --git a/Documentation/ABI/removed/sysfs-bus-nfit b/Documentation/ABI/removed/sysfs-bus-nfit index ae8c1ca53828..277437005def 100644 --- a/Documentation/ABI/removed/sysfs-bus-nfit +++ b/Documentation/ABI/removed/sysfs-bus-nfit @@ -1,7 +1,7 @@ What: /sys/bus/nd/devices/regionX/nfit/ecc_unit_size Date: Aug, 2017 KernelVersion: v4.14 (Removed v4.18) -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Size of a write request to a DIMM that will not incur a read-modify-write cycle at the memory controller. diff --git a/Documentation/ABI/stable/procfs-audit_loginuid b/Documentation/ABI/stable/procfs-audit_loginuid new file mode 100644 index 000000000000..cda405178391 --- /dev/null +++ b/Documentation/ABI/stable/procfs-audit_loginuid @@ -0,0 +1,27 @@ +What: Audit Login UID +Date: 2005-02-01 +KernelVersion: 2.6.11-rc2 1e2d1492e178 ("[PATCH] audit: handle loginuid through proc") +Contact: linux-audit@redhat.com +Users: audit and login applications +Description: + The /proc/$pid/loginuid pseudofile is written to set and + read to get the audit login UID of process $pid as a + decimal unsigned int (%u, u32). If it is unset, + permissions are not needed to set it. The accessor must + have CAP_AUDIT_CONTROL in the initial user namespace to + write it if it has been set. It cannot be written again + if AUDIT_FEATURE_LOGINUID_IMMUTABLE is enabled. It + cannot be unset if AUDIT_FEATURE_ONLY_UNSET_LOGINUID is + enabled. + +What: Audit Login Session ID +Date: 2008-03-13 +KernelVersion: 2.6.25-rc7 1e0bd7550ea9 ("[PATCH] export sessionid alongside the loginuid in procfs") +Contact: linux-audit@redhat.com +Users: audit and login applications +Description: + The /proc/$pid/sessionid pseudofile is read to get the + audit login session ID of process $pid as a decimal + unsigned int (%u, u32). It is set automatically, + serially assigned with each new login. + diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index d447a611c41b..c78fc9282876 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -82,6 +82,24 @@ Description: Allows the root user to read or write 64 bit data directly If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory +What: /sys/kernel/debug/habanalabs/hl<n>/data_dma +Date: Apr 2021 +KernelVersion: 5.13 +Contact: ogabbay@kernel.org +Description: Allows the root user to read from the device's internal + memory (DRAM/SRAM) through a DMA engine. + This property is a binary blob that contains the result of the + DMA transfer. + This custom interface is needed (instead of using the generic + Linux user-space PCI mapping) because the amount of internal + memory is huge (>32GB) and reading it via the PCI bar will take + a very long time. + This interface doesn't support concurrency in the same device. + In GAUDI and GOYA, this action can cause undefined behavior + in case the it is done while the device is executing user + workloads. + Only supported on GAUDI at this stage. + What: /sys/kernel/debug/habanalabs/hl<n>/device Date: Jan 2019 KernelVersion: 5.1 @@ -90,6 +108,24 @@ Description: Enables the root user to set the device to specific state. Valid values are "disable", "enable", "suspend", "resume". User can read this property to see the valid values +What: /sys/kernel/debug/habanalabs/hl<n>/dma_size +Date: Apr 2021 +KernelVersion: 5.13 +Contact: ogabbay@kernel.org +Description: Specify the size of the DMA transaction when using DMA to read + from the device's internal memory. The value can not be larger + than 128MB. Writing to this value initiates the DMA transfer. + When the write is finished, the user can read the "data_dma" + blob + +What: /sys/kernel/debug/habanalabs/hl<n>/dump_security_violations +Date: Jan 2021 +KernelVersion: 5.12 +Contact: ogabbay@kernel.org +Description: Dumps all security violations to dmesg. This will also ack + all security violations meanings those violations will not be + dumped next time user calls this API + What: /sys/kernel/debug/habanalabs/hl<n>/engines Date: Jul 2019 KernelVersion: 5.3 @@ -154,6 +190,16 @@ Description: Displays the hop values and physical address for a given ASID e.g. to display info about VA 0x1000 for ASID 1 you need to do: echo "1 0x1000" > /sys/kernel/debug/habanalabs/hl0/mmu +What: /sys/kernel/debug/habanalabs/hl<n>/mmu_error +Date: Mar 2021 +KernelVersion: 5.12 +Contact: fkassabri@habana.ai +Description: Check and display page fault or access violation mmu errors for + all MMUs specified in mmu_cap_mask. + e.g. to display error info for MMU hw cap bit 9, you need to do: + echo "0x200" > /sys/kernel/debug/habanalabs/hl0/mmu_error + cat /sys/kernel/debug/habanalabs/hl0/mmu_error + What: /sys/kernel/debug/habanalabs/hl<n>/set_power_state Date: Jan 2019 KernelVersion: 5.1 @@ -161,6 +207,13 @@ Contact: ogabbay@kernel.org Description: Sets the PCI power state. Valid values are "1" for D0 and "2" for D3Hot +What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err +Date: Mar 2020 +KernelVersion: 5.6 +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>/userptr Date: Jan 2019 KernelVersion: 5.1 @@ -174,19 +227,4 @@ Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays a list with information about all the active virtual - address mappings per ASID - -What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err -Date: Mar 2020 -KernelVersion: 5.6 -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>/dump_security_violations -Date: Jan 2021 -KernelVersion: 5.12 -Contact: ogabbay@kernel.org -Description: Dumps all security violations to dmesg. This will also ack - all security violations meanings those violations will not be - dumped next time user calls this API + address mappings per ASID and all user mappings of HW blocks diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd index 14a6fe9422b3..80b420b5d6b8 100644 --- a/Documentation/ABI/testing/sysfs-block-rnbd +++ b/Documentation/ABI/testing/sysfs-block-rnbd @@ -44,3 +44,21 @@ Date: Feb 2020 KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> Description: Contains the device access mode: ro, rw or migration. + +What: /sys/block/rnbd<N>/rnbd/resize +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Write the number of sectors to change the size of the disk. + +What: /sys/block/rnbd<N>/rnbd/remap_device +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Remap the disconnected device if the session is not destroyed yet. + +What: /sys/block/rnbd<N>/rnbd/nr_poll_queues +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the number of poll-mode queues diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe b/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe new file mode 100644 index 000000000000..ad3bbc6fa751 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe @@ -0,0 +1,14 @@ +What: /sys/bus/coresight/devices/trbe<cpu>/align +Date: March 2021 +KernelVersion: 5.13 +Contact: Anshuman Khandual <anshuman.khandual@arm.com> +Description: (Read) Shows the TRBE write pointer alignment. This value + is fetched from the TRBIDR register. + +What: /sys/bus/coresight/devices/trbe<cpu>/flag +Date: March 2021 +KernelVersion: 5.13 +Contact: Anshuman Khandual <anshuman.khandual@arm.com> +Description: (Read) Shows if TRBE updates in the memory are with access + and dirty flag updates as well. This value is fetched from + the TRBIDR register. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa new file mode 100644 index 000000000000..3c7d132281b0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa @@ -0,0 +1,30 @@ +What: /sys/bus/event_source/devices/dsa*/format +Date: April 2021 +KernelVersion: 5.13 +Contact: Tom Zanussi <tom.zanussi@linux.intel.com> +Description: Read-only. Attribute group to describe the magic bits + that go into perf_event_attr.config or + perf_event_attr.config1 for the IDXD DSA pmu. (See also + ABI/testing/sysfs-bus-event_source-devices-format). + + Each attribute in this group defines a bit range in + perf_event_attr.config or perf_event_attr.config1. + All supported attributes are listed below (See the + IDXD DSA Spec for possible attribute values):: + + event_category = "config:0-3" - event category + event = "config:4-31" - event ID + + filter_wq = "config1:0-31" - workqueue filter + filter_tc = "config1:32-39" - traffic class filter + filter_pgsz = "config1:40-43" - page size filter + filter_sz = "config1:44-51" - transfer size filter + filter_eng = "config1:52-59" - engine filter + +What: /sys/bus/event_source/devices/dsa*/cpumask +Date: April 2021 +KernelVersion: 5.13 +Contact: Tom Zanussi <tom.zanussi@linux.intel.com> +Description: Read-only. This file always returns the cpu to which the + IDXD DSA pmu is bound for access to all dsa pmu + performance monitoring events. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index d957f5da5c04..267973541e72 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -33,6 +33,52 @@ Description: Description of the physical chip / device for device X. Typically a part number. +What: /sys/bus/iio/devices/iio:deviceX/label +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Optional symbolic label for a device. + This is useful for userspace to be able to better identify an + individual device. + + The contents of the label are free-form, but there are some + standardized uses: + + For proximity sensors which give the proximity (of a person) to + a certain wlan or wwan antenna the following standardized labels + are used: + + * "proximity-wifi" + * "proximity-lte" + * "proximity-wifi-lte" + * "proximity-wifi-left" + * "proximity-wifi-right" + + These are used to indicate to userspace that these proximity + sensors may be used to tune transmit power to ensure that + Specific Absorption Rate (SAR) limits are honored. + The "-left" and "-right" labels are for devices with multiple + antennas. + + In some laptops/tablets the standardized proximity sensor labels + instead indicate proximity to a specific part of the device: + + * "proximity-palmrest" indicates proximity to the keyboard's palmrest + * "proximity-palmrest-left" indicates proximity to the left part of the palmrest + * "proximity-palmrest-right" indicates proximity to the right part of the palmrest + * "proximity-lap" indicates the device is being used on someone's lap + + Note "proximity-lap" is special in that its value may be + calculated by firmware from other sensor readings, rather then + being a raw sensor reading. + + For accelerometers used in 2-in-1s with 360° (yoga-style) hinges, + which have an accelerometer in both their base and their display, + the following standardized labels are used: + + * "accel-base" + * "accel-display" + What: /sys/bus/iio/devices/iio:deviceX/current_timestamp_clock KernelVersion: 4.5 Contact: linux-iio@vger.kernel.org @@ -325,6 +371,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset What: /sys/bus/iio/devices/iio:deviceX/in_magn_offset What: /sys/bus/iio/devices/iio:deviceX/in_rot_offset What: /sys/bus/iio/devices/iio:deviceX/in_angl_offset +What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceX_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -656,6 +703,8 @@ What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en What: /sys/.../iio:deviceX/events/in_voltageY_thresh_either_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_falling_en KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -733,6 +782,32 @@ Description: a given event type is enabled a future point (and not those for whatever event was previously enabled). +What: /sys/.../events/in_capacitanceY_adaptive_thresh_rising_en +What: /sys/.../events/in_capacitanceY_adaptive_thresh_falling_en +KernelVersion: 5.13 +Contact: linux-iio@vger.kernel.org +Descrption: + Adaptive thresholds are similar to normal fixed thresholds + but the value is expressed as an offset from a value which + provides a low frequency approximation of the channel itself. + Thus these detect if a rapid change occurs in the specified + direction which crosses tracking value + offset. + Tracking value calculation is devices specific. + +What: /sys/.../in_capacitanceY_adaptive_thresh_rising_timeout +What: /sys/.../in_capacitanceY_adaptive_thresh_falling_timeout +KernelVersion: 5.11 +Contact: linux-iio@vger.kernel.org +Descrption: + When adaptive thresholds are used, the tracking signal + may adjust too slowly to step changes in the raw signal. + *_timeout (in seconds) specifies a time for which the + difference between the slow tracking signal and the raw + signal is allowed to remain out-of-range before a reset + event occurs in which the tracking signal is made equal + to the raw signal, allowing slow tracking to resume and the + adaptive threshold event detection to function as expected. + What: /sys/.../events/in_accel_thresh_rising_value What: /sys/.../events/in_accel_thresh_falling_value What: /sys/.../events/in_accel_x_raw_thresh_rising_value @@ -773,6 +848,10 @@ What: /sys/.../events/in_proximity0_thresh_falling_value What: /sys/.../events/in_proximity0_thresh_rising_value What: /sys/.../events/in_illuminance_thresh_rising_value What: /sys/.../events/in_illuminance_thresh_falling_value +What: /sys/.../events/in_capacitanceY_thresh_rising_value +What: /sys/.../events/in_capacitanceY_thresh_falling_value +What: /sys/.../events/in_capacitanceY_thresh_adaptive_rising_value +What: /sys/.../events/in_capacitanceY_thresh_falling_rising_value KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -1118,12 +1197,16 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/length KernelVersion: 2.6.35 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/length +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Number of scans contained by the buffer. What: /sys/bus/iio/devices/iio:deviceX/buffer/enable KernelVersion: 2.6.35 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/enable +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Actually start the buffer capture up. Will start trigger @@ -1131,11 +1214,16 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/scan_elements KernelVersion: 2.6.37 +What: /sys/bus/iio/devices/iio:deviceX/bufferY +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Directory containing interfaces for elements that will be captured for a single triggered sample set in the buffer. + Since kernel 5.11 the scan_elements attributes are merged into + the bufferY directory, to be configurable per buffer. + What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en @@ -1164,6 +1252,34 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_en What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en What: /sys/.../iio:deviceX/scan_elements/in_proximity_en KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_accel_x_en +What: /sys/.../iio:deviceX/bufferY/in_accel_y_en +What: /sys/.../iio:deviceX/bufferY/in_accel_z_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_en +What: /sys/.../iio:deviceX/bufferY/in_magn_x_en +What: /sys/.../iio:deviceX/bufferY/in_magn_y_en +What: /sys/.../iio:deviceX/bufferY/in_magn_z_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_en +What: /sys/.../iio:deviceX/bufferY/in_timestamp_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY-voltageZ_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_en +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_en +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_en +What: /sys/.../iio:deviceX/bufferY/in_incli_x_en +What: /sys/.../iio:deviceX/bufferY/in_incli_y_en +What: /sys/.../iio:deviceX/bufferY/in_pressureY_en +What: /sys/.../iio:deviceX/bufferY/in_pressure_en +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_en +What: /sys/.../iio:deviceX/bufferY/in_proximity_en +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Scan element control for triggered data capture. @@ -1185,6 +1301,23 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_type What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type What: /sys/.../iio:deviceX/scan_elements/in_proximity_type KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_accel_type +What: /sys/.../iio:deviceX/bufferY/in_anglvel_type +What: /sys/.../iio:deviceX/bufferY/in_magn_type +What: /sys/.../iio:deviceX/bufferY/in_incli_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_type +What: /sys/.../iio:deviceX/bufferY/in_timestamp_type +What: /sys/.../iio:deviceX/bufferY/in_pressureY_type +What: /sys/.../iio:deviceX/bufferY/in_pressure_type +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_type +What: /sys/.../iio:deviceX/bufferY/in_proximity_type +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Description of the scan element data storage within the buffer @@ -1241,6 +1374,33 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_index What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index What: /sys/.../iio:deviceX/scan_elements/in_proximity_index KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_voltageY_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_index +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_index +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_index +What: /sys/.../iio:deviceX/bufferY/in_accel_x_index +What: /sys/.../iio:deviceX/bufferY/in_accel_y_index +What: /sys/.../iio:deviceX/bufferY/in_accel_z_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_index +What: /sys/.../iio:deviceX/bufferY/in_magn_x_index +What: /sys/.../iio:deviceX/bufferY/in_magn_y_index +What: /sys/.../iio:deviceX/bufferY/in_magn_z_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_index +What: /sys/.../iio:deviceX/bufferY/in_incli_x_index +What: /sys/.../iio:deviceX/bufferY/in_incli_y_index +What: /sys/.../iio:deviceX/bufferY/in_timestamp_index +What: /sys/.../iio:deviceX/bufferY/in_pressureY_index +What: /sys/.../iio:deviceX/bufferY/in_pressure_index +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_index +What: /sys/.../iio:deviceX/bufferY/in_proximity_index +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A single positive integer specifying the position of this @@ -1455,6 +1615,8 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/watermark KernelVersion: 4.2 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/watermark +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A single positive integer specifying the maximum number of scan @@ -1473,6 +1635,8 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/data_available KernelVersion: 4.16 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/data_available +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A read-only value indicating the bytes of data available in the @@ -1823,3 +1987,12 @@ Description: hinge, keyboard, screen. It means the three channels each correspond respectively to hinge angle, keyboard angle, and screen angle. + +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_hysteresis_relative +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_hysteresis_relative +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Specify the percent for light sensor relative to the channel + absolute value that a data field should change before an event + is generated. Units are a percentage of the prior reading. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 deleted file mode 100644 index bac3d0d48b7b..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 +++ /dev/null @@ -1,133 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_count_count_mode_available -What: /sys/bus/iio/devices/iio:deviceX/in_count_noise_error_available -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -What: /sys/bus/iio/devices/iio:deviceX/in_index_index_polarity_available -What: /sys/bus/iio/devices/iio:deviceX/in_index_synchronous_mode_available -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Discrete set of available values for the respective counter - configuration are listed in this file. - -What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_mode -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Count mode for channel Y. Four count modes are available: - normal, range limit, non-recycle, and modulo-n. The preset value - for channel Y is used by the count mode where required. - - Normal: - Counting is continuous in either direction. - - Range Limit: - An upper or lower limit is set, mimicking limit switches - in the mechanical counterpart. The upper limit is set to - the preset value, while the lower limit is set to 0. The - counter freezes at count = preset when counting up, and - at count = 0 when counting down. At either of these - limits, the counting is resumed only when the count - direction is reversed. - - Non-recycle: - Counter is disabled whenever a 24-bit count overflow or - underflow takes place. The counter is re-enabled when a - new count value is loaded to the counter via a preset - operation or write to raw. - - Modulo-N: - A count boundary is set between 0 and the preset value. - The counter is reset to 0 at count = preset when - counting up, while the counter is set to the preset - value at count = 0 when counting down; the counter does - not freeze at the bundary points, but counts - continuously throughout. - -What: /sys/bus/iio/devices/iio:deviceX/in_countY_noise_error -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Read-only attribute that indicates whether excessive noise is - present at the channel Y count inputs in quadrature clock mode; - irrelevant in non-quadrature clock mode. - -What: /sys/bus/iio/devices/iio:deviceX/in_countY_preset -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - If the counter device supports preset registers, the preset - count for channel Y is provided by this attribute. - -What: /sys/bus/iio/devices/iio:deviceX/in_countY_quadrature_mode -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Configure channel Y counter for non-quadrature or quadrature - clock mode. Selecting non-quadrature clock mode will disable - synchronous load mode. In quadrature clock mode, the channel Y - scale attribute selects the encoder phase division (scale of 1 - selects full-cycle, scale of 0.5 selects half-cycle, scale of - 0.25 selects quarter-cycle) processed by the channel Y counter. - - Non-quadrature: - The filter and decoder circuit are bypassed. Encoder A - input serves as the count input and B as the UP/DOWN - direction control input, with B = 1 selecting UP Count - mode and B = 0 selecting Down Count mode. - - Quadrature: - Encoder A and B inputs are digitally filtered and - decoded for UP/DN clock. - -What: /sys/bus/iio/devices/iio:deviceX/in_countY_set_to_preset_on_index -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Whether to set channel Y counter with channel Y preset value - when channel Y index input is active, or continuously count. - Valid attribute values are boolean. - -What: /sys/bus/iio/devices/iio:deviceX/in_indexY_index_polarity -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Active level of channel Y index input; irrelevant in - non-synchronous load mode. - -What: /sys/bus/iio/devices/iio:deviceX/in_indexY_synchronous_mode -KernelVersion: 4.10 -Contact: linux-iio@vger.kernel.org -Description: - This interface is deprecated; please use the Counter subsystem. - - Configure channel Y counter for non-synchronous or synchronous - load mode. Synchronous load mode cannot be selected in - non-quadrature clock mode. - - Non-synchronous: - A logic low level is the active level at this index - input. The index function (as enabled via - set_to_preset_on_index) is performed directly on the - active level of the index input. - - Synchronous: - Intended for interfacing with encoder Index output in - quadrature clock mode. The active level is configured - via index_polarity. The index function (as enabled via - set_to_preset_on_index) is performed synchronously with - the quadrature clock on the active level of the index - input. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 index 40df5c9fef99..9dae94aa880b 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 @@ -1,11 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity -Date: January 2017 -KernelVersion: 4.11 -Contact: linux-iio@vger.kernel.org -Description: - Show or set the gain boost of the amp, from 0-31 range. - default 31 - What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range Date: January 2017 KernelVersion: 4.11 diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 b/Documentation/ABI/testing/sysfs-bus-iio-humidity index 5b78af5f341d..cb0d7e75d297 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity @@ -6,4 +6,5 @@ Description: Controls the heater device within the humidity sensor to get rid of excess condensation. - Valid control values are 0 = OFF, and 1 = ON. + In some devices, this is just a switch in which case 0 = OFF, + and 1 = ON. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x deleted file mode 100644 index b72bb62552cf..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x +++ /dev/null @@ -1,9 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw -What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available -KernelVersion: 4.3 -Contact: linux-iio@vger.kernel.org -Description: - Controls the heater device within the humidity sensor to get - rid of excess condensation. - - Valid control values are 0 = OFF, and 1 = ON. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 deleted file mode 100644 index 73498ff666bd..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 +++ /dev/null @@ -1,62 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_count0_preset -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the current preset value. Writing sets the - preset value. Encoder counts continuously from 0 to preset - value, depending on direction (up/down). - -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the list possible quadrature modes. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Configure the device counter quadrature modes: - - - non-quadrature: - Encoder IN1 input servers as the count input (up - direction). - - - quadrature: - Encoder IN1 and IN2 inputs are mixed to get direction - and count. - -What: /sys/bus/iio/devices/iio:deviceX/in_count_polarity_available -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the list possible active edges. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_polarity -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Configure the device encoder/counter active edge: - - - rising-edge - - falling-edge - - both-edges - - In non-quadrature mode, device counts up on active edge. - - In quadrature mode, encoder counting scenarios are as follows: - - +---------+----------+--------------------+--------------------+ - | Active | Level on | IN1 signal | IN2 signal | - | edge | opposite +----------+---------+----------+---------+ - | | signal | Rising | Falling | Rising | Falling | - +---------+----------+----------+---------+----------+---------+ - | Rising | High -> | Down | - | Up | - | - | edge | Low -> | Up | - | Down | - | - +---------+----------+----------+---------+----------+---------+ - | Falling | High -> | - | Up | - | Down | - | edge | Low -> | - | Down | - | Up | - +---------+----------+----------+---------+----------+---------+ - | Both | High -> | Down | Up | Up | Down | - | edges | Low -> | Up | Down | Down | Up | - +---------+----------+----------+---------+----------+---------+ diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity index 2172f3bb9c64..3aac6dab8775 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity @@ -8,3 +8,17 @@ Description: considered close to the device. If the value read from the sensor is above or equal to the value in this file an object should typically be considered near. + +What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity +Date: March 2014 +KernelVersion: 3.15 +Contact: linux-iio@vger.kernel.org +Description: + Proximity sensors sometimes have a controllable amplifier + on the signal from which time of flight measurements are + taken. + The appropriate values to take is dependent on both the + sensor and it's operating environment: + * as3935 (0-31 range) + 18 = indoors (default) + 14 = outdoors diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 index c59d95346341..1e5c40775a6c 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 @@ -6,15 +6,6 @@ Description: Get the current distance in meters of storm (1km steps) 1000-40000 = distance in meters -What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity -Date: March 2014 -KernelVersion: 3.15 -Contact: Matt Ranostay <matt.ranostay@konsulko.com> -Description: - Show or set the gain boost of the amp, from 0-31 range. - 18 = indoors (default) - 14 = outdoors - What /sys/bus/iio/devices/iio:deviceX/noise_level_tripped Date: May 2017 KernelVersion: 4.13 diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit index 63ef0b9ecce7..e7282d184a74 100644 --- a/Documentation/ABI/testing/sysfs-bus-nfit +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -5,7 +5,7 @@ Interface Table (NFIT)' section in the ACPI specification What: /sys/bus/nd/devices/nmemX/nfit/serial Date: Jun, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Serial number of the NVDIMM (non-volatile dual in-line memory module), assigned by the module vendor. @@ -14,7 +14,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/handle Date: Apr, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) The address (given by the _ADR object) of the device on its parent bus of the NVDIMM device containing the NVDIMM region. @@ -23,7 +23,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/device Date: Apr, 2015 KernelVersion: v4.1 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Device id for the NVDIMM, assigned by the module vendor. @@ -31,7 +31,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/rev_id Date: Jun, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Revision of the NVDIMM, assigned by the module vendor. @@ -39,7 +39,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/phys_id Date: Apr, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Handle (i.e., instance number) for the SMBIOS (system management BIOS) Memory Device structure describing the NVDIMM @@ -49,7 +49,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/flags Date: Jun, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) The flags in the NFIT memory device sub-structure indicate the state of the data on the nvdimm relative to its energy @@ -68,7 +68,7 @@ What: /sys/bus/nd/devices/nmemX/nfit/format1 What: /sys/bus/nd/devices/nmemX/nfit/formats Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) The interface codes indicate support for persistent memory mapped directly into system physical address space and / or a @@ -84,7 +84,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/vendor Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Vendor id of the NVDIMM. @@ -92,7 +92,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/dsm_mask Date: May, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) The bitmask indicates the supported device specific control functions relative to the NVDIMM command family supported by the @@ -102,7 +102,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/family Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Displays the NVDIMM family command sets. Values 0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL, @@ -118,7 +118,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/id Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) ACPI specification 6.2 section 5.2.25.9, defines an identifier for an NVDIMM, which refelects the id attribute. @@ -127,7 +127,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Sub-system vendor id of the NVDIMM non-volatile memory subsystem controller. @@ -136,7 +136,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem controller, assigned by the non-volatile memory subsystem @@ -146,7 +146,7 @@ Description: What: /sys/bus/nd/devices/nmemX/nfit/subsystem_device Date: Apr, 2016 KernelVersion: v4.7 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) Sub-system device id for the NVDIMM non-volatile memory subsystem controller, assigned by the non-volatile memory @@ -156,7 +156,7 @@ Description: What: /sys/bus/nd/devices/ndbusX/nfit/revision Date: Jun, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) ACPI NFIT table revision number. @@ -164,7 +164,7 @@ Description: What: /sys/bus/nd/devices/ndbusX/nfit/scrub Date: Sep, 2016 KernelVersion: v4.9 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RW) This shows the number of full Address Range Scrubs (ARS) that have been completed since driver load time. Userspace can @@ -177,7 +177,7 @@ Description: What: /sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub Date: Sep, 2016 KernelVersion: v4.9 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RW) Provides a way to toggle the behavior between just adding the address (cache line) where the MCE happened to the poison @@ -196,7 +196,7 @@ Description: What: /sys/bus/nd/devices/ndbusX/nfit/dsm_mask Date: Jun, 2017 KernelVersion: v4.13 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) The bitmask indicates the supported bus specific control functions. See the section named 'NVDIMM Root Device _DSMs' in @@ -205,7 +205,7 @@ Description: What: /sys/bus/nd/devices/ndbusX/nfit/firmware_activate_noidle Date: Apr, 2020 KernelVersion: v5.8 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RW) The Intel platform implementation of firmware activate support exposes an option let the platform force idle devices in @@ -225,7 +225,7 @@ Description: What: /sys/bus/nd/devices/regionX/nfit/range_index Date: Jun, 2015 KernelVersion: v4.2 -Contact: linux-nvdimm@lists.01.org +Contact: nvdimm@lists.linux.dev Description: (RO) A unique number provided by the BIOS to identify an address range. Used by NVDIMM Region Mapping Structure to uniquely refer diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem index 8316c33862a0..92e2db0e2d3d 100644 --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -1,7 +1,7 @@ What: /sys/bus/nd/devices/nmemX/papr/flags Date: Apr, 2020 KernelVersion: v5.8 -Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org, +Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev, Description: (RO) Report flags indicating various states of a papr-pmem NVDIMM device. Each flag maps to a one or @@ -36,7 +36,7 @@ Description: What: /sys/bus/nd/devices/nmemX/papr/perf_stats Date: May, 2020 KernelVersion: v5.9 -Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org, +Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev, Description: (RO) Report various performance stats related to papr-scm NVDIMM device. Each stat is reported on a new line with each line diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 25c9c39770c6..ef00fada2efb 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -195,10 +195,13 @@ What: /sys/bus/pci/devices/.../index Date: July 2010 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com Description: - Reading this attribute will provide the firmware - given instance (SMBIOS type 41 device type instance) of the - PCI device. The attribute will be created only if the firmware - has given an instance number to the PCI device. + Reading this attribute will provide the firmware given instance + number of the PCI device. Depending on the platform this can + be for example the SMBIOS type 41 device type instance or the + user-defined ID (UID) on s390. The attribute will be created + only if the firmware has given an instance number to the PCI + device and that number is guaranteed to uniquely identify the + device in the system. Users: Userspace applications interested in knowing the firmware assigned device type instance of the PCI @@ -375,3 +378,32 @@ Description: The value comes from the PCI kernel device state and can be one of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold". The file is read only. + +What: /sys/bus/pci/devices/.../sriov_vf_total_msix +Date: January 2021 +Contact: Leon Romanovsky <leonro@nvidia.com> +Description: + This file is associated with a SR-IOV physical function (PF). + It contains the total number of MSI-X vectors available for + assignment to all virtual functions (VFs) associated with PF. + The value will be zero if the device doesn't support this + functionality. For supported devices, the value will be + constant and won't be changed after MSI-X vectors assignment. + +What: /sys/bus/pci/devices/.../sriov_vf_msix_count +Date: January 2021 +Contact: Leon Romanovsky <leonro@nvidia.com> +Description: + This file is associated with a SR-IOV virtual function (VF). + It allows configuration of the number of MSI-X vectors for + the VF. This allows devices that have a global pool of MSI-X + vectors to optimally divide them between VFs based on VF usage. + + The values accepted are: + * > 0 - this number will be reported as the Table Size in the + VF's MSI-X capability + * < 0 - not valid + * = 0 - will reset to the device default value + + The file is writable if the PF is bound to a driver that + implements ->sriov_set_msix_vec_count(). diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic index 1936f7324155..4ec03cd36357 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic @@ -1,4 +1,5 @@ -What: /sys/devices/pci0000:00/*/QEMU0001:00/capability +What: /sys/devices/pci0000:00/*/QEMU0001:00/capability for MMIO + /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/capability for PCI Date: Jan 2021 Contact: zhenwei pi <pizhenwei@bytedance.com> Description: @@ -12,6 +13,7 @@ Description: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/specs/pvpanic.txt What: /sys/devices/pci0000:00/*/QEMU0001:00/events + /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/events for PCI Date: Jan 2021 Contact: zhenwei pi <pizhenwei@bytedance.com> Description: diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index d7f09d011b6d..c41c68f64693 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -1,31 +1,3 @@ -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain RX speed per lane. - All RX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the number of RX lanes the XDomain - is using simultaneously through its upstream port. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain TX speed per lane. - All TX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports number of TX lanes the XDomain - is using simultaneously through its upstream port. - What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl Date: Jun 2018 KernelVersion: 4.17 @@ -162,6 +134,13 @@ Contact: thunderbolt-software@lists.01.org Description: This attribute contains name of this device extracted from the device DROM. +What: /sys/bus/thunderbolt/devices/.../maxhopid +Date: Jul 2021 +KernelVersion: 5.13 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Only set for XDomains. The maximum HopID the other host + supports as its input HopID. + What: /sys/bus/thunderbolt/devices/.../rx_speed Date: Jan 2020 KernelVersion: 5.5 diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 386bc230a33d..5e6b74f30406 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -97,10 +97,7 @@ Description: object. The values are represented in ms. If the value is less than 1 jiffy, it is considered to be 0, which means no polling. This value is meaningless if the governor is - not polling; thus. If the governor is not using - devfreq-provided central polling - (/sys/class/devfreq/.../central_polling is 0), this value - may be useless. + not polling. A list of governors that support the node: - simple_ondmenad diff --git a/Documentation/ABI/testing/sysfs-class-net-phydev b/Documentation/ABI/testing/sysfs-class-net-phydev index 40ced0ea4316..ac722dd5e694 100644 --- a/Documentation/ABI/testing/sysfs-class-net-phydev +++ b/Documentation/ABI/testing/sysfs-class-net-phydev @@ -51,3 +51,15 @@ Description: Boolean value indicating whether the PHY device is used in standalone mode, without a net_device associated, by PHYLINK. Attribute created only when this is the case. + +What: /sys/class/mdio_bus/<bus>/<device>/phy_dev_flags +Date: March 2021 +KernelVersion: 5.13 +Contact: netdev@vger.kernel.org +Description: + 32-bit hexadecimal number representing a bit mask of the + configuration bits passed from the consumer of the PHY + (Ethernet MAC, switch, etc.) to the PHY driver. The flags are + only used internally by the kernel and their placement are + not meant to be stable across kernel versions. This is intended + for facilitating the debugging of PHY drivers. diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi index ed79f5893421..47e6b9732337 100644 --- a/Documentation/ABI/testing/sysfs-class-net-qmi +++ b/Documentation/ABI/testing/sysfs-class-net-qmi @@ -58,3 +58,19 @@ Description: Indicates the mux id associated to the qmimux network interface during its creation. + +What: /sys/class/net/<iface>/qmi/pass_through +Date: January 2021 +KernelVersion: 5.12 +Contact: Subash Abhinov Kasiviswanathan <subashab@codeaurora.org> +Description: + Boolean. Default: 'N' + + Set this to 'Y' to enable 'pass-through' mode, allowing packets + in MAP format to be passed on to the stack. + + Normally the rmnet driver (CONFIG_RMNET) is then used to process + and demultiplex these packets. + + 'Pass-through' mode can be enabled when the device is in + 'raw-ip' mode only. diff --git a/Documentation/ABI/testing/sysfs-class-power-surface b/Documentation/ABI/testing/sysfs-class-power-surface new file mode 100644 index 000000000000..79cde4dcf2f5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-power-surface @@ -0,0 +1,15 @@ +What: /sys/class/power_supply/<supply_name>/alarm +Date: April 2021 +KernelVersion: 5.13 +Contact: Maximilian Luz <luzmaximilian@gmail.com> +Description: + Battery trip point. When the remaining battery capacity crosses this + value in either direction, the system will be notified and if + necessary woken. + + Set to zero to clear/disable. + + Access: Read, Write + + Valid values: In micro-Wh or micro-Ah, depending on the power unit + of the battery diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client index 2aa05b3e348e..0b5997ab3365 100644 --- a/Documentation/ABI/testing/sysfs-class-rnbd-client +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client @@ -85,6 +85,19 @@ Description: Expected format is the following:: By default "rw" is used. + nr_poll_queues + specifies the number of poll-mode queues. If the IO has HIPRI flag, + the block-layer will send the IO via the poll-mode queue. + For fast network and device the polling is faster than interrupt-base + IO handling because it saves time for context switching, switching to + another process, handling the interrupt and switching back to the + issuing process. + + Set -1 if you want to set it as the number of CPUs + By default rnbd client creates only irq-mode queues. + + NOTICE: MUST make a unique session for a device using the poll-mode queues. + Exit Codes: If the device is already mapped it will fail with EEXIST. If the input diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client index 0f7165aab251..49a4157c7bf1 100644 --- a/Documentation/ABI/testing/sysfs-class-rtrs-client +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client @@ -34,6 +34,9 @@ Description: Multipath policy specifies which path should be selected on each IO min-inflight (1): select path with minimum inflights. + min-latency (2): + select path with minimum latency. + What: /sys/class/rtrs-client/<session-name>/paths/ Date: Feb 2020 KernelVersion: 5.7 @@ -95,6 +98,15 @@ KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> Description: RO, Contains the destination address of the path +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/cur_latency +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the latency time calculated by the heart-beat messages. + Whenever the client sends heart-beat message, it checks the time gap + between sending the heart-beat message and receiving the ACK. + This value can be changed regularly. + What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reset_all Date: Feb 2020 KernelVersion: 5.7 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 0eee30b27ab6..fe13baa53c59 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -285,7 +285,7 @@ Description: Disable L3 cache indices All AMD processors with L3 caches provide this functionality. For details, see BKDGs at - http://developer.amd.com/documentation/guides/Pages/default.aspx + https://www.amd.com/en/support/tech-docs?keyword=bios+kernel What: /sys/devices/system/cpu/cpufreq/boost diff --git a/Documentation/ABI/testing/sysfs-driver-xdata b/Documentation/ABI/testing/sysfs-driver-xdata new file mode 100644 index 000000000000..f574e8e6dca2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xdata @@ -0,0 +1,49 @@ +What: /sys/class/misc/drivers/dw-xdata-pcie.<device>/write +Date: April 2021 +KernelVersion: 5.13 +Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com> +Description: Allows the user to enable the PCIe traffic generator which + will create write TLPs frames - from the Root Complex to the + Endpoint direction or to disable the PCIe traffic generator + in all directions. + + Write y/1/on to enable, n/0/off to disable + + Usage e.g. + echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/write + or + echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/write + + The user can read the current PCIe link throughput generated + through this generator in MB/s. + + Usage e.g. + cat /sys/class/misc/dw-xdata-pcie.<device>/write + 204 + + The file is read and write. + +What: /sys/class/misc/dw-xdata-pcie.<device>/read +Date: April 2021 +KernelVersion: 5.13 +Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com> +Description: Allows the user to enable the PCIe traffic generator which + will create read TLPs frames - from the Endpoint to the Root + Complex direction or to disable the PCIe traffic generator + in all directions. + + Write y/1/on to enable, n/0/off to disable + + Usage e.g. + echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/read + or + echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/read + + The user can read the current PCIe link throughput generated + through this generator in MB/s. + + Usage e.g. + cat /sys/class/misc/dw-xdata-pcie.<device>/read + 199 + + The file is read and write. diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv index 637c668cbe45..12ed843e1d3e 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv @@ -39,8 +39,8 @@ Description: The uv_type entry contains the hub revision number. This value can be used to identify the UV system version:: - "0.*" = Hubless UV ('*' is subtype) + "0.*" = Hubless UV ('*' is subtype) "3.0" = UV2 "5.0" = UV3 "7.0" = UV4 diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index cbeac1bebe2f..4849b8e84e42 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -276,7 +276,7 @@ Date April 2019 Contact: "Daniel Rosenberg" <drosen@google.com> Description: If checkpoint=disable, it displays the number of blocks that are unusable. - If checkpoint=enable it displays the enumber of blocks that + If checkpoint=enable it displays the number of blocks that would be unusable if checkpoint=disable were to be set. What: /sys/fs/f2fs/<disk>/encoding @@ -409,3 +409,32 @@ Description: Give a way to change checkpoint merge daemon's io priority. I/O priority "3". We can select the class between "rt" and "be", and set the I/O priority within valid range of it. "," delimiter is necessary in between I/O class and priority number. + +What: /sys/fs/f2fs/<disk>/ovp_segments +Date: March 2021 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: Shows the number of overprovision segments. + +What: /sys/fs/f2fs/<disk>/compr_written_block +Date: March 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Show the block count written after compression since mount. Note + that when the compressed blocks are deleted, this count doesn't + decrease. If you write "0" here, you can initialize + compr_written_block and compr_saved_block to "0". + +What: /sys/fs/f2fs/<disk>/compr_saved_block +Date: March 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Show the saved block count with compression since mount. Note + that when the compressed blocks are deleted, this count doesn't + decrease. If you write "0" here, you can initialize + compr_written_block and compr_saved_block to "0". + +What: /sys/fs/f2fs/<disk>/compr_new_inode +Date: March 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Show the count of inode newly enabled for compression since mount. + Note that when the compression is disabled for the files, this count + doesn't decrease. If you write "0" here, you can initialize + compr_new_inode to "0". diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-cma b/Documentation/ABI/testing/sysfs-kernel-mm-cma new file mode 100644 index 000000000000..02b2bb60c296 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-cma @@ -0,0 +1,25 @@ +What: /sys/kernel/mm/cma/ +Date: Feb 2021 +Contact: Minchan Kim <minchan@kernel.org> +Description: + /sys/kernel/mm/cma/ contains a subdirectory for each CMA + heap name (also sometimes called CMA areas). + + Each CMA heap subdirectory (that is, each + /sys/kernel/mm/cma/<cma-heap-name> directory) contains the + following items: + + alloc_pages_success + alloc_pages_fail + +What: /sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_success +Date: Feb 2021 +Contact: Minchan Kim <minchan@kernel.org> +Description: + the number of pages CMA API succeeded to allocate + +What: /sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_fail +Date: Feb 2021 +Contact: Minchan Kim <minchan@kernel.org> +Description: + the number of pages CMA API failed to allocate diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module index a485434d2a0f..88bddf192ceb 100644 --- a/Documentation/ABI/testing/sysfs-module +++ b/Documentation/ABI/testing/sysfs-module @@ -37,13 +37,13 @@ Description: Maximum time allowed for periodic transfers per microframe (μs) What: /sys/module/*/{coresize,initsize} Date: Jan 2012 -KernelVersion:»·3.3 +KernelVersion: 3.3 Contact: Kay Sievers <kay.sievers@vrfy.org> Description: Module size in bytes. What: /sys/module/*/taint Date: Jan 2012 -KernelVersion:»·3.3 +KernelVersion: 3.3 Contact: Kay Sievers <kay.sievers@vrfy.org> Description: Module taint flags: == ===================== diff --git a/Documentation/ABI/testing/sysfs-platform-intel-pmc b/Documentation/ABI/testing/sysfs-platform-intel-pmc new file mode 100644 index 000000000000..ef199af75ab0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-intel-pmc @@ -0,0 +1,20 @@ +What: /sys/devices/platform/<platform>/etr3 +Date: Apr 2021 +KernelVersion: 5.13 +Contact: "Tomas Winkler" <tomas.winkler@intel.com> +Description: + The file exposes "Extended Test Mode Register 3" global + reset bits. The bits are used during an Intel platform + manufacturing process to indicate that consequent reset + of the platform is a "global reset". This type of reset + is required in order for manufacturing configurations + to take effect. + + Display global reset setting bits for PMC. + * bit 31 - global reset is locked + * bit 20 - global reset is set + Writing bit 20 value to the etr3 will induce + a platform "global reset" upon consequent platform reset, + in case the register is not locked. + The "global reset bit" should be locked on a production + system and the file is in read-only mode. diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 3b0876c77355..588d97366a46 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt @@ -847,7 +847,7 @@ Symposium on Distributed Computing} 'It's entirely possible that the current user could be replaced by RCU and/or seqlocks, and we could get rid of brlocks entirely.' . - Steve Hemminger responds by replacing them with RCU. + Stephen Hemminger responds by replacing them with RCU. } } diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst index 716ad9b23c9a..dd3ca68b5df1 100644 --- a/Documentation/admin-guide/LSM/LoadPin.rst +++ b/Documentation/admin-guide/LSM/LoadPin.rst @@ -11,8 +11,8 @@ restrictions without needing to sign the files individually. The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and can be controlled at boot-time with the kernel command line option -"``loadpin.enabled``". By default, it is enabled, but can be disabled at -boot ("``loadpin.enabled=0``"). +"``loadpin.enforce``". By default, it is enabled, but can be disabled at +boot ("``loadpin.enforce=0``"). LoadPin starts pinning when it sees the first file loaded. If the block device backing the filesystem is not read-only, a sysctl is @@ -28,4 +28,4 @@ different mechanisms such as ``CONFIG_MODULE_SIG`` and ``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while still use LoadPin to protect the integrity of other files kernel loads. The full list of valid file types can be found in ``kernel_read_file_str`` -defined in ``include/linux/fs.h``. +defined in ``include/linux/kernel_read_file.h``. diff --git a/Documentation/admin-guide/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst index 226f64473e8e..99fbc8a64ba9 100644 --- a/Documentation/admin-guide/cgroup-v1/index.rst +++ b/Documentation/admin-guide/cgroup-v1/index.rst @@ -17,6 +17,7 @@ Control Groups version 1 hugetlb memcg_test memory + misc net_cls net_prio pids diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 0936412e044e..41191b5fb69d 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -360,8 +360,8 @@ U != 0, K = unlimited: U != 0, K < U: Kernel memory is a subset of the user memory. This setup is useful in - deployments where the total amount of memory per-cgroup is overcommited. - Overcommiting kernel memory limits is definitely not recommended, since the + deployments where the total amount of memory per-cgroup is overcommitted. + Overcommitting kernel memory limits is definitely not recommended, since the box can still run out of non-reclaimable memory. In this case, the admin could set up K so that the sum of all groups is never greater than the total memory, and freely set U at the cost of his @@ -851,6 +851,9 @@ At reading, current status of OOM is shown. (if 1, oom-killer is disabled) - under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may be stopped.) + - oom_kill integer counter + The number of processes belonging to this cgroup killed by any + kind of OOM killer. 11. Memory Pressure =================== diff --git a/Documentation/admin-guide/cgroup-v1/misc.rst b/Documentation/admin-guide/cgroup-v1/misc.rst new file mode 100644 index 000000000000..661614c24df3 --- /dev/null +++ b/Documentation/admin-guide/cgroup-v1/misc.rst @@ -0,0 +1,4 @@ +=============== +Misc controller +=============== +Please refer "Misc" documentation in Documentation/admin-guide/cgroup-v2.rst diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 64c62b979f2f..b1e81aa8598a 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -65,8 +65,11 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou 5-7-1. RDMA Interface Files 5-8. HugeTLB 5.8-1. HugeTLB Interface Files - 5-8. Misc - 5-8-1. perf_event + 5-9. Misc + 5.9-1 Miscellaneous cgroup Interface Files + 5.9-2 Migration and Ownership + 5-10. Others + 5-10-1. perf_event 5-N. Non-normative information 5-N-1. CPU controller root cgroup process behaviour 5-N-2. IO controller root cgroup process behaviour @@ -2171,6 +2174,72 @@ HugeTLB Interface Files Misc ---- +The Miscellaneous cgroup provides the resource limiting and tracking +mechanism for the scalar resources which cannot be abstracted like the other +cgroup resources. Controller is enabled by the CONFIG_CGROUP_MISC config +option. + +A resource can be added to the controller via enum misc_res_type{} in the +include/linux/misc_cgroup.h file and the corresponding name via misc_res_name[] +in the kernel/cgroup/misc.c file. Provider of the resource must set its +capacity prior to using the resource by calling misc_cg_set_capacity(). + +Once a capacity is set then the resource usage can be updated using charge and +uncharge APIs. All of the APIs to interact with misc controller are in +include/linux/misc_cgroup.h. + +Misc Interface Files +~~~~~~~~~~~~~~~~~~~~ + +Miscellaneous controller provides 3 interface files. If two misc resources (res_a and res_b) are registered then: + + misc.capacity + A read-only flat-keyed file shown only in the root cgroup. It shows + miscellaneous scalar resources available on the platform along with + their quantities:: + + $ cat misc.capacity + res_a 50 + res_b 10 + + misc.current + A read-only flat-keyed file shown in the non-root cgroups. It shows + the current usage of the resources in the cgroup and its children.:: + + $ cat misc.current + res_a 3 + res_b 0 + + misc.max + A read-write flat-keyed file shown in the non root cgroups. Allowed + maximum usage of the resources in the cgroup and its children.:: + + $ cat misc.max + res_a max + res_b 4 + + Limit can be set by:: + + # echo res_a 1 > misc.max + + Limit can be set to max by:: + + # echo res_a max > misc.max + + Limits can be set higher than the capacity value in the misc.capacity + file. + +Migration and Ownership +~~~~~~~~~~~~~~~~~~~~~~~ + +A miscellaneous scalar resource is charged to the cgroup in which it is used +first, and stays charged to that cgroup until that resource is freed. Migrating +a process to a different cgroup does not move the charge to the destination +cgroup where the process has moved. + +Others +------ + perf_event ~~~~~~~~~~ diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index 13783dc68ab7..f170d8820258 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -714,6 +714,7 @@ DebugData Displays information about active CIFS sessions and version. Stats Lists summary resource usage information as well as per share statistics. +open_files List all the open file handles on all active SMB sessions. ======================= ======================================================= Configuration pseudo-files: @@ -794,6 +795,8 @@ LinuxExtensionsEnabled If set to one then the client will attempt to support and want to map the uid and gid fields to values supplied at mount (rather than the actual values, then set this to zero. (default 1) +dfscache List the content of the DFS cache. + If set to 0, the client will clear the cache. ======================= ======================================================= These experimental features and tracing can be enabled by changing flags in diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 63fd4e6a014b..9c2be821c225 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -4,7 +4,7 @@ 1 char Memory devices 1 = /dev/mem Physical memory access - 2 = /dev/kmem Kernel virtual memory access + 2 = /dev/kmem OBSOLETE - replaced by /proc/kcore 3 = /dev/null Null device 4 = /dev/port I/O port access 5 = /dev/zero Null byte source @@ -289,7 +289,7 @@ 152 = /dev/kpoll Kernel Poll Driver 153 = /dev/mergemem Memory merge device 154 = /dev/pmu Macintosh PowerBook power manager - 155 = /dev/isictl MultiTech ISICom serial control + 155 = 156 = /dev/lcd Front panel LCD display 157 = /dev/ac Applicom Intl Profibus card 158 = /dev/nwbutton Netwinder external button @@ -477,11 +477,6 @@ 18 block Sanyo CD-ROM 0 = /dev/sjcd Sanyo CD-ROM - 19 char Cyclades serial card - 0 = /dev/ttyC0 First Cyclades port - ... - 31 = /dev/ttyC31 32nd Cyclades port - 19 block "Double" compressed disk 0 = /dev/double0 First compressed disk ... @@ -493,11 +488,6 @@ See the Double documentation for the meaning of the mirror devices. - 20 char Cyclades serial card - alternate devices - 0 = /dev/cub0 Callout device for ttyC0 - ... - 31 = /dev/cub31 Callout device for ttyC31 - 20 block Hitachi CD-ROM (under development) 0 = /dev/hitcd Hitachi CD-ROM diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 6c04aea8f4cd..b119b8277b3e 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -347,7 +347,7 @@ Examples <debugfs>/dynamic_debug/control // enable messages in files of which the paths include string "usb" - nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control + nullarbor:~ # echo -n 'file *usb* +p' > <debugfs>/dynamic_debug/control // enable all messages nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control diff --git a/Documentation/admin-guide/gpio/gpio-mockup.rst b/Documentation/admin-guide/gpio/gpio-mockup.rst index 9fa1618b3adc..493071da1738 100644 --- a/Documentation/admin-guide/gpio/gpio-mockup.rst +++ b/Documentation/admin-guide/gpio/gpio-mockup.rst @@ -17,17 +17,18 @@ module. gpio_mockup_ranges This parameter takes an argument in the form of an array of integer - pairs. Each pair defines the base GPIO number (if any) and the number - of lines exposed by the chip. If the base GPIO is -1, the gpiolib - will assign it automatically. + pairs. Each pair defines the base GPIO number (non-negative integer) + and the first number after the last of this chip. If the base GPIO + is -1, the gpiolib will assign it automatically. while the following + parameter is the number of lines exposed by the chip. - Example: gpio_mockup_ranges=-1,8,-1,16,405,4 + Example: gpio_mockup_ranges=-1,8,-1,16,405,409 The line above creates three chips. The first one will expose 8 lines, the second 16 and the third 4. The base GPIO for the third chip is set to 405 while for two first chips it will be assigned automatically. - gpio_named_lines + gpio_mockup_named_lines This parameter doesn't take any arguments. It lets the driver know that GPIO lines exposed by it should be named. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 423116c4e787..dc00afcabb95 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -35,7 +35,6 @@ problems and bugs in particular. :maxdepth: 1 reporting-issues - Reporting bugs (obsolete) <reporting-bugs> security-bugs bug-hunting bug-bisect diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 1132796a8d96..3996b54158bf 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -68,6 +68,13 @@ For example one can add to the command line following parameter: where the final item represents CPUs 100,101,125,126,150,151,... +The value "N" can be used to represent the numerically last CPU on the system, +i.e "foo_cpus=16-N" would be equivalent to "16-31" on a 32 core system. + +Keep in mind that "N" is dynamic, so if system changes cause the bitmap width +to change, such as less cores in the CPU list, then N and any ranges using N +will also change. Use the same on a small 4 core system, and "16-N" becomes +"16-3" and now the same boot input will be flagged as invalid (start > end). This document may not be entirely up to date and comprehensive. The command @@ -140,6 +147,7 @@ parameter is applicable:: PPT Parallel port support is enabled. PS2 Appropriate PS/2 support is enabled. RAM RAM disk support is enabled. + RISCV RISCV architecture is enabled. RDT Intel Resource Director Technology. S390 S390 architecture is enabled. SCSI Appropriate SCSI support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 04545725f187..cb89dbdedc46 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -50,7 +50,7 @@ CONFIG_ACPI_DEBUG must be enabled to produce any ACPI debug output. Bits in debug_layer correspond to a _COMPONENT in an ACPI source file, e.g., - #define _COMPONENT ACPI_PCI_COMPONENT + #define _COMPONENT ACPI_EVENTS Bits in debug_level correspond to a level in ACPI_DEBUG_PRINT statements, e.g., ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... @@ -60,8 +60,6 @@ Enable processor driver info messages: acpi.debug_layer=0x20000000 - Enable PCI/PCI interrupt routing info messages: - acpi.debug_layer=0x400000 Enable AML "Debug" output, i.e., stores to the Debug object while interpreting AML: acpi.debug_layer=0xffffffff acpi.debug_level=0x2 @@ -784,6 +782,16 @@ cs89x0_media= [HW,NET] Format: { rj45 | aui | bnc } + csdlock_debug= [KNL] Enable debug add-ons of cross-CPU function call + handling. When switched on, additional debug data is + printed to the console in case a hanging CPU is + detected, and that CPU is pinged again in order to try + to resolve the hang situation. + 0: disable csdlock debugging (default) + 1: enable basic csdlock debugging (minor impact) + ext: enable extended csdlock debugging (more impact, + but more data) + dasd= [HW,NET] See header of drivers/s390/block/dasd_devmap.c. @@ -1461,6 +1469,12 @@ Don't use this when you are not running on the android emulator + gpio-mockup.gpio_mockup_ranges + [HW] Sets the ranges of gpiochip of for this device. + Format: <start1>,<end1>,<start2>,<end2>... + gpio-mockup.gpio_mockup_named_lines + [HW] Let the driver know GPIO lines should be named. + gpt [EFI] Forces disk with valid GPT signature but invalid Protective MBR to be treated as GPT. If the primary GPT is corrupted, it enables the backup/alternate @@ -1484,10 +1498,6 @@ Format: <unsigned int> such that (rxsize & ~0x1fffc0) == 0. Default: 1024 - gpio-mockup.gpio_mockup_ranges - [HW] Sets the ranges of gpiochip of for this device. - Format: <start1>,<end1>,<start2>,<end2>... - hardlockup_all_cpu_backtrace= [KNL] Should the hard-lockup detector generate backtraces on all cpus. @@ -1825,6 +1835,18 @@ initcall functions. Useful for debugging built-in modules and initcalls. + initramfs_async= [KNL] + Format: <bool> + Default: 1 + This parameter controls whether the initramfs + image is unpacked asynchronously, concurrently + with devices being probed and + initialized. This should normally just work, + but as a debugging aid, one can get the + historical behaviour of the initramfs + unpacking being completed before device_ and + late_ initcalls. + initrd= [BOOT] Specify the location of the initial ramdisk initrdmem= [KNL] Specify a physical address and size from which to @@ -1869,13 +1891,6 @@ bypassed by not enabling DMAR with this option. In this case, gfx device will use physical address for DMA. - forcedac [X86-64] - With this option iommu will not optimize to look - for io virtual address below 32-bit forcing dual - address cycle on pci bus for cards supporting greater - than 32-bit addressing. The default is to look - for translation below 32-bit and if not available - then look in the higher range. strict [Default Off] With this option on every unmap_single operation will result in a hardware IOTLB flush operation as opposed @@ -1964,6 +1979,14 @@ nobypass [PPC/POWERNV] Disable IOMMU bypass, using IOMMU for PCI devices. + iommu.forcedac= [ARM64, X86] Control IOVA allocation for PCI devices. + Format: { "0" | "1" } + 0 - Try to allocate a 32-bit DMA address first, before + falling back to the full range if needed. + 1 - Allocate directly from the full usable range, + forcing Dual Address Cycle for PCI cards supporting + greater than 32-bit addressing. + iommu.strict= [ARM64] Configure TLB invalidation behaviour Format: { "0" | "1" } 0 - Lazy mode. @@ -2279,8 +2302,7 @@ state is kept private from the host. Not valid if the kernel is running in EL2. - Defaults to VHE/nVHE based on hardware support and - the value of CONFIG_ARM64_VHE. + Defaults to VHE/nVHE based on hardware support. kvm-arm.vgic_v3_group0_trap= [KVM,ARM] Trap guest accesses to GICv3 group-0 @@ -2794,7 +2816,24 @@ seconds. Use this parameter to check at some other rate. 0 disables periodic checking. - memtest= [KNL,X86,ARM,PPC] Enable memtest + memory_hotplug.memmap_on_memory + [KNL,X86,ARM] Boolean flag to enable this feature. + Format: {on | off (default)} + When enabled, runtime hotplugged memory will + allocate its internal metadata (struct pages) + from the hotadded memory which will allow to + hotadd a lot of memory without requiring + additional memory to do so. + This feature is disabled by default because it + has some implication on large (e.g. GB) + allocations in some configurations (e.g. small + memory blocks). + The state of the flag can be read in + /sys/module/memory_hotplug/parameters/memmap_on_memory. + Note that even when enabled, there are a few cases where + the feature is not effective. + + memtest= [KNL,X86,ARM,PPC,RISCV] Enable memtest Format: <integer> default : 0 <disable> Specifies the number of memtest passes to be @@ -3243,6 +3282,8 @@ nohugeiomap [KNL,X86,PPC,ARM64] Disable kernel huge I/O mappings. + nohugevmalloc [PPC] Disable kernel huge vmalloc mappings. + nosmt [KNL,S390] Disable symmetric multithreading (SMT). Equivalent to smt=1. @@ -3472,7 +3513,8 @@ nr_uarts= [SERIAL] maximum number of UARTs to be registered. - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + numa_balancing= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic + NUMA balancing. Allowed values are enable and disable numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. @@ -3592,6 +3634,96 @@ Currently this function knows 686a and 8231 chips. Format: [spp|ps2|epp|ecp|ecpepp] + pata_legacy.all= [HW,LIBATA] + Format: <int> + Set to non-zero to probe primary and secondary ISA + port ranges on PCI systems where no PCI PATA device + has been found at either range. Disabled by default. + + pata_legacy.autospeed= [HW,LIBATA] + Format: <int> + Set to non-zero if a chip is present that snoops speed + changes. Disabled by default. + + pata_legacy.ht6560a= [HW,LIBATA] + Format: <int> + Set to 1, 2, or 3 for HT 6560A on the primary channel, + the secondary channel, or both channels respectively. + Disabled by default. + + pata_legacy.ht6560b= [HW,LIBATA] + Format: <int> + Set to 1, 2, or 3 for HT 6560B on the primary channel, + the secondary channel, or both channels respectively. + Disabled by default. + + pata_legacy.iordy_mask= [HW,LIBATA] + Format: <int> + IORDY enable mask. Set individual bits to allow IORDY + for the respective channel. Bit 0 is for the first + legacy channel handled by this driver, bit 1 is for + the second channel, and so on. The sequence will often + correspond to the primary legacy channel, the secondary + legacy channel, and so on, but the handling of a PCI + bus and the use of other driver options may interfere + with the sequence. By default IORDY is allowed across + all channels. + + pata_legacy.opti82c46x= [HW,LIBATA] + Format: <int> + Set to 1, 2, or 3 for Opti 82c611A on the primary + channel, the secondary channel, or both channels + respectively. Disabled by default. + + pata_legacy.opti82c611a= [HW,LIBATA] + Format: <int> + Set to 1, 2, or 3 for Opti 82c465MV on the primary + channel, the secondary channel, or both channels + respectively. Disabled by default. + + pata_legacy.pio_mask= [HW,LIBATA] + Format: <int> + PIO mode mask for autospeed devices. Set individual + bits to allow the use of the respective PIO modes. + Bit 0 is for mode 0, bit 1 is for mode 1, and so on. + All modes allowed by default. + + pata_legacy.probe_all= [HW,LIBATA] + Format: <int> + Set to non-zero to probe tertiary and further ISA + port ranges on PCI systems. Disabled by default. + + pata_legacy.probe_mask= [HW,LIBATA] + Format: <int> + Probe mask for legacy ISA PATA ports. Depending on + platform configuration and the use of other driver + options up to 6 legacy ports are supported: 0x1f0, + 0x170, 0x1e8, 0x168, 0x1e0, 0x160, however probing + of individual ports can be disabled by setting the + corresponding bits in the mask to 1. Bit 0 is for + the first port in the list above (0x1f0), and so on. + By default all supported ports are probed. + + pata_legacy.qdi= [HW,LIBATA] + Format: <int> + Set to non-zero to probe QDI controllers. By default + set to 1 if CONFIG_PATA_QDI_MODULE, 0 otherwise. + + pata_legacy.winbond= [HW,LIBATA] + Format: <int> + Set to non-zero to probe Winbond controllers. Use + the standard I/O port (0x130) if 1, otherwise the + value given is the I/O port to use (typically 0x1b0). + By default set to 1 if CONFIG_PATA_WINBOND_VLB_MODULE, + 0 otherwise. + + pata_platform.pio_mask= [HW,LIBATA] + Format: <int> + Supported PIO mode mask. Set individual bits to allow + the use of the respective PIO modes. Bit 0 is for + mode 0, bit 1 is for mode 1, and so on. Mode 0 only + allowed by default. + pause_on_oops= Halt all CPUs after the first oops has been printed for the specified number of seconds. This is to be used if @@ -4061,6 +4193,17 @@ fully seed the kernel's CRNG. Default is controlled by CONFIG_RANDOM_TRUST_CPU. + randomize_kstack_offset= + [KNL] Enable or disable kernel stack offset + randomization, which provides roughly 5 bits of + entropy, frustrating memory corruption attacks + that depend on stack address determinism or + cross-syscall address exposures. This is only + available on architectures that have defined + CONFIG_HAVE_ARCH_RANDOMIZE_KSTACK_OFFSET. + Format: <bool> (1/Y/y=enable, 0/N/n=disable) + Default is CONFIG_RANDOMIZE_KSTACK_OFFSET_DEFAULT. + ras=option[,option,...] [KNL] RAS-specific options cec_disable [X86] @@ -4068,9 +4211,7 @@ see CONFIG_RAS_CEC help text. rcu_nocbs= [KNL] - The argument is a cpu list, as described above, - except that the string "all" can be used to - specify every CPU on the system. + 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. @@ -4259,6 +4400,18 @@ rcuscale.kfree_rcu_test= [KNL] Set to measure performance of kfree_rcu() flooding. + rcuscale.kfree_rcu_test_double= [KNL] + Test the double-argument variant of kfree_rcu(). + If this parameter has the same value as + rcuscale.kfree_rcu_test_single, both the single- + and double-argument variants are tested. + + rcuscale.kfree_rcu_test_single= [KNL] + Test the single-argument variant of kfree_rcu(). + If this parameter has the same value as + rcuscale.kfree_rcu_test_double, both the single- + and double-argument variants are tested. + rcuscale.kfree_nthreads= [KNL] The number of threads running loops of kfree_rcu(). @@ -4725,7 +4878,7 @@ sbni= [NET] Granch SBNI12 leased line adapter - sched_debug [KNL] Enables verbose scheduler debug messages. + sched_verbose [KNL] Enables verbose scheduler debug messages. schedstats= [KNL,X86] Enable or disable scheduled statistics. Allowed values are enable and disable. This feature @@ -4877,6 +5030,10 @@ slram= [HW,MTD] + slab_merge [MM] + Enable merging of slabs with similar size when the + kernel is built without CONFIG_SLAB_MERGE_DEFAULT. + slab_nomerge [MM] Disable merging of slabs with similar size. May be necessary if there is some reason to distinguish @@ -4924,6 +5081,9 @@ lower than slub_max_order. For more information see Documentation/vm/slub.rst. + slub_merge [MM, SLUB] + Same with slab_merge. + slub_nomerge [MM, SLUB] Same with slab_nomerge. This is supported for legacy. See slab_nomerge for more information. @@ -5100,27 +5260,37 @@ spia_peddr= split_lock_detect= - [X86] Enable split lock detection + [X86] Enable split lock detection or bus lock detection When enabled (and if hardware support is present), atomic instructions that access data across cache line - boundaries will result in an alignment check exception. + boundaries will result in an alignment check exception + for split lock detection or a debug exception for + bus lock detection. off - not enabled - warn - the kernel will emit rate limited warnings + warn - the kernel will emit rate-limited warnings about applications triggering the #AC - exception. This mode is the default on CPUs - that supports split lock detection. + exception or the #DB exception. This mode is + the default on CPUs that support split lock + detection or bus lock detection. Default + behavior is by #AC if both features are + enabled in hardware. fatal - the kernel will send SIGBUS to applications - that trigger the #AC exception. + that trigger the #AC exception or the #DB + exception. Default behavior is by #AC if + both features are enabled in hardware. If an #AC exception is hit in the kernel or in firmware (i.e. not while executing in user mode) the kernel will oops in either "warn" or "fatal" mode. + #DB exception for bus lock is triggered only when + CPL > 0. + srbds= [X86,INTEL] Control the Special Register Buffer Data Sampling (SRBDS) mitigation. @@ -5462,6 +5632,18 @@ See Documentation/admin-guide/mm/transhuge.rst for more details. + trusted.source= [KEYS] + Format: <string> + This parameter identifies the trust source as a backend + for trusted keys implementation. Supported trust + sources: + - "tpm" + - "tee" + If not specified then it defaults to iterating through + the trust source list starting with TPM and assigns the + first trust source as a backend which is initialized + successfully during iteration. + tsc= Disable clocksource stability checks for TSC. Format: <string> [x86] reliable: mark tsc clocksource as reliable, this diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 531f689311f2..5e51ee5b0358 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -332,23 +332,3 @@ To reduce its OS jitter, do at least one of the following: kthreads from being created in the first place. However, please note that this will not eliminate OS jitter, but will instead shift it to RCU_SOFTIRQ. - -Name: - watchdog/%u - -Purpose: - Detect software lockups on each CPU. - -To reduce its OS jitter, do at least one of the following: - -1. Build with CONFIG_LOCKUP_DETECTOR=n, which will prevent these - kthreads from being created in the first place. -2. Boot with "nosoftlockup=0", which will also prevent these kthreads - from being created. Other related watchdog and softlockup boot - parameters may be found in Documentation/admin-guide/kernel-parameters.rst - and Documentation/watchdog/watchdog-parameters.rst. -3. Echo a zero to /proc/sys/kernel/watchdog to disable the - watchdog timer. -4. Echo a large number of /proc/sys/kernel/watchdog_thresh in - order to reduce the frequency of OS jitter due to the watchdog - timer down to a level that is acceptable for your workload. diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 91fd6846ce17..6721a80a2d4f 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -52,6 +52,7 @@ detailed description): - LCD Shadow (PrivacyGuard) enable and disable - Lap mode sensor - Setting keyboard language + - WWAN Antenna type A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1490,6 +1491,25 @@ fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan), nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden), tr(Turkey) +WWAN Antenna type +----------------- + +sysfs: wwan_antenna_type + +On some newer Thinkpads we need to set SAR value based on the antenna +type. This interface will be used by userspace to get the antenna type +and set the corresponding SAR value, as is required for FCC certification. + +The available commands are:: + + cat /sys/devices/platform/thinkpad_acpi/wwan_antenna_type + +Currently 2 antenna types are supported as mentioned below: +- type a +- type b + +The property is read-only. If the platform doesn't have support the sysfs +class is not created. Adaptive keyboard ----------------- diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index 5307f90738aa..05d51d2d8beb 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -357,6 +357,15 @@ creates ZONE_MOVABLE as following. Unfortunately, there is no information to show which memory block belongs to ZONE_MOVABLE. This is TBD. +.. note:: + Techniques that rely on long-term pinnings of memory (especially, RDMA and + vfio) are fundamentally problematic with ZONE_MOVABLE and, therefore, memory + hot remove. Pinned pages cannot reside on ZONE_MOVABLE, to guarantee that + memory can still get hot removed - be aware that pinning can fail even if + there is plenty of free memory in ZONE_MOVABLE. In addition, using + ZONE_MOVABLE might make page pinning more expensive, because pages have to be + migrated off that zone first. + .. _memory_hotplug_how_to_offline_memory: How to offline memory diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index c2f826409bf0..166697325947 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -151,7 +151,7 @@ Each cache level's directory provides its attributes. For example, the following shows a single cache level and the attributes available for software to query:: - # tree sys/devices/system/node/node0/memory_side_cache/ + # tree /sys/devices/system/node/node0/memory_side_cache/ /sys/devices/system/node/node0/memory_side_cache/ |-- index1 | |-- indexing diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst index 3b8a336511a4..c9c37f16eef8 100644 --- a/Documentation/admin-guide/mm/transhuge.rst +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -402,7 +402,7 @@ compact_fail but failed. It is possible to establish how long the stalls were using the function -tracer to record how long was spent in __alloc_pages_nodemask and +tracer to record how long was spent in __alloc_pages() and using the mm_page_alloc tracepoint to identify which allocations were for huge pages. diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 65eefa66c0ba..3aa38e8b8361 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -63,36 +63,36 @@ the generic ioctl available. The ``uffdio_api.features`` bitmask returned by the ``UFFDIO_API`` ioctl defines what memory types are supported by the ``userfaultfd`` and what -events, except page fault notifications, may be generated. - -If the kernel supports registering ``userfaultfd`` ranges on hugetlbfs -virtual memory areas, ``UFFD_FEATURE_MISSING_HUGETLBFS`` will be set in -``uffdio_api.features``. Similarly, ``UFFD_FEATURE_MISSING_SHMEM`` will be -set if the kernel supports registering ``userfaultfd`` ranges on shared -memory (covering all shmem APIs, i.e. tmpfs, ``IPCSHM``, ``/dev/zero``, -``MAP_SHARED``, ``memfd_create``, etc). - -The userland application that wants to use ``userfaultfd`` with hugetlbfs -or shared memory need to set the corresponding flag in -``uffdio_api.features`` to enable those features. - -If the userland desires to receive notifications for events other than -page faults, it has to verify that ``uffdio_api.features`` has appropriate -``UFFD_FEATURE_EVENT_*`` bits set. These events are described in more -detail below in `Non-cooperative userfaultfd`_ section. - -Once the ``userfaultfd`` has been enabled the ``UFFDIO_REGISTER`` ioctl should -be invoked (if present in the returned ``uffdio_api.ioctls`` bitmask) to -register a memory range in the ``userfaultfd`` by setting the +events, except page fault notifications, may be generated: + +- The ``UFFD_FEATURE_EVENT_*`` flags indicate that various other events + other than page faults are supported. These events are described in more + detail below in the `Non-cooperative userfaultfd`_ section. + +- ``UFFD_FEATURE_MISSING_HUGETLBFS`` and ``UFFD_FEATURE_MISSING_SHMEM`` + indicate that the kernel supports ``UFFDIO_REGISTER_MODE_MISSING`` + registrations for hugetlbfs and shared memory (covering all shmem APIs, + i.e. tmpfs, ``IPCSHM``, ``/dev/zero``, ``MAP_SHARED``, ``memfd_create``, + etc) virtual memory areas, respectively. + +- ``UFFD_FEATURE_MINOR_HUGETLBFS`` indicates that the kernel supports + ``UFFDIO_REGISTER_MODE_MINOR`` registration for hugetlbfs virtual memory + areas. + +The userland application should set the feature flags it intends to use +when invoking the ``UFFDIO_API`` ioctl, to request that those features be +enabled if supported. + +Once the ``userfaultfd`` API has been enabled the ``UFFDIO_REGISTER`` +ioctl should be invoked (if present in the returned ``uffdio_api.ioctls`` +bitmask) to register a memory range in the ``userfaultfd`` by setting the uffdio_register structure accordingly. The ``uffdio_register.mode`` bitmask will specify to the kernel which kind of faults to track for -the range (``UFFDIO_REGISTER_MODE_MISSING`` would track missing -pages). The ``UFFDIO_REGISTER`` ioctl will return the +the range. The ``UFFDIO_REGISTER`` ioctl will return the ``uffdio_register.ioctls`` bitmask of ioctls that are suitable to resolve userfaults on the range registered. Not all ioctls will necessarily be -supported for all memory types depending on the underlying virtual -memory backend (anonymous memory vs tmpfs vs real filebacked -mappings). +supported for all memory types (e.g. anonymous memory vs. shmem vs. +hugetlbfs), or all types of intercepted faults. Userland can use the ``uffdio_register.ioctls`` to manage the virtual address space in the background (to add or potentially also remove @@ -100,21 +100,46 @@ memory from the ``userfaultfd`` registered range). This means a userfault could be triggering just before userland maps in the background the user-faulted page. -The primary ioctl to resolve userfaults is ``UFFDIO_COPY``. That -atomically copies a page into the userfault registered range and wakes -up the blocked userfaults -(unless ``uffdio_copy.mode & UFFDIO_COPY_MODE_DONTWAKE`` is set). -Other ioctl works similarly to ``UFFDIO_COPY``. They're atomic as in -guaranteeing that nothing can see an half copied page since it'll -keep userfaulting until the copy has finished. +Resolving Userfaults +-------------------- + +There are three basic ways to resolve userfaults: + +- ``UFFDIO_COPY`` atomically copies some existing page contents from + userspace. + +- ``UFFDIO_ZEROPAGE`` atomically zeros the new page. + +- ``UFFDIO_CONTINUE`` maps an existing, previously-populated page. + +These operations are atomic in the sense that they guarantee nothing can +see a half-populated page, since readers will keep userfaulting until the +operation has finished. + +By default, these wake up userfaults blocked on the range in question. +They support a ``UFFDIO_*_MODE_DONTWAKE`` ``mode`` flag, which indicates +that waking will be done separately at some later time. + +Which ioctl to choose depends on the kind of page fault, and what we'd +like to do to resolve it: + +- For ``UFFDIO_REGISTER_MODE_MISSING`` faults, the fault needs to be + resolved by either providing a new page (``UFFDIO_COPY``), or mapping + the zero page (``UFFDIO_ZEROPAGE``). By default, the kernel would map + the zero page for a missing fault. With userfaultfd, userspace can + decide what content to provide before the faulting thread continues. + +- For ``UFFDIO_REGISTER_MODE_MINOR`` faults, there is an existing page (in + the page cache). Userspace has the option of modifying the page's + contents before resolving the fault. Once the contents are correct + (modified or not), userspace asks the kernel to map the page and let the + faulting thread continue with ``UFFDIO_CONTINUE``. Notes: -- If you requested ``UFFDIO_REGISTER_MODE_MISSING`` when registering then - you must provide some kind of page in your thread after reading from - the uffd. You must provide either ``UFFDIO_COPY`` or ``UFFDIO_ZEROPAGE``. - The normal behavior of the OS automatically providing a zero page on - an anonymous mmaping is not in place. +- You can tell which kind of fault occurred by examining + ``pagefault.flags`` within the ``uffd_msg``, checking for the + ``UFFD_PAGEFAULT_FLAG_*`` flags. - None of the page-delivering ioctls default to the range that you registered with. You must fill in all fields for the appropriate @@ -122,9 +147,9 @@ Notes: - You get the address of the access that triggered the missing page event out of a struct uffd_msg that you read in the thread from the - uffd. You can supply as many pages as you want with ``UFFDIO_COPY`` or - ``UFFDIO_ZEROPAGE``. Keep in mind that unless you used DONTWAKE then - the first of any of those IOCTLs wakes up the faulting thread. + uffd. You can supply as many pages as you want with these IOCTLs. + Keep in mind that unless you used DONTWAKE then the first of any of + those IOCTLs wakes up the faulting thread. - Be sure to test for all errors including (``pollfd[0].revents & POLLERR``). This can happen, e.g. when ranges diff --git a/Documentation/admin-guide/perf/hisi-pmu.rst b/Documentation/admin-guide/perf/hisi-pmu.rst index 404a5c3d9d00..546979360513 100644 --- a/Documentation/admin-guide/perf/hisi-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -53,6 +53,60 @@ Example usage of perf:: $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 +For HiSilicon uncore PMU v2 whose identifier is 0x30, the topology is the same +as PMU v1, but some new functions are added to the hardware. + +(a) L3C PMU supports filtering by core/thread within the cluster which can be +specified as a bitmap:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02,tt_core=0x3/ sleep 5 + +This will only count the operations from core/thread 0 and 1 in this cluster. + +(b) Tracetag allow the user to chose to count only read, write or atomic +operations via the tt_req parameeter in perf. The default value counts all +operations. tt_req is 3bits, 3'b100 represents read operations, 3'b101 +represents write operations, 3'b110 represents atomic store operations and +3'b111 represents atomic non-store operations, other values are reserved:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02,tt_req=0x4/ sleep 5 + +This will only count the read operations in this cluster. + +(c) Datasrc allows the user to check where the data comes from. It is 5 bits. +Some important codes are as follows: +5'b00001: comes from L3C in this die; +5'b01000: comes from L3C in the cross-die; +5'b01001: comes from L3C which is in another socket; +5'b01110: comes from the local DDR; +5'b01111: comes from the cross-die DDR; +5'b10000: comes from cross-socket DDR; +etc, it is mainly helpful to find that the data source is nearest from the CPU +cores. If datasrc_cfg is used in the multi-chips, the datasrc_skt shall be +configured in perf command:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xE/, + hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xF/ sleep 5 + +(d)Some HiSilicon SoCs encapsulate multiple CPU and IO dies. Each CPU die +contains several Compute Clusters (CCLs). The I/O dies are called Super I/O +clusters (SICL) containing multiple I/O clusters (ICLs). Each CCL/ICL in the +SoC has a unique ID. Each ID is 11bits, include a 6-bit SCCL-ID and 5-bit +CCL/ICL-ID. For I/O die, the ICL-ID is followed by: +5'b00000: I/O_MGMT_ICL; +5'b00001: Network_ICL; +5'b00011: HAC_ICL; +5'b10000: PCIe_ICL; + +Users could configure IDs to count data come from specific CCL/ICL, by setting +srcid_cmd & srcid_msk, and data desitined for specific CCL/ICL by setting +tgtid_cmd & tgtid_msk. A set bit in srcid_msk/tgtid_msk means the PMU will not +check the bit when matching against the srcid_cmd/tgtid_cmd. + +If all of these options are disabled, it can works by the default value that +doesn't distinguish the filter condition and ID information and will return +the total counter values in the PMU counters. + The current driver does not support sampling. So "perf record" is unsupported. Also attach to a task is unsupported as the events are all uncore. diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index b0a1ae7df13b..8f107d8c9261 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -3,7 +3,7 @@ Ramoops oops/panic logger Sergiu Iordache <sergiu@chromium.org> -Updated: 17 November 2011 +Updated: 10 Feb 2021 Introduction ------------ @@ -30,6 +30,8 @@ mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use depends on atomic operations. At least on ARM, pgprot_noncached causes the memory to be mapped strongly ordered, and atomic operations on strongly ordered memory are implementation defined, and won't work on many ARMs such as omaps. +Setting ``mem_type=2`` attempts to treat the memory region as normal memory, +which enables full cache on it. This can improve the performance. The memory area is divided into ``record_size`` chunks (also rounded down to power of two) and each kmesg dump writes a ``record_size`` chunk of diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst deleted file mode 100644 index 409fa91d7495..000000000000 --- a/Documentation/admin-guide/reporting-bugs.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _reportingbugs: - -.. note:: - - This document is obsolete, and will be replaced by - 'Documentation/admin-guide/reporting-issues.rst' in the near future. - -Reporting bugs -++++++++++++++ - -Background -========== - -The upstream Linux kernel maintainers only fix bugs for specific kernel -versions. Those versions include the current "release candidate" (or -rc) -kernel, any "stable" kernel versions, and any "long term" kernels. - -Please see https://www.kernel.org/ for a list of supported kernels. Any -kernel marked with [EOL] is "end of life" and will not have any fixes -backported to it. - -If you've found a bug on a kernel version that isn't listed on kernel.org, -contact your Linux distribution or embedded vendor for support. -Alternatively, you can attempt to run one of the supported stable or -rc -kernels, and see if you can reproduce the bug on that. It's preferable -to reproduce the bug on the latest -rc kernel. - - -How to report Linux kernel bugs -=============================== - - -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f <filename> - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://vger.kernel.org/lkml/). - - -Tips for reporting bugs ------------------------ - -If you haven't reported a bug before, please read: - - https://www.chiark.greenend.org.uk/~sgtatham/bugs.html - - http://www.catb.org/esr/faqs/smart-questions.html - -It's REALLY important to report bugs that seem unrelated as separate email -threads or separate bugzilla entries. If you report several unrelated -bugs at once, it's difficult for maintainers to tease apart the relevant -data. - - -Gather information ------------------- - -The most important information in a bug report is how to reproduce the -bug. This includes system information, and (most importantly) -step-by-step instructions for how a user can trigger the bug. - -If the failure includes an "OOPS:", take a picture of the screen, capture -a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/admin-guide/bug-hunting.rst" before posting your -bug report. This explains what you should do with the "Oops" information -to make it useful to the recipient. - -This is a suggested format for a bug report sent via email or bugzilla. -Having a standardized bug report form makes it easier for you not to -overlook things, and easier for the developers to find the pieces of -information they're really interested in. If some information is not -relevant to your bug, feel free to exclude it. - -First run the ver_linux script included as scripts/ver_linux, which -reports the version of some important subsystems. Run this script with -the command ``awk -f scripts/ver_linux``. - -Use that information to fill in all fields of the bug report form, and -post it to the mailing list with a subject of "PROBLEM: <one line -summary from [1.]>" for easy identification by the developers:: - - [1.] One line summary of the problem: - [2.] Full description of the problem/report: - [3.] Keywords (i.e., modules, networking, kernel): - [4.] Kernel information - [4.1.] Kernel version (from /proc/version): - [4.2.] Kernel .config file: - [5.] Most recent kernel version which did not have the bug: - [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/admin-guide/bug-hunting.rst) - [7.] A small shell script or example program which triggers the - problem (if possible) - [8.] Environment - [8.1.] Software (add the output of the ver_linux script here) - [8.2.] Processor information (from /proc/cpuinfo): - [8.3.] Module information (from /proc/modules): - [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) - [8.5.] PCI information ('lspci -vvv' as root) - [8.6.] SCSI information (from /proc/scsi/scsi) - [8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): - [X.] Other notes, patches, fixes, workarounds: - - -Follow up -========= - -Expectations for bug reporters ------------------------------- - -Linux kernel maintainers expect bug reporters to be able to follow up on -bug reports. That may include running new tests, applying patches, -recompiling your kernel, and/or re-triggering your bug. The most -frustrating thing for maintainers is for someone to report a bug, and then -never follow up on a request to try out a fix. - -That said, it's still useful for a kernel maintainer to know a bug exists -on a supported kernel, even if you can't follow up with retests. Follow -up reports, such as replying to the email thread with "I tried the latest -kernel and I can't reproduce my bug anymore" are also helpful, because -maintainers have to assume silence means things are still broken. - -Expectations for kernel maintainers ------------------------------------ - -Linux kernel maintainers are busy, overworked human beings. Some times -they may not be able to address your bug in a day, a week, or two weeks. -If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at https://LWN.net for more info: - - https://lwn.net/Calendar/ - -In general, kernel maintainers take 1 to 5 business days to respond to -bugs. The majority of kernel maintainers are employed to work on the -kernel, and they may not work on the weekends. Maintainers are scattered -around the world, and they may not work in your time zone. Unless you -have a high priority bug, please wait at least a week after the first bug -report before sending the maintainer a reminder email. - -The exceptions to this rule are regressions, kernel crashes, security holes, -or userspace breakage caused by new kernel behavior. Those bugs should be -addressed by the maintainers ASAP. If you suspect a maintainer is not -responding to these types of bugs in a timely manner (especially during a -merge window), escalate the bug to LKML and Linus Torvalds. - -Thank you! - -[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 07879d01fe68..18d8e25ba9df 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -9,25 +9,6 @@ (for example by the kernel's build system) might contain content taken from files which use a more restrictive license. -.. important:: - - This document is being prepared to replace - 'Documentation/admin-guide/reporting-bugs.rst'. The main work is done and - you are already free to follow its instructions when reporting issues to the - Linux kernel developers. But keep in mind, below text still needs a few - finishing touches and review. It was merged to the Linux kernel sources at - this stage to make this process easier and increase the text's visibility. - - Any improvements for the text or other feedback is thus very much welcome. - Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 'Jonathan - Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing list (LKML) - <linux-kernel@vger.kernel.org>' and the 'Linux Kernel Documentation List - <linux-doc@vger.kernel.org>' in CC. - - Areas in the text that still need work or discussion contain a hint like this - which point out the remaining issues; all of them start with the word "FIXME" - to make them easy to find. - Reporting issues ++++++++++++++++ @@ -36,46 +17,45 @@ Reporting issues The short guide (aka TL;DR) =========================== -If you're facing multiple issues with the Linux kernel at once, report each -separately to its developers. Try your best guess which kernel part might be -causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its -developers expect to be told about issues. Note, it's rarely -`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases -the report needs to be sent by email! - -Check the destination thoroughly for existing reports; also search the LKML -archives and the web. Join existing discussion if you find matches. If you -don't find any, install `the latest Linux mainline kernel -<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using -add-on kernel modules. Also ensure the kernel is running in a healthy -environment and is not already tainted before the issue occurs. - -If you can reproduce your issue with the mainline kernel, send a report to the -destination you determined earlier. Make sure it includes all relevant -information, which in case of a regression should mention the change that's -causing it which can often can be found with a bisection. Also ensure the -report reaches all people that need to know about it, for example the security -team, the stable maintainers or the developers of the patch that causes a -regression. Once the report is out, answer any questions that might be raised -and help where you can. That includes keeping the ball rolling: every time a -new rc1 mainline kernel is released, check if the issue is still happening -there and attach a status update to your initial report. - -If you can not reproduce the issue with the mainline kernel, consider sticking -with it; if you'd like to use an older version line and want to see it fixed -there, first make sure it's still supported. Install its latest release as -vanilla kernel. If you cannot reproduce the issue there, try to find the commit -that fixed it in mainline or any discussion preceding it: those will often -mention if backporting is planed or considered too complex. If backporting was -not discussed, ask if it's in the cards. In case you don't find any commits or -a preceding discussion, see the Linux-stable mailing list archives for existing -reports, as it might be a regression specific to the version line. If it is, -report it like you would report a problem in mainline (including the -bisection). - -If you reached this point without a solution, ask for advice one the -subsystem's mailing list. - +Are you facing a regression with vanilla kernels from the same stable or +longterm series? One still supported? Then search the `LKML +<https://lore.kernel.org/lkml/>`_ and the `Linux stable mailing list +<https://lore.kernel.org/stable/>`_ archives for matching reports to join. If +you don't find any, install `the latest release from that series +<https://kernel.org/>`_. If it still shows the issue, report it to the stable +mailing list (stable@vger.kernel.org) and CC the regressions list +(regressions@lists.linux.dev); ideally also CC the maintainer and the mailing +list for the subsystem in question. + +In all other cases try your best guess which kernel part might be causing the +issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers +expect to be told about problems, which most of the time will be by email with a +mailing list in CC. Check the destination's archives for matching reports; +search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you +don't find any to join, install `the latest mainline kernel +<https://kernel.org/>`_. If the issue is present there, send a report. + +The issue was fixed there, but you would like to see it resolved in a still +supported stable or longterm series as well? Then install its latest release. +If it shows the problem, search for the change that fixed it in mainline and +check if backporting is in the works or was discarded; if it's neither, ask +those who handled the change for it. + +**General remarks**: When installing and testing a kernel as outlined above, +ensure it's vanilla (IOW: not patched and not using add-on modules). Also make +sure it's built and running in a healthy environment and not already tainted +before the issue occurs. + +If you are facing multiple issues with the Linux kernel at once, report each +separately. While writing your report, include all information relevant to the +issue, like the kernel and the distro used. In case of a regression, CC the +regressions mailing list (regressions@lists.linux.dev) to your report. Also try +to pin-point the culprit with a bisection; if you succeed, include its +commit-id and CC everyone in the sign-off-by chain. + +Once the report is out, answer any questions that come up and help where you +can. That includes keeping the ball rolling by occasionally retesting with newer +releases and sending a status update afterwards. Step-by-step guide how to report issues to the kernel maintainers ================================================================= @@ -94,28 +74,23 @@ early if an issue that looks like a Linux kernel problem is actually caused by something else. These steps thus help to ensure the time you invest in this process won't feel wasted in the end: - * Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'. + * Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues. + + * Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the `Linux Kernel Mailing + List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports, + join the discussion instead of sending a new one. * See if the issue you are dealing with qualifies as regression, security issue, or a really severe problem: those are 'issues of high priority' that need special handling in some steps that are about to follow. - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. - - * Locate the driver or kernel subsystem that seems to be causing the issue. - Find out how and where its developers expect reports. Note: most of the - time this won't be bugzilla.kernel.org, as issues typically need to be sent - by mail to a maintainer and a public mailing list. - - * Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report. + * Make sure it's not the kernel's surroundings that are causing the issue + you face. * Create a fresh backup and put system repair and restore tools at hand. @@ -123,8 +98,8 @@ process won't feel wasted in the end: kernel modules on-the-fly, which solutions like DKMS might be doing locally without your knowledge. - * Make sure it's not the kernel's surroundings that are causing the issue - you face. + * Check if your kernel was 'tainted' when the issue occurred, as the event + that made the kernel set this flag might be causing the issue you face. * Write down coarsely how to reproduce the issue. If you deal with multiple issues at once, create separate notes for each of them and make sure they @@ -132,20 +107,35 @@ process won't feel wasted in the end: needs to get reported to the kernel developers separately, unless they are strongly entangled. + * If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'. + + * Locate the driver or kernel subsystem that seems to be causing the issue. + Find out how and where its developers expect reports. Note: most of the + time this won't be bugzilla.kernel.org, as issues typically need to be sent + by mail to a maintainer and a public mailing list. + + * Search the archives of the bug tracker or mailing list in question + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report. + After these preparations you'll now enter the main part: - * Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway. + * Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' build. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored. * Ensure the kernel you just installed does not 'taint' itself when running. * Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels. * Optimize your notes: try to find and write the most straightforward way to @@ -154,8 +144,8 @@ After these preparations you'll now enter the main part: that hear about it for the first time. And if you learned something in this process, consider searching again for existing reports about the issue. - * If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code. + * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error. * If your problem is a regression, try to narrow down when the issue was introduced as much as possible. @@ -184,28 +174,55 @@ After these preparations you'll now enter the main part: help yourself, if you don't get any help or if it's unsatisfying. +Reporting regressions within a stable and longterm kernel line +-------------------------------------------------------------- + +This subsection is for you, if you followed above process and got sent here at +the point about regression within a stable or longterm kernel version line. You +face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a +switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such +regressions as quickly as possible, hence there is a streamlined process to +report them: + + * Check if the kernel developers still maintain the Linux kernel version + line you care about: go to the `front page of kernel.org + <https://kernel.org/>`_ and make sure it mentions + the latest release of the particular version line without an '[EOL]' tag. + + * Check the archives of the `Linux stable mailing list + <https://lore.kernel.org/stable/>`_ for existing reports. + + * Install the latest release from the particular version line as a vanilla + kernel. Ensure this kernel is not tainted and still shows the problem, as + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well. + + * Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev); if you suspect the cause in a particular + subsystem, CC its maintainer and its mailing list. Roughly describe the + issue and ideally explain how to reproduce it. Mention the first version + that shows the problem and the last version that's working fine. Then + wait for further instructions. + +The reference section below explains each of these steps in more detail. + + Reporting issues only occurring in older kernel version lines ------------------------------------------------------------- -This section is for you, if you tried the latest mainline kernel as outlined +This subsection is for you, if you tried the latest mainline kernel as outlined above, but failed to reproduce your issue there; at the same time you want to -see the issue fixed in older version lines or a vendor kernel that's regularly -rebased on new stable or longterm releases. If that case follow these steps: +see the issue fixed in a still supported stable or longterm series or vendor +kernels regularly rebased on those. If that the case, follow these steps: * Prepare yourself for the possibility that going through the next few steps might not get the issue solved in older releases: the fix might be too big or risky to get backported there. - * Check if the kernel developers still maintain the Linux kernel version - line you care about: go to the front page of kernel.org and make sure it - mentions the latest release of the particular version line without an - '[EOL]' tag. - - * Check the archives of the Linux stable mailing list for existing reports. - - * Install the latest release from the particular version line as a vanilla - kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there. + * Perform the first three steps in the section "Dealing with regressions + within a stable and longterm kernel line" above. * Search the Linux kernel version control system for the change that fixed the issue in mainline, as its commit message might tell you if the fix is @@ -215,22 +232,13 @@ rebased on new stable or longterm releases. If that case follow these steps: deemed unsuitable for backporting. If backporting was not considered at all, join the newest discussion, asking if it's in the cards. - * Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it. - * One of the former steps should lead to a solution. If that doesn't work out, ask the maintainers for the subsystem that seems to be causing the issue for advice; CC the mailing list for the particular subsystem as well as the stable mailing list. +The reference section below explains each of these steps in more detail. + Reference section: Reporting issues to the kernel maintainers ============================================================= @@ -276,54 +284,103 @@ issues to the Linux kernel developers. Make sure you're using the upstream Linux kernel ------------------------------------------------ - *Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'.* + *Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues.* Like most programmers, Linux kernel developers don't like to spend time dealing -with reports for issues that don't even happen with the source code they -maintain: it's just a waste everybody's time, yours included. That's why you -later will have to test your issue with the latest 'vanilla' kernel: a kernel -that was build using the Linux sources taken straight from `kernel.org -<https://kernel.org/>`_ and not modified or enhanced in any way. - -Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers, -…) and most kernels shipped by Linux distributors are ancient from the point of -kernel development and heavily modified. They thus do not qualify for reporting -an issue to the Linux kernel developers: the issue you face with such a kernel -might be fixed already or caused by the changes or additions, even if they look -small or totally unrelated. That's why issues with such kernels need to be -reported to the vendor that distributed it. Its developers should look into the +with reports for issues that don't even happen with their current code. It's +just a waste everybody's time, especially yours. Unfortunately such situations +easily happen when it comes to the kernel and often leads to frustration on both +sides. That's because almost all Linux-based kernels pre-installed on devices +(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux +distributors are quite distant from the official Linux kernel as distributed by +kernel.org: these kernels from these vendors are often ancient from the point of +Linux development or heavily modified, often both. + +Most of these vendor kernels are quite unsuitable for reporting issues to the +Linux kernel developers: an issue you face with one of them might have been +fixed by the Linux kernel developers months or years ago already; additionally, +the modifications and enhancements by the vendor might be causing the issue you +face, even if they look small or totally unrelated. That's why you should report +issues with these kernels to the vendor. Its developers should look into the report and, in case it turns out to be an upstream issue, fix it directly -upstream or report it there. In practice that sometimes does not work out. If -that the case, you might want to circumvent the vendor by installing the latest -mainline kernel yourself and reporting the issue as outlined in this document; -just make sure to use really fresh kernel (see below). - - -.. note:: - - FIXME: Should we accept reports for issues with kernel images that are pretty - close to vanilla? But when are they close enough and how to put that line in - words? Maybe something like this? +upstream or forward the report there. In practice that often does not work out +or might not what you want. You thus might want to consider circumventing the +vendor by installing the very latest Linux kernel core yourself. If that's an +option for you move ahead in this process, as a later step in this guide will +explain how to do that once it rules out other potential causes for your issue. + +Note, the previous paragraph is starting with the word 'most', as sometimes +developers in fact are willing to handle reports about issues occurring with +vendor kernels. If they do in the end highly depends on the developers and the +issue in question. Your chances are quite good if the distributor applied only +small modifications to a kernel based on a recent Linux version; that for +example often holds true for the mainline kernels shipped by Debian GNU/Linux +Sid or Fedora Rawhide. Some developers will also accept reports about issues +with kernels from distributions shipping the latest stable kernel, as long as +its only slightly modified; that for example is often the case for Arch Linux, +regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better +want to use a mainline Linux and avoid using a stable kernel for this +process, as outlined in the section 'Install a fresh kernel for testing' in more +detail. + +Obviously you are free to ignore all this advice and report problems with an old +or heavily modified vendor kernel to the upstream Linux developers. But note, +those often get rejected or ignored, so consider yourself warned. But it's still +better than not reporting the issue at all: sometimes such reports directly or +indirectly will help to get the issue fixed over time. + + +Search for existing reports, first run +-------------------------------------- + + *Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the Linux Kernel Mailing + List (LKML). If you find matching reports, join the discussion instead of + sending a new one.* + +Reporting an issue that someone else already brought forward is often a waste of +time for everyone involved, especially you as the reporter. So it's in your own +interest to thoroughly check if somebody reported the issue already. At this +step of the process it's okay to just perform a rough search: a later step will +tell you to perform a more detailed search once you know where your issue needs +to be reported to. Nevertheless, do not hurry with this step of the reporting +process, it can save you time and trouble. + +Simply search the internet with your favorite search engine first. Afterwards, +search the `Linux Kernel Mailing List (LKML) archives +<https://lore.kernel.org/lkml/>`_. - *Note: Some Linux kernel developers accept reports from vendor kernels that - are known to be close to upstream. That for example is often the case for - the kernels that Debian GNU/Linux Sid or Fedora Rawhide ship, which are - normally following mainline closely and carry only a few patches. So a - report with one of these might be accepted by the developers that need to - handle it. But if they do, depends heavily on the individual developers and - the issue at hand. That's why installing a mainline vanilla kernel is the - safe bet.* +If you get flooded with results consider telling your search engine to limit +search timeframe to the past month or year. And wherever you search, make sure +to use good search terms; vary them a few times, too. While doing so try to +look at the issue from the perspective of someone else: that will help you to +come up with other words to use as search terms. Also make sure not to use too +many search terms at once. Remember to search with and without information like +the name of the kernel driver or the name of the affected hardware component. +But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') +often is not much helpful, as it is too specific. Instead try search terms like +the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip +('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - *Arch Linux, other Fedora releases, and openSUSE Tumbleweed often use quite - recent stable kernels that are pretty close to upstream, too. Some - developers accept bugs from them as well. But note that you normally should - avoid stable kernels for reporting issues and use a mainline kernel instead - (see below).* +In case you find an existing report about your issue, join the discussion, as +you might be able to provide valuable additional information. That can be +important even when a fix is prepared or in its final stages already, as +developers might look for people that can provide additional information or +test a proposed fix. Jump to the section 'Duties after the report went out' for +details on how to get properly involved. - Are there any other major Linux distributions that should be mentioned here? +Note, searching `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ might also +be a good idea, as that might provide valuable insights or turn up matching +reports. If you find the latter, just keep in mind: most subsystems expect +reports in different places, as described below in the section "Check where you +need to report your issue". The developers that should take care of the issue +thus might not even be aware of the bugzilla ticket. Hence, check the ticket if +the issue already got reported as outlined in this document and if not consider +doing so. Issue of high priority? @@ -365,6 +422,75 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error), as the kernel remains running after the latter. +Ensure a healthy environment +---------------------------- + + *Make sure it's not the kernel's surroundings that are causing the issue + you face.* + +Problems that look a lot like a kernel issue are sometimes caused by build or +runtime environment. It's hard to rule out that problem completely, but you +should minimize it: + + * Use proven tools when building your kernel, as bugs in the compiler or the + binutils can cause the resulting kernel to misbehave. + + * Ensure your computer components run within their design specifications; + that's especially important for the main processor, the main memory, and the + motherboard. Therefore, stop undervolting or overclocking when facing a + potential kernel issue. + + * Try to make sure it's not faulty hardware that is causing your issue. Bad + main memory for example can result in a multitude of issues that will + manifest itself in problems looking like kernel issues. + + * If you're dealing with a filesystem issue, you might want to check the file + system in question with ``fsck``, as it might be damaged in a way that leads + to unexpected kernel behavior. + + * When dealing with a regression, make sure it's not something else that + changed in parallel to updating the kernel. The problem for example might be + caused by other software that was updated at the same time. It can also + happen that a hardware component coincidentally just broke when you rebooted + into a new kernel for the first time. Updating the systems BIOS or changing + something in the BIOS Setup can also lead to problems that on look a lot + like a kernel regression. + + +Prepare for emergencies +----------------------- + + *Create a fresh backup and put system repair and restore tools at hand.* + +Reminder, you are dealing with computers, which sometimes do unexpected things, +especially if you fiddle with crucial parts like the kernel of its operating +system. That's what you are about to do in this process. Thus, make sure to +create a fresh backup; also ensure you have all tools at hand to repair or +reinstall the operating system as well as everything you need to restore the +backup. + + +Make sure your kernel doesn't get enhanced +------------------------------------------ + + *Ensure your system does not enhance its kernels by building additional + kernel modules on-the-fly, which solutions like DKMS might be doing locally + without your knowledge.* + +The risk your issue report gets ignored or rejected dramatically increases if +your kernel gets enhanced in any way. That's why you should remove or disable +mechanisms like akmods and DKMS: those build add-on kernel modules +automatically, for example when you install a new Linux kernel or boot it for +the first time. Also remove any modules they might have installed. Then reboot +before proceeding. + +Note, you might not be aware that your system is using one of these solutions: +they often get set up silently when you install Nvidia's proprietary graphics +driver, VirtualBox, or other software that requires a some support from a +module not part of the Linux kernel. That why your might need to uninstall the +packages with such software to get rid of any 3rd party kernel module. + + Check 'taint' flag ------------------ @@ -433,9 +559,52 @@ three things: the name of the module in question). -Locate kernel area that causes the issue +Document how to reproduce issue +------------------------------- + + *Write down coarsely how to reproduce the issue. If you deal with multiple + issues at once, create separate notes for each of them and make sure they + work independently on a freshly booted system. That's needed, as each issue + needs to get reported to the kernel developers separately, unless they are + strongly entangled.* + +If you deal with multiple issues at once, you'll have to report each of them +separately, as they might be handled by different developers. Describing +various issues in one report also makes it quite difficult for others to tear +it apart. Hence, only combine issues in one report if they are very strongly +entangled. + +Additionally, during the reporting process you will have to test if the issue +happens with other kernel versions. Therefore, it will make your work easier if +you know exactly how to reproduce an issue quickly on a freshly booted system. + +Note: it's often fruitless to report issues that only happened once, as they +might be caused by a bit flip due to cosmic radiation. That's why you should +try to rule that out by reproducing the issue before going further. Feel free +to ignore this advice if you are experienced enough to tell a one-time error +due to faulty hardware apart from a kernel issue that rarely happens and thus +is hard to reproduce. + + +Regression in stable or longterm kernel? ---------------------------------------- + *If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'.* + +Regression within a stable and longterm kernel version line are something the +Linux developers want to fix badly, as such issues are even more unwanted than +regression in the main development branch, as they can quickly affect a lot of +people. The developers thus want to learn about such issues as quickly as +possible, hence there is a streamlined process to report them. Note, +regressions with newer kernel version line (say something broke when switching +from 5.9.15 to 5.10.5) do not qualify. + + +Check where you need to report your issue +----------------------------------------- + *Locate the driver or kernel subsystem that seems to be causing the issue. Find out how and where its developers expect reports. Note: most of the time this won't be bugzilla.kernel.org, as issues typically need to be sent @@ -526,26 +695,6 @@ example above does not have such a line. That is the case for most sections, as Linux kernel development is completely driven by mail. Very few subsystems use a bug tracker, and only some of those rely on bugzilla.kernel.org. - -.. note:: - - FIXME: The old text took a totally different approach to bugzilla.kernel.org, - as it mentions it as the place to file issue for people that don't known how - to contact the appropriate people. The new one mentions it rarely; and when - it does like here, it warns users that it's often the wrong place to go. - - This approach was chosen as the main author of this document noticed quite a - few users (or even a lot?) get no reply to the bugs they file in bugzilla. - That's kind of expected, as quite a few (many? most?) of the maintainers - don't even get notified when reports for their subsystem get filed there. And - not getting a single reply to report is something that is just annoying for - users and might make them angry. Improving bugzilla.k.o would be an option, - but on the kernel and maintainers summit 2017 it was agreed on to first go - this route (sorry it took so long): it's easier to achieve and less - controversial, as putting additional burden on already overworked maintainers - is unlikely to get well received. - - In this and many other cases you thus have to look for lines starting with 'Mail:' instead. Those mention the name and the email addresses for the maintainers of the particular code. Also look for a line starting with 'Mailing @@ -558,21 +707,6 @@ and might leave some work for other developers on the subsystem specific list; and LKML is important to have one place where all issue reports can be found. -.. note:: - - FIXME: Above section tells users to always CC LKML. These days it's a kind of - "catch-all" list anyway, which nearly nobody seems to follow closely. So it - seems appropriate to go "all in" and make people send their reports here, - too, as everything (reports, fixes, ...) then can be found in one place (at - least for all reports sent by mail and all subsystems that CC LKML). - - Related: Should we create mailing list like 'linux-issues@vger.kernel.org' - and tell users above to always CC it when reporting issues? Then there would - be one central place reporters could search for existing reports (at least - for issues reported by mail) without getting regular LKML traffic mixed into - the results. - - Finding the maintainers with the help of a script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -611,205 +745,89 @@ modified during tree-wide cleanups by developers that do not care about the particular driver at all. -Search for existing reports ---------------------------- +Search for existing reports, second run +--------------------------------------- *Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report.* - -Reporting an issue that someone else already brought forward is often a waste -of time for everyone involved, especially you as the reporter. So it's in your -own interest to thoroughly check if somebody reported the issue already. Thus -do not hurry with this step of the reporting process. Spending 30 to 60 minutes -or even more time can save you and others quite a lot of time and trouble. - -The best place to search is the bug tracker or the mailing list where your -report needs to be filed. You'll find quite a few of those lists on -`lore.kernel.org <https://lore.kernel.org/>`_, but some are hosted in -different places. That for example is the case for the ath10k WiFi driver used -as example in the previous step. But you'll often find the archives for these -lists easily on the net. Searching for 'archive ath10k@lists.infradead.org' for -example will quickly lead you to the `Info page for the ath10k mailing list -<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links -to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_. - -Sadly this and quite a few other lists miss a way to search the archives. In -those cases use a regular internet search engine and add something like + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report.* + +As mentioned earlier already: reporting an issue that someone else already +brought forward is often a waste of time for everyone involved, especially you +as the reporter. That's why you should search for existing report again, now +that you know where they need to be reported to. If it's mailing list, you will +often find its archives on `lore.kernel.org <https://lore.kernel.org/>`_. + +But some list are hosted in different places. That for example is the case for +the ath10k WiFi driver used as example in the previous step. But you'll often +find the archives for these lists easily on the net. Searching for 'archive +ath10k@lists.infradead.org' for example will lead you to the `Info page for the +ath10k mailing list <https://lists.infradead.org/mailman/listinfo/ath10k>`_, +which at the top links to its +`list archives <https://lists.infradead.org/pipermail/ath10k/>`_. Sadly this and +quite a few other lists miss a way to search the archives. In those cases use a +regular internet search engine and add something like 'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits the results to the archives at that URL. -Additionally, search the internet and the `Linux Kernel Mailing List (LKML) -archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be -in some other subsystem. Searching in `bugzilla.kernel.org -<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find -anything there keep in mind: most subsystems expect reports in different -places, hence those you find there might have not even reached the people -responsible for the subsystem in question. Nevertheless, the data there might -provide valuable insights. - -If you get flooded with results consider telling your search engine to limit -search timeframe to the past month or year. And wherever you search, make sure -to use good search terms; vary them a few times, too. While doing so try to -look at the issue from the perspective of someone else: that will help you to -come up with other words to use as search terms. Also make sure not to use too -many search terms at once. Remember to search with and without information like -the name of the kernel driver or the name of the affected hardware component. -But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') -often is not much helpful, as it is too specific. Instead try search terms like -the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip -('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - -In case you find an existing report about your issue, join the discussion, as -you might be able to provide valuable additional information. That can be -important even when a fix is prepared or in its final stages already, as -developers might look for people that can provide additional information or -test a proposed fix. Jump to the section 'Duties after the report went out' for -details on how to get properly involved. - - -Prepare for emergencies ------------------------ - - *Create a fresh backup and put system repair and restore tools at hand.* - -Reminder, you are dealing with computers, which sometimes do unexpected things, -especially if you fiddle with crucial parts like the kernel of its operating -system. That's what you are about to do in this process. Thus, make sure to -create a fresh backup; also ensure you have all tools at hand to repair or -reinstall the operating system as well as everything you need to restore the -backup. - - -Make sure your kernel doesn't get enhanced ------------------------------------------- - - *Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing locally - without your knowledge.* - -Your kernel must be 'vanilla' when reporting an issue, but stops being pure as -soon as it loads a kernel module not built from the sources used to compile the -kernel image itself. That's why you need to ensure your Linux kernel stays -vanilla by removing or disabling mechanisms like akmods and DKMS: those might -build additional kernel modules automatically, for example when your boot into -a newly installed Linux kernel the first time. Reboot after removing them and -any modules they installed. - -Note, you might not be aware that your system is using one of these solutions: -they often get set up silently when you install Nvidia's proprietary graphics -driver, VirtualBox, or other software that requires a some support from a -module not part of the Linux kernel. That why your might need to uninstall the -packages with such software to get rid of any 3rd party kernel module. - - -Ensure a healthy environment ----------------------------- - - *Make sure it's not the kernel's surroundings that are causing the issue - you face.* - -Problems that look a lot like a kernel issue are sometimes caused by build or -runtime environment. It's hard to rule out that problem completely, but you -should minimize it: - - * Use proven tools when building your kernel, as bugs in the compiler or the - binutils can cause the resulting kernel to misbehave. - - * Ensure your computer components run within their design specifications; - that's especially important for the main processor, the main memory, and the - motherboard. Therefore, stop undervolting or overclocking when facing a - potential kernel issue. - - * Try to make sure it's not faulty hardware that is causing your issue. Bad - main memory for example can result in a multitude of issues that will - manifest itself in problems looking like kernel issues. - - * If you're dealing with a filesystem issue, you might want to check the file - system in question with ``fsck``, as it might be damaged in a way that leads - to unexpected kernel behavior. - - * When dealing with a regression, make sure it's not something else that - changed in parallel to updating the kernel. The problem for example might be - caused by other software that was updated at the same time. It can also - happen that a hardware component coincidentally just broke when you rebooted - into a new kernel for the first time. Updating the systems BIOS or changing - something in the BIOS Setup can also lead to problems that on look a lot - like a kernel regression. - +It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again +at this point. If your report needs to be filed in a bug tracker, you may want +to check the mailing list archives for the subsystem as well, as someone might +have reported it only there. -Document how to reproduce issue -------------------------------- +For details how to search and what to do if you find matching reports see +"Search for existing reports, first run" above. - *Write down coarsely how to reproduce the issue. If you deal with multiple - issues at once, create separate notes for each of them and make sure they - work independently on a freshly booted system. That's needed, as each issue - needs to get reported to the kernel developers separately, unless they are - strongly entangled.* - -If you deal with multiple issues at once, you'll have to report each of them -separately, as they might be handled by different developers. Describing -various issues in one report also makes it quite difficult for others to tear -it apart. Hence, only combine issues in one report if they are very strongly -entangled. - -Additionally, during the reporting process you will have to test if the issue -happens with other kernel versions. Therefore, it will make your work easier if -you know exactly how to reproduce an issue quickly on a freshly booted system. - -Note: it's often fruitless to report issues that only happened once, as they -might be caused by a bit flip due to cosmic radiation. That's why you should -try to rule that out by reproducing the issue before going further. Feel free -to ignore this advice if you are experienced enough to tell a one-time error -due to faulty hardware apart from a kernel issue that rarely happens and thus -is hard to reproduce. +Do not hurry with this step of the reporting process: spending 30 to 60 minutes +or even more time can save you and others quite a lot of time and trouble. Install a fresh kernel for testing ---------------------------------- - *Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway.* - -Reporting an issue to the Linux kernel developers they fixed weeks or months -ago is annoying for them and wasting their and your time. That's why it's in -everybody's interest to check if the issue occurs with the latest codebase -before reporting it. - -In the scope of the Linux kernel the term 'latest' means: a kernel version -recently created from the main line of development, as this 'mainline' tree is -where developers first apply fixes; only after that are they are allowed to get -backported to older, still supported version lines called 'stable' and -'longterm' kernels. That's why you should check a recent mainline kernel, even -if you deal with an issue you only want to see fixed in an older version line. -Another reason: some fixes are only applied to mainline or recent version -lines, as it's too hard or risky to backport them to older versions. If that -the case, reporting the issue again is unlikely to change anything. - -Longterm kernels (sometimes called "LTS kernels") are therefore unsuitable for -testing; they simply are too distant from current development. Even the latest -Linux 'stable' kernel is a significant bit behind and thus better avoided. At -least most of the time, as sometimes a stable kernel can the best choice; but -in those situations you might want to wait a few days anyway: - -Choosing between mainline, stable and waiting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head over to `kernel.org <https://kernel.org/>`_ to decide which version to -use. Ignore the big yellow button that says 'Latest release' and look a little -lower for a table. At its top you'll see a line starting with 'mainline', which -most of the time will point to a pre-release with a version number like -'5.8-rc2'. If that's the case, you'll want to use this mainline kernel for -testing. Do not let that 'rc' scare you, these 'development kernels' are pretty -reliable — and you made a backup, as you were instructed above, didn't you? - -In about two out of every nine to ten weeks, 'mainline' might point you to a + *Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' built. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored.* + +As mentioned in the detailed explanation for the first step already: Like most +programmers, Linux kernel developers don't like to spend time dealing with +reports for issues that don't even happen with the current code. It's just a +waste everybody's time, especially yours. That's why it's in everybody's +interest that you confirm the issue still exists with the latest upstream code +before reporting it. You are free to ignore this advice, but as outlined +earlier: doing so dramatically increases the risk that your issue report might +get rejected or simply ignored. + +In the scope of the kernel "latest upstream" normally means: + + * Install a mainline kernel; the latest stable kernel can be an option, but + most of the time is better avoided. Longterm kernels (sometimes called 'LTS + kernels') are unsuitable at this point of the process. The next subsection + explains all of this in more detail. + + * The over next subsection describes way to obtain and install such a kernel. + It also outlines that using a pre-compiled kernel are fine, but better are + vanilla, which means: it was built using Linux sources taken straight `from + kernel.org <https://kernel.org/>`_ and not modified or enhanced in any way. + +Choosing the right version for testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Head over to `kernel.org <https://kernel.org/>`_ to find out which version you +want to use for testing. Ignore the big yellow button that says 'Latest release' +and look a little lower at the table. At its top you'll see a line starting with +mainline, which most of the time will point to a pre-release with a version +number like '5.8-rc2'. If that's the case, you'll want to use this mainline +kernel for testing, as that where all fixes have to be applied first. Do not let +that 'rc' scare you, these 'development kernels' are pretty reliable — and you +made a backup, as you were instructed above, didn't you? + +In about two out of every nine to ten weeks, mainline might point you to a proper release with a version number like '5.7'. If that happens, consider suspending the reporting process until the first pre-release of the next version (5.8-rc1) shows up on kernel.org. That's because the Linux development @@ -830,45 +848,79 @@ case mainline for some reason does currently not work for you. An in general: using it for reproducing the issue is also better than not reporting it issue at all. +Better avoid using the latest stable kernel outside merge windows, as all fixes +must be applied to mainline first. That's why checking the latest mainline +kernel is so important: any issue you want to see fixed in older version lines +needs to be fixed in mainline first before it can get backported, which can +take a few days or weeks. Another reason: the fix you hope for might be too +hard or risky for backporting; reporting the issue again hence is unlikely to +change anything. + +These aspects are also why longterm kernels (sometimes called "LTS kernels") +are unsuitable for this part of the reporting process: they are to distant from +the current code. Hence go and test mainline first and follow the process +further: if the issue doesn't occur with mainline it will guide you how to get +it fixed in older version lines, if that's in the cards for the fix in question. + How to obtain a fresh Linux kernel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use pre-built or self-compiled kernel for testing; if you choose the -latter approach, you can either obtain the source code using git or download it -as tar archive. - -Using a pre-compiled kernel for testing is often the quickest, easiest, and -safest way – especially is you are unfamiliar with the Linux kernel. But it -needs to be a vanilla kernel, which can be hard to come buy. You are in luck if -you are using a popular Linux distribution: for quite a few of them you'll find -repositories on the net that contain packages with the latest mainline or -stable kernels in vanilla fashion. It's totally okay to use these, just make -sure from the repository's documentation they are really vanilla. And ensure -the packages contain the latest versions as offered on kernel.org; they are -likely unsuitable if the package is older than a week, as new mainline and -stable kernels typically get released at least once a week. And be aware that -you might need to get build your own kernel later anyway when it comes to -helping test fixes, as described later in this document. - -Developers and experienced Linux users familiar with git are often best served -by obtaining the latest Linux kernel sources straight from the `official -development repository on kernel.org +**Using a pre-compiled kernel**: This is often the quickest, easiest, and safest +way for testing — especially is you are unfamiliar with the Linux kernel. The +problem: most of those shipped by distributors or add-on repositories are build +from modified Linux sources. They are thus not vanilla and therefore often +unsuitable for testing and issue reporting: the changes might cause the issue +you face or influence it somehow. + +But you are in luck if you are using a popular Linux distribution: for quite a +few of them you'll find repositories on the net that contain packages with the +latest mainline or stable Linux built as vanilla kernel. It's totally okay to +use these, just make sure from the repository's description they are vanilla or +at least close to it. Additionally ensure the packages contain the latest +versions as offered on kernel.org. The packages are likely unsuitable if they +are older than a week, as new mainline and stable kernels typically get released +at least once a week. + +Please note that you might need to build your own kernel manually later: that's +sometimes needed for debugging or testing fixes, as described later in this +document. Also be aware that pre-compiled kernels might lack debug symbols that +are needed to decode messages the kernel prints when a panic, Oops, warning, or +BUG occurs; if you plan to decode those, you might be better off compiling a +kernel yourself (see the end of this subsection and the section titled 'Decode +failure messages' for details). + +**Using git**: Developers and experienced Linux users familiar with git are +often best served by obtaining the latest Linux kernel sources straight from the +`official development repository on kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_. Those are likely a bit ahead of the latest mainline pre-release. Don't worry about it: they are as reliable as a proper pre-release, unless the kernel's development cycle is currently in the middle of a merge window. But even then they are quite reliable. -People unfamiliar with git are often best served by downloading the sources as -tarball from `kernel.org <https://kernel.org/>`_. +**Conventional**: People unfamiliar with git are often best served by +downloading the sources as tarball from `kernel.org <https://kernel.org/>`_. -How to actually build a kernel isnot described here, as many websites explain +How to actually build a kernel is not described here, as many websites explain the necessary steps already. If you are new to it, consider following one of those how-to's that suggest to use ``make localmodconfig``, as that tries to pick up the configuration of your current kernel and then tries to adjust it somewhat for your system. That does not make the resulting kernel any better, but quicker to compile. +Note: If you are dealing with a panic, Oops, warning, or BUG from the kernel, +please try to enable CONFIG_KALLSYMS when configuring your kernel. +Additionally, enable CONFIG_DEBUG_KERNEL and CONFIG_DEBUG_INFO, too; the +latter is the relevant one of those two, but can only be reached if you enable +the former. Be aware CONFIG_DEBUG_INFO increases the storage space required to +build a kernel by quite a bit. But that's worth it, as these options will allow +you later to pinpoint the exact line of code that triggers your issue. The +section 'Decode failure messages' below explains this in more detail. + +But keep in mind: Always keep a record of the issue encountered in case it is +hard to reproduce. Sending an undecoded report is better than not reporting +the issue at all. + Check 'taint' flag ------------------ @@ -888,7 +940,7 @@ Reproduce issue with the fresh kernel ------------------------------------- *Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels.* Check if the issue occurs with the fresh Linux kernel version you just @@ -923,31 +975,55 @@ instead you can join. Decode failure messages ----------------------- -.. note:: + *If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error.* - FIXME: The text in this section is a placeholder for now and quite similar to - the old text found in 'Documentation/admin-guide/reporting-bugs.rst' - currently. It and the document it references are known to be outdated and - thus need to be revisited. Thus consider this note a request for help: if you - are familiar with this topic, please write a few lines that would fit here. - Alternatively, simply outline the current situation roughly to the main - authors of this document (see intro), as they might be able to write - something then. +When the kernel detects an internal problem, it will log some information about +the executed code. This makes it possible to pinpoint the exact line in the +source code that triggered the issue and shows how it was called. But that only +works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring +your kernel. If you did so, consider to decode the information from the +kernel's log. That will make it a lot easier to understand what lead to the +'panic', 'Oops', 'warning', or 'BUG', which increases the chances that someone +can provide a fix. - This section in the end should answer questions like "when is this actually - needed", "what .config options to ideally set earlier to make this step easy - or unnecessary?" (likely CONFIG_UNWINDER_ORC when it's available, otherwise - CONFIG_UNWINDER_FRAME_POINTER; but is there anything else needed?). +Decoding can be done with a script you find in the Linux source tree. If you +are running a kernel you compiled yourself earlier, call it like this:: -.. + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + +If you are running a packaged vanilla kernel, you will likely have to install +the corresponding packages with debug symbols. Then call the script (which you +might need to get from the Linux sources if your distro does not package it) +like this:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +The script will work on log lines like the following, which show the address of +the code the kernel was executing when the error occurred:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +Once decoded, these lines will look like this:: - *If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code.* + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module -When the kernel detects an error, it will print a stack dump that allows to -identify the exact line of code where the issue happens. But that information -sometimes needs to get decoded to be readable, which is explained in -admin-guide/bug-hunting.rst. +In this case the executed code was built from the file +'~/linux-5.10.5/test-module/test-module.c' and the error occurred by the +instructions found in line '16'. + +The script will similarly decode the addresses mentioned in the section +starting with 'Call trace', which show the path to the function where the +problem occurred. Additionally, the script will show the assembler output for +the code section the kernel was executing. + +Note, if you can't get this to work, simply skip this step and mention the +reason for it in the report. If you're lucky, it might not be needed. And if it +is, someone might help you to get things going. Also be aware this is just one +of several ways to decode kernel stack traces. Sometimes different steps will +be required to retrieve the relevant details. Don't worry about that, if that's +needed in your case, developers will tell you what to do. Special care for regressions @@ -1000,8 +1076,7 @@ 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 -oldnoconfig`` to adjust it for the needs of the new version without enabling -any new feature, as those are allowed to cause regressions. +olddefconfig`` to adjust it for the needs of the new version. Write and send the report @@ -1166,17 +1241,27 @@ Special handling for high priority issues Reports for high priority issues need special handling. -**Severe bugs**: make sure the subject or ticket title as well as the first +**Severe issues**: make sure the subject or ticket title as well as the first paragraph makes the severeness obvious. -**Regressions**: If the issue is a regression add [REGRESSION] to the mail's -subject or the title in the bug-tracker. If you did not perform a bisection -mention at least the latest mainline version you tested that worked fine (say -5.7) and the oldest where the issue occurs (say 5.8). If you did a successful -bisection mention the commit id and subject of the change that causes the -regression. Also make sure to add the author of that change to your report; if -you need to file your bug in a bug-tracker forward the report to him in a -private mail and mention where your filed it. +**Regressions**: make the report's subject start with '[REGRESSION]'. + +In case you performed a successful bisection, use the title of the change that +introduced the regression as the second part of your subject. Make the report +also mention the commit id of the culprit. In case of an unsuccessful bisection, +make your report mention the latest tested version that's working fine (say 5.7) +and the oldest where the issue occurs (say 5.8-rc1). + +When sending the report by mail, CC the Linux regressions mailing list +(regressions@lists.linux.dev). In case the report needs to be filed to some web +tracker, proceed to do so. Once filed, forward the report by mail to the +regressions list; CC the maintainer and the mailing list for the subsystem in +question. Make sure to inline the forwarded report, hence do not attach it. +Also add a short note at the top where you mention the URL to the ticket. + +When mailing or forwarding the report, 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. **Security issues**: for these issues your will have to evaluate if a short-term risk to other users would arise if details were publicly disclosed. @@ -1255,7 +1340,7 @@ you never have heard of yet; or you might be asked to apply a patch to the Linux kernel sources to test if it helps. In some cases it will be fine sending a reply asking for instructions how to do that. But before going that route try to find the answer own your own by searching the internet; alternatively -consider asking in other places for advice. For example ask a fried or post +consider asking in other places for advice. For example ask a friend or post about it to a chatroom or forum you normally hang out. **Be patient**: If you are really lucky you might get a reply to your report @@ -1390,32 +1475,11 @@ easier. And with a bit of luck there might be someone in the team that knows a bit about programming and might be able to write a fix. -Details about reporting issues only occurring in older kernel version lines ---------------------------------------------------------------------------- +Reference for "Reporting regressions within a stable and longterm kernel line" +------------------------------------------------------------------------------ -This subsection provides details for steps you need to take if you could not -reproduce your issue with a mainline kernel, but want to see it fixed in older -version lines (aka stable and longterm kernels). - -Some fixes are too complex -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Prepare yourself for the possibility that going through the next few steps - might not get the issue solved in older releases: the fix might be too big - or risky to get backported there.* - -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'. - -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 -longterm kernels, but too risky to integrate into older ones. So be aware the -fix you are hoping for might be one of those that won't be backported to the -version line your care about. In that case you'll have no other choice then to -live with the issue or switch to a newer Linux version, unless you want to -patch the fix into your kernels yourself. +This subsection provides details for the steps you need to perform if you face +a regression within a stable and longterm kernel line. Make sure the particular version line still gets support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1431,7 +1495,7 @@ chosen and gets supported for at least two years (often six). That's why you need to check if the kernel developers still support the version line you care for. -Note, if kernel.org lists two 'stable' version lines on the front page, you +Note, if kernel.org lists two stable version lines on the front page, you should consider switching to the newer one and forget about the older one: support for it is likely to be abandoned soon. Then it will get a "end-of-life" (EOL) stamp. Version lines that reached that point still get mentioned on the @@ -1454,12 +1518,108 @@ Reproduce issue with the newest release *Install the latest release from the particular version line as a vanilla kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there.* + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well.* Before investing any more time in this process you want to check if the issue was already fixed in the latest release of version line you're interested in. This kernel needs to be vanilla and shouldn't be tainted before the issue -happens, as detailed outlined already above in the process of testing mainline. +happens, as detailed outlined already above in the section "Install a fresh +kernel for testing". + +Did you first notice the regression with a vendor kernel? Then changes the +vendor applied might be interfering. You need to rule that out by performing +a recheck. Say something broke when you updated from 5.10.4-vendor.42 to +5.10.5-vendor.43. Then after testing the latest 5.10 release as outlined in +the previous paragraph check if a vanilla build of Linux 5.10.4 works fine as +well. If things are broken there, the issue does not qualify as upstream +regression and you need switch back to the main step-by-step guide to report +the issue. + +Report the regression +~~~~~~~~~~~~~~~~~~~~~ + + *Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev); if you suspect the cause in a particular + subsystem, CC its maintainer and its mailing list. Roughly describe the + issue and ideally explain how to reproduce it. Mention the first version + that shows the problem and the last version that's working fine. Then + wait for further instructions.* + +When reporting a regression that happens within a stable or longterm kernel +line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for +the start to get the issue reported quickly. Hence a rough description to the +stable and regressions mailing list is all it takes; but in case you suspect +the cause in a particular subsystem, CC its maintainers and its mailing list +as well, because that will speed things up. + +And note, it helps developers a great deal if you can specify the exact version +that introduced the problem. Hence if possible within a reasonable time frame, +try to find that version using vanilla kernels. Lets assume something broke when +your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as +instructed above go and check the latest kernel from that version line, say +5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches +the distributor applied interfere. If the issue doesn't manifest itself there, +try 5.10.7 and then (depending on the outcome) 5.10.8 or 5.10.6 to find the +first version where things broke. Mention it in the report and state that 5.10.9 +is still broken. + +What the previous paragraph outlines is basically a rough manual 'bisection'. +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 +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. + + +Reference for "Reporting issues only occurring in older kernel version lines" +----------------------------------------------------------------------------- + +This section provides details for the steps you need to take if you could not +reproduce your issue with a mainline kernel, but want to see it fixed in older +version lines (aka stable and longterm kernels). + +Some fixes are too complex +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *Prepare yourself for the possibility that going through the next few steps + might not get the issue solved in older releases: the fix might be too big + or risky to get backported there.* + +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'. + +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 +longterm kernels, but too risky to integrate into older ones. So be aware the +fix you are hoping for might be one of those that won't be backported to the +version line your care about. In that case you'll have no other choice then to +live with the issue or switch to a newer Linux version, unless you want to +patch the fix into your kernels yourself. + +Common preparations +~~~~~~~~~~~~~~~~~~~ + + *Perform the first three steps in the section "Reporting issues only + occurring in older kernel version lines" above.* + +You need to carry out a few steps already described in another section of this +guide. Those steps will let you: + + * Check if the kernel developers still maintain the Linux kernel version line + you care about. + + * Search the Linux stable mailing list for exiting reports. + + * Check with the latest release. + Check code history and search for existing discussions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1513,41 +1673,6 @@ discussions abound it. join the discussion: mention the version where you face the issue and that you would like to see it fixed, if suitable. -Check if it's a regression specific to stable or longterm kernels -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it.* - -Sometimes you won't find anything in the previous step: the issue you face -might have never occurred in mainline, as it is caused by some change that is -incomplete or not correctly applied. To check this, install the first release -from version line you care about, e.g., if you care about 5.4.x, install 5.4. - -If the issue doesn't show itself there, it's a regression specific to the -particular version line. In that case you need to report it like an issue -happening in mainline, like the last few steps in the main section in the above -outline. - -One of them suggests doing a bisection, which you are strongly advised to do in -this case. After finding the culprit, search the net for existing reports -again: not only search for the exact subject and the commit-id (proper and -shortened to twelve characters) of the change, but also for the commit-id -(proper and shortened) mentioned as 'Upstream commit' in the commit message. - -Write the report; just keep a few specialties in mind: CC or forward the report -to the stable maintainers, the stable mailing list, which the :ref:`MAINTAINERS -<maintainers>` file mentions in the section "STABLE BRANCH". If you performed a -successful bisection, CC the author of the change and include its subject and -the shortened commit-id. Ask for advice ~~~~~~~~~~~~~~ @@ -1560,8 +1685,7 @@ Ask for advice If the previous three steps didn't get you closer to a solution there is only one option left: ask for advice. Do that in a mail you sent to the maintainers for the subsystem where the issue seems to have its roots; CC the mailing list -for the subsystem as well as the stable mailing list the :ref:`MAINTAINERS -<maintainers>` file mention in the section "STABLE BRANCH". +for the subsystem as well as the stable mailing list (stable@vger.kernel.org). Why some issues won't get any reaction or remain unfixed after being reported @@ -1629,3 +1753,13 @@ issues to the Linux kernel developers: the length and complexity of this document and the implications between the lines illustrate that. But that's how it is for now. The main author of this text hopes documenting the state of the 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 + 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". diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 1d56a6b73a4e..68b21395a743 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -483,10 +483,11 @@ modprobe ======== The full path to the usermode helper for autoloading kernel modules, -by default "/sbin/modprobe". This binary is executed when the kernel -requests a module. For example, if userspace passes an unknown -filesystem type to mount(), then the kernel will automatically request -the corresponding filesystem module by executing this usermode helper. +by default ``CONFIG_MODPROBE_PATH``, which in turn defaults to +"/sbin/modprobe". This binary is executed when the kernel requests a +module. For example, if userspace passes an unknown filesystem type +to mount(), then the kernel will automatically request the +corresponding filesystem module by executing this usermode helper. This usermode helper should insert the needed module into the kernel. This sysctl only affects module autoloading. It has no effect on the @@ -1457,11 +1458,22 @@ unprivileged_bpf_disabled ========================= Writing 1 to this entry will disable unprivileged calls to ``bpf()``; -once disabled, calling ``bpf()`` without ``CAP_SYS_ADMIN`` will return -``-EPERM``. +once disabled, calling ``bpf()`` without ``CAP_SYS_ADMIN`` or ``CAP_BPF`` +will return ``-EPERM``. Once set to 1, this can't be cleared from the +running kernel anymore. -Once set, this can't be cleared. +Writing 2 to this entry will also disable unprivileged calls to ``bpf()``, +however, an admin can still change this setting later on, if needed, by +writing 0 or 1 to this entry. +If ``BPF_UNPRIV_DEFAULT_OFF`` is enabled in the kernel config, then this +entry will default to 2 instead of 0. + += ============================================================= +0 Unprivileged calls to ``bpf()`` are enabled +1 Unprivileged calls to ``bpf()`` are disabled without recovery +2 Unprivileged calls to ``bpf()`` are disabled += ============================================================= watchdog ======== diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index f2ab8a5b6a4b..4150f74c521a 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -64,6 +64,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on: - arm64 - arm32 - ppc64 + - ppc32 - sparc64 - mips64 - s390x @@ -73,7 +74,6 @@ two flavors of JITs, the newer eBPF JIT currently supported on: And the older cBPF JIT supported on the following archs: - mips - - ppc - sparc eBPF JITs are a superset of cBPF JITs, meaning the kernel will @@ -311,6 +311,17 @@ permit to distribute the load on several cpus. If set to 1 (default), timestamps are sampled as soon as possible, before queueing. +netdev_unregister_timeout_secs +------------------------------ + +Unregister network device timeout in seconds. +This option controls the timeout (in seconds) used to issue a warning while +waiting for a network device refcount to drop to 0 during device +unregistration. A lower value may be useful during bisection to detect +a leaked reference faster. A larger value may be useful to prevent false +warnings on slow/loaded systems. +Default value is 10, minimum 1, maximum 3600. + optmem_max ---------- diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 67dfa4c29093..60ce5f5ebab6 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -90,8 +90,8 @@ Command Function ``b`` Will immediately reboot the system without syncing or unmounting your disks. -``c`` Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. +``c`` Will perform a system crash and a crashdump will be taken + if configured. ``d`` Shows all locks that are held. diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index 5422407a96d7..8de008c0c5ad 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -522,7 +522,7 @@ and the short name of the data device. They all can be found in: ================ =========== xfs_iwalk-$pid Inode scans of the entire filesystem. Currently limited to mount time quotacheck. - xfs-blockgc Background garbage collection of disk space that have been + xfs-gc Background garbage collection of disk space that have been speculatively allocated beyond EOF or for staging copy on write operations. ================ =========== diff --git a/Documentation/arch.rst b/Documentation/arch.rst new file mode 100644 index 000000000000..f10bd32a5972 --- /dev/null +++ b/Documentation/arch.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +CPU Architectures +================= + +These books provide programming details about architecture-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + arm/index + arm64/index + ia64/index + m68k/index + mips/index + nios2/index + openrisc/index + parisc/index + powerpc/index + riscv/index + s390/index + sh/index + sparc/index + x86/index + xtensa/index diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst index b4bea32472b6..d4f34ae9e6f4 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arm/index.rst @@ -52,6 +52,7 @@ SoC-specific documents stm32/stm32f746-overview stm32/overview stm32/stm32h743-overview + stm32/stm32h750-overview stm32/stm32f769-overview stm32/stm32f429-overview stm32/stm32mp157-overview diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 94cd73383594..c50be711ec72 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -18,12 +18,12 @@ Orion family - 88F5181L - 88F5182 - - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf - - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf - - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + - Datasheet: https://web.archive.org/web/20210124231420/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-datasheet.pdf + - Programmer's User Guide: https://web.archive.org/web/20210124231536/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-opensource-manual.pdf + - User Manual: https://web.archive.org/web/20210124231631/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-usermanual.pdf - 88F5281 - - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + - Datasheet: https://web.archive.org/web/20131028144728/http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - 88F6183 Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible @@ -38,33 +38,33 @@ Kirkwood family Flavors: - 88F6282 a.k.a Armada 300 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6283 a.k.a Armada 310 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6190 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20130730072715/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6192 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20131113121446/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6182 - 88F6180 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616201621/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20130730091654/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6281 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120131133709/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20120620073511/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf Homepage: - http://www.marvell.com/embedded-processors/kirkwood/ + https://web.archive.org/web/20160513194943/http://www.marvell.com/embedded-processors/kirkwood/ Core: Feroceon 88fr131 ARMv5 compatible Linux kernel mach directory: @@ -78,14 +78,15 @@ Discovery family Flavors: - MV78100 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616194711/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120451/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV78200 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20140801121623/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120458/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV76100 Not supported by the Linux kernel. @@ -106,9 +107,9 @@ EBU Armada family - 88F6707 - 88F6W11 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf - - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf + - Product Brief: https://web.archive.org/web/20121115063038/http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf + - Hardware Spec: https://web.archive.org/web/20140617183747/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf + - Functional Spec: https://web.archive.org/web/20140617183701/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf Core: Sheeva ARMv7 compatible PJ4B @@ -116,7 +117,7 @@ EBU Armada family Armada 375 Flavors: - 88F6720 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf + - Product Brief: https://web.archive.org/web/20131216023516/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf Core: ARM Cortex-A9 @@ -126,8 +127,8 @@ EBU Armada family - 88F6820 Armada 385 - 88F6828 Armada 388 - - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ - - Functional Spec: http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf + - Product infos: https://web.archive.org/web/20181006144616/http://www.marvell.com/embedded-processors/armada-38x/ + - Functional Spec: https://web.archive.org/web/20200420191927/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf Core: ARM Cortex-A9 @@ -136,7 +137,7 @@ EBU Armada family - 88F6920 Armada 390 - 88F6928 Armada 398 - - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ + - Product infos: https://web.archive.org/web/20181020222559/http://www.marvell.com/embedded-processors/armada-39x/ Core: ARM Cortex-A9 @@ -150,16 +151,16 @@ EBU Armada family not to be confused with the non-SMP 78xx0 SoCs Product Brief: - http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + https://web.archive.org/web/20121021173528/http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf Functional Spec: - http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + https://web.archive.org/web/20180829171131/http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf - Hardware Specs: - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF + - https://web.archive.org/web/20141127013651/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + - https://web.archive.org/web/20141222000224/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + - https://web.archive.org/web/20141222000230/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP @@ -180,13 +181,13 @@ EBU Armada family ARMv8 ARM Cortex A53 (ARMv8) Homepage: - http://www.marvell.com/embedded-processors/armada-3700/ + https://web.archive.org/web/20181103003602/http://www.marvell.com/embedded-processors/armada-3700/ Product Brief: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf + https://web.archive.org/web/20210121194810/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf Hardware Spec: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf + https://web.archive.org/web/20210202162011/http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-37* @@ -198,11 +199,11 @@ EBU Armada family ARMv8 Core: ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-70xx/ + https://web.archive.org/web/20181020222606/http://www.marvell.com/embedded-processors/armada-70xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf + - https://web.archive.org/web/20161010105541/http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf + - https://web.archive.org/web/20160928154533/http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-70* @@ -214,11 +215,11 @@ EBU Armada family ARMv8 ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-80xx/ + https://web.archive.org/web/20181022004830/http://www.marvell.com/embedded-processors/armada-80xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf + - https://web.archive.org/web/20210124233728/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-8020-product-brief-2017-12.pdf + - https://web.archive.org/web/20161010105532/http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-80* @@ -233,10 +234,10 @@ Avanta family - 88F6560 Homepage: - http://www.marvell.com/broadband/ + https://web.archive.org/web/20181005145041/http://www.marvell.com/broadband/ Product Brief: - http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + https://web.archive.org/web/20180829171057/http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf No public datasheet available. @@ -255,7 +256,7 @@ Storage family - 88RC1580 Product infos: - http://www.marvell.com/storage/armada-sp/ + https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/ Core: Sheeva ARMv7 comatible Quad-core PJ4C @@ -269,16 +270,16 @@ Dove family (application processor) - 88AP510 a.k.a Armada 510 Product Brief: - http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + https://web.archive.org/web/20111102020643/http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf Hardware Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + https://web.archive.org/web/20160428160231/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf Functional Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + https://web.archive.org/web/20120130172443/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf Homepage: - http://www.marvell.com/application-processors/armada-500/ + https://web.archive.org/web/20160822232651/http://www.marvell.com/application-processors/armada-500/ Core: ARMv7 compatible @@ -295,22 +296,22 @@ PXA 2xx/3xx/93x/95x family - Application processor only - Core: ARMv5 XScale1 core - PXA270, PXA271, PXA272 - - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf - - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf - - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + - Product Brief : https://web.archive.org/web/20150927135510/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + - Design guide : https://web.archive.org/web/20120111181937/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + - Developers manual : https://web.archive.org/web/20150927164805/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + - Specification : https://web.archive.org/web/20140211221535/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + - Specification update : https://web.archive.org/web/20120111104906/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf - Application processor only - Core: ARMv5 XScale2 core - PXA300, PXA310, PXA320 - - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf - - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf - - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip - - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf - - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip - - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + - PXA 300 Product Brief : https://web.archive.org/web/20120111121203/http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + - PXA 310 Product Brief : https://web.archive.org/web/20120111104515/http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + - PXA 320 Product Brief : https://web.archive.org/web/20121021182826/http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + - Design guide : https://web.archive.org/web/20130727144625/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + - Developers manual : https://web.archive.org/web/20130727144605/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + - Specifications : https://web.archive.org/web/20130727144559/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + - Specification Update : https://web.archive.org/web/20150927183411/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + - Reference Manual : https://web.archive.org/web/20120111103844/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf - Application processor only - Core: ARMv5 XScale3 core - PXA930, PXA935 @@ -341,26 +342,26 @@ MMP/MMP2/MMP3 family (communication processor) Flavors: - PXA168, a.k.a Armada 168 - - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp - - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf - - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf - - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf - - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf - - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf - - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + - Homepage : https://web.archive.org/web/20110926014256/http://www.marvell.com/application-processors/armada-100/armada-168.jsp + - Product brief : https://web.archive.org/web/20111102030100/http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + - Hardware manual : https://web.archive.org/web/20160428165359/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + - Software manual : https://web.archive.org/web/20160428154454/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + - Specification update : https://web.archive.org/web/20150927160338/http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + - Boot ROM manual : https://web.archive.org/web/20130727205559/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + - App node package : https://web.archive.org/web/20141005090706/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf - Application processor only - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA910/PXA920 - - Homepage : http://www.marvell.com/communication-processors/pxa910/ - - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + - Homepage : https://web.archive.org/web/20150928121236/http://www.marvell.com/communication-processors/pxa910/ + - Product Brief : https://archive.org/download/marvell-pxa910-pb/Marvell_PXA910_Platform-001_PB.pdf - Application processor with Communication processor - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - - PXA688, a.k.a. MMP2, a.k.a Armada 610 - - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + - PXA688, a.k.a. MMP2, a.k.a Armada 610 (OLPC XO-1.75) + - Product Brief : https://web.archive.org/web/20111102023255/http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf - Application processor only - Core: ARMv7 compatible Sheeva PJ4 88sv581x core - - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) - - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf + - PXA2128, a.k.a. MMP3, a.k.a Armada 620 (OLPC XO-4) + - Product Brief : https://web.archive.org/web/20120824055155/http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf - Application processor only - Core: Dual-core ARMv7 compatible Sheeva PJ4C core - PXA960/PXA968/PXA978 (Linux support not upstream) diff --git a/Documentation/arm/stm32/stm32h750-overview.rst b/Documentation/arm/stm32/stm32h750-overview.rst new file mode 100644 index 000000000000..0e51235c9547 --- /dev/null +++ b/Documentation/arm/stm32/stm32h750-overview.rst @@ -0,0 +1,34 @@ +================== +STM32H750 Overview +================== + +Introduction +------------ + +The STM32H750 is a Cortex-M7 MCU aimed at various applications. +It features: + +- Cortex-M7 core running up to @480MHz +- 128K internal flash, 1MBytes internal RAM +- FMC controller to connect SDRAM, NOR and NAND memories +- Dual mode QSPI +- SD/MMC/SDIO support +- Ethernet controller +- USB OTFG FS & HS controllers +- I2C, SPI, CAN busses support +- Several 16 & 32 bits general purpose timers +- Serial Audio interface +- LCD controller +- HDMI-CEC +- SPDIFRX +- DFSDM + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32H750_). + +.. _STM32H750: https://www.st.com/en/microcontrollers-microprocessors/stm32h750-value-line.html + +:Authors: Dillon Min <dillon.minfei@gmail.com> + diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst index f732f957421f..9b0b5e458a1e 100644 --- a/Documentation/arm/uefi.rst +++ b/Documentation/arm/uefi.rst @@ -64,4 +64,11 @@ linux,uefi-mmap-desc-size 32-bit Size in bytes of each entry in the UEFI memory map. linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. + +linux,initrd-start 64-bit Physical start address of an initrd + +linux,initrd-end 64-bit Physical end address of an initrd + +kaslr-seed 64-bit Entropy used to randomize the kernel image + base address location. ========================== ====== =========================================== diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index 7552dbc1cc54..18b8cc1bf32c 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -202,9 +202,10 @@ Before jumping into the kernel, the following conditions must be met: - System registers - All writable architected system registers at the exception level where - the kernel image will be entered must be initialised by software at a - higher exception level to prevent execution in an UNKNOWN state. + All writable architected system registers at or below the exception + level where the kernel image will be entered must be initialised by + software at a higher exception level to prevent execution in an UNKNOWN + state. - SCR_EL3.FIQ must have the same value across all CPUs the kernel is executing on. @@ -270,9 +271,46 @@ Before jumping into the kernel, the following conditions must be met: having 0b1 set for the corresponding bit for each of the auxiliary counters present. + For CPUs with the Fine Grained Traps (FEAT_FGT) extension present: + + - If EL3 is present and the kernel is entered at EL2: + + - SCR_EL3.FGTEn (bit 27) must be initialised to 0b1. + + For CPUs with Advanced SIMD and floating point support: + + - If EL3 is present: + + - CPTR_EL3.TFP (bit 10) must be initialised to 0b0. + + - If EL2 is present and the kernel is entered at EL1: + + - CPTR_EL2.TFP (bit 10) must be initialised to 0b0. + + For CPUs with the Scalable Vector Extension (FEAT_SVE) present: + + - if EL3 is present: + + - CPTR_EL3.EZ (bit 8) must be initialised to 0b1. + + - ZCR_EL3.LEN must be initialised to the same value for all CPUs the + kernel is executed on. + + - If the kernel is entered at EL1 and EL2 is present: + + - CPTR_EL2.TZ (bit 8) must be initialised to 0b0. + + - CPTR_EL2.ZEN (bits 17:16) must be initialised to 0b11. + + - ZCR_EL2.LEN must be initialised to the same value for all CPUs the + kernel will execute on. + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must -enter the kernel in the same exception level. +enter the kernel in the same exception level. Where the values documented +disable traps it is permissible for these traps to be enabled so long as +those traps are handled transparently by higher exception levels as though +the values documented were set. The boot loader is expected to enter the kernel on each CPU in the following manner: diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index 87821662eeb2..ec1a5a63c1d0 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -74,7 +74,7 @@ HWCAP_ASIMD HWCAP_EVTSTRM The generic timer is configured to generate events at a frequency of - approximately 100KHz. + approximately 10KHz. HWCAP_AES Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001. diff --git a/Documentation/arm64/pointer-authentication.rst b/Documentation/arm64/pointer-authentication.rst index 30b2ab06526b..f127666ea3a8 100644 --- a/Documentation/arm64/pointer-authentication.rst +++ b/Documentation/arm64/pointer-authentication.rst @@ -107,3 +107,37 @@ filter out the Pointer Authentication system key registers from KVM_GET/SET_REG_* ioctls and mask those features from cpufeature ID register. Any attempt to use the Pointer Authentication instructions will result in an UNDEFINED exception being injected into the guest. + + +Enabling and disabling keys +--------------------------- + +The prctl PR_PAC_SET_ENABLED_KEYS allows the user program to control which +PAC keys are enabled in a particular task. It takes two arguments, the +first being a bitmask of PR_PAC_APIAKEY, PR_PAC_APIBKEY, PR_PAC_APDAKEY +and PR_PAC_APDBKEY specifying which keys shall be affected by this prctl, +and the second being a bitmask of the same bits specifying whether the key +should be enabled or disabled. For example:: + + prctl(PR_PAC_SET_ENABLED_KEYS, + PR_PAC_APIAKEY | PR_PAC_APIBKEY | PR_PAC_APDAKEY | PR_PAC_APDBKEY, + PR_PAC_APIBKEY, 0, 0); + +disables all keys except the IB key. + +The main reason why this is useful is to enable a userspace ABI that uses PAC +instructions to sign and authenticate function pointers and other pointers +exposed outside of the function, while still allowing binaries conforming to +the ABI to interoperate with legacy binaries that do not sign or authenticate +pointers. + +The idea is that a dynamic loader or early startup code would issue this +prctl very early after establishing that a process may load legacy binaries, +but before executing any PAC instructions. + +For compatibility with previous kernel versions, processes start up with IA, +IB, DA and DB enabled, and are reset to this state on exec(). Processes created +via fork() and clone() inherit the key enabled state from the calling process. + +It is recommended to avoid disabling the IA key, as this has higher performance +overhead than disabling any of the other keys. diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst index 4a9d9c794ee5..459e6b66ff68 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arm64/tagged-address-abi.rst @@ -40,7 +40,7 @@ space obtained in one of the following ways: during creation and with the same restrictions as for ``mmap()`` above (e.g. data, bss, stack). -The AArch64 Tagged Address ABI has two stages of relaxation depending +The AArch64 Tagged Address ABI has two stages of relaxation depending on how the user addresses are used by the kernel: 1. User addresses not accessed by the kernel but used for address space @@ -113,6 +113,12 @@ ABI relaxation: - ``shmat()`` and ``shmdt()``. +- ``brk()`` (since kernel v5.6). + +- ``mmap()`` (since kernel v5.6). + +- ``mremap()``, the ``new_address`` argument (since kernel v5.6). + Any attempt to use non-zero tagged pointers may result in an error code being returned, a (fatal) signal being raised, or other modes of failure. diff --git a/Documentation/block/data-integrity.rst b/Documentation/block/data-integrity.rst index 4f2452a95c43..07a97aa26668 100644 --- a/Documentation/block/data-integrity.rst +++ b/Documentation/block/data-integrity.rst @@ -1,4 +1,4 @@ -============== +============== Data Integrity ============== diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 0e15f9b05c9d..437de2a7a5de 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -258,3 +258,18 @@ Q: Can BPF functionality such as new program or map types, new helpers, etc be added out of kernel module code? A: NO. + +Q: Directly calling kernel function is an ABI? +---------------------------------------------- +Q: Some kernel functions (e.g. tcp_slow_start) can be called +by BPF programs. Do these kernel functions become an ABI? + +A: NO. + +The kernel function protos will change and the bpf programs will be +rejected by the verifier. Also, for example, some of the bpf-callable +kernel functions have already been used by other kernel tcp +cc (congestion-control) implementations. If any of these kernel +functions has changed, both the in-tree and out-of-tree kernel tcp cc +implementations have to be changed. The same goes for the bpf +programs and they have to be adjusted accordingly. diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 2ed89abbf9a4..253496af8fef 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -29,7 +29,7 @@ list: This may also include issues related to XDP, BPF tracing, etc. Given netdev has a high volume of traffic, please also add the BPF -maintainers to Cc (from kernel MAINTAINERS_ file): +maintainers to Cc (from kernel ``MAINTAINERS`` file): * Alexei Starovoitov <ast@kernel.org> * Daniel Borkmann <daniel@iogearbox.net> @@ -234,11 +234,11 @@ be subject to change. Q: samples/bpf preference vs selftests? --------------------------------------- -Q: When should I add code to `samples/bpf/`_ and when to BPF kernel -selftests_ ? +Q: When should I add code to ``samples/bpf/`` and when to BPF kernel +selftests_? A: In general, we prefer additions to BPF kernel selftests_ rather than -`samples/bpf/`_. The rationale is very simple: kernel selftests are +``samples/bpf/``. The rationale is very simple: kernel selftests are regularly run by various bots to test for kernel regressions. The more test cases we add to BPF selftests, the better the coverage @@ -246,9 +246,9 @@ and the less likely it is that those could accidentally break. It is not that BPF kernel selftests cannot demo how a specific feature can be used. -That said, `samples/bpf/`_ may be a good place for people to get started, +That said, ``samples/bpf/`` may be a good place for people to get started, so it might be advisable that simple demos of features could go into -`samples/bpf/`_, but advanced functional and corner-case testing rather +``samples/bpf/``, but advanced functional and corner-case testing rather into kernel selftests. If your sample looks like a test case, then go for BPF kernel selftests @@ -449,6 +449,19 @@ from source at https://github.com/acmel/dwarves +pahole starts to use libbpf definitions and APIs since v1.13 after the +commit 21507cd3e97b ("pahole: add libbpf as submodule under lib/bpf"). +It works well with the git repository because the libbpf submodule will +use "git submodule update --init --recursive" to update. + +Unfortunately, the default github release source code does not contain +libbpf submodule source code and this will cause build issues, the tarball +from https://git.kernel.org/pub/scm/devel/pahole/pahole.git/ is same with +github, you can get the source tarball with corresponding libbpf submodule +codes from + +https://fedorapeople.org/~acme/dwarves + Some distros have pahole version 1.16 packaged already, e.g. Fedora, Gentoo. @@ -645,10 +658,9 @@ when: .. Links .. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/ -.. _MAINTAINERS: ../../MAINTAINERS .. _netdev-FAQ: ../networking/netdev-FAQ.rst -.. _samples/bpf/: ../../samples/bpf/ -.. _selftests: ../../tools/testing/selftests/bpf/ +.. _selftests: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/ .. _Documentation/dev-tools/kselftest.rst: https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html .. _Documentation/bpf/btf.rst: btf.rst diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 44dc789de2b4..846354cd2d69 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -84,6 +84,7 @@ sequentially and type id is assigned to each recognized type starting from id #define BTF_KIND_FUNC_PROTO 13 /* Function Proto */ #define BTF_KIND_VAR 14 /* Variable */ #define BTF_KIND_DATASEC 15 /* Section */ + #define BTF_KIND_FLOAT 16 /* Floating point */ Note that the type section encodes debug info, not just pure types. ``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. @@ -95,8 +96,8 @@ Each type contains the following common data:: /* "info" bits arrangement * bits 0-15: vlen (e.g. # of struct's members) * bits 16-23: unused - * bits 24-27: kind (e.g. int, ptr, array...etc) - * bits 28-30: unused + * bits 24-28: kind (e.g. int, ptr, array...etc) + * bits 29-30: unused * bit 31: kind_flag, currently used by * struct, union and fwd */ @@ -452,6 +453,18 @@ map definition. * ``offset``: the in-section offset of the variable * ``size``: the size of the variable in bytes +2.2.16 BTF_KIND_FLOAT +~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: any valid offset + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_FLOAT + * ``info.vlen``: 0 + * ``size``: the size of the float type in bytes: 2, 4, 8, 12 or 16. + +No additional type data follow ``btf_type``. + 3. BTF Kernel API ***************** diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 4f2874b729c3..a702f67dd45f 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -12,9 +12,6 @@ BPF instruction-set. The Cilium project also maintains a `BPF and XDP Reference Guide`_ that goes into great technical depth about the BPF Architecture. -The primary info for the bpf syscall is available in the `man-pages`_ -for `bpf(2)`_. - BPF Type Format (BTF) ===================== @@ -35,6 +32,12 @@ Two sets of Questions and Answers (Q&A) are maintained. bpf_design_QA bpf_devel_QA +Syscall API +=========== + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. For more information about the userspace API, see +Documentation/userspace-api/ebpf/index.rst. Helper functions ================ diff --git a/Documentation/cdrom/cdrom-standard.rst b/Documentation/cdrom/cdrom-standard.rst index 70500b189cc8..5845960ca382 100644 --- a/Documentation/cdrom/cdrom-standard.rst +++ b/Documentation/cdrom/cdrom-standard.rst @@ -146,18 +146,18 @@ with the kernel as a block device by registering the following general *struct file_operations*:: struct file_operations cdrom_fops = { - NULL, /∗ lseek ∗/ - block _read , /∗ read—general block-dev read ∗/ - block _write, /∗ write—general block-dev write ∗/ - NULL, /∗ readdir ∗/ - NULL, /∗ select ∗/ - cdrom_ioctl, /∗ ioctl ∗/ - NULL, /∗ mmap ∗/ - cdrom_open, /∗ open ∗/ - cdrom_release, /∗ release ∗/ - NULL, /∗ fsync ∗/ - NULL, /∗ fasync ∗/ - NULL /∗ revalidate ∗/ + NULL, /* lseek */ + block _read , /* read--general block-dev read */ + block _write, /* write--general block-dev write */ + NULL, /* readdir */ + NULL, /* select */ + cdrom_ioctl, /* ioctl */ + NULL, /* mmap */ + cdrom_open, /* open */ + cdrom_release, /* release */ + NULL, /* fsync */ + NULL, /* fasync */ + NULL /* revalidate */ }; Every active CD-ROM device shares this *struct*. The routines @@ -250,12 +250,12 @@ The drive-specific, minor-like information that is registered with `cdrom.c`, currently contains the following fields:: struct cdrom_device_info { - const struct cdrom_device_ops * ops; /* device operations for this major */ + const struct cdrom_device_ops * ops; /* device operations for this major */ struct list_head list; /* linked list of all device_info */ struct gendisk * disk; /* matching block layer disk */ void * handle; /* driver-dependent data */ - int mask; /* mask of capability: disables them */ + int mask; /* mask of capability: disables them */ int speed; /* maximum speed for reading data */ int capacity; /* number of discs in a jukebox */ @@ -569,7 +569,7 @@ the *CDC_CLOSE_TRAY* bit in *mask*. In the file `cdrom.c` you will encounter many constructions of the type:: - if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ... + if (cdo->capability & ~cdi->mask & CDC _<capability>) ... There is no *ioctl* to set the mask... The reason is that I think it is better to control the **behavior** rather than the diff --git a/Documentation/conf.py b/Documentation/conf.py index fd65168c10f8..879e86dbea66 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -331,27 +331,34 @@ htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -'papersize': 'a4paper', + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', -# The font size ('10pt', '11pt' or '12pt'). -'pointsize': '11pt', + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '11pt', -# Latex figure (float) alignment -#'figure_align': 'htbp', + # Latex figure (float) alignment + #'figure_align': 'htbp', -# Don't mangle with UTF-8 chars -'inputenc': '', -'utf8extra': '', + # Don't mangle with UTF-8 chars + 'inputenc': '', + 'utf8extra': '', -# Additional stuff for the LaTeX preamble. + # Set document margins + 'sphinxsetup': ''' + hmargin=0.5in, vmargin=1in, + parsedliteralwraps=true, + verbatimhintsturnover=false, + ''', + + # Additional stuff for the LaTeX preamble. 'preamble': ''' - % Use some font with UTF-8 support with XeLaTeX + % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} \\setsansfont{DejaVu Sans} \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - ''' + ''', } # At least one book (translations) may have Asian characters diff --git a/Documentation/core-api/cachetlb.rst b/Documentation/core-api/cachetlb.rst index a1582cc79f0f..fe4290e26729 100644 --- a/Documentation/core-api/cachetlb.rst +++ b/Documentation/core-api/cachetlb.rst @@ -213,9 +213,9 @@ Here are the routines, one by one: there will be no entries in the cache for the kernel address space for virtual addresses in the range 'start' to 'end-1'. - The first of these two routines is invoked after map_kernel_range() + The first of these two routines is invoked after vmap_range() has installed the page table entries. The second is invoked - before unmap_kernel_range() deletes the page table entries. + before vunmap_range() deletes the page table entries. There exists another whole class of cpu cache issues which currently require a whole different set of interfaces to handle properly. diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index e6d23f117308..00a1d4fa3f9e 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -565,6 +565,16 @@ dma_alloc_pages(). page must be the pointer returned by dma_alloc_pages(). :: + int + dma_mmap_pages(struct device *dev, struct vm_area_struct *vma, + size_t size, struct page *page) + +Map an allocation returned from dma_alloc_pages() into a user address space. +dev and size must be the same as those passed into dma_alloc_pages(). +page must be the pointer returned by dma_alloc_pages(). + +:: + void * dma_alloc_noncoherent(struct device *dev, size_t size, dma_addr_t *dma_handle, enum dma_data_direction dir, @@ -586,6 +596,84 @@ dma_alloc_noncoherent(). :: + struct sg_table * + dma_alloc_noncontiguous(struct device *dev, size_t size, + enum dma_data_direction dir, gfp_t gfp, + unsigned long attrs); + +This routine allocates <size> bytes of non-coherent and possibly non-contiguous +memory. It returns a pointer to struct sg_table that describes the allocated +and DMA mapped memory, or NULL if the allocation failed. The resulting memory +can be used for struct page mapped into a scatterlist are suitable for. + +The return sg_table is guaranteed to have 1 single DMA mapped segment as +indicated by sgt->nents, but it might have multiple CPU side segments as +indicated by sgt->orig_nents. + +The dir parameter specified if data is read and/or written by the device, +see dma_map_single() for details. + +The gfp parameter allows the caller to specify the ``GFP_`` flags (see +kmalloc()) for the allocation, but rejects flags used to specify a memory +zone such as GFP_DMA or GFP_HIGHMEM. + +The attrs argument must be either 0 or DMA_ATTR_ALLOC_SINGLE_PAGES. + +Before giving the memory to the device, dma_sync_sgtable_for_device() needs +to be called, and before reading memory written by the device, +dma_sync_sgtable_for_cpu(), just like for streaming DMA mappings that are +reused. + +:: + + void + dma_free_noncontiguous(struct device *dev, size_t size, + struct sg_table *sgt, + enum dma_data_direction dir) + +Free memory previously allocated using dma_alloc_noncontiguous(). dev, size, +and dir must all be the same as those passed into dma_alloc_noncontiguous(). +sgt must be the pointer returned by dma_alloc_noncontiguous(). + +:: + + void * + dma_vmap_noncontiguous(struct device *dev, size_t size, + struct sg_table *sgt) + +Return a contiguous kernel mapping for an allocation returned from +dma_alloc_noncontiguous(). dev and size must be the same as those passed into +dma_alloc_noncontiguous(). sgt must be the pointer returned by +dma_alloc_noncontiguous(). + +Once a non-contiguous allocation is mapped using this function, the +flush_kernel_vmap_range() and invalidate_kernel_vmap_range() APIs must be used +to manage the coherency between the kernel mapping, the device and user space +mappings (if any). + +:: + + void + dma_vunmap_noncontiguous(struct device *dev, void *vaddr) + +Unmap a kernel mapping returned by dma_vmap_noncontiguous(). dev must be the +same the one passed into dma_alloc_noncontiguous(). vaddr must be the pointer +returned by dma_vmap_noncontiguous(). + + +:: + + int + dma_mmap_noncontiguous(struct device *dev, struct vm_area_struct *vma, + size_t size, struct sg_table *sgt) + +Map an allocation returned from dma_alloc_noncontiguous() into a user address +space. dev and size must be the same as those passed into +dma_alloc_noncontiguous(). sgt must be the pointer returned by +dma_alloc_noncontiguous(). + +:: + int dma_get_cache_alignment(void) diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index a77c24c27f7b..8214e215a8bf 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -42,10 +42,10 @@ irq_domain usage ================ An interrupt controller driver creates and registers an irq_domain by -calling one of the irq_domain_add_*() functions (each mapping method -has a different allocator function, more on that later). The function -will return a pointer to the irq_domain on success. The caller must -provide the allocator function with an irq_domain_ops structure. +calling one of the irq_domain_add_*() or irq_domain_create_*() functions +(each mapping method has a different allocator function, more on that later). +The function will return a pointer to the irq_domain on success. The caller +must provide the allocator function with an irq_domain_ops structure. In most cases, the irq_domain will begin empty without any mappings between hwirq and IRQ numbers. Mappings are added to the irq_domain @@ -147,6 +147,7 @@ Legacy irq_domain_add_simple() irq_domain_add_legacy() irq_domain_add_legacy_isa() + irq_domain_create_simple() irq_domain_create_legacy() The Legacy mapping is a special case for drivers that already have a @@ -169,13 +170,13 @@ supported. For example, ISA controllers would use the legacy map for mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ numbers. -Most users of legacy mappings should use irq_domain_add_simple() which -will use a legacy domain only if an IRQ range is supplied by the -system and will otherwise use a linear domain mapping. The semantics -of this call are such that if an IRQ range is specified then +Most users of legacy mappings should use irq_domain_add_simple() or +irq_domain_create_simple() which will use a legacy domain only if an IRQ range +is supplied by the system and will otherwise use a linear domain mapping. +The semantics of this call are such that if an IRQ range is specified then descriptors will be allocated on-the-fly for it, and if no range is -specified it will fall through to irq_domain_add_linear() which means -*no* irq descriptors will be allocated. +specified it will fall through to irq_domain_add_linear() or +irq_domain_create_linear() which means *no* irq descriptors will be allocated. A typical use case for simple domains is where an irqchip provider is supporting both dynamic and static IRQ assignments. @@ -186,6 +187,7 @@ that the driver using the simple domain call irq_create_mapping() before any irq_find_mapping() since the latter will actually work for the static IRQ assignment case. +irq_domain_add_simple() and irq_domain_create_simple() as well as irq_domain_add_legacy() and irq_domain_create_legacy() are functionally equivalent, except for the first argument is different - the former accepts an Open Firmware specific 'struct device_node', while the latter diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 201b5423303b..a42f9baddfbf 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -92,3 +92,9 @@ More Memory Management Functions :export: .. kernel-doc:: mm/page_alloc.c +.. kernel-doc:: mm/mempolicy.c +.. kernel-doc:: include/linux/mm_types.h + :internal: +.. kernel-doc:: include/linux/mm.h + :internal: +.. kernel-doc:: include/linux/mmzone.h diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 160e710d992f..f063a384c7c8 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -79,7 +79,19 @@ Pointers printed without a specifier extension (i.e unadorned %p) are hashed to prevent leaking information about the kernel memory layout. This has the added benefit of providing a unique identifier. On 64-bit machines the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it -gathers enough entropy. If you *really* want the address see %px below. +gathers enough entropy. + +When possible, use specialised modifiers such as %pS or %pB (described below) +to avoid the need of providing an unhashed address that has to be interpreted +post-hoc. If not possible, and the aim of printing the address is to provide +more information for debugging, use %p and boot the kernel with the +``no_hash_pointers`` parameter during debugging, which will print all %p +addresses unmodified. If you *really* always want the unmodified address, see +%px below. + +If (and only if) you are printing addresses as a content of a virtual file in +e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a +userspace process, use the %pK modifier described below instead of %p or %px. Error Pointers -------------- @@ -139,6 +151,11 @@ For printing kernel pointers which should be hidden from unprivileged users. The behaviour of %pK depends on the kptr_restrict sysctl - see Documentation/admin-guide/sysctl/kernel.rst for more details. +This modifier is *only* intended when producing content of a file read by +userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the +section about %p above for discussion about how to manage hashing pointers +in printk(). + Unmodified Addresses -------------------- @@ -153,6 +170,13 @@ equivalent to %lx (or %lu). %px is preferred because it is more uniquely grep'able. If in the future we need to modify the way the kernel handles printing pointers we will be better equipped to find the call sites. +Before using %px, consider if using %p is sufficient together with enabling the +``no_hash_pointers`` kernel parameter during debugging sessions (see the %p +description above). One valid scenario for %px might be printing information +immediately before a panic, which prevents any sensitive information to be +exploited anyway, and with %px there would be no need to reproduce the panic +with no_hash_pointers. + Pointer Differences ------------------- @@ -540,7 +564,7 @@ Flags bitfields such as page flags, gfp_flags :: - %pGp referenced|uptodate|lru|active|private + %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff %pGg GFP_USER|GFP_DMA32|GFP_NOWARN %pGv read|exec|mayread|maywrite|mayexec|denywrite @@ -567,6 +591,24 @@ For printing netdev_features_t. Passed by reference. +V4L2 and DRM FourCC code (pixel format) +--------------------------------------- + +:: + + %p4cc + +Print a FourCC code used by V4L2 or DRM, including format endianness and +its numerical value as hexadecimal. + +Passed by reference. + +Examples:: + + %p4cc BG12 little-endian (0x32314742) + %p4cc Y10 little-endian (0x20303159) + %p4cc NV12 big-endian (0xb231564e) + Thanks ====== diff --git a/Documentation/core-api/rbtree.rst b/Documentation/core-api/rbtree.rst index 6b88837fbf82..ed1a9fbc779e 100644 --- a/Documentation/core-api/rbtree.rst +++ b/Documentation/core-api/rbtree.rst @@ -201,7 +201,7 @@ search trees, such as for traversals or users relying on a the particular order for their own logic. To this end, users can use 'struct rb_root_cached' to optimize O(logN) rb_first() calls to a simple pointer fetch avoiding potentially expensive tree iterations. This is done at negligible runtime -overhead for maintanence; albeit larger memory footprint. +overhead for maintenance; albeit larger memory footprint. Similar to the rb_root structure, cached rbtrees are initialized to be empty via:: diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst index 9b76337f6756..5ad9e0abe42c 100644 --- a/Documentation/core-api/symbol-namespaces.rst +++ b/Documentation/core-api/symbol-namespaces.rst @@ -43,14 +43,14 @@ exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace. Please note that due to macro expansion that argument needs to be a -preprocessor symbol. E.g. to export the symbol `usb_stor_suspend` into the -namespace `USB_STORAGE`, use:: +preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the +namespace ``USB_STORAGE``, use:: EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); -The corresponding ksymtab entry struct `kernel_symbol` will have the member -`namespace` set accordingly. A symbol that is exported without a namespace will -refer to `NULL`. There is no default namespace if none is defined. `modpost` +The corresponding ksymtab entry struct ``kernel_symbol`` will have the member +``namespace`` set accordingly. A symbol that is exported without a namespace will +refer to ``NULL``. There is no default namespace if none is defined. ``modpost`` and kernel/module.c make use the namespace at build time or module load time, respectively. @@ -64,7 +64,7 @@ and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace. There are multiple ways of specifying this define and it depends on the subsystem and the maintainer's preference, which one to use. The first option -is to define the default namespace in the `Makefile` of the subsystem. E.g. to +is to define the default namespace in the ``Makefile`` of the subsystem. E.g. to export all symbols defined in usb-common into the namespace USB_COMMON, add a line like this to drivers/usb/common/Makefile:: @@ -96,7 +96,7 @@ using a statement like:: MODULE_IMPORT_NS(USB_STORAGE); -This will create a `modinfo` tag in the module for each imported namespace. +This will create a ``modinfo`` tag in the module for each imported namespace. This has the side effect, that the imported namespaces of a module can be inspected with modinfo:: @@ -113,7 +113,7 @@ metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section 4. Loading Modules that use namespaced Symbols ============================================== -At module loading time (e.g. `insmod`), the kernel will check each symbol +At module loading time (e.g. ``insmod``), the kernel will check each symbol referenced from the module for its availability and whether the namespace it might be exported to has been imported by the module. The default behaviour of the kernel is to reject loading modules that don't specify sufficient imports. @@ -138,19 +138,19 @@ missing imports. Fixing missing imports can be done with:: A typical scenario for module authors would be:: - write code that depends on a symbol from a not imported namespace - - `make` + - ``make`` - notice the warning of modpost telling about a missing import - - run `make nsdeps` to add the import to the correct code location + - run ``make nsdeps`` to add the import to the correct code location For subsystem maintainers introducing a namespace, the steps are very similar. -Again, `make nsdeps` will eventually add the missing namespace imports for +Again, ``make nsdeps`` will eventually add the missing namespace imports for in-tree modules:: - move or add symbols to a namespace (e.g. with EXPORT_SYMBOL_NS()) - - `make` (preferably with an allmodconfig to cover all in-kernel + - ``make`` (preferably with an allmodconfig to cover all in-kernel modules) - notice the warning of modpost telling about a missing import - - run `make nsdeps` to add the import to the correct code location + - run ``make nsdeps`` to add the import to the correct code location You can also run nsdeps for external module builds. A typical usage is:: diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst new file mode 100644 index 000000000000..51fed1bd72ec --- /dev/null +++ b/Documentation/dev-tools/checkpatch.rst @@ -0,0 +1,755 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========== +Checkpatch +========== + +Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial +style violations in patches and optionally corrects them. Checkpatch can +also be run on file contexts and without the kernel tree. + +Checkpatch is not always right. Your judgement takes precedence over checkpatch +messages. If your code looks better with the violations, then its probably +best left alone. + + +Options +======= + +This section will describe the options checkpatch can be run with. + +Usage:: + + ./scripts/checkpatch.pl [OPTION]... [FILE]... + +Available options: + + - -q, --quiet + + Enable quiet mode. + + - -v, --verbose + Enable verbose mode. Additional verbose test descriptions are output + so as to provide information on why that particular message is shown. + + - --no-tree + + Run checkpatch without the kernel tree. + + - --no-signoff + + Disable the 'Signed-off-by' line check. The sign-off is a simple line at + the end of the explanation for the patch, which certifies that you wrote it + or otherwise have the right to pass it on as an open-source patch. + + Example:: + + Signed-off-by: Random J Developer <random@developer.example.org> + + Setting this flag effectively stops a message for a missing signed-off-by + line in a patch context. + + - --patch + + Treat FILE as a patch. This is the default option and need not be + explicitly specified. + + - --emacs + + Set output to emacs compile window format. This allows emacs users to jump + from the error in the compile window directly to the offending line in the + patch. + + - --terse + + Output only one line per report. + + - --showfile + + Show the diffed file position instead of the input file position. + + - -g, --git + + Treat FILE as a single commit or a git revision range. + + Single commit with: + + - <rev> + - <rev>^ + - <rev>~n + + Multiple commits with: + + - <rev1>..<rev2> + - <rev1>...<rev2> + - <rev>-<count> + + - -f, --file + + Treat FILE as a regular source file. This option must be used when running + checkpatch on source files in the kernel. + + - --subjective, --strict + + Enable stricter tests in checkpatch. By default the tests emitted as CHECK + do not activate by default. Use this flag to activate the CHECK tests. + + - --list-types + + Every message emitted by checkpatch has an associated TYPE. Add this flag + to display all the types in checkpatch. + + Note that when this flag is active, checkpatch does not read the input FILE, + and no message is emitted. Only a list of types in checkpatch is output. + + - --types TYPE(,TYPE2...) + + Only display messages with the given types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES + + - --ignore TYPE(,TYPE2...) + + Checkpatch will not emit messages for the specified types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES + + - --show-types + + By default checkpatch doesn't display the type associated with the messages. + Set this flag to show the message type in the output. + + - --max-line-length=n + + Set the max line length (default 100). If a line exceeds the specified + length, a LONG_LINE message is emitted. + + + The message level is different for patch and file contexts. For patches, + a WARNING is emitted. While a milder CHECK is emitted for files. So for + file contexts, the --strict flag must also be enabled. + + - --min-conf-desc-length=n + + Set the Kconfig entry minimum description length, if shorter, warn. + + - --tab-size=n + + Set the number of spaces for tab (default 8). + + - --root=PATH + + PATH to the kernel tree root. + + This option must be specified when invoking checkpatch from outside + the kernel root. + + - --no-summary + + Suppress the per file summary. + + - --mailback + + Only produce a report in case of Warnings or Errors. Milder Checks are + excluded from this. + + - --summary-file + + Include the filename in summary. + + - --debug KEY=[0|1] + + Turn on/off debugging of KEY, where KEY is one of 'values', 'possible', + 'type', and 'attr' (default is all off). + + - --fix + + This is an EXPERIMENTAL feature. If correctable errors exists, a file + <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the + automatically fixable errors corrected. + + - --fix-inplace + + EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes. + + DO NOT USE this flag unless you are absolutely sure and you have a backup + in place. + + - --ignore-perl-version + + Override checking of perl version. Runtime errors maybe encountered after + enabling this flag if the perl version does not meet the minimum specified. + + - --codespell + + Use the codespell dictionary for checking spelling errors. + + - --codespellfile + + Use the specified codespell file. + Default is '/usr/share/codespell/dictionary.txt'. + + - --typedefsfile + + Read additional types from this file. + + - --color[=WHEN] + + Use colors 'always', 'never', or only when output is a terminal ('auto'). + Default is 'auto'. + + - --kconfig-prefix=WORD + + Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`). + + - -h, --help, --version + + Display the help text. + +Message Levels +============== + +Messages in checkpatch are divided into three levels. The levels of messages +in checkpatch denote the severity of the error. They are: + + - ERROR + + This is the most strict level. Messages of type ERROR must be taken + seriously as they denote things that are very likely to be wrong. + + - WARNING + + This is the next stricter level. Messages of type WARNING requires a + more careful review. But it is milder than an ERROR. + + - CHECK + + This is the mildest level. These are things which may require some thought. + +Type Descriptions +================= + +This section contains a description of all the message types in checkpatch. + +.. Types in this section are also parsed by checkpatch. +.. The types are grouped into subsections based on use. + + +Allocation style +---------------- + + **ALLOC_ARRAY_ARGS** + The first argument for kcalloc or kmalloc_array should be the + number of elements. sizeof() as the first argument is generally + wrong. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + **ALLOC_SIZEOF_STRUCT** + The allocation style is bad. In general for family of + allocation functions using sizeof() to get memory size, + constructs like:: + + p = alloc(sizeof(struct foo), ...) + + should be:: + + p = alloc(sizeof(*p), ...) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory + + **ALLOC_WITH_MULTIPLY** + Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a + sizeof multiply. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + +API usage +--------- + + **ARCH_DEFINES** + Architecture specific defines should be avoided wherever + possible. + + **ARCH_INCLUDE_LINUX** + Whenever asm/file.h is included and linux/file.h exists, a + conversion can be made when linux/file.h includes asm/file.h. + However this is not always the case (See signal.h). + This message type is emitted only for includes from arch/. + + **AVOID_BUG** + BUG() or BUG_ON() should be avoided totally. + Use WARN() and WARN_ON() instead, and handle the "impossible" + error condition as gracefully as possible. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on + + **CONSIDER_KSTRTO** + The simple_strtol(), simple_strtoll(), simple_strtoul(), and + simple_strtoull() functions explicitly ignore overflows, which + may lead to unexpected results in callers. The respective kstrtol(), + kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the + correct replacements. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull + + **LOCKDEP** + The lockdep_no_validate class was added as a temporary measure to + prevent warnings on conversion of device->sem to device->mutex. + It should not be used for any other purpose. + See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/ + + **MALFORMED_INCLUDE** + The #include statement has a malformed path. This has happened + because the author has included a double slash "//" in the pathname + accidentally. + + **USE_LOCKDEP** + lockdep_assert_held() annotations should be preferred over + assertions based on spin_is_locked() + See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations + + **UAPI_INCLUDE** + No #include statements in include/uapi should use a uapi/ path. + + +Comment style +------------- + + **BLOCK_COMMENT_STYLE** + The comment style is incorrect. The preferred style for multi- + line comments is:: + + /* + * This is the preferred style + * for multi line comments. + */ + + The networking comment style is a bit different, with the first line + not empty like the former:: + + /* This is the preferred comment style + * for files in net/ and drivers/net/ + */ + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + **C99_COMMENTS** + C99 style single line comments (//) should not be used. + Prefer the block comment style instead. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + +Commit message +-------------- + + **BAD_SIGN_OFF** + The signed-off-by line does not fall in line with the standards + specified by the community. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1 + + **BAD_STABLE_ADDRESS_STYLE** + The email format for stable is incorrect. + Some valid options for stable address are:: + + 1. stable@vger.kernel.org + 2. stable@kernel.org + + For adding version info, the following comment style should be used:: + + stable@vger.kernel.org # version info + + **COMMIT_COMMENT_SYMBOL** + Commit log lines starting with a '#' are ignored by git as + comments. To solve this problem addition of a single space + infront of the log line is enough. + + **COMMIT_MESSAGE** + The patch is missing a commit description. A brief + description of the changes made by the patch should be added. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + **MISSING_SIGN_OFF** + The patch is missing a Signed-off-by line. A signed-off-by + line should be added according to Developer's certificate of + Origin. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **NO_AUTHOR_SIGN_OFF** + The author of the patch has not signed off the patch. It is + required that a simple sign off line should be present at the + end of explanation of the patch to denote that the author has + written it or otherwise has the rights to pass it on as an open + source patch. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **DIFF_IN_COMMIT_MSG** + Avoid having diff content in commit message. + This causes problems when one tries to apply a file containing both + the changelog and the diff because patch(1) tries to apply the diff + which it found in the changelog. + See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/ + + **GERRIT_CHANGE_ID** + To be picked up by gerrit, the footer of the commit message might + have a Change-Id like:: + + Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b + Signed-off-by: A. U. Thor <author@example.com> + + The Change-Id line must be removed before submitting. + + **GIT_COMMIT_ID** + The proper way to reference a commit id is: + commit <12+ chars of sha1> ("<title line>") + + An example may be:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + +Comparison style +---------------- + + **ASSIGN_IN_IF** + Do not use assignments in if condition. + Example:: + + if ((foo = bar(...)) < BAZ) { + + should be written as:: + + foo = bar(...); + if (foo < BAZ) { + + **BOOL_COMPARISON** + Comparisons of A to true and false are better written + as A and !A. + See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/ + + **COMPARISON_TO_NULL** + Comparisons to NULL in the form (foo == NULL) or (foo != NULL) + are better written as (!foo) and (foo). + + **CONSTANT_COMPARISON** + Comparisons with a constant or upper case identifier on the left + side of the test should be avoided. + + +Macros, Attributes and Symbols +------------------------------ + + **ARRAY_SIZE** + The ARRAY_SIZE(foo) macro should be preferred over + sizeof(foo)/sizeof(foo[0]) for finding number of elements in an + array. + + The macro is defined in include/linux/kernel.h:: + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + + **AVOID_EXTERNS** + Function prototypes don't need to be declared extern in .h + files. It's assumed by the compiler and is unnecessary. + + **AVOID_L_PREFIX** + Local symbol names that are prefixed with `.L` should be avoided, + as this has special meaning for the assembler; a symbol entry will + not be emitted into the symbol table. This can prevent `objtool` + from generating correct unwind info. + + Symbols with STB_LOCAL binding may still be used, and `.L` prefixed + local symbol names are still generally usable within a function, + but `.L` prefixed local symbol names should not be used to denote + the beginning or end of code regions via + `SYM_CODE_START_LOCAL`/`SYM_CODE_END` + + **BIT_MACRO** + Defines like: 1 << <digit> could be BIT(digit). + The BIT() macro is defined in include/linux/bitops.h:: + + #define BIT(nr) (1UL << (nr)) + + **CONST_READ_MOSTLY** + When a variable is tagged with the __read_mostly annotation, it is a + signal to the compiler that accesses to the variable will be mostly + reads and rarely(but NOT never) a write. + + const __read_mostly does not make any sense as const data is already + read-only. The __read_mostly annotation thus should be removed. + + **DATE_TIME** + It is generally desirable that building the same source code with + the same set of tools is reproducible, i.e. the output is always + exactly the same. + + The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, + and enables warnings if they are used as they can lead to + non-deterministic builds. + See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps + + **DEFINE_ARCH_HAS** + The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong. + + For big conceptual features use Kconfig symbols instead. And for + smaller things where we have compatibility fallback functions but + want architectures able to override them with optimized ones, we + should either use weak functions (appropriate for some cases), or + the symbol that protects them should be the same symbol we use. + See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/ + + **INIT_ATTRIBUTE** + Const init definitions should use __initconst instead of + __initdata. + + Similarly init definitions without const require a separate + use of const. + + **INLINE_LOCATION** + The inline keyword should sit between storage class and type. + + For example, the following segment:: + + inline static int example_function(void) + { + ... + } + + should be:: + + static inline int example_function(void) + { + ... + } + + **MULTISTATEMENT_MACRO_USE_DO_WHILE** + Macros with multiple statements should be enclosed in a + do - while block. Same should also be the case for macros + starting with `if` to avoid logic defects:: + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl + + **WEAK_DECLARATION** + Using weak declarations like __attribute__((weak)) or __weak + can have unintended link defects. Avoid using them. + + +Functions and Variables +----------------------- + + **CAMELCASE** + Avoid CamelCase Identifiers. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming + + **FUNCTION_WITHOUT_ARGS** + Function declarations without arguments like:: + + int foo() + + should be:: + + int foo(void) + + **GLOBAL_INITIALISERS** + Global variables should not be initialized explicitly to + 0 (or NULL, false, etc.). Your compiler (or rather your + loader, which is responsible for zeroing out the relevant + sections) automatically does it for you. + + **INITIALISED_STATIC** + Static variables should not be initialized explicitly to zero. + Your compiler (or rather your loader) automatically does + it for you. + + **RETURN_PARENTHESES** + return is not a function and as such doesn't need parentheses:: + + return (bar); + + can simply be:: + + return bar; + + +Spacing and Brackets +-------------------- + + **ASSIGNMENT_CONTINUATIONS** + Assignment operators should not be written at the start of a + line but should follow the operand at the previous line. + + **BRACES** + The placement of braces is stylistically incorrect. + The preferred way is to put the opening brace last on the line, + and put the closing brace first:: + + if (x is true) { + we do y + } + + This applies for all non-functional blocks. + However, there is one special case, namely functions: they have the + opening brace at the beginning of the next line, thus:: + + int function(int x) + { + body of function + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **BRACKET_SPACE** + Whitespace before opening bracket '[' is prohibited. + There are some exceptions: + + 1. With a type on the left:: + + ;int [] a; + + 2. At the beginning of a line for slice initialisers:: + + [0...10] = 5, + + 3. Inside a curly brace:: + + = { [0...10] = 5 } + + **CODE_INDENT** + Code indent should use tabs instead of spaces. + Outside of comments, documentation and Kconfig, + spaces are never used for indentation. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **CONCATENATED_STRING** + Concatenated elements should have a space in between. + Example:: + + printk(KERN_INFO"bar"); + + should be:: + + printk(KERN_INFO "bar"); + + **ELSE_AFTER_BRACE** + `else {` should follow the closing block `}` on the same line. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **LINE_SPACING** + Vertical space is wasted given the limited number of lines an + editor window can display when multiple blank lines are used. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **OPEN_BRACE** + The opening brace should be following the function definitions on the + next line. For any non-functional block it should be on the same line + as the last construct. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **POINTER_LOCATION** + When using pointer data or a function that returns a pointer type, + the preferred use of * is adjacent to the data name or function name + and not adjacent to the type name. + Examples:: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SPACING** + Whitespace style used in the kernel sources is described in kernel docs. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SWITCH_CASE_INDENT_LEVEL** + switch should be at the same indent as case. + Example:: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **TRAILING_WHITESPACE** + Trailing whitespace should always be removed. + Some editors highlight the trailing whitespace and cause visual + distractions when editing files. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **WHILE_AFTER_BRACE** + while should follow the closing bracket on the same line:: + + do { + ... + } while(something); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + +Others +------ + + **CONFIG_DESCRIPTION** + Kconfig symbols should have a help text which fully describes + it. + + **CORRUPTED_PATCH** + The patch seems to be corrupted or lines are wrapped. + Please regenerate the patch file before sending it to the maintainer. + + **DOS_LINE_ENDINGS** + For DOS-formatted patches, there are extra ^M symbols at the end of + the line. These should be removed. + + **EXECUTE_PERMISSIONS** + There is no reason for source files to be executable. The executable + bit can be removed safely. + + **NON_OCTAL_PERMISSIONS** + Permission bits should use 4 digit octal permissions (like 0700 or 0444). + Avoid using any other base like decimal. + + **NOT_UNIFIED_DIFF** + The patch file does not appear to be in unified-diff format. Please + regenerate the patch file before sending it to the maintainer. + + **PRINTF_0XDECIMAL** + Prefixing 0x with decimal output is defective and should be corrected. + + **TRAILING_STATEMENTS** + Trailing statements (for example after any conditional) should be + on the next line. + Like:: + + if (x == y) break; + + should be:: + + if (x == y) + break; diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 9e989baae154..5fce2b06f229 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -124,6 +124,8 @@ box for setups where kernels are built and run on the same machine. In cases where the kernel runs on a separate machine, special preparations must be made, depending on where the gcov tool is used: +.. _gcov-test: + a) gcov is run on the TEST machine The gcov tool version on the test machine must be compatible with the @@ -143,6 +145,8 @@ a) gcov is run on the TEST machine machine. If any of the path components is symbolic link, the actual directory needs to be used instead (due to make's CURDIR handling). +.. _gcov-build: + b) gcov is run on the BUILD machine The following files need to be copied after each test case from test @@ -211,7 +215,7 @@ Appendix A: gather_on_build.sh ------------------------------ Sample script to gather coverage meta files on the build machine -(see 6a): +(see :ref:`Separated build and test machines a. <gcov-test>`): .. code-block:: sh @@ -244,7 +248,7 @@ Appendix B: gather_on_test.sh ----------------------------- Sample script to gather coverage data files on the test machine -(see 6b): +(see :ref:`Separated build and test machines b. <gcov-build>`): .. code-block:: sh diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst index 4756f6b3a04e..8e0f1fe8d17a 100644 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -114,7 +114,7 @@ Examples of using the Linux-provided gdb helpers [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved .... -- Examine fields of the current task struct:: +- Examine fields of the current task struct(supported by x86 and arm64 only):: (gdb) p $lx_current().pid $1 = 4998 diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 1b1cf4f5c9d9..010a2af1e7d9 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -7,6 +7,9 @@ be used to work on the kernel. For now, the documents have been pulled together without any significant effort to integrate them into a coherent whole; patches welcome! +A brief overview of testing-specific tools can be found in +Documentation/dev-tools/testing-overview.rst + .. class:: toc-title Table of contents @@ -14,6 +17,8 @@ whole; patches welcome! .. toctree:: :maxdepth: 2 + testing-overview + checkpatch coccinelle sparse kcov diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index ddf4239a5890..d3f335ffc751 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -11,46 +11,56 @@ designed to find out-of-bound and use-after-free bugs. KASAN has three modes: 2. software tag-based KASAN (similar to userspace HWASan), 3. hardware tag-based KASAN (based on hardware memory tagging). -Software KASAN modes (1 and 2) use compile-time instrumentation to insert -validity checks before every memory access, and therefore require a compiler +Generic KASAN is mainly used for debugging due to a large memory overhead. +Software tag-based KASAN can be used for dogfood testing as it has a lower +memory overhead that allows using it with real workloads. Hardware tag-based +KASAN comes with low memory and performance overheads and, therefore, can be +used in production. Either as an in-field memory bug detector or as a security +mitigation. + +Software KASAN modes (#1 and #2) use compile-time instrumentation to insert +validity checks before every memory access and, therefore, require a compiler version that supports that. -Generic KASAN is supported in both GCC and Clang. With GCC it requires version +Generic KASAN is supported in GCC and Clang. With GCC, it requires version 8.3.0 or later. Any supported Clang version is compatible, but detection of out-of-bounds accesses for global variables is only supported since Clang 11. -Tag-based KASAN is only supported in Clang. +Software tag-based KASAN mode is only supported in Clang. -Currently generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390 +The hardware KASAN mode (#3) relies on hardware to perform the checks but +still requires a compiler version that supports memory tagging instructions. +This mode is supported in GCC 10+ and Clang 11+. + +Both software KASAN modes work with SLUB and SLAB memory allocators, +while the hardware tag-based KASAN currently only supports SLUB. + +Currently, generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390, and riscv architectures, and tag-based KASAN modes are supported only for arm64. Usage ----- -To enable KASAN configure kernel with:: - - CONFIG_KASAN = y - -and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN), -CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN), and -CONFIG_KASAN_HW_TAGS (to enable hardware tag-based KASAN). +To enable KASAN, configure the kernel with:: -For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and -CONFIG_KASAN_INLINE. Outline and inline are compiler instrumentation types. -The former produces smaller binary while the latter is 1.1 - 2 times faster. + CONFIG_KASAN=y -Both software KASAN modes work with both SLUB and SLAB memory allocators, -while the hardware tag-based KASAN currently only support SLUB. +and choose between ``CONFIG_KASAN_GENERIC`` (to enable generic KASAN), +``CONFIG_KASAN_SW_TAGS`` (to enable software tag-based KASAN), and +``CONFIG_KASAN_HW_TAGS`` (to enable hardware tag-based KASAN). -For better error reports that include stack traces, enable CONFIG_STACKTRACE. +For software modes, also choose between ``CONFIG_KASAN_OUTLINE`` and +``CONFIG_KASAN_INLINE``. Outline and inline are compiler instrumentation types. +The former produces a smaller binary while the latter is 1.1-2 times faster. -To augment reports with last allocation and freeing stack of the physical page, -it is recommended to enable also CONFIG_PAGE_OWNER and boot with page_owner=on. +To include alloc and free stack traces of affected slab objects into reports, +enable ``CONFIG_STACKTRACE``. To include alloc and free stack traces of affected +physical pages, enable ``CONFIG_PAGE_OWNER`` and boot with ``page_owner=on``. Error reports ~~~~~~~~~~~~~ -A typical out-of-bounds access generic KASAN report looks like this:: +A typical KASAN report looks like this:: ================================================================== BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] @@ -123,68 +133,75 @@ A typical out-of-bounds access generic KASAN report looks like this:: ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc ================================================================== -The header of the report provides a short summary of what kind of bug happened -and what kind of access caused it. It's followed by a stack trace of the bad -access, a stack trace of where the accessed memory was allocated (in case bad -access happens on a slab object), and a stack trace of where the object was -freed (in case of a use-after-free bug report). Next comes a description of -the accessed slab object and information about the accessed memory page. +The report header summarizes what kind of bug happened and what kind of access +caused it. It is followed by a stack trace of the bad access, a stack trace of +where the accessed memory was allocated (in case a slab object was accessed), +and a stack trace of where the object was freed (in case of a use-after-free +bug report). Next comes a description of the accessed slab object and the +information about the accessed memory page. -In the last section the report shows memory state around the accessed address. -Internally KASAN tracks memory state separately for each memory granule, which +In the end, the report shows the memory state around the accessed address. +Internally, KASAN tracks memory state separately for each memory granule, which is either 8 or 16 aligned bytes depending on KASAN mode. Each number in the memory state section of the report shows the state of one of the memory granules that surround the accessed address. -For generic KASAN the size of each memory granule is 8. The state of each +For generic KASAN, the size of each memory granule is 8. The state of each granule is encoded in one shadow byte. Those 8 bytes can be accessible, -partially accessible, freed or be a part of a redzone. KASAN uses the following -encoding for each shadow byte: 0 means that all 8 bytes of the corresponding +partially accessible, freed, or be a part of a redzone. KASAN uses the following +encoding for each shadow byte: 00 means that all 8 bytes of the corresponding memory region are accessible; number N (1 <= N <= 7) means that the first N bytes are accessible, and other (8 - N) bytes are not; any negative value indicates that the entire 8-byte word is inaccessible. KASAN uses different negative values to distinguish between different kinds of inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). -In the report above the arrows point to the shadow byte 03, which means that -the accessed address is partially accessible. For tag-based KASAN modes this -last report section shows the memory tags around the accessed address -(see the `Implementation details`_ section). +In the report above, the arrow points to the shadow byte ``03``, which means +that the accessed address is partially accessible. + +For tag-based KASAN modes, this last report section shows the memory tags around +the accessed address (see the `Implementation details`_ section). + +Note that KASAN bug titles (like ``slab-out-of-bounds`` or ``use-after-free``) +are best-effort: KASAN prints the most probable bug type based on the limited +information it has. The actual type of the bug might be different. + +Generic KASAN also reports up to two auxiliary call stack traces. These stack +traces point to places in code that interacted with the object but that are not +directly present in the bad access stack trace. Currently, this includes +call_rcu() and workqueue queuing. Boot parameters ~~~~~~~~~~~~~~~ +KASAN is affected by the generic ``panic_on_warn`` command line parameter. +When it is enabled, KASAN panics the kernel after printing a bug report. + +By default, KASAN prints a bug report only for the first invalid memory access. +With ``kasan_multi_shot``, KASAN prints a report on every invalid access. This +effectively disables ``panic_on_warn`` for KASAN reports. + Hardware tag-based KASAN mode (see the section about various modes below) is intended for use in production as a security mitigation. Therefore, it supports -boot parameters that allow to disable KASAN competely or otherwise control -particular KASAN features. +boot parameters that allow disabling KASAN or controlling its features. - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``). +- ``kasan.mode=sync`` or ``=async`` controls whether KASAN is configured in + synchronous or asynchronous mode of execution (default: ``sync``). + Synchronous mode: a bad access is detected immediately when a tag + check fault occurs. + Asynchronous mode: a bad access detection is delayed. When a tag check + fault occurs, the information is stored in hardware (in the TFSR_EL1 + register for arm64). The kernel periodically checks the hardware and + only reports tag faults during these checks. + - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack traces collection (default: ``on``). - ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN - report or also panic the kernel (default: ``report``). Note, that tag - checking gets disabled after the first reported bug. - -For developers -~~~~~~~~~~~~~~ - -Software KASAN modes use compiler instrumentation to insert validity checks. -Such instrumentation might be incompatible with some part of the kernel, and -therefore needs to be disabled. To disable instrumentation for specific files -or directories, add a line similar to the following to the respective kernel -Makefile: - -- For a single file (e.g. main.o):: - - KASAN_SANITIZE_main.o := n - -- For all files in one directory:: - - KASAN_SANITIZE := n - + report or also panic the kernel (default: ``report``). The panic happens even + if ``kasan_multi_shot`` is enabled. Implementation details ---------------------- @@ -192,12 +209,11 @@ Implementation details Generic KASAN ~~~~~~~~~~~~~ -From a high level perspective, KASAN's approach to memory error detection is -similar to that of kmemcheck: use shadow memory to record whether each byte of -memory is safe to access, and use compile-time instrumentation to insert checks -of shadow memory on each memory access. +Software KASAN modes use shadow memory to record whether each byte of memory is +safe to access and use compile-time instrumentation to insert shadow memory +checks before each memory access. -Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB +Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (16TB to cover 128TB on x86_64) and uses direct mapping with a scale and offset to translate a memory address to its corresponding shadow address. @@ -206,113 +222,105 @@ address:: static inline void *kasan_mem_to_shadow(const void *addr) { - return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + return (void *)((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + KASAN_SHADOW_OFFSET; } where ``KASAN_SHADOW_SCALE_SHIFT = 3``. Compile-time instrumentation is used to insert memory access checks. Compiler -inserts function calls (__asan_load*(addr), __asan_store*(addr)) before each -memory access of size 1, 2, 4, 8 or 16. These functions check whether memory -access is valid or not by checking corresponding shadow memory. - -GCC 5.0 has possibility to perform inline instrumentation. Instead of making -function calls GCC directly inserts the code to check the shadow memory. -This option significantly enlarges kernel but it gives x1.1-x2 performance -boost over outline instrumented kernel. +inserts function calls (``__asan_load*(addr)``, ``__asan_store*(addr)``) before +each memory access of size 1, 2, 4, 8, or 16. These functions check whether +memory accesses are valid or not by checking corresponding shadow memory. -Generic KASAN also reports the last 2 call stacks to creation of work that -potentially has access to an object. Call stacks for the following are shown: -call_rcu() and workqueue queuing. +With inline instrumentation, instead of making function calls, the compiler +directly inserts the code to check shadow memory. This option significantly +enlarges the kernel, but it gives an x1.1-x2 performance boost over the +outline-instrumented kernel. -Generic KASAN is the only mode that delays the reuse of freed object via +Generic KASAN is the only mode that delays the reuse of freed objects via quarantine (see mm/kasan/quarantine.c for implementation). Software tag-based KASAN ~~~~~~~~~~~~~~~~~~~~~~~~ -Software tag-based KASAN requires software memory tagging support in the form -of HWASan-like compiler instrumentation (see HWASan documentation for details). - -Software tag-based KASAN is currently only implemented for arm64 architecture. +Software tag-based KASAN uses a software memory tagging approach to checking +access validity. It is currently only implemented for the arm64 architecture. Software tag-based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs -to store a pointer tag in the top byte of kernel pointers. Like generic KASAN -it uses shadow memory to store memory tags associated with each 16-byte memory -cell (therefore it dedicates 1/16th of the kernel memory for shadow memory). +to store a pointer tag in the top byte of kernel pointers. It uses shadow memory +to store memory tags associated with each 16-byte memory cell (therefore, it +dedicates 1/16th of the kernel memory for shadow memory). -On each memory allocation software tag-based KASAN generates a random tag, tags -the allocated memory with this tag, and embeds this tag into the returned +On each memory allocation, software tag-based KASAN generates a random tag, tags +the allocated memory with this tag, and embeds the same tag into the returned pointer. Software tag-based KASAN uses compile-time instrumentation to insert checks -before each memory access. These checks make sure that tag of the memory that -is being accessed is equal to tag of the pointer that is used to access this -memory. In case of a tag mismatch software tag-based KASAN prints a bug report. +before each memory access. These checks make sure that the tag of the memory +that is being accessed is equal to the tag of the pointer that is used to access +this memory. In case of a tag mismatch, software tag-based KASAN prints a bug +report. -Software tag-based KASAN also has two instrumentation modes (outline, that -emits callbacks to check memory accesses; and inline, that performs the shadow +Software tag-based KASAN also has two instrumentation modes (outline, which +emits callbacks to check memory accesses; and inline, which performs the shadow memory checks inline). With outline instrumentation mode, a bug report is -simply printed from the function that performs the access check. With inline -instrumentation a brk instruction is emitted by the compiler, and a dedicated -brk handler is used to print bug reports. +printed from the function that performs the access check. With inline +instrumentation, a ``brk`` instruction is emitted by the compiler, and a +dedicated ``brk`` handler is used to print bug reports. Software tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through -pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently +pointers with the 0xFF pointer tag are not checked). The value 0xFE is currently reserved to tag freed memory regions. -Software tag-based KASAN currently only supports tagging of -kmem_cache_alloc/kmalloc and page_alloc memory. +Software tag-based KASAN currently only supports tagging of slab and page_alloc +memory. Hardware tag-based KASAN ~~~~~~~~~~~~~~~~~~~~~~~~ -Hardware tag-based KASAN is similar to the software mode in concept, but uses +Hardware tag-based KASAN is similar to the software mode in concept but uses hardware memory tagging support instead of compiler instrumentation and shadow memory. Hardware tag-based KASAN is currently only implemented for arm64 architecture and based on both arm64 Memory Tagging Extension (MTE) introduced in ARMv8.5 -Instruction Set Architecture, and Top Byte Ignore (TBI). +Instruction Set Architecture and Top Byte Ignore (TBI). Special arm64 instructions are used to assign memory tags for each allocation. Same tags are assigned to pointers to those allocations. On every memory -access, hardware makes sure that tag of the memory that is being accessed is -equal to tag of the pointer that is used to access this memory. In case of a -tag mismatch a fault is generated and a report is printed. +access, hardware makes sure that the tag of the memory that is being accessed is +equal to the tag of the pointer that is used to access this memory. In case of a +tag mismatch, a fault is generated, and a report is printed. Hardware tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through -pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently +pointers with the 0xFF pointer tag are not checked). The value 0xFE is currently reserved to tag freed memory regions. -Hardware tag-based KASAN currently only supports tagging of -kmem_cache_alloc/kmalloc and page_alloc memory. +Hardware tag-based KASAN currently only supports tagging of slab and page_alloc +memory. -If the hardware doesn't support MTE (pre ARMv8.5), hardware tag-based KASAN -won't be enabled. In this case all boot parameters are ignored. +If the hardware does not support MTE (pre ARMv8.5), hardware tag-based KASAN +will not be enabled. In this case, all KASAN boot parameters are ignored. -Note, that enabling CONFIG_KASAN_HW_TAGS always results in in-kernel TBI being -enabled. Even when kasan.mode=off is provided, or when the hardware doesn't +Note that enabling CONFIG_KASAN_HW_TAGS always results in in-kernel TBI being +enabled. Even when ``kasan.mode=off`` is provided or when the hardware does not support MTE (but supports TBI). -Hardware tag-based KASAN only reports the first found bug. After that MTE tag +Hardware tag-based KASAN only reports the first found bug. After that, MTE tag checking gets disabled. -What memory accesses are sanitised by KASAN? --------------------------------------------- +Shadow memory +------------- -The kernel maps memory in a number of different parts of the address -space. This poses something of a problem for KASAN, which requires -that all addresses accessed by instrumented code have a valid shadow -region. +The kernel maps memory in several different parts of the address space. +The range of kernel virtual addresses is large: there is not enough real +memory to support a real shadow region for every address that could be +accessed by the kernel. Therefore, KASAN only maps real shadow for certain +parts of the address space. -The range of kernel virtual addresses is large: there is not enough -real memory to support a real shadow region for every address that -could be accessed by the kernel. - -By default -~~~~~~~~~~ +Default behaviour +~~~~~~~~~~~~~~~~~ By default, architectures only map real memory over the shadow region for the linear mapping (and potentially other small areas). For all @@ -321,10 +329,9 @@ page is mapped over the shadow area. This read-only shadow page declares all memory accesses as permitted. This presents a problem for modules: they do not live in the linear -mapping, but in a dedicated module space. By hooking in to the module -allocator, KASAN can temporarily map real shadow memory to cover -them. This allows detection of invalid accesses to module globals, for -example. +mapping but in a dedicated module space. By hooking into the module +allocator, KASAN temporarily maps real shadow memory to cover them. +This allows detection of invalid accesses to module globals, for example. This also creates an incompatibility with ``VMAP_STACK``: if the stack lives in vmalloc space, it will be shadowed by the read-only page, and @@ -335,9 +342,10 @@ CONFIG_KASAN_VMALLOC ~~~~~~~~~~~~~~~~~~~~ With ``CONFIG_KASAN_VMALLOC``, KASAN can cover vmalloc space at the -cost of greater memory usage. Currently this is only supported on x86. +cost of greater memory usage. Currently, this is supported on x86, +riscv, s390, and powerpc. -This works by hooking into vmalloc and vmap, and dynamically +This works by hooking into vmalloc and vmap and dynamically allocating real shadow memory to back the mappings. Most mappings in vmalloc space are small, requiring less than a full @@ -356,28 +364,76 @@ memory. To avoid the difficulties around swapping mappings around, KASAN expects that the part of the shadow region that covers the vmalloc space will -not be covered by the early shadow page, but will be left -unmapped. This will require changes in arch-specific code. +not be covered by the early shadow page but will be left unmapped. +This will require changes in arch-specific code. -This allows ``VMAP_STACK`` support on x86, and can simplify support of +This allows ``VMAP_STACK`` support on x86 and can simplify support of architectures that do not have a fixed module region. -CONFIG_KASAN_KUNIT_TEST and CONFIG_KASAN_MODULE_TEST ----------------------------------------------------- +For developers +-------------- -KASAN tests consist of two parts: +Ignoring accesses +~~~~~~~~~~~~~~~~~ + +Software KASAN modes use compiler instrumentation to insert validity checks. +Such instrumentation might be incompatible with some parts of the kernel, and +therefore needs to be disabled. + +Other parts of the kernel might access metadata for allocated objects. +Normally, KASAN detects and reports such accesses, but in some cases (e.g., +in memory allocators), these accesses are valid. + +For software KASAN modes, to disable instrumentation for a specific file or +directory, add a ``KASAN_SANITIZE`` annotation to the respective kernel +Makefile: + +- For a single file (e.g., main.o):: + + KASAN_SANITIZE_main.o := n + +- For all files in one directory:: + + KASAN_SANITIZE := n + +For software KASAN modes, to disable instrumentation on a per-function basis, +use the KASAN-specific ``__no_sanitize_address`` function attribute or the +generic ``noinstr`` one. + +Note that disabling compiler instrumentation (either on a per-file or a +per-function basis) makes KASAN ignore the accesses that happen directly in +that code for software KASAN modes. It does not help when the accesses happen +indirectly (through calls to instrumented functions) or with the hardware +tag-based mode that does not use compiler instrumentation. + +For software KASAN modes, to disable KASAN reports in a part of the kernel code +for the current task, annotate this part of the code with a +``kasan_disable_current()``/``kasan_enable_current()`` section. This also +disables the reports for indirect accesses that happen through function calls. + +For tag-based KASAN modes (include the hardware one), to disable access +checking, use ``kasan_reset_tag()`` or ``page_kasan_tag_reset()``. Note that +temporarily disabling access checking via ``page_kasan_tag_reset()`` requires +saving and restoring the per-page KASAN tag via +``page_kasan_tag``/``page_kasan_tag_set``. + +Tests +~~~~~ + +There are KASAN tests that allow verifying that KASAN works and can detect +certain types of memory corruptions. The tests consist of two parts: 1. Tests that are integrated with the KUnit Test Framework. Enabled with ``CONFIG_KASAN_KUNIT_TEST``. These tests can be run and partially verified -automatically in a few different ways, see the instructions below. +automatically in a few different ways; see the instructions below. 2. Tests that are currently incompatible with KUnit. Enabled with ``CONFIG_KASAN_MODULE_TEST`` and can only be run as a module. These tests can -only be verified manually, by loading the kernel module and inspecting the +only be verified manually by loading the kernel module and inspecting the kernel log for KASAN reports. -Each KUnit-compatible KASAN test prints a KASAN report if an error is detected. -Then the test prints its number and status. +Each KUnit-compatible KASAN test prints one of multiple KASAN reports if an +error is detected. Then the test prints its number and status. When a test passes:: @@ -405,30 +461,24 @@ Or, if one of the tests failed:: not ok 1 - kasan - There are a few ways to run KUnit-compatible KASAN tests. 1. Loadable module -~~~~~~~~~~~~~~~~~~ -With ``CONFIG_KUNIT`` enabled, ``CONFIG_KASAN_KUNIT_TEST`` can be built as -a loadable module and run on any architecture that supports KASAN by loading -the module with insmod or modprobe. The module is called ``test_kasan``. + With ``CONFIG_KUNIT`` enabled, KASAN-KUnit tests can be built as a loadable + module and run by loading ``test_kasan.ko`` with ``insmod`` or ``modprobe``. 2. Built-In -~~~~~~~~~~~ -With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in -on any architecure that supports KASAN. These and any other KUnit tests enabled -will run and print the results at boot as a late-init call. + With ``CONFIG_KUNIT`` built-in, KASAN-KUnit tests can be built-in as well. + In this case, the tests will run at boot as a late-init call. 3. Using kunit_tool -~~~~~~~~~~~~~~~~~~~ -With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it's also -possible use ``kunit_tool`` to see the results of these and other KUnit tests -in a more readable way. This will not print the KASAN reports of the tests that -passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ -for more up-to-date information on ``kunit_tool``. + With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it is also + possible to use ``kunit_tool`` to see the results of KUnit tests in a more + readable way. This will not print the KASAN reports of the tests that passed. + See `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ + for more up-to-date information on ``kunit_tool``. .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index be7a0b0e1f28..d85ce238ace7 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2019, Google LLC. + The Kernel Concurrency Sanitizer (KCSAN) ======================================== diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index a901def730d9..dcefee707ccd 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -239,8 +239,8 @@ using a shell script test runner. ``kselftest/module.sh`` is designed to facilitate this process. There is also a header file provided to assist writing kernel modules that are for use with kselftest: -- ``tools/testing/kselftest/kselftest_module.h`` -- ``tools/testing/kselftest/kselftest/module.sh`` +- ``tools/testing/selftests/kselftest_module.h`` +- ``tools/testing/selftests/kselftest/module.sh`` How to use ---------- diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst index a6ca0af14098..8d8c238f7f79 100644 --- a/Documentation/dev-tools/kunit/tips.rst +++ b/Documentation/dev-tools/kunit/tips.rst @@ -78,8 +78,82 @@ Similarly to the above, it can be useful to add test-specific logic. void test_only_hook(void) { } #endif -TODO(dlatypov@google.com): add an example of using ``current->kunit_test`` in -such a hook when it's not only updated for ``CONFIG_KASAN=y``. +This test-only code can be made more useful by accessing the current kunit +test, see below. + +Accessing the current test +-------------------------- + +In some cases, you need to call test-only code from outside the test file, e.g. +like in the example above or if you're providing a fake implementation of an +ops struct. +There is a ``kunit_test`` field in ``task_struct``, so you can access it via +``current->kunit_test``. + +Here's a slightly in-depth example of how one could implement "mocking": + +.. code-block:: c + + #include <linux/sched.h> /* for current */ + + struct test_data { + int foo_result; + int want_foo_called_with; + }; + + static int fake_foo(int arg) + { + struct kunit *test = current->kunit_test; + struct test_data *test_data = test->priv; + + KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); + return test_data->foo_result; + } + + static void example_simple_test(struct kunit *test) + { + /* Assume priv is allocated in the suite's .init */ + struct test_data *test_data = test->priv; + + test_data->foo_result = 42; + test_data->want_foo_called_with = 1; + + /* 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); + } + + +Note: here we're able to get away with using ``test->priv``, but if you wanted +something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. + +Failing the current test +------------------------ + +But sometimes, you might just want to fail the current test. In that case, we +have ``kunit_fail_current_test(fmt, args...)`` which is defined in ``<kunit/test-bug.h>`` and +doesn't require pulling in ``<kunit/test.h>``. + +E.g. say we had an option to enable some extra debug checks on some data structure: + +.. code-block:: c + + #include <kunit/test-bug.h> + + #ifdef CONFIG_EXTRA_DEBUG_CHECKS + static void validate_my_data(struct data *data) + { + if (is_valid(data)) + return; + + kunit_fail_current_test("data %p is invalid", data); + + /* Normal, non-KUnit, error reporting code here. */ + } + #else + static void my_debug_function(void) { } + #endif + Customizing error messages -------------------------- diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..b5b46709969c --- /dev/null +++ b/Documentation/dev-tools/testing-overview.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Kernel Testing Guide +==================== + + +There are a number of different tools for testing the Linux kernel, so knowing +when to use each of them can be a challenge. This document provides a rough +overview of their differences, and how they fit together. + + +Writing and Running Tests +========================= + +The bulk of kernel tests are written using either the kselftest or KUnit +frameworks. These both provide infrastructure to help make running tests and +groups of tests easier, as well as providing helpers to aid in writing new +tests. + +If you're looking to verify the behaviour of the Kernel — particularly specific +parts of the kernel — then you'll want to use KUnit or kselftest. + + +The Difference Between KUnit and kselftest +------------------------------------------ + +KUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system +for "white box" testing: because test code is part of the kernel, it can access +internal structures and functions which aren't exposed to userspace. + +KUnit tests therefore are best written against small, self-contained parts +of the kernel, which can be tested in isolation. This aligns well with the +concept of 'unit' testing. + +For example, a KUnit test might test an individual kernel function (or even a +single codepath through a function, such as an error handling case), rather +than a feature as a whole. + +This also makes KUnit tests very fast to build and run, allowing them to be +run frequently as part of the development process. + +There is a KUnit test style guide which may give further pointers in +Documentation/dev-tools/kunit/style.rst + + +kselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is +largely implemented in userspace, and tests are normal userspace scripts or +programs. + +This makes it easier to write more complicated tests, or tests which need to +manipulate the overall system state more (e.g., spawning processes, etc.). +However, it's not possible to call kernel functions directly from kselftest. +This means that only kernel functionality which is exposed to userspace somehow +(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest. To +work around this, some tests include a companion kernel module which exposes +more information or functionality. If a test runs mostly or entirely within the +kernel, however, KUnit may be the more appropriate tool. + +kselftest is therefore suited well to tests of whole features, as these will +expose an interface to userspace, which can be tested, but not implementation +details. This aligns well with 'system' or 'end-to-end' testing. + +For example, all new system calls should be accompanied by kselftest tests. + +Code Coverage Tools +=================== + +The Linux Kernel supports two different code coverage measurement tools. These +can be used to verify that a test is executing particular functions or lines +of code. This is useful for determining how much of the kernel is being tested, +and for finding corner-cases which are not covered by the appropriate test. + +:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel +to get global or per-module coverage. Unlike KCOV, it does not record per-task +coverage. Coverage data can be read from debugfs, and interpreted using the +usual gcov tooling. + +:doc:`kcov` is a feature which can be built in to the kernel to allow +capturing coverage on a per-task level. It's therefore useful for fuzzing and +other situations where information about code executed during, for example, a +single syscall is useful. + + +Dynamic Analysis Tools +====================== + +The kernel also supports a number of dynamic analysis tools, which attempt to +detect classes of issues when they occur in a running kernel. These typically +each look for a different class of bugs, such as invalid memory accesses, +concurrency issues such as data races, or other undefined behaviour like +integer overflows. + +Some of these tools are listed below: + +* kmemleak detects possible memory leaks. See + Documentation/dev-tools/kmemleak.rst +* KASAN detects invalid memory accesses such as out-of-bounds and + use-after-free errors. See Documentation/dev-tools/kasan.rst +* UBSAN detects behaviour that is undefined by the C standard, like integer + overflows. See Documentation/dev-tools/ubsan.rst +* KCSAN detects data races. See Documentation/dev-tools/kcsan.rst +* KFENCE is a low-overhead detector of memory issues, which is much faster than + KASAN and can be used in production. See Documentation/dev-tools/kfence.rst +* lockdep is a locking correctness validator. See + Documentation/locking/lockdep-design.rst +* There are several other pieces of debug instrumentation in the kernel, many + of which can be found in lib/Kconfig.debug + +These tools tend to test the kernel as a whole, and do not "pass" like +kselftest or KUnit tests. They can be combined with KUnit or kselftest by +running tests on a kernel with these tools enabled: you can then be sure +that none of these errors are occurring during the test. + +Some of these tools integrate with KUnit or kselftest and will +automatically fail tests if an issue is detected. + diff --git a/Documentation/devicetree/bindings/.gitignore b/Documentation/devicetree/bindings/.gitignore index 3a05b99bfa26..a77719968a7e 100644 --- a/Documentation/devicetree/bindings/.gitignore +++ b/Documentation/devicetree/bindings/.gitignore @@ -1,4 +1,4 @@ # SPDX-License-Identifier: GPL-2.0-only *.example.dts -processed-schema*.yaml -processed-schema*.json +/processed-schema*.yaml +/processed-schema*.json diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 780e5618ec0a..5ccfed90cc70 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -5,7 +5,7 @@ DT_MK_SCHEMA ?= dt-mk-schema DT_SCHEMA_LINT = $(shell which yamllint) -DT_SCHEMA_MIN_VERSION = 2020.8.1 +DT_SCHEMA_MIN_VERSION = 2021.2.1 PHONY += check_dtschema_version check_dtschema_version: @@ -48,13 +48,16 @@ define rule_chkdt $(call cmd,mk_schema) endef -DT_DOCS = $(shell $(find_cmd) | sed -e 's|^$(srctree)/||') +DT_DOCS = $(patsubst $(srctree)/%,%,$(shell $(find_cmd))) override DTC_FLAGS := \ -Wno-avoid_unnecessary_addr_size \ -Wno-graph_child_address \ -Wno-interrupt_provider +# Disable undocumented compatible checks until warning free +override DT_CHECKER_FLAGS ?= + $(obj)/processed-schema-examples.json: $(DT_DOCS) $(src)/.yamllint check_dtschema_version FORCE $(call if_changed_rule,chkdt) diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 5f6769bf45bd..97fb96266344 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -109,6 +109,7 @@ properties: - libretech,aml-s905d-pc - phicomm,n1 - smartlabs,sml5442tw + - videostrong,gxl-kii-pro - const: amlogic,s905d - const: amlogic,meson-gxl @@ -120,8 +121,10 @@ properties: - khadas,vim2 - kingnovel,r-box-pro - libretech,aml-s912-pc + - minix,neo-u9h - nexbox,a1 - tronsmart,vega-s96 + - videostrong,gxm-kiii-pro - wetek,core2 - const: amlogic,s912 - const: amlogic,meson-gxm diff --git a/Documentation/devicetree/bindings/arm/apple.yaml b/Documentation/devicetree/bindings/arm/apple.yaml new file mode 100644 index 000000000000..1e772c85206c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/apple.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/apple.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple ARM Machine Device Tree Bindings + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + ARM platforms using SoCs designed by Apple Inc., branded "Apple Silicon". + + This currently includes devices based on the "M1" SoC, starting with the + three Mac models released in late 2020: + + - Mac mini (M1, 2020) + - MacBook Pro (13-inch, M1, 2020) + - MacBook Air (M1, 2020) + + The compatible property should follow this format: + + compatible = "apple,<targettype>", "apple,<socid>", "apple,arm-platform"; + + <targettype> represents the board/device and comes from the `target-type` + property of the root node of the Apple Device Tree, lowercased. It can be + queried on macOS using the following command: + + $ ioreg -d2 -l | grep target-type + + <socid> is the lowercased SoC ID. Apple uses at least *five* different + names for their SoCs: + + - Marketing name ("M1") + - Internal name ("H13G") + - Codename ("Tonga") + - SoC ID ("T8103") + - Package/IC part number ("APL1102") + + Devicetrees should use the lowercased SoC ID, to avoid confusion if + multiple SoCs share the same marketing name. This can be obtained from + the `compatible` property of the arm-io node of the Apple Device Tree, + which can be queried as follows on macOS: + + $ ioreg -n arm-io | grep compatible + +properties: + $nodename: + const: "/" + compatible: + oneOf: + - description: Apple M1 SoC based platforms + items: + - enum: + - apple,j274 # Mac mini (M1, 2020) + - apple,j293 # MacBook Pro (13-inch, M1, 2020) + - apple,j313 # MacBook Air (M1, 2020) + - const: apple,t8103 + - const: apple,arm-platform + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml index e55731f43c84..2cd4e4a32278 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml @@ -21,6 +21,7 @@ properties: items: - enum: - netgear,r8000p + - tplink,archer-c2300-v1 - const: brcm,bcm4906 - const: brcm,bcm4908 diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml index a2c63c8b1d10..b369b374fc4a 100644 --- a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml @@ -26,10 +26,7 @@ properties: - const: simple-mfd mboxes: - $ref: '/schemas/types.yaml#/definitions/phandle' - description: | - Phandle to the firmware device's Mailbox. - (See: ../mailbox/mailbox.txt for more information) + maxItems: 1 clocks: type: object @@ -64,6 +61,21 @@ properties: - compatible - "#reset-cells" + pwm: + type: object + + properties: + compatible: + const: raspberrypi,firmware-poe-pwm + + "#pwm-cells": + # See pwm.yaml in this directory for a description of the cells format. + const: 2 + + required: + - compatible + - "#pwm-cells" + additionalProperties: false required: @@ -87,5 +99,10 @@ examples: compatible = "raspberrypi,firmware-reset"; #reset-cells = <1>; }; + + pwm: pwm { + compatible = "raspberrypi,firmware-poe-pwm"; + #pwm-cells = <2>; + }; }; ... diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 26b886b20b27..f3c7249c73d6 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -85,6 +85,8 @@ properties: compatible: enum: + - apple,icestorm + - apple,firestorm - arm,arm710t - arm,arm720t - arm,arm740t @@ -256,13 +258,11 @@ properties: where voltage is in V, frequency is in MHz. power-domains: - $ref: '/schemas/types.yaml#/definitions/phandle-array' description: List of phandles and PM domain specifiers, as defined by bindings of the PM domain provider (see also ../power_domain.txt). power-domain-names: - $ref: '/schemas/types.yaml#/definitions/string-array' description: A list of power domain name strings sorted in the same order as the power-domains property. diff --git a/Documentation/devicetree/bindings/arm/ete.yaml b/Documentation/devicetree/bindings/arm/ete.yaml new file mode 100644 index 000000000000..7f9b2d1e1147 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ete.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# Copyright 2021, Arm Ltd +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/ete.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: ARM Embedded Trace Extensions + +maintainers: + - Suzuki K Poulose <suzuki.poulose@arm.com> + - Mathieu Poirier <mathieu.poirier@linaro.org> + +description: | + Arm Embedded Trace Extension(ETE) is a per CPU trace component that + allows tracing the CPU execution. It overlaps with the CoreSight ETMv4 + architecture and has extended support for future architecture changes. + The trace generated by the ETE could be stored via legacy CoreSight + components (e.g, TMC-ETR) or other means (e.g, using a per CPU buffer + Arm Trace Buffer Extension (TRBE)). Since the ETE can be connected to + legacy CoreSight components, a node must be listed per instance, along + with any optional connection graph as per the coresight bindings. + See bindings/arm/coresight.txt. + +properties: + $nodename: + pattern: "^ete([0-9a-f]+)$" + compatible: + items: + - const: arm,embedded-trace-extension + + cpu: + description: | + Handle to the cpu this ETE is bound to. + $ref: /schemas/types.yaml#/definitions/phandle + + out-ports: + description: | + Output connections from the ETE to legacy CoreSight trace bus. + $ref: /schemas/graph.yaml#/properties/ports + properties: + port: + description: Output connection from the ETE to legacy CoreSight Trace bus. + $ref: /schemas/graph.yaml#/properties/port + +required: + - compatible + - cpu + +additionalProperties: false + +examples: + +# An ETE node without legacy CoreSight connections + - | + ete0 { + compatible = "arm,embedded-trace-extension"; + cpu = <&cpu_0>; + }; +# An ETE node with legacy CoreSight connections + - | + ete1 { + compatible = "arm,embedded-trace-extension"; + cpu = <&cpu_1>; + + out-ports { /* legacy coresight connection */ + port { + ete1_out_port: endpoint { + remote-endpoint = <&funnel_in_port0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 297c87f45db8..e3c50f231d71 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -617,6 +617,7 @@ properties: - kam,imx7d-flex-concentrator # Kamstrup OMNIA Flex Concentrator - kam,imx7d-flex-concentrator-mfg # Kamstrup OMNIA Flex Concentrator in manufacturing mode - novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board + - remarkable,imx7d-remarkable2 # i.MX7D ReMarkable 2 E-Ink Tablet - technexion,imx7d-pico-dwarf # TechNexion i.MX7D Pico-Dwarf - technexion,imx7d-pico-hobbit # TechNexion i.MX7D Pico-Hobbit - technexion,imx7d-pico-nymph # TechNexion i.MX7D Pico-Nymph @@ -688,6 +689,14 @@ properties: - variscite,var-som-mx8mm # i.MX8MM Variscite VAR-SOM-MX8MM module - const: fsl,imx8mm + - description: Engicam i.Core MX8M Mini SoM based boards + items: + - enum: + - engicam,icore-mx8mm-ctouch2 # i.MX8MM Engicam i.Core MX8M Mini C.TOUCH 2.0 + - engicam,icore-mx8mm-edimm2.2 # i.MX8MM Engicam i.Core MX8M Mini EDIMM2.2 Starter Kit + - const: engicam,icore-mx8mm # i.MX8MM Engicam i.Core MX8M Mini SoM + - const: fsl,imx8mm + - description: Kontron BL i.MX8MM (N801X S) Board items: - const: kontron,imx8mm-n801x-s @@ -733,6 +742,7 @@ properties: - einfochips,imx8mq-thor96 # i.MX8MQ Thor96 Board - fsl,imx8mq-evk # i.MX8MQ EVK Board - google,imx8mq-phanbell # Google Coral Edge TPU + - kontron,pitx-imx8m # Kontron pITX-imx8m Board - purism,librem5-devkit # Purism Librem5 devkit - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk @@ -755,6 +765,12 @@ properties: - const: zii,imx8mq-ultra - const: fsl,imx8mq + - description: i.MX8QM based Boards + items: + - enum: + - fsl,imx8qm-mek # i.MX8QM MEK Board + - const: fsl,imx8qm + - description: i.MX8QXP based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt index a21f7709596c..0705e765f432 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt @@ -142,8 +142,8 @@ mpp50 50 gpio, ge1(rxclk), mss_i2c(sda), spi1(csn0), uart2(txd), uart0(rxd), xg( mpp51 51 gpio, ge1(rxd0), mss_i2c(sck), spi1(csn1), uart2(rxd), uart0(cts), sdio(pwr10) mpp52 52 gpio, ge1(rxd1), synce1(clk), synce2(clk), spi1(csn2), uart1(cts), led(clk), pcie(rstoutn), pcie0(clkreq) mpp53 53 gpio, ge1(rxd2), ptp(clk), spi1(csn3), uart1(rxd), led(stb), sdio(led) -mpp54 54 gpio, ge1(rxd3), synce2(clk), ptp(pclk_out), synce1(clk), led(data), sdio(hw_rst), sdio(wr_protect) -mpp55 55 gpio, ge1(rxctl_rxdv), ptp(pulse), sdio(led), sdio(card_detect) +mpp54 54 gpio, ge1(rxd3), synce2(clk), ptp(pclk_out), synce1(clk), led(data), sdio(hw_rst), sdio_wp(wr_protect) +mpp55 55 gpio, ge1(rxctl_rxdv), ptp(pulse), sdio(led), sdio_cd(card_detect) mpp56 56 gpio, tdm(drx), au(i2sdo_spdifo), spi0(clk), uart1(rxd), sata1(present_act), sdio(clk) mpp57 57 gpio, mss_i2c(sda), ptp(pclk_out), tdm(intn), au(i2sbclk), spi0(mosi), uart1(txd), sata0(present_act), sdio(cmd) mpp58 58 gpio, mss_i2c(sck), ptp(clk), tdm(rstn), au(i2sdi), spi0(miso), uart1(cts), led(clk), sdio(d0) diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 93b3bdf6eaeb..aff57a8c8c30 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -118,6 +118,10 @@ properties: - enum: - mediatek,mt8183-evb - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8195-evb + - const: mediatek,mt8195 - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) items: - enum: @@ -125,6 +129,38 @@ properties: - google,krane-sku176 - const: google,krane - const: mediatek,mt8183 + - description: Google Damu (ASUS Chromebook Flip CM3) + items: + - const: google,damu + - const: mediatek,mt8183 + - description: Google Juniper (Acer Chromebook Spin 311) + items: + - const: google,juniper-sku16 + - const: google,juniper + - const: mediatek,mt8183 + - description: Google Kakadu (ASUS Chromebook Detachable CM3) + items: + - const: google,kakadu-rev3 + - const: google,kakadu-rev2 + - const: google,kakadu + - const: mediatek,mt8183 + - description: Google Kodama (Lenovo 10e Chromebook Tablet) + items: + - enum: + - google,kodama-sku16 + - google,kodama-sku272 + - google,kodama-sku288 + - google,kodama-sku32 + - const: google,kodama + - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8183-pumpkin + - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8516-pumpkin + - const: mediatek,mt8516 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index d8c9108c3b4a..78c50733985c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -13,6 +13,7 @@ Required Properties: - "mediatek,mt6779-mmsys", "syscon" - "mediatek,mt6797-mmsys", "syscon" - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" + - "mediatek,mt8167-mmsys", "syscon" - "mediatek,mt8173-mmsys", "syscon" - "mediatek,mt8183-mmsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index c299dc907f6c..62fcbd883392 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -22,6 +22,7 @@ properties: compatible: enum: - qcom,sc7180-llcc + - qcom,sc7280-llcc - qcom,sdm845-llcc - qcom,sm8150-llcc - qcom,sm8250-llcc diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml index 61d08c473eb8..a316eef1b728 100644 --- a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml +++ b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml @@ -24,6 +24,7 @@ properties: items: - enum: - honestar,ssd201htv2 # Honestar SSD201_HT_V2 devkit + - m5stack,unitv2 # M5Stack UnitV2 - const: mstar,infinity2m - description: infinity3 boards diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.txt b/Documentation/devicetree/bindings/arm/npcm/npcm.txt deleted file mode 100644 index 2d87d9ecea85..000000000000 --- a/Documentation/devicetree/bindings/arm/npcm/npcm.txt +++ /dev/null @@ -1,6 +0,0 @@ -NPCM Platforms Device Tree Bindings ------------------------------------ -NPCM750 SoC -Required root node properties: - - compatible = "nuvoton,npcm750"; - diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml new file mode 100644 index 000000000000..95e51378089c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/npcm/npcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NPCM Platforms Device Tree Bindings + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: WPCM450 based boards + items: + - enum: + - supermicro,x9sci-ln4f-bmc # Supermicro X9SCI-LN4F server's BMC + - const: nuvoton,wpcm450 + + - description: NPCM750 based boards + items: + - enum: + - nuvoton,npcm750-evb # NPCM750 evaluation board + - const: nuvoton,npcm750 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 174134f920e1..9b27e991bddc 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -37,6 +37,7 @@ description: | msm8994 msm8996 sc7180 + sc7280 sdm630 sdm660 sdm845 @@ -137,6 +138,16 @@ properties: - const: qcom,msm8916 - items: + - enum: + - sony,karin_windy + - sony,karin-row + - sony,satsuki-row + - sony,sumire-row + - sony,suzuran-row + - qcom,msm8994 + - const: qcom,apq8094 + + - items: - const: qcom,msm8996-mtp - items: @@ -166,16 +177,24 @@ properties: - items: - enum: + - qcom,sc7280-idp + - const: qcom,sc7280 + + - items: + - enum: - xiaomi,lavender - const: qcom,sdm660 - items: - enum: - qcom,sdx55-mtp + - qcom,sdx55-telit-fn980-tlb + - qcom,sdx55-t55 - const: qcom,sdx55 - items: - enum: + - qcom,ipq6018-cp01 - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 @@ -187,6 +206,7 @@ properties: - items: - enum: + - qcom,sm8350-hdk - qcom,sm8350-mtp - const: qcom,sm8350 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index c3036f95c7bc..4a6f772c1043 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -134,6 +134,7 @@ properties: - friendlyarm,nanopi-m4 - friendlyarm,nanopi-m4b - friendlyarm,nanopi-neo4 + - friendlyarm,nanopi-r4s - const: rockchip,rk3399 - description: GeekBuying GeekBox diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index e7525a3395e5..9a77ab74be99 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -53,6 +53,10 @@ properties: - const: st,stm32h743 - items: - enum: + - st,stm32h750i-art-pi + - const: st,stm32h750 + - items: + - enum: - shiratech,stm32mp157a-iot-box # IoT Box - shiratech,stm32mp157a-stinger96 # Stinger96 - st,stm32mp157c-ed1 @@ -64,6 +68,23 @@ properties: - const: st,stm32mp157c-ev1 - const: st,stm32mp157c-ed1 - const: st,stm32mp157 + + - description: Engicam i.Core STM32MP1 SoM based Boards + items: + - enum: + - engicam,icore-stm32mp1-ctouch2 # STM32MP1 Engicam i.Core STM32MP1 C.TOUCH 2.0 + - engicam,icore-stm32mp1-edimm2.2 # STM32MP1 Engicam i.Core STM32MP1 EDIMM2.2 Starter Kit + - const: engicam,icore-stm32mp1 # STM32MP1 Engicam i.Core STM32MP1 SoM + - const: st,stm32mp157 + + - description: Engicam MicroGEA STM32MP1 SoM based Boards + items: + - enum: + - engicam,microgea-stm32mp1-microdev2.0 + - engicam,microgea-stm32mp1-microdev2.0-of7 + - const: engicam,microgea-stm32mp1 + - const: st,stm32mp157 + - description: Octavo OSD32MP15x System-in-Package based boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 08607c7ec1bf..ac750025a2eb 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -802,6 +802,11 @@ properties: - const: tbs-biometrics,a711 - const: allwinner,sun8i-a83t + - description: Topwise A721 Tablet + items: + - const: topwise,a721 + - const: allwinner,sun4i-a10 + - description: Utoo P66 items: - const: utoo,p66 diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index c6e1c1e63e43..c5aa362e4026 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -23,6 +23,8 @@ properties: items: - enum: - ti,am654-evm + - siemens,iot2050-basic + - siemens,iot2050-advanced - const: ti,am654 - description: K3 J721E SoC @@ -33,6 +35,13 @@ properties: items: - const: ti,j7200 + - description: K3 AM642 SoC + items: + - enum: + - ti,am642-evm + - ti,am642-sk + - const: ti,am642 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/trbe.yaml b/Documentation/devicetree/bindings/arm/trbe.yaml new file mode 100644 index 000000000000..4402d7bfd1fc --- /dev/null +++ b/Documentation/devicetree/bindings/arm/trbe.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# Copyright 2021, Arm Ltd +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/trbe.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: ARM Trace Buffer Extensions + +maintainers: + - Anshuman Khandual <anshuman.khandual@arm.com> + +description: | + Arm Trace Buffer Extension (TRBE) is a per CPU component + for storing trace generated on the CPU to memory. It is + accessed via CPU system registers. The software can verify + if it is permitted to use the component by checking the + TRBIDR register. + +properties: + $nodename: + const: "trbe" + compatible: + items: + - const: arm,trace-buffer-extension + + interrupts: + description: | + Exactly 1 PPI must be listed. For heterogeneous systems where + TRBE is only supported on a subset of the CPUs, please consult + the arm,gic-v3 binding for details on describing a PPI partition. + maxItems: 1 + +required: + - compatible + - interrupts + +additionalProperties: false + +examples: + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + trbe { + compatible = "arm,trace-buffer-extension"; + interrupts = <GIC_PPI 15 IRQ_TYPE_LEVEL_HIGH>; + }; +... diff --git a/Documentation/devicetree/bindings/ata/ahci-ceva.txt b/Documentation/devicetree/bindings/ata/ahci-ceva.txt index 7561cc4de371..bfb6da0281ec 100644 --- a/Documentation/devicetree/bindings/ata/ahci-ceva.txt +++ b/Documentation/devicetree/bindings/ata/ahci-ceva.txt @@ -38,6 +38,8 @@ Required properties: Optional properties: - ceva,broken-gen2: limit to gen1 speed instead of gen2. + - phys: phandle for the PHY device + - resets: phandle to the reset controller for the SATA IP Examples: ahci@fd0c0000 { @@ -56,4 +58,6 @@ Examples: ceva,p1-burst-params = /bits/ 8 <0x0A 0x08 0x4A 0x06>; ceva,p1-retry-params = /bits/ 16 <0x0216 0x7F06>; ceva,broken-gen2; + phys = <&psgtr 1 PHY_TYPE_SATA 1 1>; + resets = <&zynqmp_reset ZYNQMP_RESET_SATA>; }; diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml new file mode 100644 index 000000000000..a75e9a8f539a --- /dev/null +++ b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/nvidia,tegra-ahci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra AHCI SATA Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra124-ahci + - nvidia,tegra132-ahci + - nvidia,tegra210-ahci + - nvidia,tegra186-ahci + + reg: + minItems: 2 + maxItems: 3 + items: + - description: AHCI registers + - description: SATA configuration and IPFS registers + - description: SATA AUX registers + + interrupts: + maxItems: 1 + + clock-names: + items: + - const: sata + - const: sata-oob + + clocks: + maxItems: 2 + + reset-names: + minItems: 2 + items: + - const: sata + - const: sata-cold + - const: sata-oob + + resets: + minItems: 2 + maxItems: 3 + + iommus: + maxItems: 1 + + interconnect-names: + items: + - const: dma-mem + - const: write + + interconnects: + maxItems: 2 + + power-domains: + items: + - description: SAX power-domain + + phy-names: + items: + - const: sata-0 + + phys: + maxItems: 1 + + hvdd-supply: + description: SATA HVDD regulator supply. + + vddio-supply: + description: SATA VDDIO regulator supply. + + avdd-supply: + description: SATA AVDD regulator supply. + + target-5v-supply: + description: SATA 5V power regulator supply. + + target-12v-supply: + description: SATA 12V power regulator supply. + +required: + - compatible + - reg + - interrupts + - clock-names + - clocks + - reset-names + - resets + +allOf: + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra124-ahci + - nvidia,tegra132-ahci + then: + properties: + reg: + maxItems: 2 + reset-names: + minItems: 3 + resets: + minItems: 3 + required: + - phys + - phy-names + - hvdd-supply + - vddio-supply + - avdd-supply + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra210-ahci + then: + properties: + reg: + minItems: 3 + reset-names: + minItems: 3 + resets: + minItems: 3 + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-ahci + then: + properties: + reg: + minItems: 3 + reset-names: + maxItems: 2 + resets: + maxItems: 2 + required: + - iommus + - interconnect-names + - interconnects + - power-domains + +additionalProperties: true + +examples: + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/reset/tegra210-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + sata@70020000 { + compatible = "nvidia,tegra210-ahci"; + reg = <0x70027000 0x00002000>, /* AHCI */ + <0x70020000 0x00007000>, /* SATA */ + <0x70001100 0x00010000>; /* SATA AUX */ + interrupts = <GIC_SPI 23 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA210_CLK_SATA>, + <&tegra_car TEGRA210_CLK_SATA_OOB>; + clock-names = "sata", "sata-oob"; + resets = <&tegra_car 124>, + <&tegra_car 129>, + <&tegra_car 123>; + reset-names = "sata", "sata-cold", "sata-oob"; + }; diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt b/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt deleted file mode 100644 index 12ab2f723eb0..000000000000 --- a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt +++ /dev/null @@ -1,44 +0,0 @@ -Tegra SoC SATA AHCI controller - -Required properties : -- compatible : Must be one of: - - Tegra124 : "nvidia,tegra124-ahci" - - Tegra132 : "nvidia,tegra132-ahci", "nvidia,tegra124-ahci" - - Tegra210 : "nvidia,tegra210-ahci" -- reg : Should contain 2 entries: - - AHCI register set (SATA BAR5) - - SATA register set -- interrupts : Defines the interrupt used by SATA -- 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: - - sata - - sata-oob -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - sata - - sata-oob - - sata-cold -- phys : Must contain an entry for each entry in phy-names. - See ../phy/phy-bindings.txt for details. -- phy-names : Must include the following entries: - - For Tegra124 and Tegra132: - - sata-phy : XUSB PADCTL SATA PHY -- For Tegra124 and Tegra132: - - hvdd-supply : Defines the SATA HVDD regulator - - vddio-supply : Defines the SATA VDDIO regulator - - avdd-supply : Defines the SATA AVDD regulator - - target-5v-supply : Defines the SATA 5V power regulator - - target-12v-supply : Defines the SATA 12V power regulator - -Optional properties: -- reg : - - AUX register set -- clock-names : - - cml1 : - cml1 clock should be defined here if the PHY driver - doesn't manage them. If it does, they should not be. -- phy-names : - - For T210: - - sata-phy diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml index e9c4cf834aa7..e5d9d45dab8a 100644 --- a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml @@ -44,7 +44,7 @@ examples: - | clk@1c20000 { #clock-cells = <0>; - compatible = "allwinner,sun4i-a10-pll1"; + compatible = "allwinner,sun4i-a10-pll1-clk"; reg = <0x01c20000 0x4>; clocks = <&osc24M>; clock-output-names = "osc24M"; diff --git a/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt b/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt index 0ba1d83ff363..ed1df32c577a 100644 --- a/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt +++ b/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt @@ -1,6 +1,6 @@ * Time Base Generator Clock bindings for Marvell Armada 37xx SoCs -Marvell Armada 37xx SoCs provde Time Base Generator clocks which are +Marvell Armada 37xx SoCs provide Time Base Generator clocks which are used as parent clocks for the peripheral clocks. The TBG clock consumer should specify the desired clock by having the diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml index c268debe5b8d..28675b0b80f1 100644 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml @@ -60,7 +60,6 @@ properties: maxItems: 2 idt,xtal-load-femtofarads: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 9000 maximum: 22760 description: Optional load capacitor for XTAL1 and XTAL2 @@ -84,7 +83,6 @@ patternProperties: enum: [ 1800000, 2500000, 3300000 ] idt,slew-percent: description: The Slew rate control for CMOS single-ended. - $ref: /schemas/types.yaml#/definitions/uint32 enum: [ 80, 85, 90, 100 ] required: diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml index 940486ef1051..0f6fe365ebf3 100644 --- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml @@ -107,8 +107,8 @@ examples: interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>; reg = <0x5b010000 0x10000>; clocks = <&sdhc0_lpcg IMX_LPCG_CLK_4>, - <&sdhc0_lpcg IMX_LPCG_CLK_0>, - <&sdhc0_lpcg IMX_LPCG_CLK_5>; - clock-names = "ipg", "per", "ahb"; + <&sdhc0_lpcg IMX_LPCG_CLK_5>, + <&sdhc0_lpcg IMX_LPCG_CLK_0>; + clock-names = "ipg", "ahb", "per"; power-domains = <&pd IMX_SC_R_SDHC_0>; }; diff --git a/Documentation/devicetree/bindings/clock/mediatek,mt7621-sysc.yaml b/Documentation/devicetree/bindings/clock/mediatek,mt7621-sysc.yaml new file mode 100644 index 000000000000..915f84efd763 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/mediatek,mt7621-sysc.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/mediatek,mt7621-sysc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MT7621 Clock Device Tree Bindings + +maintainers: + - Sergio Paracuellos <sergio.paracuellos@gmail.com> + +description: | + The MT7621 has a PLL controller from where the cpu clock is provided + as well as derived clocks for the bus and the peripherals. It also + can gate SoC device clocks. + + Each clock is assigned an identifier and client nodes use this identifier + to specify the clock which they consume. + + All these identifiers could be found in: + [1]: <include/dt-bindings/clock/mt7621-clk.h>. + + The clocks are provided inside a system controller node. + +properties: + compatible: + items: + - const: mediatek,mt7621-sysc + - const: syscon + + reg: + maxItems: 1 + + "#clock-cells": + description: + The first cell indicates the clock number, see [1] for available + clocks. + const: 1 + + ralink,memctl: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle of syscon used to control memory registers + + clock-output-names: + maxItems: 8 + +required: + - compatible + - reg + - '#clock-cells' + - ralink,memctl + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt7621-clk.h> + + sysc: sysc@0 { + compatible = "mediatek,mt7621-sysc", "syscon"; + reg = <0x0 0x100>; + #clock-cells = <1>; + ralink,memctl = <&memc>; + clock-output-names = "xtal", "cpu", "bus", + "50m", "125m", "150m", + "250m", "270m"; + }; diff --git a/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml index 0e8b07710451..6d39344d2b70 100644 --- a/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml +++ b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml @@ -18,10 +18,12 @@ description: | properties: compatible: - oneOf: - - items: - - enum: - - socionext,milbeaut-m10v-ccu + enum: + - socionext,milbeaut-m10v-ccu + + reg: + maxItems: 1 + clocks: maxItems: 1 description: external clock @@ -41,7 +43,7 @@ examples: # Clock controller node: - | m10v-clk-ctrl@1d021000 { - compatible = "socionext,milbeaut-m10v-clk-ccu"; + compatible = "socionext,milbeaut-m10v-ccu"; reg = <0x1d021000 0x4000>; #clock-cells = <1>; clocks = <&clki40mhz>; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml new file mode 100644 index 000000000000..d902f137ab17 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sdm845.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding + +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 SDM845 + + See also: + - dt-bindings/clock/qcom,gcc-sdm845.h + +properties: + compatible: + const: qcom,gcc-sdm845 + + clocks: + items: + - description: Board XO source + - description: Board active XO source + - description: Sleep clock source + - description: PCIE 0 Pipe clock source + - description: PCIE 1 Pipe clock source + + clock-names: + items: + - const: bi_tcxo + - const: bi_tcxo_ao + - const: sleep_clk + - const: pcie_0_pipe_clk + - const: pcie_1_pipe_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + protected-clocks: + description: + Protected clock specifier list as per common clock binding. + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + # Example for GCC for SDM845: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sdm845"; + reg = <0x100000 0x1f0000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&sleep_clk>, + <&pcie0_lane>, + <&pcie1_lane>; + clock-names = "bi_tcxo", "bi_tcxo_ao", "sleep_clk", "pcie_0_pipe_clk", "pcie_1_pipe_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index ee0467fb5e31..490edad25830 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -32,7 +32,6 @@ description: | - dt-bindings/clock/qcom,gcc-mdm9615.h - dt-bindings/reset/qcom,gcc-mdm9615.h - dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) - - dt-bindings/clock/qcom,gcc-sdm845.h properties: compatible: @@ -52,7 +51,6 @@ properties: - qcom,gcc-mdm9615 - qcom,gcc-sdm630 - qcom,gcc-sdm660 - - qcom,gcc-sdm845 '#clock-cells': const: 1 diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3568-cru.yaml b/Documentation/devicetree/bindings/clock/rockchip,rk3568-cru.yaml new file mode 100644 index 000000000000..b2c26097827f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3568-cru.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/rockchip,rk3568-cru.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROCKCHIP rk3568 Family Clock Control Module Binding + +maintainers: + - Elaine Zhang <zhangqing@rock-chips.com> + - Heiko Stuebner <heiko@sntech.de> + +description: | + The RK3568 clock controller generates the clock and also implements a + reset controller for SoC peripherals. + (examples: provide SCLK_UART1\PCLK_UART1 and SRST_P_UART1\SRST_S_UART1 for UART module) + 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 the dt-bindings/clock/rk3568-cru.h headers and can be + used in device tree sources. + +properties: + compatible: + enum: + - rockchip,rk3568-cru + - rockchip,rk3568-pmucru + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + +required: + - compatible + - reg + - "#clock-cells" + - "#reset-cells" + +additionalProperties: false + +examples: + # Clock Control Module node: + - | + pmucru: clock-controller@fdd00000 { + compatible = "rockchip,rk3568-pmucru"; + reg = <0xfdd00000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + - | + cru: clock-controller@fdd20000 { + compatible = "rockchip,rk3568-cru"; + reg = <0xfdd20000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index b6daedd62516..92b49bc37939 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -149,6 +149,17 @@ properties: maxItems: 6 $ref: /schemas/types.yaml#/definitions/uint32-array + sink-vdos-v1: + description: An array of u32 with each entry, a Vendor Defined Message Object (VDO), + providing additional information corresponding to the product, the detailed bit + definitions and the order of each VDO can be found in + "USB Power Delivery Specification Revision 2.0, Version 1.3" chapter 6.4.4.3.1 Discover + Identity. User can specify the VDO array via VDO_IDH/_CERT/_PRODUCT/_CABLE/_AMA defined in + dt-bindings/usb/pd.h. + minItems: 3 + maxItems: 6 + $ref: /schemas/types.yaml#/definitions/uint32-array + op-sink-microwatt: description: Sink required operating power in microwatt, if source can't offer the power, Capability Mismatch is set. Required for power sink and @@ -197,6 +208,20 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 enum: [1, 2, 3] + slow-charger-loop: + description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to + still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby + state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification + Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W - + 5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during + SNK_DISCOVERY) and the actual currrent limit after reception of PS_Ready for PD link or during + SNK_READY for non-pd link. + type: boolean + +dependencies: + sink-vdos-v1: [ 'sink-vdos' ] + sink-vdos: [ 'sink-vdos-v1' ] + required: - compatible diff --git a/Documentation/devicetree/bindings/counter/interrupt-counter.yaml b/Documentation/devicetree/bindings/counter/interrupt-counter.yaml new file mode 100644 index 000000000000..fd075d104631 --- /dev/null +++ b/Documentation/devicetree/bindings/counter/interrupt-counter.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/counter/interrupt-counter.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Interrupt counter + +maintainers: + - Oleksij Rempel <o.rempel@pengutronix.de> + +description: | + A generic interrupt counter to measure interrupt frequency. It was developed + and used for agricultural devices to measure rotation speed of wheels or + other tools. Since the direction of rotation is not important, only one + signal line is needed. + Interrupts or gpios are required. If both are defined, the interrupt will + take precedence for counting interrupts. + +properties: + compatible: + const: interrupt-counter + + interrupts: + maxItems: 1 + + gpios: + maxItems: 1 + +required: + - compatible + +anyOf: + - required: [ interrupts-extended ] + - required: [ interrupts ] + - required: [ gpios ] + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + + counter-0 { + compatible = "interrupt-counter"; + interrupts-extended = <&gpio 0 IRQ_TYPE_EDGE_RISING>; + }; + + counter-1 { + compatible = "interrupt-counter"; + gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + }; + + counter-2 { + compatible = "interrupt-counter"; + interrupts-extended = <&gpio 2 IRQ_TYPE_EDGE_RISING>; + gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + }; + +... diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml index 1d48ac712b23..a410d2cedde6 100644 --- a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml +++ b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml @@ -14,6 +14,7 @@ properties: enum: - ti,j721e-sa2ul - ti,am654-sa2ul + - ti,am64-sa2ul reg: maxItems: 1 @@ -45,6 +46,18 @@ properties: description: Address translation for the possible RNG child node for SA2UL + clocks: + items: + - description: Clock used by PKA + - description: Main Input Clock + - description: Clock used by rng + + clock-names: + items: + - const: pka_in_clk + - const: x1_clk + - const: x2_clk + patternProperties: "^rng@[a-f0-9]+$": type: object @@ -57,7 +70,16 @@ required: - power-domains - dmas - dma-names - - dma-coherent + +if: + properties: + compatible: + enum: + - ti,j721e-sa2ul + - ti,am654-sa2ul +then: + required: + - dma-coherent additionalProperties: false diff --git a/Documentation/devicetree/bindings/ddr/lpddr3.txt b/Documentation/devicetree/bindings/ddr/lpddr3.txt index a0eda35a86ee..b221e653d384 100644 --- a/Documentation/devicetree/bindings/ddr/lpddr3.txt +++ b/Documentation/devicetree/bindings/ddr/lpddr3.txt @@ -12,6 +12,9 @@ Required properties: Optional properties: +- manufacturer-id : <u32> Manufacturer ID value read from Mode Register 5 +- revision-id : <u32 u32> Revision IDs read from Mode Registers 6 and 7 + The following optional properties represent the minimum value of some AC timing parameters of the DDR device in terms of number of clock cycles. These values shall be obtained from the device data-sheet. @@ -49,6 +52,8 @@ samsung_K3QF2F20DB: lpddr3 { compatible = "samsung,K3QF2F20DB", "jedec,lpddr3"; density = <16384>; io-width = <32>; + manufacturer-id = <1>; + revision-id = <123 234>; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt index a10d1f6d85c6..ac189dd82b08 100644 --- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -12,6 +12,8 @@ Required properties: for details. - center-supply: DMC supply node. - status: Marks the node enabled/disabled. +- rockchip,pmu: Phandle to the syscon managing the "PMU general register + files". Optional properties: - interrupts: The CPU interrupt number. The interrupt specifier @@ -77,24 +79,23 @@ Following properties relate to DDR timing: - rockchip,ddr3_drv : When the DRAM type is DDR3, this parameter defines the DRAM side driver strength in ohms. Default - value is DDR3_DS_40ohm. + value is 40. - rockchip,ddr3_odt : When the DRAM type is DDR3, this parameter defines the DRAM side ODT strength in ohms. Default value - is DDR3_ODT_120ohm. + is 120. - rockchip,phy_ddr3_ca_drv : When the DRAM type is DDR3, this parameter defines the phy side CA line (incluing command line, address line and clock line) driver strength. - Default value is PHY_DRV_ODT_40. + Default value is 40. - rockchip,phy_ddr3_dq_drv : When the DRAM type is DDR3, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is PHY_DRV_ODT_40. + driver strength. Default value is 40. - rockchip,phy_ddr3_odt : When the DRAM type is DDR3, this parameter defines - the PHY side ODT strength. Default value is - PHY_DRV_ODT_240. + the PHY side ODT strength. Default value is 240. - rockchip,lpddr3_odt_dis_freq : When the DRAM type is LPDDR3, this parameter defines then ODT disable frequency in MHz (Mega Hz). @@ -104,25 +105,23 @@ Following properties relate to DDR timing: - rockchip,lpddr3_drv : When the DRAM type is LPDDR3, this parameter defines the DRAM side driver strength in ohms. Default - value is LP3_DS_34ohm. + value is 34. - rockchip,lpddr3_odt : When the DRAM type is LPDDR3, this parameter defines the DRAM side ODT strength in ohms. Default value - is LP3_ODT_240ohm. + is 240. - rockchip,phy_lpddr3_ca_drv : When the DRAM type is LPDDR3, this parameter defines the PHY side CA line (including command line, address line and clock line) driver strength. - Default value is PHY_DRV_ODT_40. + Default value is 40. - rockchip,phy_lpddr3_dq_drv : When the DRAM type is LPDDR3, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is - PHY_DRV_ODT_40. + driver strength. Default value is 40. - rockchip,phy_lpddr3_odt : When dram type is LPDDR3, this parameter define - the phy side odt strength, default value is - PHY_DRV_ODT_240. + the phy side odt strength, default value is 240. - rockchip,lpddr4_odt_dis_freq : When the DRAM type is LPDDR4, this parameter defines the ODT disable frequency in @@ -132,32 +131,30 @@ Following properties relate to DDR timing: - rockchip,lpddr4_drv : When the DRAM type is LPDDR4, this parameter defines the DRAM side driver strength in ohms. Default - value is LP4_PDDS_60ohm. + value is 60. - rockchip,lpddr4_dq_odt : When the DRAM type is LPDDR4, this parameter defines the DRAM side ODT on DQS/DQ line strength in ohms. - Default value is LP4_DQ_ODT_40ohm. + Default value is 40. - rockchip,lpddr4_ca_odt : When the DRAM type is LPDDR4, this parameter defines the DRAM side ODT on CA line strength in ohms. - Default value is LP4_CA_ODT_40ohm. + Default value is 40. - rockchip,phy_lpddr4_ca_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side CA line (including command address - line) driver strength. Default value is - PHY_DRV_ODT_40. + line) driver strength. Default value is 40. - rockchip,phy_lpddr4_ck_cs_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side clock line and CS line driver - strength. Default value is PHY_DRV_ODT_80. + strength. Default value is 80. - rockchip,phy_lpddr4_dq_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is PHY_DRV_ODT_80. + driver strength. Default value is 80. - rockchip,phy_lpddr4_odt : When the DRAM type is LPDDR4, this parameter defines - the PHY side ODT strength. Default value is - PHY_DRV_ODT_60. + the PHY side ODT strength. Default value is 60. Example: dmc_opp_table: dmc_opp_table { @@ -193,23 +190,23 @@ Example: rockchip,phy_dll_dis_freq = <125>; rockchip,auto_pd_dis_freq = <666>; rockchip,ddr3_odt_dis_freq = <333>; - rockchip,ddr3_drv = <DDR3_DS_40ohm>; - rockchip,ddr3_odt = <DDR3_ODT_120ohm>; - rockchip,phy_ddr3_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_ddr3_dq_drv = <PHY_DRV_ODT_40>; - rockchip,phy_ddr3_odt = <PHY_DRV_ODT_240>; + rockchip,ddr3_drv = <40>; + rockchip,ddr3_odt = <120>; + rockchip,phy_ddr3_ca_drv = <40>; + rockchip,phy_ddr3_dq_drv = <40>; + rockchip,phy_ddr3_odt = <240>; rockchip,lpddr3_odt_dis_freq = <333>; - rockchip,lpddr3_drv = <LP3_DS_34ohm>; - rockchip,lpddr3_odt = <LP3_ODT_240ohm>; - rockchip,phy_lpddr3_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr3_dq_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr3_odt = <PHY_DRV_ODT_240>; + rockchip,lpddr3_drv = <34>; + rockchip,lpddr3_odt = <240>; + rockchip,phy_lpddr3_ca_drv = <40>; + rockchip,phy_lpddr3_dq_drv = <40>; + rockchip,phy_lpddr3_odt = <240>; rockchip,lpddr4_odt_dis_freq = <333>; - rockchip,lpddr4_drv = <LP4_PDDS_60ohm>; - rockchip,lpddr4_dq_odt = <LP4_DQ_ODT_40ohm>; - rockchip,lpddr4_ca_odt = <LP4_CA_ODT_40ohm>; - rockchip,phy_lpddr4_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr4_ck_cs_drv = <PHY_DRV_ODT_80>; - rockchip,phy_lpddr4_dq_drv = <PHY_DRV_ODT_80>; - rockchip,phy_lpddr4_odt = <PHY_DRV_ODT_60>; + rockchip,lpddr4_drv = <60>; + rockchip,lpddr4_dq_odt = <40>; + rockchip,lpddr4_ca_odt = <40>; + rockchip,phy_lpddr4_ca_drv = <40>; + rockchip,phy_lpddr4_ck_cs_drv = <80>; + rockchip,phy_lpddr4_dq_drv = <80>; + rockchip,phy_lpddr4_odt = <60>; }; diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml index c13faf3e6581..3a7d5d731712 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml @@ -73,7 +73,6 @@ properties: clock-output-names: description: Name of the LCD pixel clock created. - $ref: /schemas/types.yaml#/definitions/string-array maxItems: 1 dmas: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml index b3e9992525c2..907fb47cc84a 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml @@ -12,8 +12,8 @@ description: | and CEC. These DT bindings follow the Synopsys DWC HDMI TX bindings defined - in Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with - the following device-specific properties. + in bridge/synopsys,dw-hdmi.yaml with the following device-specific + properties. maintainers: - Chen-Yu Tsai <wens@csie.org> diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml index 55c60919991f..32608578a352 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml @@ -77,12 +77,6 @@ examples: clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr"; - pitouchscreen: panel@0 { - compatible = "raspberrypi,touchscreen"; - reg = <0>; - - /* ... */ - }; }; ... diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml index c789784efe30..ab48ab2f4240 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -34,6 +34,15 @@ properties: description: used for reset chip control, RESET_N pin B7. maxItems: 1 + vdd10-supply: + description: Regulator that provides the supply 1.0V power. + + vdd18-supply: + description: Regulator that provides the supply 1.8V power. + + vdd33-supply: + description: Regulator that provides the supply 3.3V power. + ports: $ref: /schemas/graph.yaml#/properties/ports @@ -55,6 +64,9 @@ properties: required: - compatible - reg + - vdd10-supply + - vdd18-supply + - vdd33-supply - ports additionalProperties: false @@ -72,6 +84,9 @@ examples: reg = <0x58>; enable-gpios = <&pio 45 GPIO_ACTIVE_HIGH>; reset-gpios = <&pio 73 GPIO_ACTIVE_HIGH>; + vdd10-supply = <&pp1000_mipibrdg>; + vdd18-supply = <&pp1800_mipibrdg>; + vdd33-supply = <&pp3300_mipibrdg>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml new file mode 100644 index 000000000000..62c3bd4cb28d --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/chipone,icn6211.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Chipone ICN6211 MIPI-DSI to RGB Converter bridge + +maintainers: + - Jagan Teki <jagan@amarulasolutions.com> + +description: | + ICN6211 is MIPI-DSI to RGB Converter bridge from chipone. + + It has a flexible configuration of MIPI DSI signal input and + produce RGB565, RGB666, RGB888 output format. + +properties: + compatible: + enum: + - chipone,icn6211 + + reg: + maxItems: 1 + description: virtual channel number of a DSI peripheral + + enable-gpios: + description: Bridge EN pin, chip is reset when EN is low. + + vdd1-supply: + description: A 1.8V/2.5V/3.3V supply that power the MIPI RX. + + vdd2-supply: + description: A 1.8V/2.5V/3.3V supply that power the PLL. + + vdd3-supply: + description: A 1.8V/2.5V/3.3V supply that power the RGB output. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for MIPI DSI input + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for MIPI DPI output (panel or connector). + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - enable-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + bridge@0 { + compatible = "chipone,icn6211"; + reg = <0>; + enable-gpios = <&r_pio 0 5 GPIO_ACTIVE_HIGH>; /* LCD-RST: PL5 */ + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + bridge_in_dsi: endpoint { + remote-endpoint = <&dsi_out_bridge>; + }; + }; + + port@1 { + reg = <1>; + + bridge_out_panel: endpoint { + remote-endpoint = <&panel_out_bridge>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt deleted file mode 100644 index 33bf981fbe33..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt +++ /dev/null @@ -1,33 +0,0 @@ -Synopsys DesignWare HDMI TX Encoder -=================================== - -This document defines device tree properties for the Synopsys DesignWare HDMI -TX Encoder (DWC HDMI TX). It doesn't constitue a device tree binding -specification by itself but is meant to be referenced by platform-specific -device tree bindings. - -When referenced from platform device tree bindings the properties defined in -this document are defined as follows. The platform device tree bindings are -responsible for defining whether each property is required or optional. - -- reg: Memory mapped base address and length of the DWC HDMI TX registers. - -- reg-io-width: Width of the registers specified by the reg property. The - value is expressed in bytes and must be equal to 1 or 4 if specified. The - register width defaults to 1 if the property is not present. - -- interrupts: Reference to the DWC HDMI TX interrupt. - -- clocks: References to all the clocks specified in the clock-names property - as specified in Documentation/devicetree/bindings/clock/clock-bindings.txt. - -- clock-names: The DWC HDMI TX uses the following clocks. - - - "iahb" is the bus clock for either AHB and APB (mandatory). - - "isfr" is the internal register configuration clock (mandatory). - - "cec" is the HDMI CEC controller main clock (optional). - -- ports: The connectivity of the DWC HDMI TX with the rest of the system is - expressed in using ports as specified in the device graph bindings defined - in Documentation/devicetree/bindings/graph.txt. The numbering of the ports - is platform-specific. diff --git a/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml b/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml new file mode 100644 index 000000000000..735d0233a7d6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/lontium,lt8912b.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lontium LT8912B MIPI to HDMI Bridge + +maintainers: + - Adrien Grassein <adrien.grassein@gmail.com> + +description: | + The LT8912B is a bridge device which convert DSI to HDMI + +properties: + compatible: + enum: + - lontium,lt8912b + + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: GPIO connected to active high RESET pin. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Primary MIPI port for MIPI input + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: | + HDMI port, should be connected to a node compatible with the + hdmi-connector binding. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - reset-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c4 { + #address-cells = <1>; + #size-cells = <0>; + + hdmi-bridge@48 { + compatible = "lontium,lt8912b"; + reg = <0x48>; + reset-gpios = <&max7323 0 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + hdmi_out_in: endpoint { + data-lanes = <0 1 2 3>; + remote-endpoint = <&mipi_dsi_out>; + }; + }; + + port@1 { + reg = <1>; + + endpoint { + remote-endpoint = <&hdmi_in>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt deleted file mode 100644 index 3f6072651182..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +++ /dev/null @@ -1,88 +0,0 @@ -Renesas Gen3 DWC HDMI TX Encoder -================================ - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible : Shall contain one or more of - - "renesas,r8a774a1-hdmi" for R8A774A1 (RZ/G2M) compatible HDMI TX - - "renesas,r8a774b1-hdmi" for R8A774B1 (RZ/G2N) compatible HDMI TX - - "renesas,r8a774e1-hdmi" for R8A774E1 (RZ/G2H) compatible HDMI TX - - "renesas,r8a7795-hdmi" for R8A7795 (R-Car H3) compatible HDMI TX - - "renesas,r8a7796-hdmi" for R8A7796 (R-Car M3-W) compatible HDMI TX - - "renesas,r8a77961-hdmi" for R8A77961 (R-Car M3-W+) compatible HDMI TX - - "renesas,r8a77965-hdmi" for R8A77965 (R-Car M3-N) compatible HDMI TX - - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 and RZ/G2 compatible - HDMI TX - - When compatible with generic versions, nodes must list the SoC-specific - version corresponding to the platform first, followed by the - family-specific version. - -- reg: See dw_hdmi.txt. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have one port numbered 0 - corresponding to the video input of the controller and one port numbered 1 - corresponding to its HDMI output, and one port numbered 2 corresponding to - sound input of the controller. Each port shall have a single endpoint. - -Optional properties: - -- power-domains: Shall reference the power domain that contains the DWC HDMI, - if any. - - -Example: - - hdmi0: hdmi@fead0000 { - compatible = "renesas,r8a7795-hdmi", "renesas,rcar-gen3-hdmi"; - reg = <0 0xfead0000 0 0x10000>; - interrupts = <0 389 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; - clock-names = "iahb", "isfr"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - dw_hdmi0_in: endpoint { - remote-endpoint = <&du_out_hdmi0>; - }; - }; - port@1 { - reg = <1>; - rcar_dw_hdmi0_out: endpoint { - remote-endpoint = <&hdmi0_con>; - }; - }; - port@2 { - reg = <2>; - rcar_dw_hdmi0_sound_in: endpoint { - remote-endpoint = <&hdmi_sound_out>; - }; - }; - }; - }; - - hdmi0-out { - compatible = "hdmi-connector"; - label = "HDMI0 OUT"; - type = "a"; - - port { - hdmi0_con: endpoint { - remote-endpoint = <&rcar_dw_hdmi0_out>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml new file mode 100644 index 000000000000..0c9785c8db51 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/renesas,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car DWC HDMI TX Encoder + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: synopsys,dw-hdmi.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r8a774a1-hdmi # for RZ/G2M compatible HDMI TX + - renesas,r8a774b1-hdmi # for RZ/G2N compatible HDMI TX + - renesas,r8a774e1-hdmi # for RZ/G2H compatible HDMI TX + - renesas,r8a7795-hdmi # for R-Car H3 compatible HDMI TX + - renesas,r8a7796-hdmi # for R-Car M3-W compatible HDMI TX + - renesas,r8a77961-hdmi # for R-Car M3-W+ compatible HDMI TX + - renesas,r8a77965-hdmi # for R-Car M3-N compatible HDMI TX + - const: renesas,rcar-gen3-hdmi + + reg-io-width: + const: 1 + + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Parallel RGB input port + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: HDMI output port + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: Sound input port + + required: + - port@0 + - port@1 + - port@2 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - ports + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + hdmi@fead0000 { + compatible = "renesas,r8a7795-hdmi", "renesas,rcar-gen3-hdmi"; + reg = <0xfead0000 0x10000>; + interrupts = <0 389 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; + clock-names = "iahb", "isfr"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + dw_hdmi0_in: endpoint { + remote-endpoint = <&du_out_hdmi0>; + }; + }; + port@1 { + reg = <1>; + rcar_dw_hdmi0_out: endpoint { + remote-endpoint = <&hdmi0_con>; + }; + }; + port@2 { + reg = <2>; + rcar_dw_hdmi0_sound_in: endpoint { + remote-endpoint = <&hdmi_sound_out>; + }; + }; + }; + }; + + hdmi0-out { + compatible = "hdmi-connector"; + label = "HDMI0 OUT"; + type = "a"; + + port { + hdmi0_con: endpoint { + remote-endpoint = <&rcar_dw_hdmi0_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml new file mode 100644 index 000000000000..9be44a682e67 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/synopsys,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common Properties for Synopsys DesignWare HDMI TX Controller + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + This document defines device tree properties for the Synopsys DesignWare HDMI + TX controller (DWC HDMI TX) IP core. It doesn't constitute a full device tree + binding specification by itself but is meant to be referenced by device tree + bindings for the platform-specific integrations of the DWC HDMI TX. + + When referenced from platform device tree bindings the properties defined in + this document are defined as follows. The platform device tree bindings are + responsible for defining whether each property is required or optional. + +properties: + reg: + maxItems: 1 + + reg-io-width: + description: + Width (in bytes) of the registers specified by the reg property. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [1, 4] + default: 1 + + clocks: + minItems: 2 + maxItems: 5 + items: + - description: The bus clock for either AHB and APB + - description: The internal register configuration clock + additionalItems: true + + clock-names: + minItems: 2 + maxItems: 5 + items: + - const: iahb + - const: isfr + additionalItems: true + + interrupts: + maxItems: 1 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml new file mode 100644 index 000000000000..a4c3064c778c --- /dev/null +++ b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/fsl,lcdif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale/NXP i.MX LCD Interface (LCDIF) + +maintainers: + - Marek Vasut <marex@denx.de> + - Stefan Agner <stefan@agner.ch> + +description: | + (e)LCDIF display controller found in the Freescale/NXP i.MX SoCs. + +properties: + compatible: + oneOf: + - enum: + - fsl,imx23-lcdif + - fsl,imx28-lcdif + - fsl,imx6sx-lcdif + - items: + - enum: + - fsl,imx6sl-lcdif + - fsl,imx6sll-lcdif + - fsl,imx6ul-lcdif + - fsl,imx7d-lcdif + - fsl,imx8mm-lcdif + - fsl,imx8mq-lcdif + - const: fsl,imx6sx-lcdif + + reg: + maxItems: 1 + + clocks: + items: + - description: Pixel clock + - description: Bus clock + - description: Display AXI clock + minItems: 1 + + clock-names: + items: + - const: pix + - const: axi + - const: disp_axi + minItems: 1 + + interrupts: + maxItems: 1 + + port: + $ref: /schemas/graph.yaml#/properties/port + description: The LCDIF output port + +required: + - compatible + - reg + - clocks + - interrupts + - port + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: fsl,imx6sx-lcdif + then: + properties: + clocks: + minItems: 2 + maxItems: 3 + clock-names: + minItems: 2 + maxItems: 3 + required: + - clock-names + else: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + +examples: + - | + #include <dt-bindings/clock/imx6sx-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display-controller@2220000 { + compatible = "fsl,imx6sx-lcdif"; + reg = <0x02220000 0x4000>; + interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6SX_CLK_LCDIF1_PIX>, + <&clks IMX6SX_CLK_LCDIF_APB>, + <&clks IMX6SX_CLK_DISPLAY_AXI>; + clock-names = "pix", "axi", "disp_axi"; + + port { + endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml new file mode 100644 index 000000000000..af7fe9c4d196 --- /dev/null +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/imx/fsl,imx6-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX6 DWC HDMI TX Encoder + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: ../bridge/synopsys,dw-hdmi.yaml# + +properties: + compatible: + enum: + - fsl,imx6dl-hdmi + - fsl,imx6q-hdmi + + reg-io-width: + const: 1 + + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + + ddc-i2c-bus: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The HDMI DDC bus can be connected to either a system I2C master or the + functionally-reduced I2C master contained in the DWC HDMI. When connected + to a system I2C master this property contains a phandle to that I2C + master controller. + + gpr: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the iomuxc-gpr region containing the HDMI multiplexer control + register. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + description: | + This device has four video ports, corresponding to the four inputs of the + HDMI multiplexer. Each port shall have a single endpoint. + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: First input of the HDMI multiplexer + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: Second input of the HDMI multiplexer + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: Third input of the HDMI multiplexer + + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: Fourth input of the HDMI multiplexer + + anyOf: + - required: + - port@0 + - required: + - port@1 + - required: + - port@2 + - required: + - port@3 + +required: + - compatible + - reg + - clocks + - clock-names + - gpr + - interrupts + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx6qdl-clock.h> + + hdmi: hdmi@120000 { + reg = <0x00120000 0x9000>; + interrupts = <0 115 0x04>; + gpr = <&gpr>; + clocks = <&clks IMX6QDL_CLK_HDMI_IAHB>, + <&clks IMX6QDL_CLK_HDMI_ISFR>; + clock-names = "iahb", "isfr"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + hdmi_mux_0: endpoint { + remote-endpoint = <&ipu1_di0_hdmi>; + }; + }; + + port@1 { + reg = <1>; + + hdmi_mux_1: endpoint { + remote-endpoint = <&ipu1_di1_hdmi>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/imx/hdmi.txt b/Documentation/devicetree/bindings/display/imx/hdmi.txt deleted file mode 100644 index 6d021e71c9cf..000000000000 --- a/Documentation/devicetree/bindings/display/imx/hdmi.txt +++ /dev/null @@ -1,65 +0,0 @@ -Freescale i.MX6 DWC HDMI TX Encoder -=================================== - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible : Shall be one of "fsl,imx6q-hdmi" or "fsl,imx6dl-hdmi". -- reg: See dw_hdmi.txt. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have between one and four ports, - numbered 0 to 3, corresponding to the four inputs of the HDMI multiplexer. - Each port shall have a single endpoint. -- gpr : Shall contain a phandle to the iomuxc-gpr region containing the HDMI - multiplexer control register. - -Optional properties - -- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master - or the functionally-reduced I2C master contained in the DWC HDMI. When - connected to a system I2C master this property contains a phandle to that - I2C master controller. - - -Example: - - gpr: iomuxc-gpr@20e0000 { - /* ... */ - }; - - hdmi: hdmi@120000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,imx6q-hdmi"; - reg = <0x00120000 0x9000>; - interrupts = <0 115 0x04>; - gpr = <&gpr>; - clocks = <&clks 123>, <&clks 124>; - clock-names = "iahb", "isfr"; - ddc-i2c-bus = <&i2c2>; - - port@0 { - reg = <0>; - - hdmi_mux_0: endpoint { - remote-endpoint = <&ipu1_di0_hdmi>; - }; - }; - - port@1 { - reg = <1>; - - hdmi_mux_1: endpoint { - remote-endpoint = <&ipu1_di1_hdmi>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index 93b160df3eec..fbb59c9ddda6 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -64,7 +64,7 @@ Required properties (DMA function blocks): - larb: Should contain a phandle pointing to the local arbiter device as defined in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml - iommus: Should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Optional properties (RDMA function blocks): diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml index 6cdb734c91a9..dd2896a40ff0 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml @@ -22,6 +22,7 @@ properties: - mediatek,mt7623-dpi - mediatek,mt8173-dpi - mediatek,mt8183-dpi + - mediatek,mt8192-dpi reg: maxItems: 1 @@ -50,15 +51,10 @@ properties: - const: sleep port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - Output port node with endpoint definitions as described in - Documentation/devicetree/bindings/graph.txt. This port should be connected - to the input port of an attached HDMI or LVDS encoder chip. - - properties: - endpoint: - type: object + Output port node. This port should be connected to the input port of an + attached HDMI or LVDS encoder chip. required: - compatible diff --git a/Documentation/devicetree/bindings/display/msm/dpu.txt b/Documentation/devicetree/bindings/display/msm/dpu.txt index 551ae26f60da..586e6eac5b08 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu.txt +++ b/Documentation/devicetree/bindings/display/msm/dpu.txt @@ -2,14 +2,14 @@ Qualcomm Technologies, Inc. DPU KMS Description: -Device tree bindings for MSM Mobile Display Subsytem(MDSS) that encapsulates +Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates sub-blocks like DPU display controller, DSI and DP interfaces etc. The DPU display controller is found in SDM845 SoC. MDSS: Required properties: - compatible: "qcom,sdm845-mdss", "qcom,sc7180-mdss" -- reg: physical base address and length of contoller's registers. +- reg: physical base address and length of controller's registers. - reg-names: register region names. The following region is required: * "mdss" - power-domains: a power domain consumer specifier according to diff --git a/Documentation/devicetree/bindings/display/mxsfb.txt b/Documentation/devicetree/bindings/display/mxsfb.txt deleted file mode 100644 index c985871c46b3..000000000000 --- a/Documentation/devicetree/bindings/display/mxsfb.txt +++ /dev/null @@ -1,87 +0,0 @@ -* Freescale MXS LCD Interface (LCDIF) - -New bindings: -============= -Required properties: -- compatible: Should be "fsl,imx23-lcdif" for i.MX23. - Should be "fsl,imx28-lcdif" for i.MX28. - Should be "fsl,imx6sx-lcdif" for i.MX6SX. - Should be "fsl,imx8mq-lcdif" for i.MX8MQ. -- reg: Address and length of the register set for LCDIF -- interrupts: Should contain LCDIF interrupt -- clocks: A list of phandle + clock-specifier pairs, one for each - entry in 'clock-names'. -- clock-names: A list of clock names. For MXSFB it should contain: - - "pix" for the LCDIF block clock - - (MX6SX-only) "axi", "disp_axi" for the bus interface clock - -Required sub-nodes: - - port: The connection to an encoder chip. - -Example: - - lcdif1: display-controller@2220000 { - compatible = "fsl,imx6sx-lcdif", "fsl,imx28-lcdif"; - reg = <0x02220000 0x4000>; - interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX6SX_CLK_LCDIF1_PIX>, - <&clks IMX6SX_CLK_LCDIF_APB>, - <&clks IMX6SX_CLK_DISPLAY_AXI>; - clock-names = "pix", "axi", "disp_axi"; - - port { - parallel_out: endpoint { - remote-endpoint = <&panel_in_parallel>; - }; - }; - }; - -Deprecated bindings: -==================== -Required properties: -- compatible: Should be "fsl,imx23-lcdif" for i.MX23. - Should be "fsl,imx28-lcdif" for i.MX28. -- reg: Address and length of the register set for LCDIF -- interrupts: Should contain LCDIF interrupts -- display: phandle to display node (see below for details) - -* display node - -Required properties: -- bits-per-pixel: <16> for RGB565, <32> for RGB888/666. -- bus-width: number of data lines. Could be <8>, <16>, <18> or <24>. - -Required sub-node: -- display-timings: Refer to binding doc display-timing.txt for details. - -Examples: - -lcdif@80030000 { - compatible = "fsl,imx28-lcdif"; - reg = <0x80030000 2000>; - interrupts = <38 86>; - - display: display { - bits-per-pixel = <32>; - bus-width = <24>; - - display-timings { - native-mode = <&timing0>; - timing0: timing0 { - clock-frequency = <33500000>; - hactive = <800>; - vactive = <480>; - hfront-porch = <164>; - hback-porch = <89>; - hsync-len = <10>; - vback-porch = <23>; - vfront-porch = <10>; - vsync-len = <10>; - hsync-active = <0>; - vsync-active = <0>; - de-active = <1>; - pixelclk-active = <0>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml index 6960036975fa..c45c92a3d41f 100644 --- a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml +++ b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml @@ -47,7 +47,6 @@ examples: spi-max-frequency = <3125000>; spi-3wire; - spi-cs-high; reset-gpios = <&gpe 2 GPIO_ACTIVE_LOW>; diff --git a/Documentation/devicetree/bindings/display/panel/panel-dpi.yaml b/Documentation/devicetree/bindings/display/panel/panel-dpi.yaml index 0cd74c8dab42..dae0676b5c6e 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-dpi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-dpi.yaml @@ -40,7 +40,7 @@ additionalProperties: false examples: - | panel { - compatible = "osddisplays,osd057T0559-34ts", "panel-dpi"; + compatible = "startek,startek-kd050c", "panel-dpi"; label = "osddisplay"; power-supply = <&vcc_supply>; backlight = <&backlight>; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 62b0d54d87b7..b3797ba2698b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -161,6 +161,8 @@ properties: # Innolux Corporation 12.1" G121X1-L03 XGA (1024x768) TFT LCD panel - innolux,g121x1-l03 # Innolux Corporation 11.6" WXGA (1366x768) TFT LCD panel + - innolux,n116bca-ea1 + # Innolux Corporation 11.6" WXGA (1366x768) TFT LCD panel - innolux,n116bge # InnoLux 13.3" FHD (1920x1080) eDP TFT LCD panel - innolux,n125hce-gn1 diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt deleted file mode 100644 index 7d65c24fcda8..000000000000 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ /dev/null @@ -1,145 +0,0 @@ -* Renesas R-Car Display Unit (DU) - -Required Properties: - - - compatible: must be one of the following. - - "renesas,du-r8a7742" for R8A7742 (RZ/G1H) compatible DU - - "renesas,du-r8a7743" for R8A7743 (RZ/G1M) compatible DU - - "renesas,du-r8a7744" for R8A7744 (RZ/G1N) compatible DU - - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU - - "renesas,du-r8a77470" for R8A77470 (RZ/G1C) compatible DU - - "renesas,du-r8a774a1" for R8A774A1 (RZ/G2M) compatible DU - - "renesas,du-r8a774b1" for R8A774B1 (RZ/G2N) compatible DU - - "renesas,du-r8a774c0" for R8A774C0 (RZ/G2E) compatible DU - - "renesas,du-r8a774e1" for R8A774E1 (RZ/G2H) compatible DU - - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU - - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU - - "renesas,du-r8a7792" for R8A7792 (R-Car V2H) compatible DU - - "renesas,du-r8a7793" for R8A7793 (R-Car M2-N) compatible DU - - "renesas,du-r8a7794" for R8A7794 (R-Car E2) compatible DU - - "renesas,du-r8a7795" for R8A7795 (R-Car H3) compatible DU - - "renesas,du-r8a7796" for R8A7796 (R-Car M3-W) compatible DU - - "renesas,du-r8a77961" for R8A77961 (R-Car M3-W+) compatible DU - - "renesas,du-r8a77965" for R8A77965 (R-Car M3-N) compatible DU - - "renesas,du-r8a77970" for R8A77970 (R-Car V3M) compatible DU - - "renesas,du-r8a77980" for R8A77980 (R-Car V3H) compatible DU - - "renesas,du-r8a77990" for R8A77990 (R-Car E3) compatible DU - - "renesas,du-r8a77995" for R8A77995 (R-Car D3) compatible DU - - - reg: the memory-mapped I/O registers base address and length - - - interrupts: Interrupt specifiers for the DU interrupts. - - - clocks: A list of phandles + clock-specifier pairs, one for each entry in - the clock-names property. - - clock-names: Name of the clocks. This property is model-dependent. - - R8A7779 uses a single functional clock. The clock doesn't need to be - named. - - All other DU instances use one functional clock per channel The - functional clocks must be named "du.x" with "x" being the channel - numerical index. - - In addition to the functional clocks, all DU versions also support - externally supplied pixel clocks. Those clocks are optional. When - supplied they must be named "dclkin.x" with "x" being the input clock - numerical index. - - - renesas,cmms: A list of phandles to the CMM instances present in the SoC, - one for each available DU channel. The property shall not be specified for - SoCs that do not provide any CMM (such as V3M and V3H). - - - renesas,vsps: A list of phandle and channel index tuples to the VSPs that - handle the memory interfaces for the DU channels. The phandle identifies the - VSP instance that serves the DU channel, and the channel index identifies - the LIF instance in that VSP. - -Optional properties: - - resets: A list of phandle + reset-specifier pairs, one for each entry in - the reset-names property. - - reset-names: Names of the resets. This property is model-dependent. - - All but R8A7779 use one reset for a group of one or more successive - channels. The resets must be named "du.x" with "x" being the numerical - index of the lowest channel in the group. - -Required nodes: - -The connections to the DU output video ports are modeled using the OF graph -bindings specified in Documentation/devicetree/bindings/graph.txt. - -The following table lists for each supported model the port number -corresponding to each DU output. - - Port0 Port1 Port2 Port3 ------------------------------------------------------------------------------ - R8A7742 (RZ/G1H) DPAD 0 LVDS 0 LVDS 1 - - R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - - R8A7744 (RZ/G1N) DPAD 0 LVDS 0 - - - R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - - R8A77470 (RZ/G1C) DPAD 0 DPAD 1 LVDS 0 - - R8A774A1 (RZ/G2M) DPAD 0 HDMI 0 LVDS 0 - - R8A774B1 (RZ/G2N) DPAD 0 HDMI 0 LVDS 0 - - R8A774C0 (RZ/G2E) DPAD 0 LVDS 0 LVDS 1 - - R8A774E1 (RZ/G2H) DPAD 0 HDMI 0 LVDS 0 - - R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - - R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - - R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - - R8A7792 (R-Car V2H) DPAD 0 DPAD 1 - - - R8A7793 (R-Car M2-N) DPAD 0 LVDS 0 - - - R8A7794 (R-Car E2) DPAD 0 DPAD 1 - - - R8A7795 (R-Car H3) DPAD 0 HDMI 0 HDMI 1 LVDS 0 - R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - - R8A77961 (R-Car M3-W+) DPAD 0 HDMI 0 LVDS 0 - - R8A77965 (R-Car M3-N) DPAD 0 HDMI 0 LVDS 0 - - R8A77970 (R-Car V3M) DPAD 0 LVDS 0 - - - R8A77980 (R-Car V3H) DPAD 0 LVDS 0 - - - R8A77990 (R-Car E3) DPAD 0 LVDS 0 LVDS 1 - - R8A77995 (R-Car D3) DPAD 0 LVDS 0 LVDS 1 - - - -Example: R8A7795 (R-Car H3) ES2.0 DU - - du: display@feb00000 { - compatible = "renesas,du-r8a7795"; - reg = <0 0xfeb00000 0 0x80000>; - interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 270 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 724>, - <&cpg CPG_MOD 723>, - <&cpg CPG_MOD 722>, - <&cpg CPG_MOD 721>; - clock-names = "du.0", "du.1", "du.2", "du.3"; - resets = <&cpg 724>, <&cpg 722>; - reset-names = "du.0", "du.2"; - renesas,cmms = <&cmm0>, <&cmm1>, <&cmm2>, <&cmm3>; - renesas,vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - du_out_rgb: endpoint { - }; - }; - port@1 { - reg = <1>; - du_out_hdmi0: endpoint { - remote-endpoint = <&dw_hdmi0_in>; - }; - }; - port@2 { - reg = <2>; - du_out_hdmi1: endpoint { - remote-endpoint = <&dw_hdmi1_in>; - }; - }; - port@3 { - reg = <3>; - du_out_lvds0: endpoint { - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/renesas,du.yaml b/Documentation/devicetree/bindings/display/renesas,du.yaml new file mode 100644 index 000000000000..121596f106da --- /dev/null +++ b/Documentation/devicetree/bindings/display/renesas,du.yaml @@ -0,0 +1,834 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/renesas,du.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Display Unit (DU) + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + These DT bindings describe the Display Unit embedded in the Renesas R-Car + Gen1, R-Car Gen2, R-Car Gen3, RZ/G1 and RZ/G2 SoCs. + +properties: + compatible: + enum: + - renesas,du-r8a7742 # for RZ/G1H compatible DU + - renesas,du-r8a7743 # for RZ/G1M compatible DU + - renesas,du-r8a7744 # for RZ/G1N compatible DU + - renesas,du-r8a7745 # for RZ/G1E compatible DU + - renesas,du-r8a77470 # for RZ/G1C compatible DU + - renesas,du-r8a774a1 # for RZ/G2M compatible DU + - renesas,du-r8a774b1 # for RZ/G2N compatible DU + - renesas,du-r8a774c0 # for RZ/G2E compatible DU + - renesas,du-r8a774e1 # for RZ/G2H compatible DU + - renesas,du-r8a7779 # for R-Car H1 compatible DU + - renesas,du-r8a7790 # for R-Car H2 compatible DU + - renesas,du-r8a7791 # for R-Car M2-W compatible DU + - renesas,du-r8a7792 # for R-Car V2H compatible DU + - renesas,du-r8a7793 # for R-Car M2-N compatible DU + - renesas,du-r8a7794 # for R-Car E2 compatible DU + - renesas,du-r8a7795 # for R-Car H3 compatible DU + - renesas,du-r8a7796 # for R-Car M3-W compatible DU + - renesas,du-r8a77961 # for R-Car M3-W+ compatible DU + - renesas,du-r8a77965 # for R-Car M3-N compatible DU + - renesas,du-r8a77970 # for R-Car V3M compatible DU + - renesas,du-r8a77980 # for R-Car V3H compatible DU + - renesas,du-r8a77990 # for R-Car E3 compatible DU + - renesas,du-r8a77995 # for R-Car D3 compatible DU + + reg: + maxItems: 1 + + # See compatible-specific constraints below. + clocks: true + clock-names: true + interrupts: + description: Interrupt specifiers, one per DU channel + resets: true + reset-names: true + + power-domains: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/port + description: | + The connections to the DU output video ports are modeled using the OF + graph bindings specified in Documentation/devicetree/bindings/graph.txt. + The number of ports and their assignment are model-dependent. Each port + shall have a single endpoint. + + patternProperties: + "^port@[0-3]$": + $ref: /schemas/graph.yaml#/properties/port + unevaluatedProperties: false + + required: + - port@0 + - port@1 + + unevaluatedProperties: false + + renesas,cmms: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: + A list of phandles to the CMM instances present in the SoC, one for each + available DU channel. + + renesas,vsps: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: + A list of phandle and channel index tuples to the VSPs that handle the + memory interfaces for the DU channels. The phandle identifies the VSP + instance that serves the DU channel, and the channel index identifies + the LIF instance in that VSP. + +required: + - compatible + - reg + - clocks + - interrupts + - resets + - ports + +allOf: + - if: + properties: + compatible: + contains: + const: renesas,du-r8a7779 + then: + properties: + clocks: + minItems: 1 + maxItems: 3 + items: + - description: Functional clock + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 1 + maxItems: 3 + items: + - const: du.0 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - interrupts + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7743 + - renesas,du-r8a7744 + - renesas,du-r8a7791 + - renesas,du-r8a7793 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7745 + - renesas,du-r8a7792 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7794 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a77470 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + port@2: + description: LVDS 0 + # port@3 is DVENC, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7742 + - renesas,du-r8a7790 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: + description: LVDS 1 + # port@3 is TCON, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7795 + then: + properties: + clocks: + minItems: 4 + maxItems: 8 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: Functional clock for DU4 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + - description: DU_DOTCLKIN3 input clock + + clock-names: + minItems: 4 + maxItems: 8 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - const: du.3 + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + + interrupts: + maxItems: 4 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.2 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: HDMI 1 + port@3: + description: LVDS 0 + + required: + - port@0 + - port@1 + - port@2 + - port@3 + + renesas,cmms: + minItems: 4 + + renesas,vsps: + minItems: 4 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774a1 + - renesas,du-r8a7796 + - renesas,du-r8a77961 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.2 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: LVDS 0 + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 3 + + renesas,vsps: + minItems: 3 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774b1 + - renesas,du-r8a774e1 + - renesas,du-r8a77965 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU3 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN3 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.3 + - pattern: '^dclkin\.[013]$' + - pattern: '^dclkin\.[013]$' + - pattern: '^dclkin\.[013]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.3 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: LVDS 0 + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 3 + + renesas,vsps: + minItems: 3 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a77970 + - renesas,du-r8a77980 + then: + properties: + clocks: + minItems: 1 + maxItems: 2 + items: + - description: Functional clock for DU0 + - description: DU_DOTCLKIN0 input clock + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: du.0 + - const: dclkin.0 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + renesas,vsps: + minItems: 1 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774c0 + - renesas,du-r8a77990 + - renesas,du-r8a77995 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: + description: LVDS 1 + # port@3 is TCON, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 2 + + renesas,vsps: + minItems: 2 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + +additionalProperties: false + +examples: + # R-Car H3 ES2.0 DU + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display@feb00000 { + compatible = "renesas,du-r8a7795"; + reg = <0xfeb00000 0x80000>; + interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 270 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 724>, + <&cpg CPG_MOD 723>, + <&cpg CPG_MOD 722>, + <&cpg CPG_MOD 721>; + clock-names = "du.0", "du.1", "du.2", "du.3"; + resets = <&cpg 724>, <&cpg 722>; + reset-names = "du.0", "du.2"; + + renesas,cmms = <&cmm0>, <&cmm1>, <&cmm2>, <&cmm3>; + renesas,vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&adv7123_in>; + }; + }; + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&dw_hdmi0_in>; + }; + }; + port@2 { + reg = <2>; + endpoint { + remote-endpoint = <&dw_hdmi1_in>; + }; + }; + port@3 { + reg = <3>; + endpoint { + remote-endpoint = <&lvds0_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt deleted file mode 100644 index 3d32ce137e7f..000000000000 --- a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt +++ /dev/null @@ -1,74 +0,0 @@ -Rockchip DWC HDMI TX Encoder -============================ - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible: should be one of the following: - "rockchip,rk3228-dw-hdmi" - "rockchip,rk3288-dw-hdmi" - "rockchip,rk3328-dw-hdmi" - "rockchip,rk3399-dw-hdmi" -- reg: See dw_hdmi.txt. -- reg-io-width: See dw_hdmi.txt. Shall be 4. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have a single port numbered 0 - corresponding to the video input of the controller. The port shall have two - endpoints, numbered 0 and 1, connected respectively to the vopb and vopl. -- rockchip,grf: Shall reference the GRF to mux vopl/vopb. - -Optional properties - -- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master - or the functionally-reduced I2C master contained in the DWC HDMI. When - connected to a system I2C master this property contains a phandle to that - I2C master controller. -- clock-names: See dw_hdmi.txt. The "cec" clock is optional. -- clock-names: May contain "cec" as defined in dw_hdmi.txt. -- clock-names: May contain "grf", power for grf io. -- clock-names: May contain "vpll", external clock for some hdmi phy. -- phys: from general PHY binding: the phandle for the PHY device. -- phy-names: Should be "hdmi" if phys references an external phy. - -Optional pinctrl entry: -- If you have both a "unwedge" and "default" pinctrl entry, dw_hdmi - will switch to the unwedge pinctrl state for 10ms if it ever gets an - i2c timeout. It's intended that this unwedge pinctrl entry will - cause the SDA line to be driven low to work around a hardware - errata. - -Example: - -hdmi: hdmi@ff980000 { - compatible = "rockchip,rk3288-dw-hdmi"; - reg = <0xff980000 0x20000>; - reg-io-width = <4>; - ddc-i2c-bus = <&i2c5>; - rockchip,grf = <&grf>; - interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; - clock-names = "iahb", "isfr"; - ports { - hdmi_in: port { - #address-cells = <1>; - #size-cells = <0>; - hdmi_in_vopb: endpoint@0 { - reg = <0>; - remote-endpoint = <&vopb_out_hdmi>; - }; - hdmi_in_vopl: endpoint@1 { - reg = <1>; - remote-endpoint = <&vopl_out_hdmi>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml new file mode 100644 index 000000000000..75cd9c686e98 --- /dev/null +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml @@ -0,0 +1,156 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/rockchip/rockchip,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip DWC HDMI TX Encoder + +maintainers: + - Mark Yao <markyao0591@gmail.com> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: ../bridge/synopsys,dw-hdmi.yaml# + +properties: + compatible: + enum: + - rockchip,rk3228-dw-hdmi + - rockchip,rk3288-dw-hdmi + - rockchip,rk3328-dw-hdmi + - rockchip,rk3399-dw-hdmi + + reg-io-width: + const: 4 + + clocks: + minItems: 2 + maxItems: 5 + items: + - {} + - {} + # The next three clocks are all optional, but shall be specified in this + # order when present. + - description: The HDMI CEC controller main clock + - description: Power for GRF IO + - description: External clock for some HDMI PHY + + clock-names: + minItems: 2 + maxItems: 5 + items: + - {} + - {} + - enum: + - cec + - grf + - vpll + - enum: + - grf + - vpll + - const: vpll + + ddc-i2c-bus: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The HDMI DDC bus can be connected to either a system I2C master or the + functionally-reduced I2C master contained in the DWC HDMI. When connected + to a system I2C master this property contains a phandle to that I2C + master controller. + + phys: + maxItems: 1 + description: The HDMI PHY + + phy-names: + const: hdmi + + pinctrl-names: + description: + The unwedge pinctrl entry shall drive the DDC SDA line low. This is + intended to work around a hardware errata that can cause the DDC I2C + bus to be wedged. + items: + - const: default + - const: unwedge + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Input of the DWC HDMI TX + + properties: + endpoint@0: + $ref: /schemas/graph.yaml#/properties/endpoint + description: Connection to the VOPB + + endpoint@1: + $ref: /schemas/graph.yaml#/properties/endpoint + description: Connection to the VOPL + + required: + - endpoint@0 + - endpoint@1 + + required: + - port + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the GRF to mux vopl/vopb. + +required: + - compatible + - reg + - reg-io-width + - clocks + - clock-names + - interrupts + - ports + - rockchip,grf + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/rk3288-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + hdmi: hdmi@ff980000 { + compatible = "rockchip,rk3288-dw-hdmi"; + reg = <0xff980000 0x20000>; + reg-io-width = <4>; + ddc-i2c-bus = <&i2c5>; + rockchip,grf = <&grf>; + interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; + clock-names = "iahb", "isfr"; + + ports { + port { + #address-cells = <1>; + #size-cells = <0>; + + hdmi_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_hdmi>; + }; + hdmi_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_hdmi>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index eaf8c54fcf50..c2499a7906f5 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -54,6 +54,7 @@ properties: compatible: items: - enum: + - apple,simple-framebuffer - allwinner,simple-framebuffer - amlogic,simple-framebuffer - const: simple-framebuffer @@ -84,9 +85,13 @@ properties: Format of the framebuffer: * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10: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: - a8b8g8r8 - r5g6b5 + - x2r10g10b10 + - x8r8g8b8 display: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/dma/qcom,gpi.yaml b/Documentation/devicetree/bindings/dma/qcom,gpi.yaml index f8142adf9aea..e302147e53c6 100644 --- a/Documentation/devicetree/bindings/dma/qcom,gpi.yaml +++ b/Documentation/devicetree/bindings/dma/qcom,gpi.yaml @@ -20,6 +20,7 @@ properties: compatible: enum: - qcom,sdm845-gpi-dma + - qcom,sm8150-gpi-dma reg: maxItems: 1 @@ -64,7 +65,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/dma/qcom-gpi.h> gpi_dma0: dma-controller@800000 { - compatible = "qcom,gpi-dma"; + compatible = "qcom,sdm845-gpi-dma"; #dma-cells = <3>; reg = <0x00800000 0x60000>; iommus = <&apps_smmu 0x0016 0x0>; diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt deleted file mode 100644 index 35383adb10f1..000000000000 --- a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt +++ /dev/null @@ -1,41 +0,0 @@ -Qualcomm's PM8941 USB ID Extcon device - -Some Qualcomm PMICs have a "misc" module that can be used to detect when -the USB ID pin has been pulled low or high. - -PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: Should contain "qcom,pm8941-misc"; - -- reg: - Usage: required - Value type: <u32> - Definition: Should contain the offset to the misc address space - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: Should contain the usb id interrupt - -- interrupt-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the string "usb_id" for the usb id interrupt - -Example: - - pmic { - usb_id: misc@900 { - compatible = "qcom,pm8941-misc"; - reg = <0x900>; - interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>; - interrupt-names = "usb_id"; - }; - } - - usb-controller { - extcon = <&usb_id>; - }; diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml new file mode 100644 index 000000000000..6a9c96f0352a --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/extcon/qcom,pm8941-misc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. PM8941 USB ID Extcon device + +maintainers: + - Guru Das Srinagesh <gurus@codeaurora.org> + +description: | + Some Qualcomm PMICs have a "misc" module that can be used to detect when + the USB ID pin has been pulled low or high. + +properties: + compatible: + items: + - const: qcom,pm8941-misc + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 2 + + interrupt-names: + minItems: 1 + items: + - const: usb_id + - const: usb_vbus + +required: + - compatible + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + pmic { + #address-cells = <1>; + #size-cells = <0>; + interrupt-controller; + #interrupt-cells = <4>; + + usb_id: misc@900 { + compatible = "qcom,pm8941-misc"; + reg = <0x900>; + interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "usb_id"; + }; + }; + + usb-controller { + extcon = <&usb_id>; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index a884955f861e..e747d73687cb 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -20,7 +20,9 @@ Required properties: * "qcom,scm-msm8996" * "qcom,scm-msm8998" * "qcom,scm-sc7180" + * "qcom,scm-sc7280" * "qcom,scm-sdm845" + * "qcom,scm-sdx55" * "qcom,scm-sm8150" * "qcom,scm-sm8250" * "qcom,scm-sm8350" diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index e811cf825019..d787d57491a1 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -245,36 +245,31 @@ Base tree contains: Overlay contains: -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region0>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_system.rbf"; - fpga-bridges = <&fpga_bridge1>; - ranges = <0x20000 0xff200000 0x100000>, - <0x0 0xc0000000 0x20000000>; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - altr,ngpio = <4>; - #gpio-cells = <2>; - clocks = <2>; - gpio-controller; - }; - - onchip-memory { - device_type = "memory"; - compatible = "altr,onchipmem-15.1"; - reg = <0x0 0x10000>; - }; - }; +/dts-v1/; +/plugin/; + +&fpga_region0 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_system.rbf"; + fpga-bridges = <&fpga_bridge1>; + ranges = <0x20000 0xff200000 0x100000>, + <0x0 0xc0000000 0x20000000>; + + gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + altr,ngpio = <4>; + #gpio-cells = <2>; + clocks = <2>; + gpio-controller; + }; + + onchip-memory { + device_type = "memory"; + compatible = "altr,onchipmem-15.1"; + reg = <0x0 0x10000>; }; }; @@ -371,25 +366,22 @@ Live Device Tree contains: }; DT Overlay contains: -/dts-v1/ /plugin/; -/ { -fragment@0 { - target = <&fpga_region0>; + +/dts-v1/; +/plugin/; + +&fpga_region0 { #address-cells = <1>; #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - firmware-name = "zynq-gpio.bin"; + firmware-name = "zynq-gpio.bin"; - gpio1: gpio@40000000 { - compatible = "xlnx,xps-gpio-1.00.a"; - reg = <0x40000000 0x10000>; - gpio-controller; - #gpio-cells = <0x2>; - xlnx,gpio-width= <0x6>; - }; + gpio1: gpio@40000000 { + compatible = "xlnx,xps-gpio-1.00.a"; + reg = <0x40000000 0x10000>; + gpio-controller; + #gpio-cells = <0x2>; + xlnx,gpio-width= <0x6>; }; }; @@ -402,41 +394,37 @@ This example programs the FPGA to have two regions that can later be partially configured. Each region has its own bridge in the FPGA fabric. DT Overlay contains: -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region0>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "base.rbf"; - - fpga-bridge@4400 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4400 0x10>; - - fpga_region1: fpga-region1 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; - - fpga-bridge@4420 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4420 0x10>; - - fpga_region2: fpga-region2 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; + +/dts-v1/; +/plugin/; + +&fpga_region0 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "base.rbf"; + + fpga-bridge@4400 { + compatible = "altr,freeze-bridge-controller"; + reg = <0x4400 0x10>; + + fpga_region1: fpga-region1 { + compatible = "fpga-region"; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + }; + + fpga-bridge@4420 { + compatible = "altr,freeze-bridge-controller"; + reg = <0x4420 0x10>; + + fpga_region2: fpga-region2 { + compatible = "fpga-region"; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; }; }; }; @@ -451,28 +439,23 @@ differences are that the FPGA is partially reconfigured due to the "partial-fpga-config" boolean and the only bridge that is controlled during programming is the FPGA based bridge of fpga_region1. -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region1>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_image2.rbf"; - partial-fpga-config; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - clocks = <0x2>; - altr,ngpio = <0x4>; - #gpio-cells = <0x2>; - gpio-controller; - }; - }; +/dts-v1/; +/plugin/; + +&fpga_region1 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_image2.rbf"; + partial-fpga-config; + + gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + clocks = <0x2>; + altr,ngpio = <0x4>; + #gpio-cells = <0x2>; + gpio-controller; }; }; diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt index 4284d293fa61..0acdfa6d62a4 100644 --- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt +++ b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt @@ -7,13 +7,24 @@ changes from passing through the bridge. The controller can also couple / enable the bridges which allows traffic to pass through the bridge normally. +Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager +Softcore is compatible with the Xilinx LogiCORE pr-decoupler. + +The Dynamic Function eXchange AXI shutdown manager prevents AXI traffic +from passing through the bridge. The controller safely handles AXI4MM +and AXI4-Lite interfaces on a Reconfigurable Partition when it is +undergoing dynamic reconfiguration, preventing the system deadlock +that can occur if AXI transactions are interrupted by DFX + The Driver supports only MMIO handling. A PR region can have multiple PR Decouplers which can be handled independently or chained via decouple/ decouple_status signals. Required properties: - compatible : Should contain "xlnx,pr-decoupler-1.00" followed by - "xlnx,pr-decoupler" + "xlnx,pr-decoupler" or + "xlnx,dfx-axi-shutdown-manager-1.00" followed by + "xlnx,dfx-axi-shutdown-manager" - regs : base address and size for decoupler module - clocks : input clock to IP - clock-names : should contain "aclk" @@ -22,6 +33,7 @@ See Documentation/devicetree/bindings/fpga/fpga-region.txt and Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: +Partial Reconfig Decoupler: fpga-bridge@100000450 { compatible = "xlnx,pr-decoupler-1.00", "xlnx-pr-decoupler"; @@ -30,3 +42,13 @@ Example: clock-names = "aclk"; bridge-enable = <0>; }; + +Dynamic Function eXchange AXI shutdown manager: + fpga-bridge@100000450 { + compatible = "xlnx,dfx-axi-shutdown-manager-1.00", + "xlnx,dfx-axi-shutdown-manager"; + regs = <0x10000045 0x10>; + clocks = <&clkc 15>; + clock-names = "aclk"; + bridge-enable = <0>; + }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt deleted file mode 100644 index e7853143fa42..000000000000 --- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt +++ /dev/null @@ -1,46 +0,0 @@ -Bindings for the Broadcom's brcm,bcm6345-gpio memory-mapped GPIO controllers. - -These bindings can be used on any BCM63xx SoC. However, BCM6338 and BCM6345 -are the only ones which don't need a pinctrl driver. -BCM6338 have 8-bit data and dirout registers, where GPIO state can be read -and/or written, and the direction changed from input to output. -BCM6345 have 16-bit data and dirout registers, where GPIO state can be read -and/or written, and the direction changed from input to output. - -Required properties: - - compatible: should be "brcm,bcm6345-gpio" - - reg-names: must contain - "dat" - data register - "dirout" - direction (output) register - - reg: address + size pairs describing the GPIO register sets; - order must correspond with the order of entries in reg-names - - #gpio-cells: must be set to 2. The first cell is the pin number and - the second cell is used to specify the gpio polarity: - 0 = active high - 1 = active low - - gpio-controller: Marks the device node as a gpio controller. - -Optional properties: - - native-endian: use native endian memory. - -Examples: - - BCM6338: - gpio: gpio-controller@fffe0407 { - compatible = "brcm,bcm6345-gpio"; - reg-names = "dirout", "dat"; - reg = <0xfffe0407 1>, <0xfffe040f 1>; - - #gpio-cells = <2>; - gpio-controller; - }; - - - BCM6345: - gpio: gpio-controller@fffe0406 { - compatible = "brcm,bcm6345-gpio"; - reg-names = "dirout", "dat"; - reg = <0xfffe0406 2>, <0xfffe040a 2>; - native-endian; - - #gpio-cells = <2>; - gpio-controller; - }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml new file mode 100644 index 000000000000..4d69f79df859 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/brcm,bcm6345-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6345 GPIO controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: |+ + Bindings for Broadcom's BCM63xx memory-mapped GPIO controllers. + + These bindings can be used on any BCM63xx SoC. However, BCM6338 and BCM6345 + are the only ones which don't need a pinctrl driver. + + BCM6338 have 8-bit data and dirout registers, where GPIO state can be read + and/or written, and the direction changed from input to output. + BCM6345 have 16-bit data and dirout registers, where GPIO state can be read + and/or written, and the direction changed from input to output. + BCM6318, BCM6328, BCM6358, BCM6362, BCM6368 and BCM63268 have 32-bit data + and dirout registers, where GPIO state can be read and/or written, and the + direction changed from input to output. + +properties: + compatible: + enum: + - brcm,bcm6318-gpio + - brcm,bcm6328-gpio + - brcm,bcm6345-gpio + - brcm,bcm6358-gpio + - brcm,bcm6362-gpio + - brcm,bcm6368-gpio + - brcm,bcm63268-gpio + + gpio-controller: true + + "#gpio-cells": + const: 2 + + gpio-ranges: + maxItems: 1 + + native-endian: true + + reg: + maxItems: 2 + + reg-names: + items: + - const: dirout + - const: dat + +required: + - compatible + - reg + - reg-names + - gpio-controller + - '#gpio-cells' + +additionalProperties: false + +examples: + - | + gpio@fffe0406 { + compatible = "brcm,bcm6345-gpio"; + reg-names = "dirout", "dat"; + reg = <0xfffe0406 2>, <0xfffe040a 2>; + native-endian; + + gpio-controller; + #gpio-cells = <2>; + }; + + - | + gpio@0 { + compatible = "brcm,bcm63268-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 52>; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml b/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml new file mode 100644 index 000000000000..5fe19fa5f67c --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/fairchild,74hc595.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic 8-bit shift register + +maintainers: + - Maxime Ripard <mripard@kernel.org> + +properties: + compatible: + enum: + - fairchild,74hc595 + - nxp,74lvc594 + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + description: + The second cell is only used to specify the GPIO polarity. + const: 2 + + registers-number: + description: Number of daisy-chained shift registers + + enable-gpios: + description: GPIO connected to the OE (Output Enable) pin. + maxItems: 1 + + spi-max-frequency: true + +patternProperties: + "^(hog-[0-9]+|.+-hog(-[0-9]+)?)$": + type: object + + properties: + gpio-hog: true + gpios: true + output-high: true + output-low: true + line-name: true + + required: + - gpio-hog + - gpios + + additionalProperties: false + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + - registers-number + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + gpio5: gpio5@0 { + compatible = "fairchild,74hc595"; + reg = <0>; + gpio-controller; + #gpio-cells = <2>; + registers-number = <4>; + spi-max-frequency = <100000>; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-74x164.txt b/Documentation/devicetree/bindings/gpio/gpio-74x164.txt deleted file mode 100644 index 2a97553d8d76..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-74x164.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Generic 8-bits shift register GPIO driver - -Required properties: -- compatible: Should contain one of the following: - "fairchild,74hc595" - "nxp,74lvc594" -- reg : chip select number -- 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 the gpio polarity: - 0 = active high - 1 = active low -- registers-number: Number of daisy-chained shift registers - -Optional properties: -- enable-gpios: GPIO connected to the OE (Output Enable) pin. - -Example: - -gpio5: gpio5@0 { - compatible = "fairchild,74hc595"; - reg = <0>; - gpio-controller; - #gpio-cells = <2>; - registers-number = <4>; - spi-max-frequency = <100000>; -}; diff --git a/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml b/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml new file mode 100644 index 000000000000..100f20cebd76 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/realtek,otto-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek Otto GPIO controller + +maintainers: + - Sander Vanheule <sander@svanheule.net> + - Bert Vermeulen <bert@biot.com> + +description: | + Realtek's GPIO controller on their MIPS switch SoCs (Otto platform) consists + of two banks of 32 GPIOs. These GPIOs can generate edge-triggered interrupts. + Each bank's interrupts are cascased into one interrupt line on the parent + interrupt controller, if provided. + This binding allows defining a single bank in the devicetree. The interrupt + controller is not supported on the fallback compatible name, which only + allows for GPIO port use. + +properties: + $nodename: + pattern: "^gpio@[0-9a-f]+$" + + compatible: + items: + - enum: + - realtek,rtl8380-gpio + - realtek,rtl8390-gpio + - const: realtek,otto-gpio + + reg: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + + ngpios: + minimum: 1 + maximum: 32 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - "#gpio-cells" + - gpio-controller + +additionalProperties: false + +dependencies: + interrupt-controller: [ interrupts ] + +examples: + - | + gpio@3500 { + compatible = "realtek,rtl8380-gpio", "realtek,otto-gpio"; + reg = <0x3500 0x1c>; + gpio-controller; + #gpio-cells = <2>; + ngpios = <24>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&rtlintc>; + interrupts = <23>; + }; + +... diff --git a/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml new file mode 100644 index 000000000000..d993e002cebe --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/rockchip,gpio-bank.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip GPIO bank + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + enum: + - rockchip,gpio-bank + - rockchip,rk3188-gpio-bank0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + +required: + - compatible + - reg + - interrupts + - clocks + - gpio-controller + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + pinctrl: pinctrl { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gpio0: gpio@2000a000 { + compatible = "rockchip,rk3188-gpio-bank0"; + reg = <0x2000a000 0x100>; + interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_gates8 9>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; + + gpio1: gpio@2003c000 { + compatible = "rockchip,gpio-bank"; + reg = <0x2003c000 0x100>; + interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_gates8 10>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml b/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml index 1a54db04f29d..bcafa494ed7a 100644 --- a/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml @@ -43,8 +43,7 @@ properties: gpio-ranges: true - gpio-ranges-group-names: - $ref: /schemas/types.yaml#/definitions/string-array + gpio-ranges-group-names: true socionext,interrupt-ranges: description: | diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index 184492162e7e..894ba217ab32 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -69,6 +69,8 @@ properties: where voltage is in V, frequency is in MHz. + dma-coherent: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/hwlock/sirf,hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/sirf,hwspinlock.txt deleted file mode 100644 index 9bb1240a68e0..000000000000 --- a/Documentation/devicetree/bindings/hwlock/sirf,hwspinlock.txt +++ /dev/null @@ -1,28 +0,0 @@ -SIRF Hardware spinlock device Binding ------------------------------------------------ - -Required properties : -- compatible : shall contain only one of the following: - "sirf,hwspinlock" - -- reg : the register address of hwspinlock - -- #hwlock-cells : hwlock users only use the hwlock id to represent a specific - hwlock, so the number of cells should be <1> here. - -Please look at the generic hwlock binding for usage information for consumers, -"Documentation/devicetree/bindings/hwlock/hwlock.txt" - -Example of hwlock provider: - hwlock { - compatible = "sirf,hwspinlock"; - reg = <0x13240000 0x00010000>; - #hwlock-cells = <1>; - }; - -Example of hwlock users: - node { - ... - hwlocks = <&hwlock 2>; - ... - }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml b/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml index 33ee575bb09d..926be9a29044 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml @@ -49,7 +49,7 @@ examples: #size-cells = <0>; adc@48 { - comatible = "ti,ads7828"; + compatible = "ti,ads7828"; reg = <0x48>; vref-supply = <&vref>; ti,differential-input; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mpc.txt b/Documentation/devicetree/bindings/i2c/i2c-mpc.txt deleted file mode 100644 index 42a390526957..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-mpc.txt +++ /dev/null @@ -1,62 +0,0 @@ -* I2C - -Required properties : - - - reg : Offset and length of the register set for the device - - compatible : should be "fsl,CHIP-i2c" where CHIP is the name of a - compatible processor, e.g. mpc8313, mpc8543, mpc8544, mpc5121, - mpc5200 or mpc5200b. For the mpc5121, an additional node - "fsl,mpc5121-i2c-ctrl" is required as shown in the example below. - -Recommended properties : - - - interrupts : <a b> where a is the interrupt number and b is a - field that represents an encoding of the sense and level - information for the interrupt. This should be encoded based on - the information in section 2) depending on the type of interrupt - controller you have. - - fsl,preserve-clocking : boolean; if defined, the clock settings - from the bootloader are preserved (not touched). - - clock-frequency : desired I2C bus clock frequency in Hz. - - fsl,timeout : I2C bus timeout in microseconds. - -Examples : - - /* MPC5121 based board */ - i2c@1740 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,mpc5121-i2c", "fsl-i2c"; - reg = <0x1740 0x20>; - interrupts = <11 0x8>; - interrupt-parent = <&ipic>; - clock-frequency = <100000>; - }; - - i2ccontrol@1760 { - compatible = "fsl,mpc5121-i2c-ctrl"; - reg = <0x1760 0x8>; - }; - - /* MPC5200B based board */ - i2c@3d00 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,mpc5200b-i2c","fsl,mpc5200-i2c","fsl-i2c"; - reg = <0x3d00 0x40>; - interrupts = <2 15 0>; - interrupt-parent = <&mpc5200_pic>; - fsl,preserve-clocking; - }; - - /* MPC8544 base board */ - i2c@3100 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,mpc8544-i2c", "fsl-i2c"; - reg = <0x3100 0x100>; - interrupts = <43 2>; - interrupt-parent = <&mpic>; - clock-frequency = <400000>; - fsl,timeout = <10000>; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml new file mode 100644 index 000000000000..98c6fcf7bf26 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-mpc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: I2C-Bus adapter for MPC824x/83xx/85xx/86xx/512x/52xx SoCs + +maintainers: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - mpc5200-i2c + - fsl,mpc5200-i2c + - fsl,mpc5121-i2c + - fsl,mpc8313-i2c + - fsl,mpc8543-i2c + - fsl,mpc8544-i2c + - const: fsl-i2c + - items: + - const: fsl,mpc5200b-i2c + - const: fsl,mpc5200-i2c + - const: fsl-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + fsl,preserve-clocking: + $ref: /schemas/types.yaml#/definitions/flag + description: | + if defined, the clock settings from the bootloader are + preserved (not touched) + + fsl,timeout: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + I2C bus timeout in microseconds + + fsl,i2c-erratum-a004447: + $ref: /schemas/types.yaml#/definitions/flag + description: | + Indicates the presence of QorIQ erratum A-004447, which + says that the standard i2c recovery scheme mechanism does + not work and an alternate implementation is needed. + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + /* MPC5121 based board */ + i2c@1740 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,mpc5121-i2c", "fsl-i2c"; + reg = <0x1740 0x20>; + interrupts = <11 0x8>; + interrupt-parent = <&ipic>; + clock-frequency = <100000>; + }; + + /* MPC5200B based board */ + i2c@3d00 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,mpc5200b-i2c", "fsl,mpc5200-i2c", "fsl-i2c"; + reg = <0x3d00 0x40>; + interrupts = <2 15 0>; + interrupt-parent = <&mpc5200_pic>; + fsl,preserve-clocking; + }; + + /* MPC8544 base board */ + i2c@3100 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,mpc8544-i2c", "fsl-i2c"; + reg = <0x3100 0x100>; + interrupts = <43 2>; + interrupt-parent = <&mpic>; + clock-frequency = <400000>; + fsl,timeout = <10000>; + }; +... diff --git a/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml b/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml index ffb2ed039a5e..715dcfa5a922 100644 --- a/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml +++ b/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml @@ -4,7 +4,7 @@ $id: "http://devicetree.org/schemas/i2c/xlnx,xps-iic-2.00.a.yaml#" $schema: "http://devicetree.org/meta-schemas/core.yaml#" -title: ilinx IIC controller Device Tree Bindings +title: Xilinx IIC controller Device Tree Bindings maintainers: - info@mocean-labs.com diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt index 1cf6182f888c..3716589d6999 100644 --- a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt +++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt @@ -10,19 +10,19 @@ Required properties: - reg: I3C master registers Mandatory properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - #address-cells: shall be set to 1 - #size-cells: shall be set to 0 Optional properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - i2c-scl-hz - i3c-scl-hz I3C device connected on the bus follow the generic description (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details). +Documentation/devicetree/bindings/i3c/i3c.yaml for more details). Example: diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml index 52042aa44d19..1f82fc923799 100644 --- a/Documentation/devicetree/bindings/i3c/i3c.yaml +++ b/Documentation/devicetree/bindings/i3c/i3c.yaml @@ -157,9 +157,10 @@ examples: i2c-scl-hz = <100000>; /* I2C device. */ - nunchuk: nunchuk@52 { - compatible = "nintendo,nunchuk"; - reg = <0x52 0x0 0x10>; + eeprom@57 { + compatible = "atmel,24c01"; + reg = <0x57 0x0 0x10>; + pagesize = <0x8>; }; /* I3C device with a static I2C address. */ diff --git a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml index adb5165505aa..62f3ca66274f 100644 --- a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml +++ b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml @@ -49,7 +49,7 @@ additionalProperties: true examples: - | i3c-master@a0000000 { - compatible = "silvaco,i3c-master"; + compatible = "silvaco,i3c-master-v1"; clocks = <&zynqmp_clk 71>, <&fclk>, <&sclk>; clock-names = "pclk", "fast_clk", "slow_clk"; interrupt-parent = <&gic>; diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt index 5020eb71eb8d..07f35f36085d 100644 --- a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt +++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt @@ -9,19 +9,19 @@ Required properties: - reg: Offset and length of I3C master registers Mandatory properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - #address-cells: shall be set to 3 - #size-cells: shall be set to 0 Optional properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - i2c-scl-hz - i3c-scl-hz I3C device connected on the bus follow the generic description (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details). +Documentation/devicetree/bindings/i3c/i3c.yaml for more details). Example: diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml new file mode 100644 index 000000000000..911a1ae9c83f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/accel/bosch,bmi088.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bosch BMI088 IMU accelerometer part + +maintainers: + - Mike Looijmans <mike.looijmans@topic.nl> + +description: | + Acceleration part of the IMU sensor with an SPI interface + Specifications about the sensor can be found at: + https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmi088-ds001.pdf + +properties: + compatible: + enum: + - bosch,bmi088-accel + + reg: + maxItems: 1 + + spi-max-frequency: true + + vdd-supply: true + + vddio-supply: true + + interrupts: + minItems: 1 + maxItems: 2 + description: | + Type should be either IRQ_TYPE_LEVEL_HIGH or IRQ_TYPE_LEVEL_LOW. + Two configurable interrupt lines exist. + + interrupt-names: + description: Specify which interrupt line is in use. + items: + enum: + - INT1 + - INT2 + minItems: 1 + maxItems: 2 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + bmi088-accel@1 { + compatible = "bosch,bmi088-accel"; + reg = <1>; + spi-max-frequency = <10000000>; + interrupt-parent = <&gpio6>; + interrupts = <19 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "INT2"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.yaml b/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.yaml index c562d25bee3b..547697e8bc8b 100644 --- a/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.yaml @@ -53,11 +53,6 @@ examples: #address-cells = <1>; #size-cells = <1>; - ts_adc_syscon: ts_adc_syscon@180a6000 { - compatible = "brcm,iproc-ts-adc-syscon","syscon"; - reg = <0x180a6000 0xc30>; - }; - adc { compatible = "brcm,iproc-static-adc"; adc-syscon = <&ts_adc_syscon>; diff --git a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml index 5b21a9fba5dd..b939f9652e3a 100644 --- a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml @@ -34,6 +34,7 @@ properties: - items: - enum: - mediatek,mt8183-auxadc + - mediatek,mt8195-auxadc - mediatek,mt8516-auxadc - const: mediatek,mt8173-auxadc diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml index 6f2398cdc82d..1e7894e524f9 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml @@ -102,7 +102,6 @@ patternProperties: st,adc-channel-names: description: List of single-ended channel names. - $ref: /schemas/types.yaml#/definitions/string-array st,filter-order: description: | diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml new file mode 100644 index 000000000000..e0670e3fbb72 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml @@ -0,0 +1,181 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads131e08.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments ADS131E0x 4-, 6- and 8-Channel ADCs + +maintainers: + - Tomislav Denis <tomislav.denis@avl.com> + +description: | + The ADS131E0x are a family of multichannel, simultaneous sampling, + 24-bit, delta-sigma, analog-to-digital converters (ADCs) with a + built-in programmable gain amplifier (PGA), internal reference + and an onboard oscillator. + The communication with ADC chip is via the SPI bus (mode 1). + + https://www.ti.com/lit/ds/symlink/ads131e08.pdf + +properties: + compatible: + enum: + - ti,ads131e04 + - ti,ads131e06 + - ti,ads131e08 + + reg: + maxItems: 1 + + spi-max-frequency: true + + spi-cpha: true + + clocks: + description: | + Device tree identifier to the clock source (2.048 MHz). + Note: clock source is selected using CLKSEL pin. + maxItems: 1 + + clock-names: + items: + - const: adc-clk + + interrupts: + description: | + IRQ line for the ADC data ready. + maxItems: 1 + + vref-supply: + description: | + Optional external voltage reference. If not supplied, internal voltage + reference is used. + + ti,vref-internal: + description: | + Select the internal voltage reference value. + 0: 2.4V + 1: 4.0V + If this field is left empty, 2.4V is selected. + Note: internal voltage reference is used only if vref-supply is not supplied. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - spi-cpha + - clocks + - clock-names + - interrupts + +patternProperties: + "^channel@([0-7])$": + $ref: "adc.yaml" + type: object + description: | + Represents the external channels which are connected to the ADC. + + properties: + reg: + description: | + The channel number. + Up to 4 channels, numbered from 0 to 3 for ti,ads131e04. + Up to 6 channels, numbered from 0 to 5 for ti,ads131e06. + Up to 8 channels, numbered from 0 to 7 for ti,ads131e08. + items: + minimum: 0 + maximum: 7 + + ti,gain: + description: | + The PGA gain value for the channel. + If this field is left empty, PGA gain 1 is used. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8, 12] + default: 1 + + ti,mux: + description: | + Channel input selection(muliplexer). + 0: Normal input. + 1: Input shorted to (VREFP + VREFN) / 2 (for offset or noise measurements). + 3: MVDD (for supply measurement) + 4: Temperature sensor + If this field is left empty, normal input is selected. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 3, 4] + default: 0 + + required: + - reg + + additionalProperties: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "ti,ads131e08"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpha; + clocks = <&clk2048k>; + clock-names = "adc-clk"; + interrupt-parent = <&gpio5>; + interrupts = <28 IRQ_TYPE_EDGE_FALLING>; + vref-supply = <&adc_vref>; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + }; + + channel@1 { + reg = <1>; + }; + + channel@2 { + reg = <2>; + ti,gain = <2>; + }; + + channel@3 { + reg = <3>; + }; + + channel@4 { + reg = <4>; + }; + + channel@5 { + reg = <5>; + }; + + channel@6 { + reg = <6>; + }; + + channel@7 { + reg = <7>; + ti,mux = <4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml new file mode 100644 index 000000000000..2155d3f5666c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/cdc/adi,ad7150.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog device AD7150 and similar capacitance to digital convertors. + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +properties: + compatible: + enum: + - adi,ad7150 + - adi,ad7151 + - adi,ad7156 + + reg: + maxItems: 1 + + vdd-supply: true + + interrupts: true + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad7150 + - adi,ad7156 + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + - if: + properties: + compatible: + contains: + const: adi,ad7151 + then: + properties: + interrupts: + minItems: 1 + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cdc@48 { + compatible = "adi,ad7150"; + reg = <0x48>; + interrupts = <25 2>, <26 2>; + interrupt-parent = <&gpio>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml index d97ee774d6a6..3f57a1b813e6 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml @@ -83,7 +83,7 @@ examples: #size-cells = <0>; gyroscope@0 { - compatible = "nxp,fxas2102c"; + compatible = "nxp,fxas21002c"; reg = <0x0>; spi-max-frequency = <2000000>; diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml index 79fba1508e89..a7574210175a 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml @@ -71,15 +71,6 @@ properties: minimum: 0 maximum: 3 - adi,scaled-output-hz: - description: - This property must be present if the clock mode is scaled-sync through - clock-names property. In this mode, the input clock can have a range - of 1Hz to 128HZ which must be scaled to originate an allowable sample - rate. This property specifies that rate. - minimum: 1900 - maximum: 2100 - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/light/capella,cm3605.yaml b/Documentation/devicetree/bindings/iio/light/capella,cm3605.yaml index 27972938b60d..c63b79c3351b 100644 --- a/Documentation/devicetree/bindings/iio/light/capella,cm3605.yaml +++ b/Documentation/devicetree/bindings/iio/light/capella,cm3605.yaml @@ -48,7 +48,6 @@ properties: vdd-supply: true capella,aset-resistance-ohms: - $ref: /schemas/types.yaml#/definitions/uint32 enum: [50000, 100000, 300000, 600000] description: > Sensitivity calibration resistance. Note that calibration curves diff --git a/Documentation/devicetree/bindings/iio/light/upisemi,us5182.yaml b/Documentation/devicetree/bindings/iio/light/upisemi,us5182.yaml index de5882cb3360..dd78abe0ec8d 100644 --- a/Documentation/devicetree/bindings/iio/light/upisemi,us5182.yaml +++ b/Documentation/devicetree/bindings/iio/light/upisemi,us5182.yaml @@ -11,12 +11,12 @@ maintainers: properties: compatible: - const: upisemi,asd5182 + const: upisemi,usd5182 reg: maxItems: 1 - upsemi,glass-coef: + upisemi,glass-coef: $ref: /schemas/types.yaml#/definitions/uint32 description: | glass attenuation factor - compensation factor of resolution 1000 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 new file mode 100644 index 000000000000..099b4be927d4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +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. + This is implemented on the EC as near/far logic and exposed to the OS + via an MKBP switch bit. + +properties: + compatible: + const: google,cros-ec-mkbp-proximity + + label: + description: Name for proximity sensor + +required: + - compatible + +additionalProperties: false + +examples: + - | + proximity { + compatible = "google,cros-ec-mkbp-proximity"; + label = "proximity-wifi-lte"; + }; diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml index db291a9390b7..7e98f47987dc 100644 --- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml +++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml @@ -66,6 +66,7 @@ properties: - st,lis3mdl-magn - st,lis2mdl - st,lsm9ds1-magn + - st,iis2mdc # Pressure sensors - st,lps001wp-press - st,lps25h-press diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 3837b17c234f..d9002a3a0abb 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -1,12 +1,9 @@ .. SPDX-License-Identifier: GPL-2.0 -=========== -Device Tree -=========== - .. toctree:: :maxdepth: 1 ABI - submitting-patches writing-bindings + writing-schema + submitting-patches diff --git a/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt b/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt index 84f1a1b505d2..be31cf05cd2e 100644 --- a/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt +++ b/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt @@ -1,7 +1,7 @@ Hisilicon RoCE DT description Hisilicon RoCE engine is a part of network subsystem. -It works depending on other part of network wubsytem, such as, gmac and +It works depending on other part of network subsystem, such as gmac and dsa fabric. Additional properties are described here: diff --git a/Documentation/devicetree/bindings/input/input.yaml b/Documentation/devicetree/bindings/input/input.yaml index ab407f266bef..d41d8743aad4 100644 --- a/Documentation/devicetree/bindings/input/input.yaml +++ b/Documentation/devicetree/bindings/input/input.yaml @@ -32,6 +32,11 @@ properties: Duration in seconds which the key should be kept pressed for device to power off automatically. Device with key pressed shutdown feature can specify this property. - $ref: /schemas/types.yaml#/definitions/uint32 + + reset-time-sec: + description: + Duration in seconds which the key should be kept pressed for device to + reset automatically. Device with key pressed reset feature can specify + this property. additionalProperties: true diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index 799e73cdb90b..36c955965d90 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -71,6 +71,16 @@ properties: - qcom,sm8250-mmss-noc - qcom,sm8250-npu-noc - qcom,sm8250-system-noc + - qcom,sm8350-aggre1-noc + - qcom,sm8350-aggre2-noc + - qcom,sm8350-config-noc + - qcom,sm8350-dc-noc + - qcom,sm8350-gem-noc + - qcom,sm8350-lpass-ag-noc + - qcom,sm8350-mc-virt + - qcom,sm8350-mmss-noc + - qcom,sm8350-compute-noc + - qcom,sm8350-system-noc '#interconnect-cells': enum: [ 1, 2 ] @@ -82,7 +92,6 @@ properties: this interconnect to send RPMh commands. qcom,bcm-voter-names: - $ref: /schemas/types.yaml#/definitions/string-array description: | Names for each of the qcom,bcm-voters specified. diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml new file mode 100644 index 000000000000..29de7807df54 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml @@ -0,0 +1,147 @@ +# 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: 3 + + clock-names: + minItems: 1 + maxItems: 3 + +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 + - 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> + + 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"; + clocks = <&rpmcc RPM_SMD_AGGR2_NOC_CLK>, + <&rpmcc RPM_SMD_AGGR2_NOC_A_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/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml new file mode 100644 index 000000000000..cf6c091a07b1 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/apple,aic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple Interrupt Controller + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + The Apple Interrupt Controller is a simple interrupt controller present on + Apple ARM SoC platforms, including various iPhone and iPad devices and the + "Apple Silicon" Macs. + + It provides the following features: + + - Level-triggered hardware IRQs wired to SoC blocks + - Single mask bit per IRQ + - Per-IRQ affinity setting + - Automatic masking on event delivery (auto-ack) + - Software triggering (ORed with hw line) + - 2 per-CPU IPIs (meant as "self" and "other", but they are interchangeable + if not symmetric) + - Automatic prioritization (single event/ack register per CPU, lower IRQs = + higher priority) + - Automatic masking on ack + - Default "this CPU" register view and explicit per-CPU views + + This device also represents the FIQ interrupt sources on platforms using AIC, + which do not go through a discrete interrupt controller. + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - const: apple,t8103-aic + - const: apple,aic + + interrupt-controller: true + + '#interrupt-cells': + const: 3 + description: | + The 1st cell contains the interrupt type: + - 0: Hardware IRQ + - 1: FIQ + + The 2nd 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 3rd cell contains the interrupt flags. This is normally + IRQ_TYPE_LEVEL_HIGH (4). + + reg: + description: | + Specifies base physical address and size of the AIC registers. + maxItems: 1 + +required: + - compatible + - '#interrupt-cells' + - interrupt-controller + - reg + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + aic: interrupt-controller@23b100000 { + compatible = "apple,t8103-aic", "apple,aic"; + #interrupt-cells = <3>; + interrupt-controller; + reg = <0x2 0x3b100000 0x0 0x8000>; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml new file mode 100644 index 000000000000..160ff4b07cac --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/idt,32434-pic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IDT 79RC32434 Interrupt Controller Device Tree Bindings + +maintainers: + - Thomas Bogendoerfer <tsbogend@alpha.franken.de> + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + "#interrupt-cells": + const: 1 + + compatible: + const: idt,32434-pic + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + +required: + - "#interrupt-cells" + - compatible + - reg + - interrupt-controller + - interrupts + +additionalProperties: false + +examples: + - | + idtpic3: interrupt-controller@3800c { + compatible = "idt,32434-pic"; + reg = <0x3800c 0x0c>; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&cpuintc>; + interrupts = <3>; + }; + +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml index d1d52d1db2be..d6bc1a687fc7 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml @@ -47,7 +47,7 @@ examples: - | #include <dt-bindings/interrupt-controller/irq.h> htintc: interrupt-controller@1fb000080 { - compatible = "loongson,htintc-1.0"; + compatible = "loongson,htpic-1.0"; reg = <0xfb000080 0x40>; interrupt-controller; #interrupt-cells = <1>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml index f38e0113f360..067165c4b836 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml @@ -10,9 +10,9 @@ maintainers: - Jiaxun Yang <jiaxun.yang@flygoat.com> description: | - This interrupt controller is found in the Loongson-3 family of chips as the primary - package interrupt controller which can route local I/O interrupt to interrupt lines - of cores. + This interrupt controller is found in the Loongson-3 family of chips and + Loongson-2K1000 chip, as the primary package interrupt controller which + can route local I/O interrupt to interrupt lines of cores. allOf: - $ref: /schemas/interrupt-controller.yaml# @@ -22,9 +22,17 @@ properties: oneOf: - const: loongson,liointc-1.0 - const: loongson,liointc-1.0a + - const: loongson,liointc-2.0 reg: - maxItems: 1 + minItems: 1 + maxItems: 3 + + reg-names: + items: + - const: main + - const: isr0 + - const: isr1 interrupt-controller: true @@ -69,6 +77,26 @@ required: unevaluatedProperties: false +if: + properties: + compatible: + contains: + enum: + - loongson,liointc-2.0 + +then: + properties: + reg: + minItems: 3 + + required: + - reg-names + +else: + properties: + reg: + maxItems: 1 + examples: - | iointc: interrupt-controller@3ff01400 { diff --git a/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml new file mode 100644 index 000000000000..9ce6804bdb99 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/nuvoton,wpcm450-aic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton WPCM450 Advanced Interrupt Controller bindings + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +properties: + '#interrupt-cells': + const: 2 + + compatible: + const: nuvoton,wpcm450-aic + + interrupt-controller: true + + reg: + maxItems: 1 + +additionalProperties: false + +required: + - '#interrupt-cells' + - compatible + - reg + - interrupt-controller + +examples: + - | + aic: interrupt-controller@b8002000 { + compatible = "nuvoton,wpcm450-aic"; + reg = <0xb8002000 0x1000>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt index e9afb48182c7..98d89e53013d 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt @@ -19,6 +19,7 @@ Properties: Value type: <string> Definition: Should contain "qcom,<soc>-pdc" and "qcom,pdc" - "qcom,sc7180-pdc": For SC7180 + - "qcom,sc7280-pdc": For SC7280 - "qcom,sdm845-pdc": For SDM845 - "qcom,sdm8250-pdc": For SM8250 - "qcom,sdm8350-pdc": For SM8350 diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index 6ba161dea4d8..9d27aa5111d4 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -34,6 +34,7 @@ properties: items: - enum: - qcom,sc7180-smmu-500 + - qcom,sc7280-smmu-500 - qcom,sc8180x-smmu-500 - qcom,sdm845-smmu-500 - qcom,sm8150-smmu-500 diff --git a/Documentation/devicetree/bindings/iommu/sprd,iommu.yaml b/Documentation/devicetree/bindings/iommu/sprd,iommu.yaml new file mode 100644 index 000000000000..7003e12f55f9 --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/sprd,iommu.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2020 Unisoc Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iommu/sprd,iommu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc IOMMU and Multi-media MMU + +maintainers: + - Chunyan Zhang <zhang.lyra@gmail.com> + +properties: + compatible: + enum: + - sprd,iommu-v1 + + "#iommu-cells": + const: 0 + description: + Unisoc IOMMUs are all single-master IOMMU devices, therefore no + additional information needs to associate with its master device. + Please refer to the generic bindings document for more details, + Documentation/devicetree/bindings/iommu/iommu.txt + + reg: + maxItems: 1 + + clocks: + description: + Reference to a gate clock phandle, since access to some of IOMMUs are + controlled by gate clock, but this is not required. + +required: + - compatible + - reg + - "#iommu-cells" + +additionalProperties: false + +examples: + - | + iommu_disp: iommu@63000800 { + compatible = "sprd,iommu-v1"; + reg = <0x63000800 0x80>; + #iommu-cells = <0>; + }; + + - | + iommu_jpg: iommu@62300300 { + compatible = "sprd,iommu-v1"; + reg = <0x62300300 0x80>; + #iommu-cells = <0>; + clocks = <&mm_gate 1>; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd253.yaml b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd253.yaml index 7a6ec1f8c0f3..73fa59e62181 100644 --- a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd253.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd253.yaml @@ -4,13 +4,13 @@ $id: http://devicetree.org/schemas/leds/backlight/kinetic,ktd253.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Kinetic Technologies KTD253 one-wire backlight +title: Kinetic Technologies KTD253 and KTD259 one-wire backlight maintainers: - Linus Walleij <linus.walleij@linaro.org> description: | - The Kinetic Technologies KTD253 is a white LED backlight that is + The Kinetic Technologies KTD253 and KTD259 are white LED backlights controlled by a single GPIO line. If you just turn on the backlight it goes to maximum backlight then you can set the level of backlight using pulses on the enable wire. This is sometimes referred to as @@ -21,7 +21,10 @@ allOf: properties: compatible: - const: kinetic,ktd253 + items: + - enum: + - kinetic,ktd253 + - kinetic,ktd259 enable-gpios: description: GPIO to use to enable/disable and dim the backlight. diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml index 47938e372987..d839e75d9788 100644 --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml @@ -19,6 +19,7 @@ properties: compatible: enum: - qcom,pm8941-wled + - qcom,pmi8994-wled - qcom,pmi8998-wled - qcom,pm660l-wled - qcom,pm8150l-wled diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt index ccebce597f37..a555d94084b7 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt @@ -4,8 +4,8 @@ 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/gpio-74x164.txt), or -by hardware using this driver. +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. diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt index da5708e7b43b..6e51c6b91ee5 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt @@ -3,7 +3,7 @@ LEDs connected to Broadcom BCM6358 controller This controller is present on BCM6358 and BCM6368. In these SoCs 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/gpio-74x164.txt), or +See Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml), or by hardware using this driver. Required properties: diff --git a/Documentation/devicetree/bindings/leds/leds-lgm.yaml b/Documentation/devicetree/bindings/leds/leds-lgm.yaml index 32bbf146c01d..f8d7963c3a13 100644 --- a/Documentation/devicetree/bindings/leds/leds-lgm.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lgm.yaml @@ -14,6 +14,17 @@ properties: compatible: const: intel,lgm-ssoled + reg: + maxItems: 1 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: sso + - const: fpid + gpio-controller: true '#gpio-cells': @@ -36,8 +47,15 @@ properties: additionalProperties: false + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + patternProperties: - "^led@[0-23]$": + "^led@[0-2]$": type: object properties: @@ -81,7 +99,7 @@ examples: #include <dt-bindings/leds/common.h> ssogpio: ssogpio@e0d40000 { - compatible = "intel,sso-led"; + compatible = "intel,lgm-ssoled"; reg = <0xE0D40000 0x2E4>; gpio-controller; #gpio-cells = <2>; @@ -103,8 +121,8 @@ examples: led-gpio = <&ssogpio 0 0>; }; - led@23 { - reg = <23>; + led@2 { + reg = <2>; function = LED_FUNCTION_POWER; color = <LED_COLOR_ID_GREEN>; led-gpio = <&ssogpio 23 0>; diff --git a/Documentation/devicetree/bindings/leds/leds-rt4505.yaml b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml new file mode 100644 index 000000000000..5b0c74aa6723 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-rt4505.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RT4505 Single Channel LED Driver + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: | + The RT4505 is a flash LED driver that can support up to 375mA and 1.5A for + torch and flash mode, respectively. + + The data sheet can be found at: + https://www.richtek.com/assets/product_file/RT4505/DS4505-02.pdf + +properties: + compatible: + const: richtek,rt4505 + + reg: + description: I2C slave address of the controller. + maxItems: 1 + + led: + type: object + $ref: common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@63 { + compatible = "richtek,rt4505"; + reg = <0x63>; + + rt4505_flash: led { + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; + led-max-microamp = <375000>; + flash-max-microamp = <1500000>; + flash-max-timeout-us = <800000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml index 15cef82cd356..1a3dff277e2b 100644 --- a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml +++ b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml @@ -34,12 +34,15 @@ properties: - fsl,imx8mm-mu - fsl,imx8mn-mu - fsl,imx8mp-mu + - fsl,imx8qm-mu - fsl,imx8qxp-mu - const: fsl,imx6sx-mu - description: To communicate with i.MX8 SCU with fast IPC items: - const: fsl,imx8-mu-scu - - const: fsl,imx8qxp-mu + - enum: + - fsl,imx8qm-mu + - fsl,imx8qxp-mu - const: fsl,imx6sx-mu reg: diff --git a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml index 168beeb7e9f7..b222f993b232 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml @@ -25,6 +25,8 @@ properties: items: - enum: - qcom,sm8250-ipcc + - qcom,sm8350-ipcc + - qcom,sc7280-ipcc - const: qcom,ipcc reg: diff --git a/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml index 26a5cca3f838..80feba82cbd6 100644 --- a/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml @@ -15,6 +15,7 @@ properties: compatible: enum: - sprd,sc9860-mailbox + - sprd,sc9863a-mailbox reg: items: @@ -22,9 +23,15 @@ properties: - description: outbox registers' base address interrupts: + minItems: 2 + maxItems: 3 + + interrupt-names: + minItems: 2 items: - - description: inbox interrupt - - description: outbox interrupt + - const: inbox + - const: outbox + - const: supp-outbox clocks: maxItems: 1 @@ -40,6 +47,7 @@ required: - compatible - reg - interrupts + - interrupt-names - "#mbox-cells" - clocks - clock-names @@ -56,5 +64,6 @@ examples: clock-names = "enable"; clocks = <&aon_gate 53>; interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "inbox", "outbox"; }; ... diff --git a/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.txt b/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.txt deleted file mode 100644 index 6c9c7daf0f5c..000000000000 --- a/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.txt +++ /dev/null @@ -1,50 +0,0 @@ -Texas Instruments' Secure Proxy -======================================== - -The Texas Instruments' secure proxy is a mailbox controller that has -configurable queues selectable at SoC(System on Chip) integration. The -Message manager is broken up into different address regions that are -called "threads" or "proxies" - each instance is unidirectional and is -instantiated at SoC integration level by system controller to indicate -receive or transmit path. - -Message Manager Device Node: -=========================== -Required properties: --------------------- -- compatible: Shall be "ti,am654-secure-proxy" -- reg-names target_data - Map the proxy data region - rt - Map the realtime status region - scfg - Map the configuration region -- reg: Contains the register map per reg-names. -- #mbox-cells Shall be 1 and shall refer to the transfer path - called thread. -- interrupt-names: Contains interrupt names matching the rx transfer path - for a given SoC. Receive interrupts shall be of the - format: "rx_<PID>". -- interrupts: Contains the interrupt information corresponding to - interrupt-names property. - -Example(AM654): ------------- - - secure_proxy: mailbox@32c00000 { - compatible = "ti,am654-secure-proxy"; - #mbox-cells = <1>; - reg-names = "target_data", "rt", "scfg"; - reg = <0x0 0x32c00000 0x0 0x100000>, - <0x0 0x32400000 0x0 0x100000>, - <0x0 0x32800000 0x0 0x100000>; - interrupt-names = "rx_011"; - interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; - }; - - dmsc: dmsc { - [...] - mbox-names = "rx", "tx"; - # RX Thread ID is 11 - # TX Thread ID is 13 - mboxes= <&secure_proxy 11>, - <&secure_proxy 13>; - [...] - }; diff --git a/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml b/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml new file mode 100644 index 000000000000..eea822861804 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/ti,secure-proxy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments' Secure Proxy + +maintainers: + - Nishanth Menon <nm@ti.com> + +description: | + The Texas Instruments' secure proxy is a mailbox controller that has + configurable queues selectable at SoC(System on Chip) integration. The + Message manager is broken up into different address regions that are + called "threads" or "proxies" - each instance is unidirectional and is + instantiated at SoC integration level by system controller to indicate + receive or transmit path. + +properties: + $nodename: + pattern: "^mailbox@[0-9a-f]+$" + + compatible: + const: ti,am654-secure-proxy + + "#mbox-cells": + const: 1 + description: + Contains the secure proxy thread ID used for the specific transfer path. + + reg-names: + items: + - const: target_data + - const: rt + - const: scfg + + reg: + minItems: 3 + + interrupt-names: + minItems: 1 + maxItems: 100 + items: + pattern: "^rx_[0-9]{3}$" + description: + Contains the interrupt name information for the Rx interrupt path for + secure proxy thread in the form 'rx_<PID>'. + + interrupts: + minItems: 1 + maxItems: 100 + description: + Contains the interrupt information for the Rx interrupt path for secure + proxy. + +required: + - compatible + - reg-names + - reg + - interrupt-names + - interrupts + - "#mbox-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + secure_proxy: mailbox@32c00000 { + compatible = "ti,am654-secure-proxy"; + #mbox-cells = <1>; + reg-names = "target_data", "rt", "scfg"; + reg = <0x32c00000 0x100000>, + <0x32400000 0x100000>, + <0x32800000 0x100000>; + interrupt-names = "rx_011"; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml index 5fa19d4aeaf3..6d8395d6bca0 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml @@ -20,16 +20,12 @@ properties: - const: allwinner,sun5i-a13-ir - const: allwinner,sun6i-a31-ir - items: - - const: allwinner,sun8i-a83t-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun8i-r40-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun50i-a64-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun50i-h6-ir + - enum: + - allwinner,sun8i-a83t-ir + - allwinner,sun8i-r40-ir + - allwinner,sun50i-a64-ir + - allwinner,sun50i-h6-ir + - allwinner,sun50i-h616-ir - const: allwinner,sun6i-a31-ir reg: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt index cf60c5acc0e4..39c1028b2dfb 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt @@ -19,7 +19,7 @@ Required properties: Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml for details. - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Example: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt index acfb50375b8a..5e53c6ab52d0 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt @@ -17,7 +17,7 @@ Required properties: Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml for details. - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Example: diff --git a/Documentation/devicetree/bindings/media/mediatek-mdp.txt b/Documentation/devicetree/bindings/media/mediatek-mdp.txt index f4798d04e925..caa24943da33 100644 --- a/Documentation/devicetree/bindings/media/mediatek-mdp.txt +++ b/Documentation/devicetree/bindings/media/mediatek-mdp.txt @@ -25,7 +25,7 @@ Required properties (DMA function blocks, child node): "mediatek,mt8173-mdp-wdma" "mediatek,mt8173-mdp-wrot" - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. - mediatek,larb: must contain the local arbiters in the current Socs, see Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt index 8217424fd4bd..06db6837cefd 100644 --- a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -4,7 +4,9 @@ Mediatek Video Codec is the video codec hw present in Mediatek SoCs which supports high resolution encoding and decoding functionalities. Required properties: -- compatible : "mediatek,mt8173-vcodec-enc" for MT8173 encoder +- compatible : must be one of the following string: + "mediatek,mt8173-vcodec-enc-vp8" for mt8173 vp8 encoder. + "mediatek,mt8173-vcodec-enc" for mt8173 avc encoder. "mediatek,mt8183-vcodec-enc" for MT8183 encoder. "mediatek,mt8173-vcodec-dec" for MT8173 decoder. - reg : Physical base address of the video codec registers and length of @@ -13,12 +15,12 @@ Required properties: - mediatek,larb : must contain the local arbiters in the current Socs. - clocks : list of clock specifiers, corresponding to entries in the clock-names property. -- clock-names: encoder must contain "venc_sel_src", "venc_sel",, - "venc_lt_sel_src", "venc_lt_sel", decoder must contain "vcodecpll", - "univpll_d2", "clk_cci400_sel", "vdec_sel", "vdecpll", "vencpll", - "venc_lt_sel", "vdec_bus_clk_src". +- clock-names: avc encoder must contain "venc_sel", vp8 encoder must + contain "venc_lt_sel", decoder must contain "vcodecpll", "univpll_d2", + "clk_cci400_sel", "vdec_sel", "vdecpll", "vencpll", "venc_lt_sel", + "vdec_bus_clk_src". - iommus : should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. One of the two following nodes: - mediatek,vpu : the node of the video processor unit, if using VPU. @@ -80,14 +82,10 @@ vcodec_dec: vcodec@16000000 { assigned-clock-rates = <0>, <0>, <0>, <1482000000>, <800000000>; }; - vcodec_enc: vcodec@18002000 { +vcodec_enc_avc: vcodec@18002000 { compatible = "mediatek,mt8173-vcodec-enc"; - reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/ - <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/ - interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; - mediatek,larb = <&larb3>, - <&larb5>; + reg = <0 0x18002000 0 0x1000>; + interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>; iommus = <&iommu M4U_PORT_VENC_RCPU>, <&iommu M4U_PORT_VENC_REC>, <&iommu M4U_PORT_VENC_BSDMA>, @@ -98,8 +96,20 @@ vcodec_dec: vcodec@16000000 { <&iommu M4U_PORT_VENC_REF_LUMA>, <&iommu M4U_PORT_VENC_REF_CHROMA>, <&iommu M4U_PORT_VENC_NBM_RDMA>, - <&iommu M4U_PORT_VENC_NBM_WDMA>, - <&iommu M4U_PORT_VENC_RCPU_SET2>, + <&iommu M4U_PORT_VENC_NBM_WDMA>; + mediatek,larb = <&larb3>; + mediatek,vpu = <&vpu>; + clocks = <&topckgen CLK_TOP_VENC_SEL>; + clock-names = "venc_sel"; + assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL>; + }; + +vcodec_enc_vp8: vcodec@19002000 { + compatible = "mediatek,mt8173-vcodec-enc-vp8"; + reg = <0 0x19002000 0 0x1000>; /* VENC_LT_SYS */ + interrupts = <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; + iommus = <&iommu M4U_PORT_VENC_RCPU_SET2>, <&iommu M4U_PORT_VENC_REC_FRM_SET2>, <&iommu M4U_PORT_VENC_BSDMA_SET2>, <&iommu M4U_PORT_VENC_SV_COMA_SET2>, @@ -108,17 +118,10 @@ vcodec_dec: vcodec@16000000 { <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>, <&iommu M4U_PORT_VENC_REF_LUMA_SET2>, <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>; + mediatek,larb = <&larb5>; mediatek,vpu = <&vpu>; - clocks = <&topckgen CLK_TOP_VENCPLL_D2>, - <&topckgen CLK_TOP_VENC_SEL>, - <&topckgen CLK_TOP_UNIVPLL1_D2>, - <&topckgen CLK_TOP_VENC_LT_SEL>; - clock-names = "venc_sel_src", - "venc_sel", - "venc_lt_sel_src", - "venc_lt_sel"; - assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>, - <&topckgen CLK_TOP_VENC_LT_SEL>; - assigned-clock-parents = <&topckgen CLK_TOP_VENCPLL_D2>, - <&topckgen CLK_TOP_UNIVPLL1_D2>; + clocks = <&topckgen CLK_TOP_VENC_LT_SEL>; + clock-names = "venc_lt_sel"; + assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>; }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index be47a7b62ca9..d8ed480482b9 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -4,14 +4,19 @@ $id: http://devicetree.org/schemas/media/nxp,imx7-mipi-csi2.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: NXP i.MX7 Mipi CSI2 +title: NXP i.MX7 MIPI CSI-2 receiver maintainers: - Rui Miguel Silva <rmfrfs@gmail.com> -description: | - This is the device node for the MIPI CSI-2 receiver core in i.MX7 soc. It is - compatible with previous version of samsung d-phy. +description: |- + The NXP i.MX7 SoC family includes a MIPI CSI-2 receiver IP core, documented + as "CSIS V3.3". The IP core seems to originate from Samsung, and may be + compatible with some of the Exynos4 ad S5P SoCs. + + While the CSI-2 receiver is separate from the MIPI D-PHY IP core, the PHY is + completely wrapped by the CSIS and doesn't expose a control interface of its + own. This binding thus covers both IP cores. properties: compatible: @@ -24,8 +29,10 @@ properties: maxItems: 1 clocks: - minItems: 3 - maxItems: 3 + items: + - description: The peripheral clock (a.k.a. APB clock) + - description: The external clock (optionally used as the pixel clock) + - description: The MIPI D-PHY clock clock-names: items: @@ -37,26 +44,16 @@ properties: maxItems: 1 phy-supply: - description: - Phandle to a regulator that provides power to the PHY. This - regulator will be managed during the PHY power on/off sequence. + description: The MIPI D-PHY digital power supply resets: - maxItems: 1 - - reset-names: - const: mrst + items: + - description: MIPI D-PHY slave reset clock-frequency: - description: - The IP main (system bus) clock frequency in Hertz + description: The desired external clock ("wrap") frequency, in Hz default: 166000000 - fsl,csis-hs-settle: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Differential receiver (HS-RX) settle time - ports: $ref: /schemas/graph.yaml#/properties/ports @@ -98,7 +95,6 @@ required: - power-domains - phy-supply - resets - - reset-names - ports additionalProperties: false @@ -111,43 +107,41 @@ examples: #include <dt-bindings/reset/imx7-reset.h> mipi_csi: mipi-csi@30750000 { - compatible = "fsl,imx7-mipi-csi2"; - reg = <0x30750000 0x10000>; - interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; - - clocks = <&clks IMX7D_IPG_ROOT_CLK>, - <&clks IMX7D_MIPI_CSI_ROOT_CLK>, - <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; - clock-names = "pclk", "wrap", "phy"; - clock-frequency = <166000000>; - - power-domains = <&pgc_mipi_phy>; - phy-supply = <®_1p0d>; - resets = <&src IMX7_RESET_MIPI_PHY_MRST>; - reset-names = "mrst"; - fsl,csis-hs-settle = <3>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - mipi_from_sensor: endpoint { - remote-endpoint = <&ov2680_to_mipi>; - data-lanes = <1>; - }; - }; - - port@1 { - reg = <1>; - - mipi_vc0_to_csi_mux: endpoint { - remote-endpoint = <&csi_mux_from_mipi_vc0>; - }; - }; + compatible = "fsl,imx7-mipi-csi2"; + reg = <0x30750000 0x10000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&clks IMX7D_IPG_ROOT_CLK>, + <&clks IMX7D_MIPI_CSI_ROOT_CLK>, + <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; + clock-names = "pclk", "wrap", "phy"; + clock-frequency = <166000000>; + + power-domains = <&pgc_mipi_phy>; + phy-supply = <®_1p0d>; + resets = <&src IMX7_RESET_MIPI_PHY_MRST>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mipi_from_sensor: endpoint { + remote-endpoint = <&ov2680_to_mipi>; + data-lanes = <1>; + }; + }; + + port@1 { + reg = <1>; + + mipi_vc0_to_csi_mux: endpoint { + remote-endpoint = <&csi_mux_from_mipi_vc0>; + }; }; + }; }; ... diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml new file mode 100644 index 000000000000..5d13cbb5251b --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx8-jpeg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX8QXP/QM JPEG decoder/encoder Device Tree Bindings + +maintainers: + - Mirela Rabulea <mirela.rabulea@nxp.com> + +description: |- + The JPEG decoder/encoder present in iMX8QXP and iMX8QM SoCs is an + ISO/IEC 10918-1 JPEG standard compliant decoder/encoder, for Baseline + and Extended Sequential DCT modes. + +properties: + compatible: + items: + - enum: + # JPEG decoder + - nxp,imx8qxp-jpgdec + # JPEG encoder + - nxp,imx8qxp-jpgenc + + reg: + maxItems: 1 + + interrupts: + description: | + There are 4 slots available in the IP, which the driver may use + If a certain slot is used, it should have an associated interrupt + The interrupt with index i is assumed to be for slot i + minItems: 1 # At least one slot is needed by the driver + maxItems: 4 # The IP has 4 slots available for use + + power-domains: + description: + List of phandle and PM domain specifier as documented in + Documentation/devicetree/bindings/power/power_domain.txt + minItems: 2 # Wrapper and 1 slot + maxItems: 5 # Wrapper and 4 slots + +required: + - compatible + - reg + - interrupts + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/firmware/imx/rsrc.h> + + jpegdec: jpegdec@58400000 { + compatible = "nxp,imx8qxp-jpgdec"; + reg = <0x58400000 0x00050000 >; + interrupts = <GIC_SPI 309 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 310 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 311 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 312 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&pd IMX_SC_R_MJPEG_DEC_MP>, + <&pd IMX_SC_R_MJPEG_DEC_S0>, + <&pd IMX_SC_R_MJPEG_DEC_S1>, + <&pd IMX_SC_R_MJPEG_DEC_S2>, + <&pd IMX_SC_R_MJPEG_DEC_S3>; + }; + + jpegenc: jpegenc@58450000 { + compatible = "nxp,imx8qxp-jpgenc"; + reg = <0x58450000 0x00050000 >; + interrupts = <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 307 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 308 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&pd IMX_SC_R_MJPEG_ENC_MP>, + <&pd IMX_SC_R_MJPEG_ENC_S0>, + <&pd IMX_SC_R_MJPEG_ENC_S1>, + <&pd IMX_SC_R_MJPEG_ENC_S2>, + <&pd IMX_SC_R_MJPEG_ENC_S3>; + }; +... diff --git a/Documentation/devicetree/bindings/media/qcom,camss.txt b/Documentation/devicetree/bindings/media/qcom,camss.txt deleted file mode 100644 index 498234629e21..000000000000 --- a/Documentation/devicetree/bindings/media/qcom,camss.txt +++ /dev/null @@ -1,236 +0,0 @@ -Qualcomm Camera Subsystem - -* Properties - -- compatible: - Usage: required - Value type: <stringlist> - Definition: Should contain one of: - - "qcom,msm8916-camss" - - "qcom,msm8996-camss" - - "qcom,sdm660-camss" -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: Register ranges as listed in the reg-names property. -- reg-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "csiphy0" - - "csiphy0_clk_mux" - - "csiphy1" - - "csiphy1_clk_mux" - - "csiphy2" (8996 only) - - "csiphy2_clk_mux" (8996 only) - - "csid0" - - "csid1" - - "csid2" (8996 only) - - "csid3" (8996 only) - - "ispif" - - "csi_clk_mux" - - "vfe0" - - "vfe1" (8996 only) -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: Interrupts as listed in the interrupt-names property. -- interrupt-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "csiphy0" - - "csiphy1" - - "csiphy2" (8996 only) - - "csid0" - - "csid1" - - "csid2" (8996 only) - - "csid3" (8996 only) - - "ispif" - - "vfe0" - - "vfe1" (8996 only) -- power-domains: - Usage: required - Value type: <prop-encoded-array> - Definition: A phandle and power domain specifier pairs to the - power domain which is responsible for collapsing - and restoring power to the peripheral. -- clocks: - Usage: required - Value type: <prop-encoded-array> - Definition: A list of phandle and clock specifier pairs as listed - in clock-names property. -- clock-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "top_ahb" - - "throttle_axi" (660 only) - - "ispif_ahb" - - "csiphy0_timer" - - "csiphy1_timer" - - "csiphy2_timer" (8996 only) - - "csiphy_ahb2crif" (660 only) - - "csi0_ahb" - - "csi0" - - "csi0_phy" - - "csi0_pix" - - "csi0_rdi" - - "cphy_csid0" (660 only) - - "csi1_ahb" - - "csi1" - - "csi1_phy" - - "csi1_pix" - - "csi1_rdi" - - "cphy_csid1" (660 only) - - "csi2_ahb" (8996 only) - - "csi2" (8996 only) - - "csi2_phy" (8996 only) - - "csi2_pix" (8996 only) - - "csi2_rdi" (8996 only) - - "cphy_csid2" (660 only) - - "csi3_ahb" (8996 only) - - "csi3" (8996 only) - - "csi3_phy" (8996 only) - - "csi3_pix" (8996 only) - - "csi3_rdi" (8996 only) - - "cphy_csid3" (660 only) - - "ahb" - - "vfe0" - - "csi_vfe0" - - "vfe0_ahb", (8996 only) - - "vfe0_stream", (8996 only) - - "vfe1", (8996 only) - - "csi_vfe1", (8996 only) - - "vfe1_ahb", (8996 only) - - "vfe1_stream", (8996 only) - - "vfe_ahb" - - "vfe_axi" -- vdda-supply: - Usage: required - Value type: <phandle> - Definition: A phandle to voltage supply for CSI2. -- iommus: - Usage: required - Value type: <prop-encoded-array> - Definition: A list of phandle and IOMMU specifier pairs. - -* Nodes - -- ports: - Usage: required - Definition: As described in video-interfaces.txt in same directory. - Properties: - - reg: - Usage: required - Value type: <u32> - Definition: Selects CSI2 PHY interface - PHY0, PHY1 - or PHY2 (8996 only) - Endpoint node properties: - - clock-lanes: - Usage: required - Value type: <u32> - Definition: The physical clock lane index. On 8916 - the value must always be <1> as the physical - clock lane is lane 1. On 8996 the value must - always be <7> as the hardware supports D-PHY - and C-PHY, indexes are in a common set and - D-PHY physical clock lane is labeled as 7. - - data-lanes: - Usage: required - Value type: <prop-encoded-array> - Definition: An array of physical data lanes indexes. - Position of an entry determines the logical - lane number, while the value of an entry - indicates physical lane index. Lane swapping - is supported. Physical lane indexes for - 8916: 0, 2, 3, 4; for 8996: 0, 1, 2, 3. - -* An Example - - camss: camss@1b00000 { - compatible = "qcom,msm8916-camss"; - reg = <0x1b0ac00 0x200>, - <0x1b00030 0x4>, - <0x1b0b000 0x200>, - <0x1b00038 0x4>, - <0x1b08000 0x100>, - <0x1b08400 0x100>, - <0x1b0a000 0x500>, - <0x1b00020 0x10>, - <0x1b10000 0x1000>; - reg-names = "csiphy0", - "csiphy0_clk_mux", - "csiphy1", - "csiphy1_clk_mux", - "csid0", - "csid1", - "ispif", - "csi_clk_mux", - "vfe0"; - interrupts = <GIC_SPI 78 0>, - <GIC_SPI 79 0>, - <GIC_SPI 51 0>, - <GIC_SPI 52 0>, - <GIC_SPI 55 0>, - <GIC_SPI 57 0>; - interrupt-names = "csiphy0", - "csiphy1", - "csid0", - "csid1", - "ispif", - "vfe0"; - power-domains = <&gcc VFE_GDSC>; - clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>, - <&gcc GCC_CAMSS_ISPIF_AHB_CLK>, - <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>, - <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>, - <&gcc GCC_CAMSS_CSI0_AHB_CLK>, - <&gcc GCC_CAMSS_CSI0_CLK>, - <&gcc GCC_CAMSS_CSI0PHY_CLK>, - <&gcc GCC_CAMSS_CSI0PIX_CLK>, - <&gcc GCC_CAMSS_CSI0RDI_CLK>, - <&gcc GCC_CAMSS_CSI1_AHB_CLK>, - <&gcc GCC_CAMSS_CSI1_CLK>, - <&gcc GCC_CAMSS_CSI1PHY_CLK>, - <&gcc GCC_CAMSS_CSI1PIX_CLK>, - <&gcc GCC_CAMSS_CSI1RDI_CLK>, - <&gcc GCC_CAMSS_AHB_CLK>, - <&gcc GCC_CAMSS_VFE0_CLK>, - <&gcc GCC_CAMSS_CSI_VFE0_CLK>, - <&gcc GCC_CAMSS_VFE_AHB_CLK>, - <&gcc GCC_CAMSS_VFE_AXI_CLK>; - clock-names = "top_ahb", - "ispif_ahb", - "csiphy0_timer", - "csiphy1_timer", - "csi0_ahb", - "csi0", - "csi0_phy", - "csi0_pix", - "csi0_rdi", - "csi1_ahb", - "csi1", - "csi1_phy", - "csi1_pix", - "csi1_rdi", - "ahb", - "vfe0", - "csi_vfe0", - "vfe_ahb", - "vfe_axi"; - vdda-supply = <&pm8916_l2>; - iommus = <&apps_iommu 3>; - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - csiphy0_ep: endpoint { - clock-lanes = <1>; - data-lanes = <0 2>; - remote-endpoint = <&ov5645_ep>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml new file mode 100644 index 000000000000..304908072d72 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml @@ -0,0 +1,256 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,msm8916-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - Todor Tomov <todor.too@gmail.com> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,msm8916-camss + + clocks: + minItems: 19 + maxItems: 19 + + clock-names: + items: + - const: top_ahb + - const: ispif_ahb + - const: csiphy0_timer + - const: csiphy1_timer + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: ahb + - const: vfe0 + - const: csi_vfe0 + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 6 + maxItems: 6 + + interrupt-names: + items: + - const: csiphy0 + - const: csiphy1 + - const: csid0 + - const: csid1 + - const: ispif + - const: vfe0 + + iommus: + maxItems: 1 + + power-domains: + items: + - description: VFE GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 1 + + data-lanes: + description: + An array of physical data lanes indexes. + Position of an entry determines the logical + lane number, while the value of an entry + indicates physical lane index. Lane swapping + is supported. Physical lane indexes; + 0, 2, 3, 4. + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 9 + maxItems: 9 + + reg-names: + items: + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csid0 + - const: csid1 + - const: ispif + - const: csi_clk_mux + - const: vfe0 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-msm8916.h> + + camss: camss@1b00000 { + compatible = "qcom,msm8916-camss"; + + clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>, + <&gcc GCC_CAMSS_ISPIF_AHB_CLK>, + <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>, + <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>, + <&gcc GCC_CAMSS_CSI0_AHB_CLK>, + <&gcc GCC_CAMSS_CSI0_CLK>, + <&gcc GCC_CAMSS_CSI0PHY_CLK>, + <&gcc GCC_CAMSS_CSI0PIX_CLK>, + <&gcc GCC_CAMSS_CSI0RDI_CLK>, + <&gcc GCC_CAMSS_CSI1_AHB_CLK>, + <&gcc GCC_CAMSS_CSI1_CLK>, + <&gcc GCC_CAMSS_CSI1PHY_CLK>, + <&gcc GCC_CAMSS_CSI1PIX_CLK>, + <&gcc GCC_CAMSS_CSI1RDI_CLK>, + <&gcc GCC_CAMSS_AHB_CLK>, + <&gcc GCC_CAMSS_VFE0_CLK>, + <&gcc GCC_CAMSS_CSI_VFE0_CLK>, + <&gcc GCC_CAMSS_VFE_AHB_CLK>, + <&gcc GCC_CAMSS_VFE_AXI_CLK>; + + clock-names = "top_ahb", + "ispif_ahb", + "csiphy0_timer", + "csiphy1_timer", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "ahb", + "vfe0", + "csi_vfe0", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 51 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 52 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 55 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csiphy0", + "csiphy1", + "csid0", + "csid1", + "ispif", + "vfe0"; + + iommus = <&apps_iommu 3>; + + power-domains = <&gcc VFE_GDSC>; + + reg = <0x01b0ac00 0x200>, + <0x01b00030 0x4>, + <0x01b0b000 0x200>, + <0x01b00038 0x4>, + <0x01b08000 0x100>, + <0x01b08400 0x100>, + <0x01b0a000 0x500>, + <0x01b00020 0x10>, + <0x01b10000 0x1000>; + + reg-names = "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csid0", + "csid1", + "ispif", + "csi_clk_mux", + "vfe0"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + + }; diff --git a/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml new file mode 100644 index 000000000000..38be41e932f0 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml @@ -0,0 +1,387 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,msm8996-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - Todor Tomov <todor.too@gmail.com> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,msm8996-camss + + clocks: + minItems: 36 + maxItems: 36 + + clock-names: + items: + - const: top_ahb + - const: ispif_ahb + - const: csiphy0_timer + - const: csiphy1_timer + - const: csiphy2_timer + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: csi2_ahb + - const: csi2 + - const: csi2_phy + - const: csi2_pix + - const: csi2_rdi + - const: csi3_ahb + - const: csi3 + - const: csi3_phy + - const: csi3_pix + - const: csi3_rdi + - const: ahb + - const: vfe0 + - const: csi_vfe0 + - const: vfe0_ahb + - const: vfe0_stream + - const: vfe1 + - const: csi_vfe1 + - const: vfe1_ahb + - const: vfe1_stream + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: ispif + - const: vfe0 + - const: vfe1 + + iommus: + maxItems: 4 + + power-domains: + items: + - description: VFE0 GDSC - Video Front End, Global Distributed Switch Controller. + - description: VFE1 GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + description: + An array of physical data lanes indexes. + Position of an entry determines the logical + lane number, while the value of an entry + indicates physical lane index. Lane swapping + is supported. Physical lane indexes are; + 0, 1, 2, 3 + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 14 + maxItems: 14 + + reg-names: + items: + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csiphy2 + - const: csiphy2_clk_mux + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: ispif + - const: csi_clk_mux + - const: vfe0 + - const: vfe1 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-msm8996.h> + #include <dt-bindings/clock/qcom,mmcc-msm8996.h> + + camss: camss@a00000 { + compatible = "qcom,msm8996-camss"; + + clocks = <&mmcc CAMSS_TOP_AHB_CLK>, + <&mmcc CAMSS_ISPIF_AHB_CLK>, + <&mmcc CAMSS_CSI0PHYTIMER_CLK>, + <&mmcc CAMSS_CSI1PHYTIMER_CLK>, + <&mmcc CAMSS_CSI2PHYTIMER_CLK>, + <&mmcc CAMSS_CSI0_AHB_CLK>, + <&mmcc CAMSS_CSI0_CLK>, + <&mmcc CAMSS_CSI0PHY_CLK>, + <&mmcc CAMSS_CSI0PIX_CLK>, + <&mmcc CAMSS_CSI0RDI_CLK>, + <&mmcc CAMSS_CSI1_AHB_CLK>, + <&mmcc CAMSS_CSI1_CLK>, + <&mmcc CAMSS_CSI1PHY_CLK>, + <&mmcc CAMSS_CSI1PIX_CLK>, + <&mmcc CAMSS_CSI1RDI_CLK>, + <&mmcc CAMSS_CSI2_AHB_CLK>, + <&mmcc CAMSS_CSI2_CLK>, + <&mmcc CAMSS_CSI2PHY_CLK>, + <&mmcc CAMSS_CSI2PIX_CLK>, + <&mmcc CAMSS_CSI2RDI_CLK>, + <&mmcc CAMSS_CSI3_AHB_CLK>, + <&mmcc CAMSS_CSI3_CLK>, + <&mmcc CAMSS_CSI3PHY_CLK>, + <&mmcc CAMSS_CSI3PIX_CLK>, + <&mmcc CAMSS_CSI3RDI_CLK>, + <&mmcc CAMSS_AHB_CLK>, + <&mmcc CAMSS_VFE0_CLK>, + <&mmcc CAMSS_CSI_VFE0_CLK>, + <&mmcc CAMSS_VFE0_AHB_CLK>, + <&mmcc CAMSS_VFE0_STREAM_CLK>, + <&mmcc CAMSS_VFE1_CLK>, + <&mmcc CAMSS_CSI_VFE1_CLK>, + <&mmcc CAMSS_VFE1_AHB_CLK>, + <&mmcc CAMSS_VFE1_STREAM_CLK>, + <&mmcc CAMSS_VFE_AHB_CLK>, + <&mmcc CAMSS_VFE_AXI_CLK>; + + clock-names = "top_ahb", + "ispif_ahb", + "csiphy0_timer", + "csiphy1_timer", + "csiphy2_timer", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "csi2_ahb", + "csi2", + "csi2_phy", + "csi2_pix", + "csi2_rdi", + "csi3_ahb", + "csi3", + "csi3_phy", + "csi3_pix", + "csi3_rdi", + "ahb", + "vfe0", + "csi_vfe0", + "vfe0_ahb", + "vfe0_stream", + "vfe1", + "csi_vfe1", + "vfe1_ahb", + "vfe1_stream", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 80 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 296 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 297 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 298 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 299 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 309 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 314 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 315 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csiphy0", + "csiphy1", + "csiphy2", + "csid0", + "csid1", + "csid2", + "csid3", + "ispif", + "vfe0", + "vfe1"; + + iommus = <&vfe_smmu 0>, + <&vfe_smmu 1>, + <&vfe_smmu 2>, + <&vfe_smmu 3>; + + power-domains = <&mmcc VFE0_GDSC>, + <&mmcc VFE1_GDSC>; + + reg = <0x00a34000 0x1000>, + <0x00a00030 0x4>, + <0x00a35000 0x1000>, + <0x00a00038 0x4>, + <0x00a36000 0x1000>, + <0x00a00040 0x4>, + <0x00a30000 0x100>, + <0x00a30400 0x100>, + <0x00a30800 0x100>, + <0x00a30c00 0x100>, + <0x00a31000 0x500>, + <0x00a00020 0x10>, + <0x00a10000 0x1000>, + <0x00a14000 0x1000>; + + reg-names = "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csiphy2", + "csiphy2_clk_mux", + "csid0", + "csid1", + "csid2", + "csid3", + "ispif", + "csi_clk_mux", + "vfe0", + "vfe1"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml new file mode 100644 index 000000000000..841a1aafdd13 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml @@ -0,0 +1,398 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,sdm660-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,sdm660-camss + + clocks: + minItems: 42 + maxItems: 42 + + clock-names: + items: + - const: ahb + - const: cphy_csid0 + - const: cphy_csid1 + - const: cphy_csid2 + - const: cphy_csid3 + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: csi2_ahb + - const: csi2 + - const: csi2_phy + - const: csi2_pix + - const: csi2_rdi + - const: csi3_ahb + - const: csi3 + - const: csi3_phy + - const: csi3_pix + - const: csi3_rdi + - const: csiphy0_timer + - const: csiphy1_timer + - const: csiphy2_timer + - const: csiphy_ahb2crif + - const: csi_vfe0 + - const: csi_vfe1 + - const: ispif_ahb + - const: throttle_axi + - const: top_ahb + - const: vfe0_ahb + - const: vfe0 + - const: vfe0_stream + - const: vfe1_ahb + - const: vfe1 + - const: vfe1_stream + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: ispif + - const: vfe0 + - const: vfe1 + + iommus: + maxItems: 4 + + power-domains: + items: + - description: VFE0 GDSC - Video Front End, Global Distributed Switch Controller. + - description: VFE1 GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 14 + maxItems: 14 + + reg-names: + items: + - const: csi_clk_mux + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csiphy2 + - const: csiphy2_clk_mux + - const: ispif + - const: vfe0 + - const: vfe1 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-sdm660.h> + #include <dt-bindings/clock/qcom,mmcc-sdm660.h> + + camss: camss@ca00000 { + compatible = "qcom,sdm660-camss"; + + clocks = <&mmcc CAMSS_AHB_CLK>, + <&mmcc CAMSS_CPHY_CSID0_CLK>, + <&mmcc CAMSS_CPHY_CSID1_CLK>, + <&mmcc CAMSS_CPHY_CSID2_CLK>, + <&mmcc CAMSS_CPHY_CSID3_CLK>, + <&mmcc CAMSS_CSI0_AHB_CLK>, + <&mmcc CAMSS_CSI0_CLK>, + <&mmcc CAMSS_CPHY_CSID0_CLK>, + <&mmcc CAMSS_CSI0PIX_CLK>, + <&mmcc CAMSS_CSI0RDI_CLK>, + <&mmcc CAMSS_CSI1_AHB_CLK>, + <&mmcc CAMSS_CSI1_CLK>, + <&mmcc CAMSS_CPHY_CSID1_CLK>, + <&mmcc CAMSS_CSI1PIX_CLK>, + <&mmcc CAMSS_CSI1RDI_CLK>, + <&mmcc CAMSS_CSI2_AHB_CLK>, + <&mmcc CAMSS_CSI2_CLK>, + <&mmcc CAMSS_CPHY_CSID2_CLK>, + <&mmcc CAMSS_CSI2PIX_CLK>, + <&mmcc CAMSS_CSI2RDI_CLK>, + <&mmcc CAMSS_CSI3_AHB_CLK>, + <&mmcc CAMSS_CSI3_CLK>, + <&mmcc CAMSS_CPHY_CSID3_CLK>, + <&mmcc CAMSS_CSI3PIX_CLK>, + <&mmcc CAMSS_CSI3RDI_CLK>, + <&mmcc CAMSS_CSI0PHYTIMER_CLK>, + <&mmcc CAMSS_CSI1PHYTIMER_CLK>, + <&mmcc CAMSS_CSI2PHYTIMER_CLK>, + <&mmcc CSIPHY_AHB2CRIF_CLK>, + <&mmcc CAMSS_CSI_VFE0_CLK>, + <&mmcc CAMSS_CSI_VFE1_CLK>, + <&mmcc CAMSS_ISPIF_AHB_CLK>, + <&mmcc THROTTLE_CAMSS_AXI_CLK>, + <&mmcc CAMSS_TOP_AHB_CLK>, + <&mmcc CAMSS_VFE0_AHB_CLK>, + <&mmcc CAMSS_VFE0_CLK>, + <&mmcc CAMSS_VFE0_STREAM_CLK>, + <&mmcc CAMSS_VFE1_AHB_CLK>, + <&mmcc CAMSS_VFE1_CLK>, + <&mmcc CAMSS_VFE1_STREAM_CLK>, + <&mmcc CAMSS_VFE_VBIF_AHB_CLK>, + <&mmcc CAMSS_VFE_VBIF_AXI_CLK>; + + clock-names = "ahb", + "cphy_csid0", + "cphy_csid1", + "cphy_csid2", + "cphy_csid3", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "csi2_ahb", + "csi2", + "csi2_phy", + "csi2_pix", + "csi2_rdi", + "csi3_ahb", + "csi3", + "csi3_phy", + "csi3_pix", + "csi3_rdi", + "csiphy0_timer", + "csiphy1_timer", + "csiphy2_timer", + "csiphy_ahb2crif", + "csi_vfe0", + "csi_vfe1", + "ispif_ahb", + "throttle_axi", + "top_ahb", + "vfe0_ahb", + "vfe0", + "vfe0_stream", + "vfe1_ahb", + "vfe1", + "vfe1_stream", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 296 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 297 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 298 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 299 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 80 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 309 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 314 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 315 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csid0", + "csid1", + "csid2", + "csid3", + "csiphy0", + "csiphy1", + "csiphy2", + "ispif", + "vfe0", + "vfe1"; + + iommus = <&mmss_smmu 0xc00>, + <&mmss_smmu 0xc01>, + <&mmss_smmu 0xc02>, + <&mmss_smmu 0xc03>; + + power-domains = <&mmcc CAMSS_VFE0_GDSC>, + <&mmcc CAMSS_VFE1_GDSC>; + + reg = <0x0ca00020 0x10>, + <0x0ca30000 0x100>, + <0x0ca30400 0x100>, + <0x0ca30800 0x100>, + <0x0ca30c00 0x100>, + <0x0c824000 0x1000>, + <0x0ca00120 0x4>, + <0x0c825000 0x1000>, + <0x0ca00124 0x4>, + <0x0c826000 0x1000>, + <0x0ca00128 0x4>, + <0x0ca31000 0x500>, + <0x0ca10000 0x1000>, + <0x0ca14000 0x1000>; + + reg-names = "csi_clk_mux", + "csid0", + "csid1", + "csid2", + "csid3", + "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csiphy2", + "csiphy2_clk_mux", + "ispif", + "vfe0", + "vfe1"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml new file mode 100644 index 000000000000..9ca5dfa7f226 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml @@ -0,0 +1,371 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,sdm845-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,sdm845-camss + + clocks: + minItems: 36 + maxItems: 36 + + clock-names: + items: + - const: camnoc_axi + - const: cpas_ahb + - const: cphy_rx_src + - const: csi0 + - const: csi0_src + - const: csi1 + - const: csi1_src + - const: csi2 + - const: csi2_src + - const: csiphy0 + - const: csiphy0_timer + - const: csiphy0_timer_src + - const: csiphy1 + - const: csiphy1_timer + - const: csiphy1_timer_src + - const: csiphy2 + - const: csiphy2_timer + - const: csiphy2_timer_src + - const: csiphy3 + - const: csiphy3_timer + - const: csiphy3_timer_src + - const: gcc_camera_ahb + - const: gcc_camera_axi + - const: slow_ahb_src + - const: soc_ahb + - const: vfe0_axi + - const: vfe0 + - const: vfe0_cphy_rx + - const: vfe0_src + - const: vfe1_axi + - const: vfe1 + - const: vfe1_cphy_rx + - const: vfe1_src + - const: vfe_lite + - const: vfe_lite_cphy_rx + - const: vfe_lite_src + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csiphy3 + - const: vfe0 + - const: vfe1 + - const: vfe_lite + + iommus: + maxItems: 4 + + power-domains: + items: + - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller. + - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller. + - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 10 + maxItems: 10 + + reg-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csiphy3 + - const: vfe0 + - const: vfe1 + - const: vfe_lite + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,camcc-sdm845.h> + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + camss: camss@a00000 { + compatible = "qcom,sdm845-camss"; + + clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>, + <&clock_camcc CAM_CC_CPAS_AHB_CLK>, + <&clock_camcc CAM_CC_CPHY_RX_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_0_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_0_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_1_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_1_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_LITE_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY0_CLK>, + <&clock_camcc CAM_CC_CSI0PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI0PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY1_CLK>, + <&clock_camcc CAM_CC_CSI1PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI1PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY2_CLK>, + <&clock_camcc CAM_CC_CSI2PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI2PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY3_CLK>, + <&clock_camcc CAM_CC_CSI3PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI3PHYTIMER_CLK_SRC>, + <&gcc GCC_CAMERA_AHB_CLK>, + <&gcc GCC_CAMERA_AXI_CLK>, + <&clock_camcc CAM_CC_SLOW_AHB_CLK_SRC>, + <&clock_camcc CAM_CC_SOC_AHB_CLK>, + <&clock_camcc CAM_CC_IFE_0_AXI_CLK>, + <&clock_camcc CAM_CC_IFE_0_CLK>, + <&clock_camcc CAM_CC_IFE_0_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_0_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_1_AXI_CLK>, + <&clock_camcc CAM_CC_IFE_1_CLK>, + <&clock_camcc CAM_CC_IFE_1_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_1_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_LITE_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CLK_SRC>; + + clock-names = "camnoc_axi", + "cpas_ahb", + "cphy_rx_src", + "csi0", + "csi0_src", + "csi1", + "csi1_src", + "csi2", + "csi2_src", + "csiphy0", + "csiphy0_timer", + "csiphy0_timer_src", + "csiphy1", + "csiphy1_timer", + "csiphy1_timer_src", + "csiphy2", + "csiphy2_timer", + "csiphy2_timer_src", + "csiphy3", + "csiphy3_timer", + "csiphy3_timer_src", + "gcc_camera_ahb", + "gcc_camera_axi", + "slow_ahb_src", + "soc_ahb", + "vfe0_axi", + "vfe0", + "vfe0_cphy_rx", + "vfe0_src", + "vfe1_axi", + "vfe1", + "vfe1_cphy_rx", + "vfe1_src", + "vfe_lite", + "vfe_lite_cphy_rx", + "vfe_lite_src"; + + interrupts = <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 477 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 478 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 479 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>; + + interrupt-names = "csid0", + "csid1", + "csid2", + "csiphy0", + "csiphy1", + "csiphy2", + "csiphy3", + "vfe0", + "vfe1", + "vfe_lite"; + + iommus = <&apps_smmu 0x0808 0x0>, + <&apps_smmu 0x0810 0x8>, + <&apps_smmu 0x0c08 0x0>, + <&apps_smmu 0x0c10 0x8>; + + power-domains = <&clock_camcc IFE_0_GDSC>, + <&clock_camcc IFE_1_GDSC>, + <&clock_camcc TITAN_TOP_GDSC>; + + reg = <0 0xacb3000 0 0x1000>, + <0 0xacba000 0 0x1000>, + <0 0xacc8000 0 0x1000>, + <0 0xac65000 0 0x1000>, + <0 0xac66000 0 0x1000>, + <0 0xac67000 0 0x1000>, + <0 0xac68000 0 0x1000>, + <0 0xacaf000 0 0x4000>, + <0 0xacb6000 0 0x4000>, + <0 0xacc4000 0 0x4000>; + + reg-names = "csid0", + "csid1", + "csid2", + "csiphy0", + "csiphy1", + "csiphy2", + "csiphy3", + "vfe0", + "vfe1", + "vfe_lite"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml new file mode 100644 index 000000000000..7b81bd7f2399 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml @@ -0,0 +1,167 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,sm8250-venus.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Venus video encode and decode accelerators + +maintainers: + - Stanimir Varbanov <stanimir.varbanov@linaro.org> + +description: | + The Venus IP is a video encode and decode accelerator present + on Qualcomm platforms + +properties: + compatible: + const: qcom,sm8250-venus + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + power-domains: + minItems: 2 + maxItems: 3 + + power-domain-names: + minItems: 2 + maxItems: 3 + items: + - const: venus + - const: vcodec0 + - const: mx + + clocks: + maxItems: 3 + + clock-names: + items: + - const: iface + - const: core + - const: vcodec0_core + + iommus: + maxItems: 1 + + memory-region: + maxItems: 1 + + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: cpu-cfg + - const: video-mem + + resets: + maxItems: 2 + + reset-names: + items: + - const: bus + - const: core + + video-decoder: + type: object + + properties: + compatible: + const: venus-decoder + + required: + - compatible + + additionalProperties: false + + video-encoder: + type: object + + properties: + compatible: + const: venus-encoder + + required: + - compatible + + additionalProperties: false + + video-firmware: + type: object + + description: | + Firmware subnode is needed when the platform does not + have TrustZone. + + properties: + iommus: + maxItems: 1 + + required: + - iommus + +required: + - compatible + - reg + - interrupts + - power-domains + - power-domain-names + - clocks + - clock-names + - interconnects + - interconnect-names + - iommus + - memory-region + - resets + - reset-names + - video-decoder + - video-encoder + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,videocc-sm8250.h> + #include <dt-bindings/interconnect/qcom,sm8250.h> + #include <dt-bindings/clock/qcom,gcc-sm8250.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + venus: video-codec@aa00000 { + compatible = "qcom,sm8250-venus"; + reg = <0x0aa00000 0xff000>; + interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&videocc MVS0C_GDSC>, + <&videocc MVS0_GDSC>, + <&rpmhpd SM8250_MX>; + power-domain-names = "venus", "vcodec0", "mx"; + + clocks = <&gcc GCC_VIDEO_AXI0_CLK>, + <&videocc VIDEO_CC_MVS0C_CLK>, + <&videocc VIDEO_CC_MVS0_CLK>; + clock-names = "iface", "core", "vcodec0_core"; + + interconnects = <&gem_noc MASTER_AMPSS_M0 &config_noc SLAVE_VENUS_CFG>, + <&mmss_noc MASTER_VIDEO_P0 &mc_virt SLAVE_EBI_CH0>; + interconnect-names = "cpu-cfg", "video-mem"; + + iommus = <&apps_smmu 0x2100 0x0400>; + memory-region = <&video_mem>; + + resets = <&gcc GCC_VIDEO_AXI0_CLK_ARES>, + <&videocc VIDEO_CC_MVS0C_CLK_ARES>; + reset-names = "bus", "core"; + + video-decoder { + compatible = "venus-decoder"; + }; + + video-encoder { + compatible = "venus-encoder"; + }; + }; diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml index 946441b4e1a5..af9e7e59e5a1 100644 --- a/Documentation/devicetree/bindings/media/rc.yaml +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -90,9 +90,12 @@ properties: - rc-leadtek-y04g0051 - rc-lme2510 - rc-manli + - rc-mecool-kii-pro + - rc-mecool-kiii-pro - rc-medion-x10 - rc-medion-x10-digitainer - rc-medion-x10-or2x + - rc-minix-neo - rc-msi-digivox-ii - rc-msi-digivox-iii - rc-msi-tvanywhere @@ -145,11 +148,13 @@ properties: - rc-videomate-s350 - rc-videomate-tv-pvr - rc-videostrong-kii-pro + - rc-vega-s9x - rc-wetek-hub - rc-wetek-play2 - rc-winfast - rc-winfast-usbii-deluxe - rc-x96max + - rc-xbox-360 - rc-xbox-dvd - rc-zx-irdec diff --git a/Documentation/devicetree/bindings/media/renesas,drif.txt b/Documentation/devicetree/bindings/media/renesas,drif.txt deleted file mode 100644 index 0d8974aa8b38..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,drif.txt +++ /dev/null @@ -1,177 +0,0 @@ -Renesas R-Car Gen3 Digital Radio Interface controller (DRIF) ------------------------------------------------------------- - -R-Car Gen3 DRIF is a SPI like receive only slave device. A general -representation of DRIF interfacing with a master device is shown below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| |-----SD0------->|D0 | -| |-----SD1------->|D1 | -+---------------------+ +---------------------+ - -As per datasheet, each DRIF channel (drifn) is made up of two internal -channels (drifn0 & drifn1). These two internal channels share the common -CLK & SYNC. Each internal channel has its own dedicated resources like -irq, dma channels, address space & clock. This internal split is not -visible to the external master device. - -The device tree model represents each internal channel as a separate node. -The internal channels sharing the CLK & SYNC are tied together by their -phandles using a property called "renesas,bonding". For the rest of -the documentation, unless explicitly stated, the word channel implies an -internal channel. - -When both internal channels are enabled they need to be managed together -as one (i.e.) they cannot operate alone as independent devices. Out of the -two, one of them needs to act as a primary device that accepts common -properties of both the internal channels. This channel is identified by a -property called "renesas,primary-bond". - -To summarize, - - When both the internal channels that are bonded together are enabled, - the zeroth channel is selected as primary-bond. This channels accepts - properties common to all the members of the bond. - - When only one of the bonded channels need to be enabled, the property - "renesas,bonding" or "renesas,primary-bond" will have no effect. That - enabled channel can act alone as any other independent device. - -Required properties of an internal channel: -------------------------------------------- -- compatible: "renesas,r8a7795-drif" if DRIF controller is a part of R8A7795 SoC. - "renesas,r8a7796-drif" if DRIF controller is a part of R8A7796 SoC. - "renesas,rcar-gen3-drif" for a generic R-Car Gen3 compatible device. - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first - followed by the generic version. - -- reg: offset and length of that channel. -- interrupts: associated with that channel. -- clocks: phandle and clock specifier of that channel. -- clock-names: clock input name string: "fck". -- dmas: phandles to the DMA channels. -- dma-names: names of the DMA channel: "rx". -- renesas,bonding: phandle to the other channel. - -Optional properties of an internal channel: -------------------------------------------- -- power-domains: phandle to the respective power domain. - -Required properties of an internal channel when: - - It is the only enabled channel of the bond (or) - - If it acts as primary among enabled bonds --------------------------------------------------------- -- pinctrl-0: pin control group to be used for this channel. -- pinctrl-names: must be "default". -- renesas,primary-bond: empty property indicating the channel acts as primary - among the bonded channels. -- port: child port node corresponding to the data input, in accordance with - the video interface bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The port - node must contain at least one endpoint. - -Optional endpoint property: ---------------------------- -- sync-active: Indicates sync signal polarity, 0/1 for low/high respectively. - This property maps to SYNCAC bit in the hardware manual. The - default is 1 (active high). - -Example: --------- - -(1) Both internal channels enabled: ------------------------------------ - -When interfacing with a third party tuner device with two data pins as shown -below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| |-----SD0------->|D0 | -| |-----SD1------->|D1 | -+---------------------+ +---------------------+ - - drif00: rif@e6f40000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f40000 0 0x64>; - interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 515>; - clock-names = "fck"; - dmas = <&dmac1 0x20>, <&dmac2 0x20>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif01>; - renesas,primary-bond; - pinctrl-0 = <&drif0_pins>; - pinctrl-names = "default"; - port { - drif0_ep: endpoint { - remote-endpoint = <&tuner_ep>; - }; - }; - }; - - drif01: rif@e6f50000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f50000 0 0x64>; - interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 514>; - clock-names = "fck"; - dmas = <&dmac1 0x22>, <&dmac2 0x22>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif00>; - }; - - -(2) Internal channel 1 alone is enabled: ----------------------------------------- - -When interfacing with a third party tuner device with one data pin as shown -below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| | |D0 (unused) | -| |-----SD-------->|D1 | -+---------------------+ +---------------------+ - - drif00: rif@e6f40000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f40000 0 0x64>; - interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 515>; - clock-names = "fck"; - dmas = <&dmac1 0x20>, <&dmac2 0x20>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif01>; - }; - - drif01: rif@e6f50000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f50000 0 0x64>; - interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 514>; - clock-names = "fck"; - dmas = <&dmac1 0x22>, <&dmac2 0x22>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif00>; - pinctrl-0 = <&drif0_pins>; - pinctrl-names = "default"; - port { - drif0_ep: endpoint { - remote-endpoint = <&tuner_ep>; - sync-active = <0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,drif.yaml b/Documentation/devicetree/bindings/media/renesas,drif.yaml new file mode 100644 index 000000000000..9cd56ff2c316 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,drif.yaml @@ -0,0 +1,271 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,drif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen3 Digital Radio Interface Controller (DRIF) + +maintainers: + - Ramesh Shanmugasundaram <rashanmu@gmail.com> + - Fabrizio Castro <fabrizio.castro.jz@renesas.com> + +description: | + R-Car Gen3 DRIF is a SPI like receive only slave device. A general + representation of DRIF interfacing with a master device is shown below. + + +---------------------+ +---------------------+ + | |-----SCK------->|CLK | + | Master |-----SS-------->|SYNC DRIFn (slave) | + | |-----SD0------->|D0 | + | |-----SD1------->|D1 | + +---------------------+ +---------------------+ + + As per datasheet, each DRIF channel (drifn) is made up of two internal + channels (drifn0 & drifn1). These two internal channels share the common + CLK & SYNC. Each internal channel has its own dedicated resources like + irq, dma channels, address space & clock. This internal split is not + visible to the external master device. + + The device tree model represents each internal channel as a separate node. + The internal channels sharing the CLK & SYNC are tied together by their + phandles using a property called "renesas,bonding". For the rest of + the documentation, unless explicitly stated, the word channel implies an + internal channel. + + When both internal channels are enabled they need to be managed together + as one (i.e.) they cannot operate alone as independent devices. Out of the + two, one of them needs to act as a primary device that accepts common + properties of both the internal channels. This channel is identified by a + property called "renesas,primary-bond". + + To summarize, + * When both the internal channels that are bonded together are enabled, + the zeroth channel is selected as primary-bond. This channels accepts + properties common to all the members of the bond. + * When only one of the bonded channels need to be enabled, the property + "renesas,bonding" or "renesas,primary-bond" will have no effect. That + enabled channel can act alone as any other independent device. + +properties: + compatible: + items: + - enum: + - renesas,r8a7795-drif # R-Car H3 + - renesas,r8a7796-drif # R-Car M3-W + - renesas,r8a77965-drif # R-Car M3-N + - renesas,r8a77990-drif # R-Car E3 + - const: renesas,rcar-gen3-drif # Generic R-Car Gen3 compatible device + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: fck + + resets: + maxItems: 1 + + dmas: + minItems: 1 + maxItems: 2 + + dma-names: + minItems: 1 + maxItems: 2 + items: + - const: rx + - const: rx + + renesas,bonding: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The phandle to the other internal channel of DRIF + + power-domains: + maxItems: 1 + + renesas,primary-bond: + type: boolean + description: + Indicates that the channel acts as primary among the bonded channels. + + port: + $ref: /schemas/graph.yaml#/properties/port + unevaluatedProperties: false + description: + Child port node corresponding to the data input. The port node must + contain at least one endpoint. + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + + properties: + sync-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: + Indicates sync signal polarity, 0/1 for low/high respectively. + This property maps to SYNCAC bit in the hardware manual. The + default is 1 (active high). + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - dmas + - dma-names + - renesas,bonding + - power-domains + +allOf: + - if: + required: + - renesas,primary-bond + then: + required: + - pinctrl-0 + - pinctrl-names + - port + + - if: + required: + - port + then: + required: + - pinctrl-0 + - pinctrl-names + else: + properties: + pinctrl-0: false + pinctrl-names: false + +additionalProperties: false + +examples: + # Example with both internal channels enabled. + # + # When interfacing with a third party tuner device with two data pins as shown + # below. + # + # +---------------------+ +---------------------+ + # | |-----SCK------->|CLK | + # | Master |-----SS-------->|SYNC DRIFn (slave) | + # | |-----SD0------->|D0 | + # | |-----SD1------->|D1 | + # +---------------------+ +---------------------+ + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + drif00: rif@e6f40000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f40000 0 0x64>; + interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 515>; + clock-names = "fck"; + dmas = <&dmac1 0x20>, <&dmac2 0x20>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif01>; + resets = <&cpg 515>; + renesas,primary-bond; + pinctrl-0 = <&drif0_pins>; + pinctrl-names = "default"; + port { + drif0_ep: endpoint { + remote-endpoint = <&tuner_ep>; + }; + }; + }; + + drif01: rif@e6f50000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f50000 0 0x64>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 514>; + clock-names = "fck"; + dmas = <&dmac1 0x22>, <&dmac2 0x22>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif00>; + resets = <&cpg 514>; + }; + }; + + # Example with internal channel 1 alone enabled. + # + # When interfacing with a third party tuner device with one data pin as shown + # below. + # + # +---------------------+ +---------------------+ + # | |-----SCK------->|CLK | + # | Master |-----SS-------->|SYNC DRIFn (slave) | + # | | |D0 (unused) | + # | |-----SD-------->|D1 | + # +---------------------+ +---------------------+ + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + drif10: rif@e6f60000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f60000 0 0x64>; + interrupts = <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 513>; + clock-names = "fck"; + dmas = <&dmac1 0x24>, <&dmac2 0x24>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 513>; + renesas,bonding = <&drif11>; + status = "disabled"; + }; + + drif11: rif@e6f70000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f70000 0 0x64>; + interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 512>; + clock-names = "fck"; + dmas = <&dmac1 0x26>, <&dmac2 0x26>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 512>; + renesas,bonding = <&drif10>; + pinctrl-0 = <&drif1_pins>; + pinctrl-names = "default"; + port { + drif1_ep: endpoint { + remote-endpoint = <&tuner_ep1>; + sync-active = <0>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/renesas,vin.yaml b/Documentation/devicetree/bindings/media/renesas,vin.yaml index fe7c4cbfe4ba..dd1a5ce5896c 100644 --- a/Documentation/devicetree/bindings/media/renesas,vin.yaml +++ b/Documentation/devicetree/bindings/media/renesas,vin.yaml @@ -193,23 +193,35 @@ required: - interrupts - clocks - power-domains - - resets - -if: - properties: - compatible: - contains: - enum: - - renesas,vin-r8a7778 - - renesas,vin-r8a7779 - - renesas,rcar-gen2-vin -then: - required: - - port -else: - required: - - renesas,id - - ports + +allOf: + - if: + not: + properties: + compatible: + contains: + enum: + - renesas,vin-r8a7778 + - renesas,vin-r8a7779 + then: + required: + - resets + + - if: + properties: + compatible: + contains: + enum: + - renesas,vin-r8a7778 + - renesas,vin-r8a7779 + - renesas,rcar-gen2-vin + then: + required: + - port + else: + required: + - renesas,id + - ports additionalProperties: false diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml index 0a7a73fd59f2..4391dce2caee 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.yaml +++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml @@ -215,130 +215,3 @@ properties: CCP2, for instance. additionalProperties: true - -examples: - # The example snippet below describes two data pipelines. ov772x and imx074 - # are camera sensors with a parallel and serial (MIPI CSI-2) video bus - # respectively. Both sensors are on the I2C control bus corresponding to the - # i2c0 controller node. ov772x sensor is linked directly to the ceu0 video - # host interface. imx074 is linked to ceu0 through the MIPI CSI-2 receiver - # (csi2). ceu0 has a (single) DMA engine writing captured data to memory. - # ceu0 node has a single 'port' node which may indicate that at any time - # only one of the following data pipelines can be active: - # ov772x -> ceu0 or imx074 -> csi2 -> ceu0. - - | - ceu@fe910000 { - compatible = "renesas,sh-mobile-ceu"; - reg = <0xfe910000 0xa0>; - interrupts = <0x880>; - - mclk: master_clock { - compatible = "renesas,ceu-clock"; - #clock-cells = <1>; - clock-frequency = <50000000>; /* Max clock frequency */ - clock-output-names = "mclk"; - }; - - port { - #address-cells = <1>; - #size-cells = <0>; - - /* Parallel bus endpoint */ - ceu0_1: endpoint@1 { - reg = <1>; /* Local endpoint # */ - remote-endpoint = <&ov772x_1_1>; /* Remote phandle */ - bus-width = <8>; /* Used data lines */ - data-shift = <2>; /* Lines 9:2 are used */ - - /* If hsync-active/vsync-active are missing, - embedded BT.656 sync is used */ - hsync-active = <0>; /* Active low */ - vsync-active = <0>; /* Active low */ - data-active = <1>; /* Active high */ - pclk-sample = <1>; /* Rising */ - }; - - /* MIPI CSI-2 bus endpoint */ - ceu0_0: endpoint@0 { - reg = <0>; - remote-endpoint = <&csi2_2>; - }; - }; - }; - - i2c { - #address-cells = <1>; - #size-cells = <0>; - - camera@21 { - compatible = "ovti,ov772x"; - reg = <0x21>; - vddio-supply = <®ulator1>; - vddcore-supply = <®ulator2>; - - clock-frequency = <20000000>; - clocks = <&mclk 0>; - clock-names = "xclk"; - - port { - /* With 1 endpoint per port no need for addresses. */ - ov772x_1_1: endpoint { - bus-width = <8>; - remote-endpoint = <&ceu0_1>; - hsync-active = <1>; - vsync-active = <0>; /* Who came up with an - inverter here ?... */ - data-active = <1>; - pclk-sample = <1>; - }; - }; - }; - - camera@1a { - compatible = "sony,imx074"; - reg = <0x1a>; - vddio-supply = <®ulator1>; - vddcore-supply = <®ulator2>; - - clock-frequency = <30000000>; /* Shared clock with ov772x_1 */ - clocks = <&mclk 0>; - clock-names = "sysclk"; /* Assuming this is the - name in the datasheet */ - port { - imx074_1: endpoint { - clock-lanes = <0>; - data-lanes = <1 2>; - remote-endpoint = <&csi2_1>; - }; - }; - }; - }; - - csi2: csi2@ffc90000 { - compatible = "renesas,sh-mobile-csi2"; - reg = <0xffc90000 0x1000>; - interrupts = <0x17a0>; - #address-cells = <1>; - #size-cells = <0>; - - port@1 { - compatible = "renesas,csi2c"; /* One of CSI2I and CSI2C. */ - reg = <1>; /* CSI-2 PHY #1 of 2: PHY_S, - PHY_M has port address 0, - is unused. */ - csi2_1: endpoint { - clock-lanes = <0>; - data-lanes = <2 1>; - remote-endpoint = <&imx074_1>; - }; - }; - port@2 { - reg = <2>; /* port 2: link to the CEU */ - - csi2_2: endpoint { - remote-endpoint = <&ceu0_0>; - }; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/media/video-mux.txt b/Documentation/devicetree/bindings/media/video-mux.txt deleted file mode 100644 index 63b9dc913e45..000000000000 --- a/Documentation/devicetree/bindings/media/video-mux.txt +++ /dev/null @@ -1,60 +0,0 @@ -Video Multiplexer -================= - -Video multiplexers allow to select between multiple input ports. Video received -on the active input port is passed through to the output port. Muxes described -by this binding are controlled by a multiplexer controller that is described by -the bindings in Documentation/devicetree/bindings/mux/mux-controller.txt - -Required properties: -- compatible : should be "video-mux" -- mux-controls : mux controller node to use for operating the mux -- #address-cells: should be <1> -- #size-cells: should be <0> -- port@*: at least three port nodes containing endpoints connecting to the - source and sink devices according to of_graph bindings. The last port is - the output port, all others are inputs. - -Optionally, #address-cells, #size-cells, and port nodes can be grouped under a -ports node as described in Documentation/devicetree/bindings/graph.txt. - -Example: - - mux: mux-controller { - compatible = "gpio-mux"; - #mux-control-cells = <0>; - - mux-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; - }; - - video-mux { - compatible = "video-mux"; - mux-controls = <&mux>; - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - mux_in0: endpoint { - remote-endpoint = <&video_source0_out>; - }; - }; - - port@1 { - reg = <1>; - - mux_in1: endpoint { - remote-endpoint = <&video_source1_out>; - }; - }; - - port@2 { - reg = <2>; - - mux_out: endpoint { - remote-endpoint = <&capture_interface_in>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/video-mux.yaml b/Documentation/devicetree/bindings/media/video-mux.yaml new file mode 100644 index 000000000000..2f28a7dad93f --- /dev/null +++ b/Documentation/devicetree/bindings/media/video-mux.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/video-mux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Video Multiplexer + +maintainers: + - Sakari Ailus <sakari.ailus@linux.intel.com> + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: + Video multiplexers allow to select between multiple input ports. Video + received on the active input port is passed through to the output port. Muxes + described by this binding are controlled by a multiplexer controller. + +properties: + compatible: + const: video-mux + + mux-controls: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + patternProperties: + '^port@': + $ref: /schemas/graph.yaml#/properties/port + + required: + - port@0 + - port@1 + - port@2 + +patternProperties: + '^port@': + $ref: /schemas/graph.yaml#/properties/port + description: + At least three port nodes containing endpoints connecting to the source + and sink devices according to of_graph bindings. The last port is the + output port, all others are inputs. + +required: + - compatible + - mux-controls + +oneOf: + - required: + - ports + - required: + - port@0 + - port@1 + - port@2 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; + }; + + video-mux { + compatible = "video-mux"; + mux-controls = <&mux>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mux_in0: endpoint { + remote-endpoint = <&video_source0_out>; + }; + }; + + port@1 { + reg = <1>; + + mux_in1: endpoint { + remote-endpoint = <&video_source1_out>; + }; + }; + + port@2 { + reg = <2>; + + mux_out: endpoint { + remote-endpoint = <&capture_interface_in>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/zx-irdec.txt b/Documentation/devicetree/bindings/media/zx-irdec.txt deleted file mode 100644 index 295b9fab593e..000000000000 --- a/Documentation/devicetree/bindings/media/zx-irdec.txt +++ /dev/null @@ -1,14 +0,0 @@ -IR Decoder (IRDEC) on ZTE ZX family SoCs - -Required properties: - - compatible: Should be "zte,zx296718-irdec". - - reg: Physical base address and length of IRDEC registers. - - interrupts: Interrupt number of IRDEC. - -Exmaples: - - irdec: ir-decoder@111000 { - compatible = "zte,zx296718-irdec"; - reg = <0x111000 0x1000>; - interrupts = <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml index 09bde65e1955..9163c3f12a85 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml @@ -37,9 +37,10 @@ properties: description: phandle of the memory controller node - core-supply: + power-domains: + maxItems: 1 description: - Phandle of voltage regulator of the SoC "core" power domain. + Phandle of the SoC "core" power domain. operating-points-v2: description: @@ -370,7 +371,7 @@ examples: nvidia,memory-controller = <&mc>; operating-points-v2 = <&dvfs_opp_table>; - core-supply = <&vdd_core>; + power-domains = <&domain>; #interconnect-cells = <0>; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt index cc443fcf4bec..d2250498c36d 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt @@ -23,7 +23,7 @@ For each opp entry in 'operating-points-v2' table: matches, the OPP gets enabled. Optional properties: -- core-supply: Phandle of voltage regulator of the SoC "core" power domain. +- power-domains: Phandle of the SoC "core" power domain. Child device nodes describe the memory settings for different configurations and clock rates. @@ -48,7 +48,7 @@ Example: interrupts = <0 78 0x04>; clocks = <&tegra_car TEGRA20_CLK_EMC>; nvidia,memory-controller = <&mc>; - core-supply = <&core_vdd_reg>; + power-domains = <&domain>; operating-points-v2 = <&opp_table>; } diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt deleted file mode 100644 index 739b7c6f2e26..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra20 MC(Memory Controller) - -Required properties: -- compatible : "nvidia,tegra20-mc-gart" -- reg : Should contain 2 register ranges: physical base address and length of - the controller's registers and the GART aperture respectively. -- 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: - - mc: the module's clock input -- interrupts : Should contain MC General interrupt. -- #reset-cells : Should be 1. This cell represents memory client module ID. - The assignments may be found in header file <dt-bindings/memory/tegra20-mc.h> - or in the TRM documentation. -- #iommu-cells: Should be 0. This cell represents the number of cells in an - IOMMU specifier needed to encode an address. GART supports only a single - address space that is shared by all devices, therefore no additional - information needed for the address encoding. -- #interconnect-cells : Should be 1. This cell represents memory client. - The assignments may be found in header file <dt-bindings/memory/tegra20-mc.h>. - -Example: - mc: memory-controller@7000f000 { - compatible = "nvidia,tegra20-mc-gart"; - reg = <0x7000f000 0x400 /* controller registers */ - 0x58000000 0x02000000>; /* GART aperture */ - clocks = <&tegra_car TEGRA20_CLK_MC>; - clock-names = "mc"; - interrupts = <GIC_SPI 77 0x04>; - #reset-cells = <1>; - #iommu-cells = <0>; - #interconnect-cells = <1>; - }; - - video-codec@6001a000 { - compatible = "nvidia,tegra20-vde"; - ... - resets = <&mc TEGRA20_MC_RESET_VDE>; - iommus = <&mc>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml new file mode 100644 index 000000000000..55caf6905399 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/nvidia,tegra20-mc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 SoC Memory Controller + +maintainers: + - Dmitry Osipenko <digetx@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +description: | + The Tegra20 Memory Controller merges request streams from various client + interfaces into request stream(s) for the various memory target devices, + and returns response data to the various clients. The Memory Controller + has a configurable arbitration algorithm to allow the user to fine-tune + performance among the various clients. + + Tegra20 Memory Controller includes the GART (Graphics Address Relocation + Table) which allows Memory Controller to provide a linear view of a + fragmented memory pages. + +properties: + compatible: + const: nvidia,tegra20-mc-gart + + reg: + items: + - description: controller registers + - description: GART registers + + clocks: + maxItems: 1 + + clock-names: + items: + - const: mc + + interrupts: + maxItems: 1 + + "#reset-cells": + const: 1 + + "#iommu-cells": + const: 0 + + "#interconnect-cells": + const: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - "#reset-cells" + - "#iommu-cells" + - "#interconnect-cells" + +additionalProperties: false + +examples: + - | + memory-controller@7000f000 { + compatible = "nvidia,tegra20-mc-gart"; + reg = <0x7000f000 0x400>, /* Controller registers */ + <0x58000000 0x02000000>; /* GART aperture */ + clocks = <&clock_controller 32>; + clock-names = "mc"; + + interrupts = <0 77 4>; + + #iommu-cells = <0>; + #reset-cells = <1>; + #interconnect-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra210-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra210-emc.yaml index 49ab09252e52..bc8477e7ab19 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra210-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra210-emc.yaml @@ -34,7 +34,7 @@ properties: - description: EMC general interrupt memory-region: - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 description: phandle to a reserved memory region describing the table of EMC frequencies trained by the firmware diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml index 0a2e2c0d0fdd..fb6af14cb49c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml @@ -39,9 +39,10 @@ properties: description: Phandle of the Memory Controller node. - core-supply: + power-domains: + maxItems: 1 description: - Phandle of voltage regulator of the SoC "core" power domain. + Phandle of the SoC "core" power domain. operating-points-v2: description: @@ -241,7 +242,7 @@ examples: nvidia,memory-controller = <&mc>; operating-points-v2 = <&dvfs_opp_table>; - core-supply = <&vdd_core>; + power-domains = <&domain>; #interconnect-cells = <0>; diff --git a/Documentation/devicetree/bindings/mfd/actions,atc260x.yaml b/Documentation/devicetree/bindings/mfd/actions,atc260x.yaml new file mode 100644 index 000000000000..dd43a0c766f3 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/actions,atc260x.yaml @@ -0,0 +1,183 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/actions,atc260x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Actions Semi ATC260x Power Management IC bindings + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + - Cristian Ciocaltea <cristian.ciocaltea@gmail.com> + +description: | + ATC260x series PMICs integrates Audio Codec, Power Management, RTC, IR + and GPIO controller blocks. Currently only the PM related functionalities + (i.e. regulators and system power-off/reboot) for the ATC2603C and ATC2609A + chip variants are supported. + ATC2603C includes 3 programmable DC-DC converters, 9 programmable LDO + regulators and 1 fixed LDO regulator. + ATC2609A includes 5 programmable DC-DC converters and 10 programmable LDO + regulators. + +allOf: + - $ref: ../input/input.yaml + +properties: + compatible: + enum: + - actions,atc2603c + - actions,atc2609a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-time-sec: + description: | + Duration in seconds which the key should be kept pressed for device + to reset automatically. The hardware default is 8. Use 0 to disable + this functionality. + enum: [0, 6, 8, 10, 12] + + regulators: + type: object + description: | + List of child nodes specifying the regulators, depending on chip variant: + * ATC2603C: dcdc[1-3], ldo[1-3,5-8,11,12], switchldo1 + * ATC2609A: dcdc[0-4], ldo[0-9] + + properties: + compatible: + enum: + - actions,atc2603c-regulator + - actions,atc2609a-regulator + + switchldo1: + type: object + $ref: ../regulator/regulator.yaml + + properties: + regulator-name: true + regulator-boot-on: true + regulator-always-on: true + regulator-min-microvolt: true + regulator-max-microvolt: true + regulator-allow-bypass: true + regulator-active-discharge: true + + additionalProperties: false + + patternProperties: + "^(dcdc[0-4]|ldo[0-9]|ldo1[1-2]|switchldo1)-supply$": + description: ATC260x voltage regulators supplies + + "^(dcdc[0-4]|ldo[0-9]|ldo1[1-2])$": + type: object + $ref: ../regulator/regulator.yaml + + properties: + regulator-name: true + regulator-boot-on: true + regulator-always-on: true + regulator-min-microvolt: true + regulator-max-microvolt: true + regulator-allow-bypass: true + + additionalProperties: false + + allOf: + - if: + properties: + compatible: + contains: + const: actions,atc2603c-regulator + then: + patternProperties: + "^(dcdc[0,4]|ldo[0,4,9])(-supply)?$": false + + "^(ldo|dcdc)": + properties: + regulator-allow-bypass: false + - if: + properties: + compatible: + contains: + const: actions,atc2609a-regulator + then: + patternProperties: + "^(ldo1[1-2]|switchldo1)(-supply)?$": false + + "^(dcdc|ldo[3-9])": + properties: + regulator-allow-bypass: false + + required: + - compatible + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + pmic@65 { + compatible = "actions,atc2603c"; + reg = <0x65>; + interrupt-parent = <&sirq>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + + reset-time-sec = <6>; + + regulators { + compatible = "actions,atc2603c-regulator"; + + dcdc1-supply = <®_5v0>; + dcdc3-supply = <®_5v0>; + ldo5-supply = <®_5v0>; + switchldo1-supply = <&vcc>; + + vdd_cpu: dcdc1 { + regulator-name = "VDD_CPU"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1400000>; + regulator-always-on; + }; + + vcc: dcdc3 { + regulator-name = "VCC"; + regulator-min-microvolt = <2600000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vcc_3v1: ldo5 { + regulator-name = "VCC_3V1"; + regulator-min-microvolt = <2600000>; + regulator-max-microvolt = <3300000>; + }; + + sd_vcc: switchldo1 { + regulator-name = "SD_VCC"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + regulator-boot-on; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt index d0a38ba8b9ce..936aa108eab4 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -9,13 +9,7 @@ primary use case of the Aspeed LPC controller is as a slave on the bus conditions it can also take the role of bus master. The LPC controller is represented as a multi-function device to account for the -mix of functionality it provides. The principle split is between the register -layout at the start of the I/O space which is, to quote the Aspeed datasheet, -"basically compatible with the [LPC registers from the] popular BMC controller -H8S/2168[1]", and everything else, where everything else is an eclectic -collection of functions with a esoteric register layout. "Everything else", -here labeled the "host" portion of the controller, includes, but is not limited -to: +mix of functionality, which includes, but is not limited to: * An IPMI Block Transfer[2] Controller @@ -44,80 +38,36 @@ Required properties =================== - compatible: One of: - "aspeed,ast2400-lpc", "simple-mfd" - "aspeed,ast2500-lpc", "simple-mfd" - "aspeed,ast2600-lpc", "simple-mfd" + "aspeed,ast2400-lpc-v2", "simple-mfd", "syscon" + "aspeed,ast2500-lpc-v2", "simple-mfd", "syscon" + "aspeed,ast2600-lpc-v2", "simple-mfd", "syscon" - reg: contains the physical address and length values of the Aspeed LPC memory region. - #address-cells: <1> - #size-cells: <1> -- ranges: Maps 0 to the physical address and length of the LPC memory - region - -Required LPC Child nodes -======================== - -BMC Node --------- - -- compatible: One of: - "aspeed,ast2400-lpc-bmc" - "aspeed,ast2500-lpc-bmc" - "aspeed,ast2600-lpc-bmc" - -- reg: contains the physical address and length values of the - H8S/2168-compatible LPC controller memory region - -Host Node ---------- - -- compatible: One of: - "aspeed,ast2400-lpc-host", "simple-mfd", "syscon" - "aspeed,ast2500-lpc-host", "simple-mfd", "syscon" - "aspeed,ast2600-lpc-host", "simple-mfd", "syscon" - -- reg: contains the address and length values of the host-related - register space for the Aspeed LPC controller - -- #address-cells: <1> -- #size-cells: <1> -- ranges: Maps 0 to the address and length of the host-related LPC memory +- ranges: Maps 0 to the physical address and length of the LPC memory region Example: lpc: lpc@1e789000 { - compatible = "aspeed,ast2500-lpc", "simple-mfd"; + compatible = "aspeed,ast2500-lpc-v2", "simple-mfd", "syscon"; reg = <0x1e789000 0x1000>; #address-cells = <1>; #size-cells = <1>; ranges = <0x0 0x1e789000 0x1000>; - lpc_bmc: lpc-bmc@0 { - compatible = "aspeed,ast2500-lpc-bmc"; + lpc_snoop: lpc-snoop@0 { + compatible = "aspeed,ast2600-lpc-snoop"; reg = <0x0 0x80>; - }; - - lpc_host: lpc-host@80 { - compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon"; - reg = <0x80 0x1e0>; - reg-io-width = <4>; - - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x80 0x1e0>; + interrupts = <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>; + snoop-ports = <0x80>; }; }; -BMC Node Children -================== - - -Host Node Children -================== LPC Host Interface Controller ------------------- @@ -149,14 +99,12 @@ Optional properties: Example: -lpc-host@80 { - lpc_ctrl: lpc-ctrl@0 { - compatible = "aspeed,ast2500-lpc-ctrl"; - reg = <0x0 0x80>; - clocks = <&syscon ASPEED_CLK_GATE_LCLK>; - memory-region = <&flash_memory>; - flash = <&spi>; - }; +lpc_ctrl: lpc-ctrl@80 { + compatible = "aspeed,ast2500-lpc-ctrl"; + reg = <0x80 0x80>; + clocks = <&syscon ASPEED_CLK_GATE_LCLK>; + memory-region = <&flash_memory>; + flash = <&spi>; }; LPC Host Controller @@ -179,9 +127,9 @@ Required properties: Example: -lhc: lhc@20 { +lhc: lhc@a0 { compatible = "aspeed,ast2500-lhc"; - reg = <0x20 0x24 0x48 0x8>; + reg = <0xa0 0x24 0xc8 0x8>; }; LPC reset control @@ -192,16 +140,18 @@ state of the LPC bus. Some systems may chose to modify this configuration. Required properties: - - compatible: "aspeed,ast2600-lpc-reset" or - "aspeed,ast2500-lpc-reset" - "aspeed,ast2400-lpc-reset" + - compatible: One of: + "aspeed,ast2600-lpc-reset"; + "aspeed,ast2500-lpc-reset"; + "aspeed,ast2400-lpc-reset"; + - reg: offset and length of the IP in the LHC memory region - #reset-controller indicates the number of reset cells expected Example: -lpc_reset: reset-controller@18 { +lpc_reset: reset-controller@98 { compatible = "aspeed,ast2500-lpc-reset"; - reg = <0x18 0x4>; + reg = <0x98 0x4>; #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml new file mode 100644 index 000000000000..afc569bc15cf --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml @@ -0,0 +1,177 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm6318-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6318 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM6318 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm6318-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm6318-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@10000080 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm6318-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0x10000080 0x80>; + ranges = <0 0x10000080 0x80>; + + gpio@0 { + compatible = "brcm,bcm6318-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 50>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@10 { + compatible = "brcm,bcm6318-pinctrl"; + reg = <0x18 0x10>, <0x54 0x18>; + + pinctrl_ephy0_spd_led: ephy0_spd_led-pins { + function = "ephy0_spd_led"; + pins = "gpio0"; + }; + + pinctrl_ephy1_spd_led: ephy1_spd_led-pins { + function = "ephy1_spd_led"; + pins = "gpio1"; + }; + + pinctrl_ephy2_spd_led: ephy2_spd_led-pins { + function = "ephy2_spd_led"; + pins = "gpio2"; + }; + + pinctrl_ephy3_spd_led: ephy3_spd_led-pins { + function = "ephy3_spd_led"; + pins = "gpio3"; + }; + + pinctrl_ephy0_act_led: ephy0_act_led-pins { + function = "ephy0_act_led"; + pins = "gpio4"; + }; + + pinctrl_ephy1_act_led: ephy1_act_led-pins { + function = "ephy1_act_led"; + pins = "gpio5"; + }; + + pinctrl_ephy2_act_led: ephy2_act_led-pins { + function = "ephy2_act_led"; + pins = "gpio6"; + }; + + pinctrl_ephy3_act_led: ephy3_act_led-pins { + function = "ephy3_act_led"; + pins = "gpio7"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio6"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio7"; + }; + }; + + pinctrl_inet_act_led: inet_act_led-pins { + function = "inet_act_led"; + pins = "gpio8"; + }; + + pinctrl_inet_fail_led: inet_fail_led-pins { + function = "inet_fail_led"; + pins = "gpio9"; + }; + + pinctrl_dsl_led: dsl_led-pins { + function = "dsl_led"; + pins = "gpio10"; + }; + + pinctrl_post_fail_led: post_fail_led-pins { + function = "post_fail_led"; + pins = "gpio11"; + }; + + pinctrl_wlan_wps_led: wlan_wps_led-pins { + function = "wlan_wps_led"; + pins = "gpio12"; + }; + + pinctrl_usb_pwron: usb_pwron-pins { + function = "usb_pwron"; + pins = "gpio13"; + }; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio13"; + }; + + pinctrl_usb_active: usb_active-pins { + function = "usb_active"; + pins = "gpio40"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml new file mode 100644 index 000000000000..c7771c86d7c1 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml @@ -0,0 +1,194 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm63268-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM63268 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM63268 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm63268-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm63268-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@100000c0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm63268-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0x100000c0 0x80>; + ranges = <0 0x100000c0 0x80>; + + gpio@0 { + compatible = "brcm,bcm63268-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 52>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@10 { + compatible = "brcm,bcm63268-pinctrl"; + reg = <0x10 0x4>, <0x18 0x8>, <0x38 0x4>; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio0"; + }; + + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio1"; + }; + }; + + pinctrl_hsspi_cs4: hsspi_cs4-pins { + function = "hsspi_cs4"; + pins = "gpio16"; + }; + + pinctrl_hsspi_cs5: hsspi_cs5-pins { + function = "hsspi_cs5"; + pins = "gpio17"; + }; + + pinctrl_hsspi_cs6: hsspi_cs6-pins { + function = "hsspi_cs6"; + pins = "gpio8"; + }; + + pinctrl_hsspi_cs7: hsspi_cs7-pins { + function = "hsspi_cs7"; + pins = "gpio9"; + }; + + pinctrl_adsl_spi: adsl_spi-pins { + pinctrl_adsl_spi_miso: adsl_spi_miso-pins { + function = "adsl_spi_miso"; + pins = "gpio18"; + }; + + pinctrl_adsl_spi_mosi: adsl_spi_mosi-pins { + function = "adsl_spi_mosi"; + pins = "gpio19"; + }; + }; + + pinctrl_vreq_clk: vreq_clk-pins { + function = "vreq_clk"; + pins = "gpio22"; + }; + + pinctrl_pcie_clkreq_b: pcie_clkreq_b-pins { + function = "pcie_clkreq_b"; + pins = "gpio23"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio30"; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio31"; + }; + + pinctrl_nand: nand-pins { + function = "nand"; + group = "nand_grp"; + }; + + pinctrl_gpio35_alt: gpio35_alt-pins { + function = "gpio35_alt"; + pin = "gpio35"; + }; + + pinctrl_dectpd: dectpd-pins { + function = "dectpd"; + group = "dectpd_grp"; + }; + + pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins { + function = "vdsl_phy_override_0"; + group = "vdsl_phy_override_0_grp"; + }; + + pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins { + function = "vdsl_phy_override_1"; + group = "vdsl_phy_override_1_grp"; + }; + + pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins { + function = "vdsl_phy_override_2"; + group = "vdsl_phy_override_2_grp"; + }; + + pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins { + function = "vdsl_phy_override_3"; + group = "vdsl_phy_override_3_grp"; + }; + + pinctrl_dsl_gpio8: dsl_gpio8-pins { + function = "dsl_gpio8"; + group = "dsl_gpio8"; + }; + + pinctrl_dsl_gpio9: dsl_gpio9-pins { + function = "dsl_gpio9"; + group = "dsl_gpio9"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml new file mode 100644 index 000000000000..33963c11ae62 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm6328-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6328 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM6328 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm6328-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm6328-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@10000080 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm6328-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0x10000080 0x80>; + ranges = <0 0x10000080 0x80>; + + gpio@0 { + compatible = "brcm,bcm6328-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 32>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@18 { + compatible = "brcm,bcm6328-pinctrl"; + reg = <0x18 0x10>; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio6"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio7"; + }; + }; + + pinctrl_inet_act_led: inet_act_led-pins { + function = "inet_act_led"; + pins = "gpio11"; + }; + + pinctrl_pcie_clkreq: pcie_clkreq-pins { + function = "pcie_clkreq"; + pins = "gpio16"; + }; + + pinctrl_ephy0_spd_led: ephy0_spd_led-pins { + function = "led"; + pins = "gpio17"; + }; + + pinctrl_ephy1_spd_led: ephy1_spd_led-pins { + function = "led"; + pins = "gpio18"; + }; + + pinctrl_ephy2_spd_led: ephy2_spd_led-pins { + function = "led"; + pins = "gpio19"; + }; + + pinctrl_ephy3_spd_led: ephy3_spd_led-pins { + function = "led"; + pins = "gpio20"; + }; + + pinctrl_ephy0_act_led: ephy0_act_led-pins { + function = "ephy0_act_led"; + pins = "gpio25"; + }; + + pinctrl_ephy1_act_led: ephy1_act_led-pins { + function = "ephy1_act_led"; + pins = "gpio26"; + }; + + pinctrl_ephy2_act_led: ephy2_act_led-pins { + function = "ephy2_act_led"; + pins = "gpio27"; + }; + + pinctrl_ephy3_act_led: ephy3_act_led-pins { + function = "ephy3_act_led"; + pins = "gpio28"; + }; + + pinctrl_hsspi_cs1: hsspi_cs1-pins { + function = "hsspi_cs1"; + pins = "hsspi_cs1"; + }; + + pinctrl_usb_port1_device: usb_port1_device-pins { + function = "usb_device_port"; + pins = "usb_port1"; + }; + + pinctrl_usb_port1_host: usb_port1_host-pins { + function = "usb_host_port"; + pins = "usb_port1"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml new file mode 100644 index 000000000000..3e44bea78b03 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml @@ -0,0 +1,130 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm6358-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6358 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM6358 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm6358-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm6358-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@fffe0080 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm6358-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0xfffe0080 0x80>; + ranges = <0 0xfffe0080 0x80>; + + gpio@0 { + compatible = "brcm,bcm6358-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 40>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@18 { + compatible = "brcm,bcm6358-pinctrl"; + reg = <0x18 0x4>; + + pinctrl_ebi_cs: ebi_cs-pins { + function = "ebi_cs"; + groups = "ebi_cs_grp"; + }; + + pinctrl_uart1: uart1-pins { + function = "uart1"; + groups = "uart1_grp"; + }; + + pinctrl_serial_led: serial_led-pins { + function = "serial_led"; + groups = "serial_led_grp"; + }; + + pinctrl_legacy_led: legacy_led-pins { + function = "legacy_led"; + groups = "legacy_led_grp"; + }; + + pinctrl_led: led-pins { + function = "led"; + groups = "led_grp"; + }; + + pinctrl_spi_cs_23: spi_cs-pins { + function = "spi_cs"; + groups = "spi_cs_grp"; + }; + + pinctrl_utopia: utopia-pins { + function = "utopia"; + groups = "utopia_grp"; + }; + + pinctrl_pwm_syn_clk: pwm_syn_clk-pins { + function = "pwm_syn_clk"; + groups = "pwm_syn_clk_grp"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + groups = "sys_irq_grp"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml new file mode 100644 index 000000000000..48d14a5fe0d5 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml @@ -0,0 +1,236 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm6362-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6362 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM6362 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm6362-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm6362-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@10000080 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm6362-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0x10000080 0x80>; + ranges = <0 0x10000080 0x80>; + + gpio@0 { + compatible = "brcm,bcm6362-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 48>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@18 { + compatible = "brcm,bcm6362-pinctrl"; + reg = <0x18 0x10>, <0x38 0x4>; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio0"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + pins = "gpio1"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio2"; + }; + + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio3"; + }; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio4"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio5"; + }; + + pinctrl_robosw_led0: robosw_led0-pins { + function = "robosw_led0"; + pins = "gpio6"; + }; + + pinctrl_robosw_led1: robosw_led1-pins { + function = "robosw_led1"; + pins = "gpio7"; + }; + + pinctrl_inet_led: inet_led-pins { + function = "inet_led"; + pins = "gpio8"; + }; + + pinctrl_spi_cs2: spi_cs2-pins { + function = "spi_cs2"; + pins = "gpio9"; + }; + + pinctrl_spi_cs3: spi_cs3-pins { + function = "spi_cs3"; + pins = "gpio10"; + }; + + pinctrl_ntr_pulse: ntr_pulse-pins { + function = "ntr_pulse"; + pins = "gpio11"; + }; + + pinctrl_uart1_scts: uart1_scts-pins { + function = "uart1_scts"; + pins = "gpio12"; + }; + + pinctrl_uart1_srts: uart1_srts-pins { + function = "uart1_srts"; + pins = "gpio13"; + }; + + pinctrl_uart1: uart1-pins { + pinctrl_uart1_sdin: uart1_sdin-pins { + function = "uart1_sdin"; + pins = "gpio14"; + }; + + pinctrl_uart1_sdout: uart1_sdout-pins { + function = "uart1_sdout"; + pins = "gpio15"; + }; + }; + + pinctrl_adsl_spi: adsl_spi-pins { + pinctrl_adsl_spi_miso: adsl_spi_miso-pins { + function = "adsl_spi_miso"; + pins = "gpio16"; + }; + + pinctrl_adsl_spi_mosi: adsl_spi_mosi-pins { + function = "adsl_spi_mosi"; + pins = "gpio17"; + }; + + pinctrl_adsl_spi_clk: adsl_spi_clk-pins { + function = "adsl_spi_clk"; + pins = "gpio18"; + }; + + pinctrl_adsl_spi_cs: adsl_spi_cs-pins { + function = "adsl_spi_cs"; + pins = "gpio19"; + }; + }; + + pinctrl_ephy0_led: ephy0_led-pins { + function = "ephy0_led"; + pins = "gpio20"; + }; + + pinctrl_ephy1_led: ephy1_led-pins { + function = "ephy1_led"; + pins = "gpio21"; + }; + + pinctrl_ephy2_led: ephy2_led-pins { + function = "ephy2_led"; + pins = "gpio22"; + }; + + pinctrl_ephy3_led: ephy3_led-pins { + function = "ephy3_led"; + pins = "gpio23"; + }; + + pinctrl_ext_irq0: ext_irq0-pins { + function = "ext_irq0"; + pins = "gpio24"; + }; + + pinctrl_ext_irq1: ext_irq1-pins { + function = "ext_irq1"; + pins = "gpio25"; + }; + + pinctrl_ext_irq2: ext_irq2-pins { + function = "ext_irq2"; + pins = "gpio26"; + }; + + pinctrl_ext_irq3: ext_irq3-pins { + function = "ext_irq3"; + pins = "gpio27"; + }; + + pinctrl_nand: nand-pins { + function = "nand"; + group = "nand_grp"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml new file mode 100644 index 000000000000..307270b0cfed --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml @@ -0,0 +1,246 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,bcm6368-gpio-sysctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6368 GPIO System Controller Device Tree Bindings + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Broadcom BCM6368 SoC GPIO system controller which provides a register map + for controlling the GPIO and pins of the SoC. + +properties: + "#address-cells": true + + "#size-cells": true + + compatible: + items: + - const: brcm,bcm6368-gpio-sysctl + - const: syscon + - const: simple-mfd + + ranges: + maxItems: 1 + + reg: + maxItems: 1 + +patternProperties: + "^gpio@[0-9a-f]+$": + # Child node + type: object + $ref: "../gpio/brcm,bcm6345-gpio.yaml" + description: + GPIO controller for the SoC GPIOs. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml. + + "^pinctrl@[0-9a-f]+$": + # Child node + type: object + $ref: "../pinctrl/brcm,bcm6368-pinctrl.yaml" + description: + Pin controller for the SoC pins. This child node definition + should follow the bindings specified in + Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml. + +required: + - "#address-cells" + - compatible + - ranges + - reg + - "#size-cells" + +additionalProperties: false + +examples: + - | + syscon@10000080 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "brcm,bcm6368-gpio-sysctl", "syscon", "simple-mfd"; + reg = <0x10000080 0x80>; + ranges = <0 0x10000080 0x80>; + + gpio@0 { + compatible = "brcm,bcm6368-gpio"; + reg-names = "dirout", "dat"; + reg = <0x0 0x8>, <0x8 0x8>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 38>; + #gpio-cells = <2>; + }; + + pinctrl: pinctrl@18 { + compatible = "brcm,bcm6368-pinctrl"; + reg = <0x18 0x4>, <0x38 0x4>; + + pinctrl_analog_afe_0: analog_afe_0-pins { + function = "analog_afe_0"; + pins = "gpio0"; + }; + + pinctrl_analog_afe_1: analog_afe_1-pins { + function = "analog_afe_1"; + pins = "gpio1"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + pins = "gpio2"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio3"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio4"; + }; + }; + + pinctrl_inet_led: inet_led-pins { + function = "inet_led"; + pins = "gpio5"; + }; + + pinctrl_ephy0_led: ephy0_led-pins { + function = "ephy0_led"; + pins = "gpio6"; + }; + + pinctrl_ephy1_led: ephy1_led-pins { + function = "ephy1_led"; + pins = "gpio7"; + }; + + pinctrl_ephy2_led: ephy2_led-pins { + function = "ephy2_led"; + pins = "gpio8"; + }; + + pinctrl_ephy3_led: ephy3_led-pins { + function = "ephy3_led"; + pins = "gpio9"; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio10"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio11"; + }; + + pinctrl_robosw_led0: robosw_led0-pins { + function = "robosw_led0"; + pins = "gpio12"; + }; + + pinctrl_robosw_led1: robosw_led1-pins { + function = "robosw_led1"; + pins = "gpio13"; + }; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio14"; + }; + + pinctrl_pci: pci-pins { + pinctrl_pci_req1: pci_req1-pins { + function = "pci_req1"; + pins = "gpio16"; + }; + + pinctrl_pci_gnt1: pci_gnt1-pins { + function = "pci_gnt1"; + pins = "gpio17"; + }; + + pinctrl_pci_intb: pci_intb-pins { + function = "pci_intb"; + pins = "gpio18"; + }; + + pinctrl_pci_req0: pci_req0-pins { + function = "pci_req0"; + pins = "gpio19"; + }; + + pinctrl_pci_gnt0: pci_gnt0-pins { + function = "pci_gnt0"; + pins = "gpio20"; + }; + }; + + pinctrl_pcmcia: pcmcia-pins { + pinctrl_pcmcia_cd1: pcmcia_cd1-pins { + function = "pcmcia_cd1"; + pins = "gpio22"; + }; + + pinctrl_pcmcia_cd2: pcmcia_cd2-pins { + function = "pcmcia_cd2"; + pins = "gpio23"; + }; + + pinctrl_pcmcia_vs1: pcmcia_vs1-pins { + function = "pcmcia_vs1"; + pins = "gpio24"; + }; + + pinctrl_pcmcia_vs2: pcmcia_vs2-pins { + function = "pcmcia_vs2"; + pins = "gpio25"; + }; + }; + + pinctrl_ebi_cs2: ebi_cs2-pins { + function = "ebi_cs2"; + pins = "gpio26"; + }; + + pinctrl_ebi_cs3: ebi_cs3-pins { + function = "ebi_cs3"; + pins = "gpio27"; + }; + + pinctrl_spi_cs2: spi_cs2-pins { + function = "spi_cs2"; + pins = "gpio28"; + }; + + pinctrl_spi_cs3: spi_cs3-pins { + function = "spi_cs3"; + pins = "gpio29"; + }; + + pinctrl_spi_cs4: spi_cs4-pins { + function = "spi_cs4"; + pins = "gpio30"; + }; + + pinctrl_spi_cs5: spi_cs5-pins { + function = "spi_cs5"; + pins = "gpio31"; + }; + + pinctrl_uart1: uart1-pins { + function = "uart1"; + group = "uart1_grp"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index 76bf16ee27ec..4dfa70a013ae 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -94,6 +94,9 @@ properties: keyboard-controller: $ref: "/schemas/input/google,cros-ec-keyb.yaml#" + proximity: + $ref: "/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml#" + codecs: type: object additionalProperties: false @@ -180,6 +183,10 @@ examples: interrupts = <99 0>; interrupt-parent = <&gpio7>; spi-max-frequency = <5000000>; + + proximity { + compatible = "google,cros-ec-mkbp-proximity"; + }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/netronix,ntxec.yaml b/Documentation/devicetree/bindings/mfd/netronix,ntxec.yaml new file mode 100644 index 000000000000..59a630025f52 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/netronix,ntxec.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/netronix,ntxec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Netronix Embedded Controller + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +description: | + This EC is found in e-book readers of multiple brands (e.g. Kobo, Tolino), and + is typically implemented as a TI MSP430 microcontroller. + +properties: + compatible: + const: netronix,ntxec + + reg: + items: + - description: The I2C address of the EC + + system-power-controller: + type: boolean + description: See Documentation/devicetree/bindings/power/power-controller.txt + + interrupts: + minItems: 1 + description: + The EC can signal interrupts via a GPIO line + + "#pwm-cells": + const: 2 + description: | + Number of cells in a PWM specifier. + + The following PWM channels are supported: + - 0: The PWM channel controlled by registers 0xa1-0xa7 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ec: embedded-controller@43 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ntxec>; + + compatible = "netronix,ntxec"; + reg = <0x43>; + system-power-controller; + interrupt-parent = <&gpio4>; + interrupts = <11 IRQ_TYPE_EDGE_FALLING>; + #pwm-cells = <2>; + }; + }; + + backlight { + compatible = "pwm-backlight"; + pwms = <&ec 0 50000>; + power-supply = <&backlight_regulator>; + }; + + backlight_regulator: regulator-dummy { + compatible = "regulator-fixed"; + regulator-name = "backlight"; + }; diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt deleted file mode 100644 index 9e5eba4a4f0d..000000000000 --- a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt +++ /dev/null @@ -1,99 +0,0 @@ -Qualcomm PM8xxx PMIC multi-function devices - -The PM8xxx family of Power Management ICs are used to provide regulated -voltages and other various functionality to Qualcomm SoCs. - -= PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8058" - "qcom,pm8821" - "qcom,pm8921" - -- #address-cells: - Usage: required - Value type: <u32> - Definition: must be 1 - -- #size-cells: - Usage: required - Value type: <u32> - Definition: must be 0 - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: specifies the interrupt that indicates a subdevice - has generated an interrupt (summary interrupt). The - format of the specifier is defined by the binding document - describing the node's interrupt parent. - -- #interrupt-cells: - Usage: required - Value type : <u32> - Definition: must be 2. Specifies the number of cells needed to encode - an interrupt source. The 1st cell contains the interrupt - number. The 2nd cell is the trigger type and level flags - encoded as follows: - - 1 = low-to-high edge triggered - 2 = high-to-low edge triggered - 4 = active high level-sensitive - 8 = active low level-sensitive - -- interrupt-controller: - Usage: required - Value type: <empty> - Definition: identifies this node as an interrupt controller - -= SUBCOMPONENTS - -The PMIC contains multiple independent functions, each described in a subnode. -The below bindings specify the set of valid subnodes. - -== Real-Time Clock - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8058-rtc" - "qcom,pm8921-rtc" - "qcom,pm8941-rtc" - "qcom,pm8018-rtc" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: single entry specifying the base address of the RTC registers - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: single entry specifying the RTC's alarm interrupt - -- allow-set-time: - Usage: optional - Value type: <empty> - Definition: indicates that the setting of RTC time is allowed by - the host CPU - -= EXAMPLE - - pmicintc: pmic@0 { - compatible = "qcom,pm8921"; - interrupts = <104 8>; - #interrupt-cells = <2>; - interrupt-controller; - #address-cells = <1>; - #size-cells = <0>; - - rtc@11d { - compatible = "qcom,pm8921-rtc"; - reg = <0x11d>; - interrupts = <0x27 0>; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml new file mode 100644 index 000000000000..9065ec53e643 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/qcom-pm8xxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8xxx PMIC multi-function devices + +maintainers: + - Satya Priya <skakit@codeaurora.org> + +description: | + The PM8xxx family of Power Management ICs are used to provide regulated + voltages and other various functionality to Qualcomm SoCs. + +properties: + compatible: + enum: + - qcom,pm8058 + - qcom,pm8821 + - qcom,pm8921 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + interrupts: + maxItems: 1 + + '#interrupt-cells': + const: 2 + + interrupt-controller: true + +patternProperties: + "rtc@[0-9a-f]+$": + type: object + $ref: "../rtc/qcom-pm8xxx-rtc.yaml" + +required: + - compatible + - '#address-cells' + - '#size-cells' + - interrupts + - '#interrupt-cells' + - interrupt-controller + +additionalProperties: false +... diff --git a/Documentation/devicetree/bindings/mfd/ricoh,rn5t618.yaml b/Documentation/devicetree/bindings/mfd/ricoh,rn5t618.yaml new file mode 100644 index 000000000000..032a7fb0b4a7 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ricoh,rn5t618.yaml @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/ricoh,rn5t618.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ricoh RN5T567/RN5T618/RC5T619 PMIC + +maintainers: + - Andreas Kemnade <andreas@kemnade.info> + +description: | + Ricoh RN5T567/RN5T618/RC5T619 is a power management IC family which + integrates 3 to 5 step-down DCDC converters, 7 to 10 low-dropout regulators, + GPIOs, and a watchdog timer. It can be controlled through an I2C interface. + The RN5T618/RC5T619 provides additionally a Li-ion battery charger, + fuel gauge, and an ADC. + The RC5T619 additionally includes USB charger detection and an RTC. + +allOf: + - if: + properties: + compatible: + contains: + const: ricoh,rn5t567 + then: + properties: + regulators: + patternProperties: + "^(DCDC[1-4]|LDO[1-5]|LDORTC[12])$": + $ref: ../regulator/regulator.yaml + additionalProperties: false + - if: + properties: + compatible: + contains: + const: ricoh,rn5t618 + then: + properties: + regulators: + patternProperties: + "^(DCDC[1-3]|LDO[1-5]|LDORTC[12])$": + $ref: ../regulator/regulator.yaml + additionalProperties: false + - if: + properties: + compatible: + contains: + const: ricoh,rc5t619 + then: + properties: + regulators: + patternProperties: + "^(DCDC[1-5]|LDO[1-9]|LDO10|LDORTC[12])$": + $ref: ../regulator/regulator.yaml + additionalProperties: false + +properties: + compatible: + enum: + - ricoh,rn5t567 + - ricoh,rn5t618 + - ricoh,rc5t619 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + system-power-controller: + type: boolean + description: | + See Documentation/devicetree/bindings/power/power-controller.txt + + regulators: + type: object + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@32 { + compatible = "ricoh,rn5t618"; + reg = <0x32>; + interrupt-parent = <&gpio5>; + interrupts = <11 IRQ_TYPE_EDGE_FALLING>; + system-power-controller; + + regulators { + DCDC1 { + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <1050000>; + }; + + DCDC2 { + regulator-min-microvolt = <1175000>; + regulator-max-microvolt = <1175000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rn5t618.txt b/Documentation/devicetree/bindings/mfd/rn5t618.txt deleted file mode 100644 index 16778ea00dbc..000000000000 --- a/Documentation/devicetree/bindings/mfd/rn5t618.txt +++ /dev/null @@ -1,52 +0,0 @@ -* Ricoh RN5T567/RN5T618 PMIC - -Ricoh RN5T567/RN5T618/RC5T619 is a power management IC family which -integrates 3 to 5 step-down DCDC converters, 7 to 10 low-dropout regulators, -GPIOs, and a watchdog timer. It can be controlled through an I2C interface. -The RN5T618/RC5T619 provides additionally a Li-ion battery charger, -fuel gauge, and an ADC. -The RC5T619 additionnally includes USB charger detection and an RTC. - -Required properties: - - compatible: must be one of - "ricoh,rn5t567" - "ricoh,rn5t618" - "ricoh,rc5t619" - - reg: the I2C slave address of the device - -Optional properties: - - interrupts: interrupt mapping for IRQ - See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - - system-power-controller: - See Documentation/devicetree/bindings/power/power-controller.txt - -Sub-nodes: - - regulators: the node is required if the regulator functionality is - needed. The valid regulator names are: DCDC1, DCDC2, DCDC3, DCDC4 - (RN5T567/RC5T619), LDO1, LDO2, LDO3, LDO4, LDO5, LDO6, LDO7, LDO8, - LDO9, LDO10, LDORTC1 and LDORTC2. - LDO7-10 are specific to RC5T619. - The common bindings for each individual regulator can be found in: - Documentation/devicetree/bindings/regulator/regulator.txt - -Example: - - pmic@32 { - compatible = "ricoh,rn5t618"; - reg = <0x32>; - interrupt-parent = <&gpio5>; - interrupts = <11 IRQ_TYPE_EDGE_FALLING>; - system-power-controller; - - regulators { - DCDC1 { - regulator-min-microvolt = <1050000>; - regulator-max-microvolt = <1050000>; - }; - - DCDC2 { - regulator-min-microvolt = <1175000>; - regulator-max-microvolt = <1175000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml new file mode 100644 index 000000000000..fe265bcab50d --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml @@ -0,0 +1,201 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd71815-pmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD71815 Power Management Integrated Circuit bindings + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + +description: | + BD71815AGW is a single-chip power management ICs for battery-powered + portable devices. It integrates 5 buck converters, 8 LDOs, a boost driver + for LED and a 500 mA single-cell linear charger. Also included is a Coulomb + counter, a real-time clock (RTC), and a 32.768 kHz clock gate and two GPOs. + +properties: + compatible: + const: rohm,bd71815 + + reg: + description: + I2C slave address. + maxItems: 1 + + interrupts: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + The first cell is the pin number and the second cell is used to specify + flags. See ../gpio/gpio.txt for more information. + + clocks: + maxItems: 1 + + "#clock-cells": + const: 0 + + clock-output-names: + const: bd71815-32k-out + + rohm,clkout-open-drain: + description: clk32kout mode. Set to 1 for "open-drain" or 0 for "cmos". + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1 + + rohm,charger-sense-resistor-ohms: + minimum: 10000000 + maximum: 50000000 + description: | + BD71827 and BD71828 have SAR ADC for measuring charging currents. + External sense resistor (RSENSE in data sheet) should be used. If + something other but 30MOhm resistor is used the resistance value + should be given here in Ohms. + default: 30000000 + + regulators: + $ref: ../regulator/rohm,bd71815-regulator.yaml + description: + List of child nodes that specify the regulators. + + gpio-reserved-ranges: + description: | + Usage of BD71828 GPIO pins can be changed via OTP. This property can be + used to mark the pins which should not be configured for GPIO. Please see + the ../gpio/gpio.txt for more information. + + rohm,enable-hidden-gpo: + description: | + The BD71815 has undocumented GPO at pin E5. Pin is marked as GND at the + data-sheet as it's location in the middle of GND pins makes it hard to + use on PCB. If your board has managed to use this pin you can enable the + second GPO by defining this property. Dont enable this if you are unsure + about how the E5 pin is connected on your board. + type: boolean + +required: + - compatible + - reg + - interrupts + - clocks + - "#clock-cells" + - regulators + - gpio-controller + - "#gpio-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/leds/common.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + pmic: pmic@4b { + compatible = "rohm,bd71815"; + reg = <0x4b>; + + interrupt-parent = <&gpio1>; + interrupts = <29 IRQ_TYPE_LEVEL_LOW>; + + clocks = <&osc 0>; + #clock-cells = <0>; + clock-output-names = "bd71815-32k-out"; + + gpio-controller; + #gpio-cells = <2>; + + rohm,charger-sense-resistor-ohms = <10000000>; + + regulators { + buck1: buck1 { + regulator-name = "buck1"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <2000000>; + regulator-always-on; + regulator-ramp-delay = <1250>; + rohm,dvs-run-voltage = <1150000>; + rohm,dvs-suspend-voltage = <950000>; + }; + buck2: buck2 { + regulator-name = "buck2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <2000000>; + regulator-always-on; + regulator-ramp-delay = <1250>; + rohm,dvs-run-voltage = <1150000>; + rohm,dvs-suspend-voltage = <950000>; + }; + buck3: buck3 { + regulator-name = "buck3"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <2700000>; + regulator-always-on; + }; + buck4: buck4 { + regulator-name = "buck4"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1850000>; + regulator-always-on; + }; + buck5: buck5 { + regulator-name = "buck5"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo1: ldo1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo2: ldo2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo3: ldo3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo4: ldo4 { + regulator-name = "ldo4"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo5: ldo5 { + regulator-name = "ldo5"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + ldo6: ldodvref { + regulator-name = "ldodvref"; + regulator-always-on; + }; + ldo7: ldolpsr { + regulator-name = "ldolpsr"; + regulator-always-on; + }; + + boost: wled { + regulator-name = "wled"; + regulator-min-microamp = <10>; + regulator-max-microamp = <25000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml index 3a6a1a26e2b3..8380166d176c 100644 --- a/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml @@ -44,6 +44,12 @@ properties: clock-output-names: const: bd71828-32k-out + rohm,clkout-open-drain: + description: clk32kout mode. Set to 1 for "open-drain" or 0 for "cmos". + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 1 + rohm,charger-sense-resistor-ohms: minimum: 10000000 maximum: 50000000 diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml new file mode 100644 index 000000000000..6483860da955 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml @@ -0,0 +1,123 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd9576-pmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD9576MUF and BD9573MUF Power Management Integrated Circuit bindings + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + +description: | + BD9576MUF and BD9573MUF are power management ICs primarily intended for + powering the R-Car series processors. + The IC provides 6 power outputs with configurable sequencing and safety + monitoring. A watchdog logic with slow ping/windowed modes is also included. + +properties: + compatible: + enum: + - rohm,bd9576 + - rohm,bd9573 + + reg: + description: + I2C slave address. + maxItems: 1 + + interrupts: + maxItems: 1 + + rohm,vout1-en-low: + description: + BD9576 and BD9573 VOUT1 regulator enable state can be individually + controlled by a GPIO. This is dictated by state of vout1-en pin during + the PMIC startup. If vout1-en is LOW during PMIC startup then the VOUT1 + enable sate is controlled via this pin. Set this property if vout1-en + is wired to be down at PMIC start-up. + type: boolean + + rohm,vout1-en-gpios: + description: + GPIO specifier to specify the GPIO connected to vout1-en for vout1 ON/OFF + state control. + maxItems: 1 + + rohm,ddr-sel-low: + description: + The BD9576 and BD9573 output voltage for DDR can be selected by setting + the ddr-sel pin low or high. Set this property if ddr-sel is grounded. + type: boolean + + rohm,watchdog-enable-gpios: + description: The GPIO line used to enable the watchdog. + maxItems: 1 + + rohm,watchdog-ping-gpios: + description: The GPIO line used to ping the watchdog. + maxItems: 1 + + rohm,hw-timeout-ms: + maxItems: 2 + description: + Watchog timeout in milliseconds. If single value is given it is + the maximum timeout. Eg. if pinging watchdog is not done within this time + limit the watchdog will be triggered. If two values are given watchdog + is configured in "window mode". Then first value is limit for short-ping + Eg. if watchdog is pinged sooner than that the watchdog will trigger. + When two values is given the second value is the maximum timeout. + # (HW) minimum for short timeout is 2ms, maximum 220 ms. + # (HW) minimum for max timeout is 4ms, maximum 4416 ms. + + regulators: + $ref: ../regulator/rohm,bd9576-regulator.yaml + description: + List of child nodes that specify the regulators. + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/leds/common.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + pmic: pmic@30 { + compatible = "rohm,bd9576"; + reg = <0x30>; + rohm,vout1-en-low; + rohm,vout1-en-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; + rohm,ddr-sel-low; + rohm,watchdog-enable-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; + rohm,watchdog-ping-gpios = <&gpio2 7 GPIO_ACTIVE_HIGH>; + rohm,hw-timeout-ms = <150>, <2300>; + + regulators { + boost1: regulator-vd50 { + regulator-name = "VD50"; + }; + buck1: regulator-vd18 { + regulator-name = "VD18"; + }; + buck2: regulator-vdddr { + regulator-name = "VDDDR"; + }; + buck3: regulator-vd10 { + regulator-name = "VD10"; + }; + ldo: regulator-voutl1 { + regulator-name = "VOUTL1"; + }; + sw: regulator-vouts1 { + regulator-name = "VOUTS1"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml index c4fc5345d38d..f6cac4b1079c 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml @@ -17,6 +17,10 @@ properties: description: I2C slave address const: 0x60 + reset-gpios: + description: GPIO connected to NRST pin (active low reset, pin 20) + maxItems: 1 + gpio-controller: true '#gpio-cells': diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml index a7e57c0913e1..dc5a29b5ef7d 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml @@ -17,6 +17,10 @@ properties: description: I2C slave address const: 0x60 + reset-gpios: + description: GPIO connected to NRST pin (active low reset, pin 20) + maxItems: 1 + gpio-controller: true '#gpio-cells': diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml index 1da6d6a958c9..48d4d53c25f9 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml @@ -19,6 +19,10 @@ properties: description: I2C slave address const: 0x60 + reset-gpios: + description: GPIO connected to NRST pin (active low reset, pin 20) + maxItems: 1 + gpio-controller: true '#gpio-cells': diff --git a/Documentation/devicetree/bindings/mmc/brcm,iproc-sdhci.yaml b/Documentation/devicetree/bindings/mmc/brcm,iproc-sdhci.yaml new file mode 100644 index 000000000000..6f569fbfa134 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,iproc-sdhci.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,iproc-sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom IPROC SDHCI controller + +maintainers: + - Ray Jui <ray.jui@broadcom.com> + - Scott Branden <scott.branden@broadcom.com> + - Nicolas Saenz Julienne <nsaenz@kernel.org> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + enum: + - brcm,bcm2835-sdhci + - brcm,bcm2711-emmc2 + - brcm,sdhci-iproc-cygnus + - brcm,sdhci-iproc + + reg: + minItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: + Handle to core clock for the sdhci controller. + + sdhci,auto-cmd12: + type: boolean + description: Specifies that controller should use auto CMD12 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/bcm-cygnus.h> + + mmc@18041000 { + compatible = "brcm,sdhci-iproc-cygnus"; + reg = <0x18041000 0x100>; + interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&lcpll0_clks BCM_CYGNUS_LCPLL0_SDIO_CLK>; + bus-width = <4>; + sdhci,auto-cmd12; + no-1-8-v; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt deleted file mode 100644 index 09d87cc1182a..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt +++ /dev/null @@ -1,37 +0,0 @@ -Broadcom IPROC SDHCI controller - -This file documents differences between the core properties described -by mmc.txt and the properties that represent the IPROC SDHCI controller. - -Required properties: -- compatible : Should be one of the following - "brcm,bcm2835-sdhci" - "brcm,bcm2711-emmc2" - "brcm,sdhci-iproc-cygnus" - "brcm,sdhci-iproc" - -Use brcm2835-sdhci for the eMMC controller on the BCM2835 (Raspberry Pi) and -bcm2711-emmc2 for the additional eMMC2 controller on BCM2711. - -Use sdhci-iproc-cygnus for Broadcom SDHCI Controllers -restricted to 32bit host accesses to SDHCI registers. - -Use sdhci-iproc for Broadcom SDHCI Controllers that allow standard -8, 16, 32-bit host access to SDHCI register. - -- clocks : The clock feeding the SDHCI controller. - -Optional properties: - - sdhci,auto-cmd12: specifies that controller should use auto CMD12. - -Example: - -sdhci0: sdhci@18041000 { - compatible = "brcm,sdhci-iproc-cygnus"; - reg = <0x18041000 0x100>; - interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&lcpll0_clks BCM_CYGNUS_LCPLL0_SDIO_CLK>; - bus-width = <4>; - sdhci,auto-cmd12; - no-1-8-v; -}; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 802c9df23752..369471814496 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -103,6 +103,26 @@ properties: Only eMMC HS400 mode need to take care of this property. default: 0 + clocks: + maxItems: 3 + description: + Handle clocks for the sdhc controller. + + clock-names: + items: + - const: ipg + - const: ahb + - const: per + + pinctrl-names: + minItems: 1 + maxItems: 4 + items: + - const: default + - const: state_100mhz + - const: state_200mhz + - const: sleep + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt index 75486cca8054..5e74db69f581 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt +++ b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt @@ -5,11 +5,11 @@ by mmc.txt and the properties used by the mmc_spi driver. Required properties: - spi-max-frequency : maximum frequency for this device (Hz). -- voltage-ranges : two cells are required, first cell specifies minimum - slot voltage (mV), second cell specifies maximum slot voltage (mV). - Several ranges could be specified. Optional properties: +- voltage-ranges : two cells are required, first cell specifies minimum + slot voltage (mV), second cell specifies maximum slot voltage (mV). + Several ranges could be specified. If not provided, 3.2v..3.4v is assumed. - gpios : may specify GPIOs in this order: Card-Detect GPIO, Write-Protect GPIO. Note that this does not follow the binding from mmc.txt, for historical reasons. diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 01630b0ecea7..8648d48dbbfd 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -31,6 +31,7 @@ properties: - const: mediatek,mt2701-mmc - items: - const: mediatek,mt8192-mmc + - const: mediatek,mt8195-mmc - const: mediatek,mt8183-mmc clocks: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-of-dwcmshc.txt b/Documentation/devicetree/bindings/mmc/sdhci-of-dwcmshc.txt deleted file mode 100644 index ee4253b33be2..000000000000 --- a/Documentation/devicetree/bindings/mmc/sdhci-of-dwcmshc.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Synopsys DesignWare Cores Mobile Storage Host Controller - -Required properties: -- compatible: should be one of the following: - "snps,dwcmshc-sdhci" -- reg: offset and length of the register set for the device. -- interrupts: a single interrupt specifier. -- clocks: Array of clocks required for SDHCI; requires at least one for - core clock. -- clock-names: Array of names corresponding to clocks property; shall be - "core" for core clock and "bus" for optional bus clock. - -Example: - sdhci2: sdhci@aa0000 { - compatible = "snps,dwcmshc-sdhci"; - reg = <0xaa0000 0x1000>; - interrupts = <GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&emmcclk>; - bus-width = <8>; - } diff --git a/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml b/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml new file mode 100644 index 000000000000..e6c9a2f77cc7 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/snps,dwcmshc-sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys Designware Mobile Storage Host Controller Binding + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + - Jisheng Zhang <Jisheng.Zhang@synaptics.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + enum: + - rockchip,rk3568-dwcmshc + - snps,dwcmshc-sdhci + + reg: + minItems: 1 + items: + - description: Offset and length of the register set for the device + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: core clock + - description: bus clock for optional + - description: axi clock for rockchip specified + - description: block clock for rockchip specified + - description: timer clock for rockchip specified + + + clock-names: + minItems: 1 + items: + - const: core + - const: bus + - const: axi + - const: block + - const: timer + + rockchip,txclk-tapnum: + description: Specify the number of delay for tx sampling. + $ref: /schemas/types.yaml#/definitions/uint8 + + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + mmc@fe310000 { + compatible = "rockchip,rk3568-dwcmshc"; + reg = <0xfe310000 0x10000>; + interrupts = <0 25 0x4>; + clocks = <&cru 17>, <&cru 18>, <&cru 19>, <&cru 20>, <&cru 21>; + clock-names = "core", "bus", "axi", "block", "timer"; + bus-width = <8>; + #address-cells = <1>; + #size-cells = <0>; + }; + - | + mmc@aa0000 { + compatible = "snps,dwcmshc-sdhci"; + reg = <0xaa000 0x1000>; + interrupts = <0 25 0x4>; + clocks = <&cru 17>, <&cru 18>; + clock-names = "core", "bus"; + bus-width = <8>; + #address-cells = <1>; + #size-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index d0e422f4b3e0..678b39952502 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -143,6 +143,13 @@ patternProperties: Ready/Busy pins. Active state refers to the NAND ready state and should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted. + secure-regions: + $ref: /schemas/types.yaml#/definitions/uint64-matrix + description: + Regions in the NAND chip which are protected using a secure element + like Trustzone. This property contains the start address and size of + the secure regions present. + required: - reg diff --git a/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml new file mode 100644 index 000000000000..99249cdfbfb3 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/linksys,ns-partitions.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Linksys Northstar partitioning + +description: | + Linksys devices based on Broadcom Northstar architecture often use two + firmware partitions. One is used for regular booting, the other is treated as + fallback. + + This binding allows defining all fixed partitions and marking those containing + firmware. System can use that information e.g. for booting or flashing + purposes. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + const: linksys,ns-partitions + + "#address-cells": + enum: [ 1, 2 ] + + "#size-cells": + enum: [ 1, 2 ] + +patternProperties: + "^partition@[0-9a-f]+$": + $ref: "partition.yaml#" + properties: + compatible: + items: + - const: linksys,ns-firmware + - const: brcm,trx + unevaluatedProperties: false + +required: + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + partitions { + compatible = "linksys,ns-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot"; + reg = <0x0 0x100000>; + read-only; + }; + + partition@100000 { + label = "nvram"; + reg = <0x100000 0x100000>; + }; + + partition@200000 { + compatible = "linksys,ns-firmware", "brcm,trx"; + reg = <0x200000 0xf00000>; + }; + + partition@1100000 { + compatible = "linksys,ns-firmware", "brcm,trx"; + reg = <0x1100000 0xf00000>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml new file mode 100644 index 000000000000..5cdd2efa9132 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/nvmem-cells.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nvmem cells + +description: | + Any partition containing the compatible "nvmem-cells" will register as a + nvmem provider. + Each direct subnodes represents a nvmem cell following the nvmem binding. + Nvmem binding to declare nvmem-cells can be found in: + Documentation/devicetree/bindings/nvmem/nvmem.yaml + +maintainers: + - Ansuel Smith <ansuelsmth@gmail.com> + +allOf: + - $ref: /schemas/nvmem/nvmem.yaml# + +properties: + compatible: + const: nvmem-cells + +required: + - compatible + +additionalProperties: true + +examples: + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + /* ... */ + + }; + art: art@1200000 { + compatible = "nvmem-cells"; + reg = <0x1200000 0x0140000>; + label = "art"; + read-only; + #address-cells = <1>; + #size-cells = <1>; + + macaddr_gmac1: macaddr_gmac1@0 { + reg = <0x0 0x6>; + }; + + macaddr_gmac2: macaddr_gmac2@6 { + reg = <0x6 0x6>; + }; + + pre_cal_24g: pre_cal_24g@1000 { + reg = <0x1000 0x2f20>; + }; + + pre_cal_5g: pre_cal_5g@5000{ + reg = <0x5000 0x2f20>; + }; + }; + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "bootloader"; + reg = <0x000000 0x100000>; + read-only; + }; + + firmware@100000 { + compatible = "brcm,trx"; + label = "firmware"; + reg = <0x100000 0xe00000>; + }; + + calibration@f00000 { + compatible = "nvmem-cells"; + label = "calibration"; + reg = <0xf00000 0x100000>; + ranges = <0 0xf00000 0x100000>; + #address-cells = <1>; + #size-cells = <1>; + + wifi0@0 { + reg = <0x000000 0x080000>; + }; + + wifi1@80000 { + reg = <0x080000 0x080000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml new file mode 100644 index 000000000000..84ad7ff30121 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml @@ -0,0 +1,196 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/qcom,nandc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm NAND controller + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +properties: + compatible: + enum: + - qcom,ipq806x-nand + - qcom,ipq4019-nand + - qcom,ipq6018-nand + - qcom,ipq8074-nand + - qcom,sdx55-nand + + reg: + maxItems: 1 + + clocks: + items: + - description: Core Clock + - description: Always ON Clock + + clock-names: + items: + - const: core + - const: aon + + "#address-cells": true + "#size-cells": true + +patternProperties: + "^nand@[a-f0-9]$": + type: object + properties: + nand-bus-width: + const: 8 + + nand-ecc-strength: + enum: [1, 4, 8] + + nand-ecc-step-size: + enum: + - 512 + +allOf: + - $ref: "nand-controller.yaml#" + + - if: + properties: + compatible: + contains: + const: qcom,ipq806x-nand + then: + properties: + dmas: + items: + - description: rxtx DMA channel + + dma-names: + items: + - const: rxtx + + qcom,cmd-crci: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Must contain the ADM command type CRCI block instance number + specified for the NAND controller on the given platform + + qcom,data-crci: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Must contain the ADM data type CRCI block instance number + specified for the NAND controller on the given platform + + - if: + properties: + compatible: + contains: + enum: + - qcom,ipq4019-nand + - qcom,ipq6018-nand + - qcom,ipq8074-nand + - qcom,sdx55-nand + + then: + properties: + dmas: + items: + - description: tx DMA channel + - description: rx DMA channel + - description: cmd DMA channel + + dma-names: + items: + - const: tx + - const: rx + - const: cmd + +required: + - compatible + - reg + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-ipq806x.h> + nand-controller@1ac00000 { + compatible = "qcom,ipq806x-nand"; + reg = <0x1ac00000 0x800>; + + clocks = <&gcc EBI2_CLK>, + <&gcc EBI2_AON_CLK>; + clock-names = "core", "aon"; + + dmas = <&adm_dma 3>; + dma-names = "rxtx"; + qcom,cmd-crci = <15>; + qcom,data-crci = <3>; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + + nand-ecc-strength = <4>; + nand-bus-width = <8>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; + + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; + }; + }; + + #include <dt-bindings/clock/qcom,gcc-ipq4019.h> + nand-controller@79b0000 { + compatible = "qcom,ipq4019-nand"; + reg = <0x79b0000 0x1000>; + + clocks = <&gcc GCC_QPIC_CLK>, + <&gcc GCC_QPIC_AHB_CLK>; + clock-names = "core", "aon"; + + dmas = <&qpicbam 0>, + <&qpicbam 1>, + <&qpicbam 2>; + dma-names = "tx", "rx", "cmd"; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-ecc-strength = <4>; + nand-bus-width = <8>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; + + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mtd/qcom_nandc.txt b/Documentation/devicetree/bindings/mtd/qcom_nandc.txt deleted file mode 100644 index 5647913d8837..000000000000 --- a/Documentation/devicetree/bindings/mtd/qcom_nandc.txt +++ /dev/null @@ -1,142 +0,0 @@ -* Qualcomm NAND controller - -Required properties: -- compatible: must be one of the following: - * "qcom,ipq806x-nand" - for EBI2 NAND controller being used in IPQ806x - SoC and it uses ADM DMA - * "qcom,ipq4019-nand" - for QPIC NAND controller v1.4.0 being used in - IPQ4019 SoC and it uses BAM DMA - * "qcom,ipq6018-nand" - for QPIC NAND controller v1.5.0 being used in - IPQ6018 SoC and it uses BAM DMA - * "qcom,ipq8074-nand" - for QPIC NAND controller v1.5.0 being used in - IPQ8074 SoC and it uses BAM DMA - * "qcom,sdx55-nand" - for QPIC NAND controller v2.0.0 being used in - SDX55 SoC and it uses BAM DMA - -- reg: MMIO address range -- clocks: must contain core clock and always on clock -- clock-names: must contain "core" for the core clock and "aon" for the - always on clock - -EBI2 specific properties: -- dmas: DMA specifier, consisting of a phandle to the ADM DMA - controller node and the channel number to be used for - NAND. Refer to dma.txt and qcom_adm.txt for more details -- dma-names: must be "rxtx" -- qcom,cmd-crci: must contain the ADM command type CRCI block instance - number specified for the NAND controller on the given - platform -- qcom,data-crci: must contain the ADM data type CRCI block instance - number specified for the NAND controller on the given - platform - -QPIC specific properties: -- dmas: DMA specifier, consisting of a phandle to the BAM DMA - and the channel number to be used for NAND. Refer to - dma.txt, qcom_bam_dma.txt for more details -- dma-names: must contain all 3 channel names : "tx", "rx", "cmd" -- #address-cells: <1> - subnodes give the chip-select number -- #size-cells: <0> - -* NAND chip-select - -Each controller may contain one or more subnodes to represent enabled -chip-selects which (may) contain NAND flash chips. Their properties are as -follows. - -Required properties: -- reg: a single integer representing the chip-select - number (e.g., 0, 1, 2, etc.) -- #address-cells: see partition.txt -- #size-cells: see partition.txt - -Optional properties: -- nand-bus-width: see nand-controller.yaml -- nand-ecc-strength: see nand-controller.yaml. If not specified, then ECC strength will - be used according to chip requirement and available - OOB size. - -Each nandcs device node may optionally contain a 'partitions' sub-node, which -further contains sub-nodes describing the flash partition mapping. See -partition.txt for more detail. - -Example: - -nand-controller@1ac00000 { - compatible = "qcom,ipq806x-nand"; - reg = <0x1ac00000 0x800>; - - clocks = <&gcc EBI2_CLK>, - <&gcc EBI2_AON_CLK>; - clock-names = "core", "aon"; - - dmas = <&adm_dma 3>; - dma-names = "rxtx"; - qcom,cmd-crci = <15>; - qcom,data-crci = <3>; - - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - - nand-ecc-strength = <4>; - nand-bus-width = <8>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; - - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; - }; - }; -}; - -nand-controller@79b0000 { - compatible = "qcom,ipq4019-nand"; - reg = <0x79b0000 0x1000>; - - clocks = <&gcc GCC_QPIC_CLK>, - <&gcc GCC_QPIC_AHB_CLK>; - clock-names = "core", "aon"; - - dmas = <&qpicbam 0>, - <&qpicbam 1>, - <&qpicbam 2>; - dma-names = "tx", "rx", "cmd"; - - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - nand-ecc-strength = <4>; - nand-bus-width = <8>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; - - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/mtd/tango-nand.txt b/Documentation/devicetree/bindings/mtd/tango-nand.txt deleted file mode 100644 index 91c8420241af..000000000000 --- a/Documentation/devicetree/bindings/mtd/tango-nand.txt +++ /dev/null @@ -1,38 +0,0 @@ -Sigma Designs Tango4 NAND Flash Controller (NFC) - -Required properties: - -- compatible: "sigma,smp8758-nand" -- reg: address/size of nfc_reg, nfc_mem, and pbus_reg -- dmas: reference to the DMA channel used by the controller -- dma-names: "rxtx" -- clocks: reference to the system clock -- #address-cells: <1> -- #size-cells: <0> - -Children nodes represent the available NAND chips. -See Documentation/devicetree/bindings/mtd/nand-controller.yaml for generic bindings. - -Example: - - nandc: nand-controller@2c000 { - compatible = "sigma,smp8758-nand"; - reg = <0x2c000 0x30>, <0x2d000 0x800>, <0x20000 0x1000>; - dmas = <&dma0 3>; - dma-names = "rxtx"; - clocks = <&clkgen SYS_CLK>; - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; /* CS0 */ - nand-ecc-strength = <14>; - nand-ecc-step-size = <1024>; - }; - - nand@1 { - reg = <1>; /* CS1 */ - nand-ecc-strength = <14>; - nand-ecc-step-size = <1024>; - }; - }; diff --git a/Documentation/devicetree/bindings/net/actions,owl-emac.yaml b/Documentation/devicetree/bindings/net/actions,owl-emac.yaml new file mode 100644 index 000000000000..1626e0a821b0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/actions,owl-emac.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/actions,owl-emac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Actions Semi Owl SoCs Ethernet MAC Controller + +maintainers: + - Cristian Ciocaltea <cristian.ciocaltea@gmail.com> + +description: | + This Ethernet MAC is used on the Owl family of SoCs from Actions Semi. + It provides the RMII and SMII interfaces and is compliant with the + IEEE 802.3 CSMA/CD standard, supporting both half-duplex and full-duplex + operation modes at 10/100 Mb/s data transfer rates. + +allOf: + - $ref: "ethernet-controller.yaml#" + +properties: + compatible: + oneOf: + - const: actions,owl-emac + - items: + - enum: + - actions,s500-emac + - const: actions,owl-emac + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 2 + + clock-names: + additionalItems: false + items: + - const: eth + - const: rmii + + resets: + maxItems: 1 + + actions,ethcfg: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the device containing custom config. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - phy-mode + - phy-handle + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/actions,s500-cmu.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/reset/actions,s500-reset.h> + + ethernet@b0310000 { + compatible = "actions,s500-emac", "actions,owl-emac"; + reg = <0xb0310000 0x10000>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cmu 59 /*CLK_ETHERNET*/>, <&cmu CLK_RMII_REF>; + clock-names = "eth", "rmii"; + resets = <&cmu RESET_ETHERNET>; + phy-mode = "rmii"; + phy-handle = <ð_phy>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + eth_phy: ethernet-phy@3 { + reg = <0x3>; + interrupt-parent = <&sirq>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml index 13c26f23a820..2f46e45dcd60 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml +++ b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml @@ -22,10 +22,18 @@ properties: maxItems: 1 interrupts: - description: RX interrupt + minItems: 1 + maxItems: 2 + items: + - description: RX interrupt + - description: TX interrupt interrupt-names: - const: rx + minItems: 1 + maxItems: 2 + items: + - const: rx + - const: tx required: - reg @@ -43,6 +51,7 @@ examples: compatible = "brcm,bcm4908-enet"; reg = <0x80002000 0x1000>; - interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "rx"; + interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "rx", "tx"; }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml b/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml new file mode 100644 index 000000000000..2f34fda55fd0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,bcm6368-mdio-mux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6368 MDIO bus multiplexer + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + +description: + This MDIO bus multiplexer defines buses that could be internal as well as + external to SoCs. When child bus is selected, one needs to select these two + properties as well to generate desired MDIO transaction on appropriate bus. + +allOf: + - $ref: "mdio.yaml#" + +properties: + compatible: + const: brcm,bcm6368-mdio-mux + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: + maxItems: 1 + +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: + - | + mdio0: mdio@10e000b0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "brcm,bcm6368-mdio-mux"; + reg = <0x10e000b0 0x6>; + + mdio_int: mdio@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + }; + + mdio_ext: mdio@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt deleted file mode 100644 index a7d57ba5f2ac..000000000000 --- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt +++ /dev/null @@ -1,56 +0,0 @@ -Broadcom Bluetooth Chips ---------------------- - -This documents the binding structure and common properties for serial -attached Broadcom devices. - -Serial attached Broadcom devices shall be a child node of the host UART -device the slave device is attached to. - -Required properties: - - - compatible: should contain one of the following: - * "brcm,bcm20702a1" - * "brcm,bcm4329-bt" - * "brcm,bcm4330-bt" - * "brcm,bcm43438-bt" - * "brcm,bcm4345c5" - * "brcm,bcm43540-bt" - * "brcm,bcm4335a0" - -Optional properties: - - - max-speed: see Documentation/devicetree/bindings/serial/serial.yaml - - shutdown-gpios: GPIO specifier, used to enable the BT module - - device-wakeup-gpios: GPIO specifier, used to wakeup the controller - - host-wakeup-gpios: GPIO specifier, used to wakeup the host processor. - deprecated, replaced by interrupts and - "host-wakeup" interrupt-names - - clocks: 1 or 2 clocks as defined in clock-names below, in that order - - clock-names: names for clock inputs, matching the clocks given - - "extclk": deprecated, replaced by "txco" - - "txco": external reference clock (not a standalone crystal) - - "lpo": external low power 32.768 kHz clock - - vbat-supply: phandle to regulator supply for VBAT - - vddio-supply: phandle to regulator supply for VDDIO - - brcm,bt-pcm-int-params: configure PCM parameters via a 5-byte array - - sco-routing: 0 = PCM, 1 = Transport, 2 = Codec, 3 = I2S - - pcm-interface-rate: 128KBps, 256KBps, 512KBps, 1024KBps, 2048KBps - - pcm-frame-type: short, long - - pcm-sync-mode: slave, master - - pcm-clock-mode: slave, master - - interrupts: must be one, used to wakeup the host processor - - interrupt-names: must be "host-wakeup" - -Example: - -&uart2 { - pinctrl-names = "default"; - pinctrl-0 = <&uart2_pins>; - - bluetooth { - compatible = "brcm,bcm43438-bt"; - max-speed = <921600>; - brcm,bt-pcm-int-params = [01 02 00 01 01]; - }; -}; diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml b/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml new file mode 100644 index 000000000000..fbdc2083bec4 --- /dev/null +++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/broadcom-bluetooth.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Bluetooth Chips + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: + This binding describes Broadcom UART-attached bluetooth chips. + +properties: + compatible: + enum: + - brcm,bcm20702a1 + - brcm,bcm4329-bt + - brcm,bcm4330-bt + - brcm,bcm4334-bt + - brcm,bcm43438-bt + - brcm,bcm4345c5 + - brcm,bcm43540-bt + - brcm,bcm4335a0 + + shutdown-gpios: + maxItems: 1 + description: GPIO specifier for the line BT_REG_ON used to + power on the BT module + + reset-gpios: + maxItems: 1 + description: GPIO specifier for the line BT_RST_N used to + reset the BT module. This should be marked as + GPIO_ACTIVE_LOW. + + device-wakeup-gpios: + maxItems: 1 + description: GPIO specifier for the line BT_WAKE used to + wakeup the controller. This is using the BT_GPIO_0 + pin on the chip when in use. + + host-wakeup-gpios: + maxItems: 1 + deprecated: true + description: GPIO specifier for the line HOST_WAKE used + to wakeup the host processor. This is using he BT_GPIO_1 + pin on the chip when in use. This is deprecated and replaced + by interrupts and "host-wakeup" interrupt-names + + clocks: + maxItems: 2 + description: 1 or 2 clocks as defined in clock-names below, + in that order + + clock-names: + description: Names of the 1 to 2 supplied clocks + items: + - const: txco + - const: lpo + - const: extclk + + vbat-supply: + description: phandle to regulator supply for VBAT + + vddio-supply: + description: phandle to regulator supply for VDDIO + + brcm,bt-pcm-int-params: + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 5 + maxItems: 5 + description: |- + configure PCM parameters via a 5-byte array: + sco-routing: 0 = PCM, 1 = Transport, 2 = Codec, 3 = I2S + pcm-interface-rate: 128KBps, 256KBps, 512KBps, 1024KBps, 2048KBps + pcm-frame-type: short, long + pcm-sync-mode: slave, master + pcm-clock-mode: slave, master + + interrupts: + items: + - description: Handle to the line HOST_WAKE used to wake + up the host processor. This uses the BT_GPIO_1 pin on + the chip when in use. + + interrupt-names: + items: + - const: host-wakeup + + max-speed: true + current-speed: true + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + uart { + uart-has-rtscts; + + bluetooth { + compatible = "brcm,bcm4330-bt"; + max-speed = <921600>; + brcm,bt-pcm-int-params = [01 02 00 01 01]; + shutdown-gpios = <&gpio 30 GPIO_ACTIVE_HIGH>; + device-wakeup-gpios = <&gpio 7 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 9 GPIO_ACTIVE_LOW>; + interrupt-parent = <&gpio>; + interrupts = <8 IRQ_TYPE_EDGE_FALLING>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml index fe6a949a2eab..55bff1586b6f 100644 --- a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -57,7 +57,6 @@ properties: - const: per clock-frequency: - $ref: /schemas/types.yaml#/definitions/uint32 description: | The oscillator frequency driving the flexcan device, filled in by the boot loader. This property should only be used the used operating system diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 6a5956347816..90ac4fef23f5 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -19,7 +19,8 @@ Required properties: "renesas,can-r8a7793" if CAN controller is a part of R8A7793 SoC. "renesas,can-r8a7794" if CAN controller is a part of R8A7794 SoC. "renesas,can-r8a7795" if CAN controller is a part of R8A7795 SoC. - "renesas,can-r8a7796" if CAN controller is a part of R8A7796 SoC. + "renesas,can-r8a7796" if CAN controller is a part of R8A77960 SoC. + "renesas,can-r8a77961" if CAN controller is a part of R8A77961 SoC. "renesas,can-r8a77965" if CAN controller is a part of R8A77965 SoC. "renesas,can-r8a77990" if CAN controller is a part of R8A77990 SoC. "renesas,can-r8a77995" if CAN controller is a part of R8A77995 SoC. @@ -40,7 +41,7 @@ Required properties: - pinctrl-names: must be "default". Required properties for R8A774A1, R8A774B1, R8A774C0, R8A774E1, R8A7795, -R8A7796, R8A77965, R8A77990, and R8A77995: +R8A77960, R8A77961, R8A77965, R8A77990, and R8A77995: For the denoted SoCs, "clkp2" can be CANFD clock. This is a div6 clock and can be used by both CAN and CAN FD controller at the same time. It needs to be scaled to maximum frequency if any of these controllers use it. This is done diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index 8a3494db4d8d..16aa192c118e 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -70,6 +70,15 @@ patternProperties: device is what the switch port is connected to $ref: /schemas/types.yaml#/definitions/phandle + dsa-tag-protocol: + description: + Instead of the default, the switch will use this tag protocol if + possible. Useful when a device supports multiple protcols and + the default is incompatible with the Ethernet device. + enum: + - dsa + - edsa + phy-handle: true phy-mode: true diff --git a/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt b/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt index 886cbe8ffb38..e3829d3e480e 100644 --- a/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt +++ b/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt @@ -5,6 +5,10 @@ Required properties for GSWIP core: - compatible : "lantiq,xrx200-gswip" for the embedded GSWIP in the xRX200 SoC + "lantiq,xrx300-gswip" for the embedded GSWIP in the + xRX300 SoC + "lantiq,xrx330-gswip" for the embedded GSWIP in the + xRX330 SoC - reg : memory range of the GSWIP core registers : memory range of the GSWIP MDIO registers : memory range of the GSWIP MII registers diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index 9f7d131bbcef..84985f53bffd 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -21,6 +21,8 @@ properties: - microchip,ksz8765 - microchip,ksz8794 - microchip,ksz8795 + - microchip,ksz8863 + - microchip,ksz8873 - microchip,ksz9477 - microchip,ksz9897 - microchip,ksz9896 diff --git a/Documentation/devicetree/bindings/net/fsl-enetc.txt b/Documentation/devicetree/bindings/net/fsl-enetc.txt index b7034ccbc1bd..9b9a3f197e2d 100644 --- a/Documentation/devicetree/bindings/net/fsl-enetc.txt +++ b/Documentation/devicetree/bindings/net/fsl-enetc.txt @@ -102,3 +102,18 @@ Example: full-duplex; }; }; + +* Integrated Endpoint Register Block bindings + +Optionally, the fsl_enetc driver can probe on the Integrated Endpoint Register +Block, which preconfigures the FIFO limits for the ENETC ports. This is a node +with the following properties: + +- reg : Specifies the address in the SoC memory space. +- compatible : Must be "fsl,ls1028a-enetc-ierb". + +Example: + ierb@1f0800000 { + compatible = "fsl,ls1028a-enetc-ierb"; + reg = <0x01 0xf0800000 0x0 0x10000>; + }; diff --git a/Documentation/devicetree/bindings/net/idt,3243x-emac.yaml b/Documentation/devicetree/bindings/net/idt,3243x-emac.yaml new file mode 100644 index 000000000000..11ffc306dd54 --- /dev/null +++ b/Documentation/devicetree/bindings/net/idt,3243x-emac.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/idt,3243x-emac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IDT 79rc3243x Ethernet controller + +description: Ethernet controller integrated into IDT 79RC3243x family SoCs + +maintainers: + - Thomas Bogendoerfer <tsbogend@alpha.franken.de> + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + const: idt,3243x-emac + + reg: + maxItems: 3 + + reg-names: + items: + - const: emac + - const: dma_rx + - const: dma_tx + + interrupts: + items: + - description: RX interrupt + - description: TX interrupt + + interrupt-names: + items: + - const: rx + - const: tx + + clocks: + maxItems: 1 + + clock-names: + items: + - const: mdioclk + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + + ethernet@60000 { + compatible = "idt,3243x-emac"; + + reg = <0x60000 0x10000>, + <0x40000 0x14>, + <0x40014 0x14>; + reg-names = "emac", "dma_rx", "dma_tx"; + + interrupt-parent = <&rcpic3>; + interrupts = <0>, <1>; + interrupt-names = "rx", "tx"; + + clocks = <&iclk>; + clock-names = "mdioclk"; + }; diff --git a/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml new file mode 100644 index 000000000000..f2e91d1bf7d7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2018 Linaro Ltd. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/intel,ixp4xx-ethernet.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel IXP4xx ethernet + +allOf: + - $ref: "ethernet-controller.yaml#" + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + The Intel IXP4xx ethernet makes use of the IXP4xx NPE (Network + Processing Engine) and the IXP4xx Queue Manager to process + the ethernet frames. It can optionally contain an MDIO bus to + talk to PHYs. + +properties: + compatible: + const: intel,ixp4xx-ethernet + + reg: + maxItems: 1 + description: Ethernet MMIO address range + + queue-rx: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the RX queue on the NPE + + queue-txready: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the TX READY queue on the NPE + + phy-mode: true + + phy-handle: true + + intel,npe-handle: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the NPE this ethernet instance is using + and the instance to use in the second cell + + mdio: + type: object + $ref: "mdio.yaml#" + description: optional node for embedded MDIO controller + +required: + - compatible + - reg + - queue-rx + - queue-txready + - intel,npe-handle + +additionalProperties: false + +examples: + - | + npe: npe@c8006000 { + compatible = "intel,ixp4xx-network-processing-engine"; + reg = <0xc8006000 0x1000>, <0xc8007000 0x1000>, <0xc8008000 0x1000>; + }; + + ethernet@c8009000 { + compatible = "intel,ixp4xx-ethernet"; + reg = <0xc8009000 0x1000>; + status = "disabled"; + queue-rx = <&qmgr 4>; + queue-txready = <&qmgr 21>; + intel,npe-handle = <&npe 1>; + phy-mode = "rgmii"; + phy-handle = <&phy1>; + }; + + ethernet@c800c000 { + compatible = "intel,ixp4xx-ethernet"; + reg = <0xc800c000 0x1000>; + status = "disabled"; + queue-rx = <&qmgr 3>; + queue-txready = <&qmgr 20>; + intel,npe-handle = <&npe 2>; + phy-mode = "rgmii"; + phy-handle = <&phy2>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy1: ethernet-phy@1 { + reg = <1>; + }; + phy2: ethernet-phy@2 { + reg = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mdio-gpio.txt b/Documentation/devicetree/bindings/net/mdio-gpio.txt index 8dbcf8295c6c..4d91a36c5cf5 100644 --- a/Documentation/devicetree/bindings/net/mdio-gpio.txt +++ b/Documentation/devicetree/bindings/net/mdio-gpio.txt @@ -2,6 +2,7 @@ MDIO on GPIOs Currently defined compatibles: - virtual,gpio-mdio +- microchip,mdio-smi0 MDC and MDIO lines connected to GPIO controllers are listed in the gpios property as described in section VIII.1 in the following order: diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index 8f86084bf12e..5fe6d3dceb08 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -43,7 +43,12 @@ description: properties: compatible: - const: "qcom,sdm845-ipa" + enum: + - qcom,sc7180-ipa + - qcom,sc7280-ipa + - qcom,sdm845-ipa + - qcom,sdx55-ipa + - qcom,sm8350-ipa reg: items: @@ -100,7 +105,6 @@ properties: - description: Whether the IPA clock is enabled (if valid) qcom,smem-state-names: - $ref: /schemas/types.yaml#/definitions/string-array description: The names of the state bits used for SMP2P output items: - const: ipa-clock-enabled-valid @@ -120,6 +124,14 @@ properties: the firmware passed to Trust Zone for authentication. Required when Trust Zone (not the modem) performs early initialization. + firmware-name: + $ref: /schemas/types.yaml#/definitions/string + description: + If present, name (or relative path) of the file within the + firmware search path containing the firmware image used when + initializing IPA hardware. Optional, and only used when + Trust Zone performs early initialization. + required: - compatible - iommus @@ -129,12 +141,23 @@ required: - interconnects - qcom,smem-states +# Either modem-init is present, or memory-region must be present. oneOf: - required: - modem-init - required: - memory-region +# If memory-region is present, firmware-name may optionally be present. +# But if modem-init is present, firmware-name must not be present. +if: + required: + - modem-init +then: + not: + required: + - firmware-name + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/renesas,ether.yaml b/Documentation/devicetree/bindings/net/renesas,ether.yaml index 8ce5ed8a58dd..c101a1ec846e 100644 --- a/Documentation/devicetree/bindings/net/renesas,ether.yaml +++ b/Documentation/devicetree/bindings/net/renesas,ether.yaml @@ -10,7 +10,7 @@ allOf: - $ref: ethernet-controller.yaml# maintainers: - - Sergei Shtylyov <sergei.shtylyov@cogentembedded.com> + - Sergei Shtylyov <sergei.shtylyov@gmail.com> properties: compatible: diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index 91ba96d43c6c..005868f703a6 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -50,7 +50,16 @@ properties: interrupt-names: true clocks: - maxItems: 1 + minItems: 1 + items: + - description: AVB functional clock + - description: Optional TXC reference clock + + clock-names: + minItems: 1 + items: + - const: fck + - const: refclk iommus: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt deleted file mode 100644 index 3b71da7e8742..000000000000 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt +++ /dev/null @@ -1,76 +0,0 @@ -Rockchip SoC RK3288 10/100/1000 Ethernet driver(GMAC) - -The device node has following properties. - -Required properties: - - compatible: should be "rockchip,<name>-gamc" - "rockchip,px30-gmac": found on PX30 SoCs - "rockchip,rk3128-gmac": found on RK312x SoCs - "rockchip,rk3228-gmac": found on RK322x SoCs - "rockchip,rk3288-gmac": found on RK3288 SoCs - "rockchip,rk3328-gmac": found on RK3328 SoCs - "rockchip,rk3366-gmac": found on RK3366 SoCs - "rockchip,rk3368-gmac": found on RK3368 SoCs - "rockchip,rk3399-gmac": found on RK3399 SoCs - "rockchip,rv1108-gmac": found on RV1108 SoCs - - reg: addresses and length of the register sets for the device. - - interrupts: Should contain the GMAC interrupts. - - interrupt-names: Should contain the interrupt names "macirq". - - rockchip,grf: phandle to the syscon grf used to control speed and mode. - - clocks: <&cru SCLK_MAC>: clock selector for main clock, from PLL or PHY. - <&cru SCLK_MAC_PLL>: PLL clock for SCLK_MAC - <&cru SCLK_MAC_RX>: clock gate for RX - <&cru SCLK_MAC_TX>: clock gate for TX - <&cru SCLK_MACREF>: clock gate for RMII referce clock - <&cru SCLK_MACREF_OUT> clock gate for RMII reference clock output - <&cru ACLK_GMAC>: AXI clock gate for GMAC - <&cru PCLK_GMAC>: APB clock gate for GMAC - - clock-names: One name for each entry in the clocks property. - - phy-mode: See ethernet.txt file in the same directory. - - pinctrl-names: Names corresponding to the numbered pinctrl states. - - pinctrl-0: pin-control mode. can be <&rgmii_pins> or <&rmii_pins>. - - clock_in_out: For RGMII, it must be "input", means main clock(125MHz) - is not sourced from SoC's PLL, but input from PHY; For RMII, "input" means - PHY provides the reference clock(50MHz), "output" means GMAC provides the - reference clock. - - snps,reset-gpio gpio number for phy reset. - - snps,reset-active-low boolean flag to indicate if phy reset is active low. - - assigned-clocks: main clock, should be <&cru SCLK_MAC>; - - assigned-clock-parents = parent of main clock. - can be <&ext_gmac> or <&cru SCLK_MAC_PLL>. - -Optional properties: - - tx_delay: Delay value for TXD timing. Range value is 0~0x7F, 0x30 as default. - - rx_delay: Delay value for RXD timing. Range value is 0~0x7F, 0x10 as default. - - phy-supply: phandle to a regulator if the PHY needs one - -Example: - -gmac: ethernet@ff290000 { - compatible = "rockchip,rk3288-gmac"; - reg = <0xff290000 0x10000>; - interrupts = <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "macirq"; - rockchip,grf = <&grf>; - clocks = <&cru SCLK_MAC>, - <&cru SCLK_MAC_RX>, <&cru SCLK_MAC_TX>, - <&cru SCLK_MACREF>, <&cru SCLK_MACREF_OUT>, - <&cru ACLK_GMAC>, <&cru PCLK_GMAC>; - clock-names = "stmmaceth", - "mac_clk_rx", "mac_clk_tx", - "clk_mac_ref", "clk_mac_refout", - "aclk_mac", "pclk_mac"; - phy-mode = "rgmii"; - pinctrl-names = "default"; - pinctrl-0 = <&rgmii_pins /*&rmii_pins*/>; - - clock_in_out = "input"; - snps,reset-gpio = <&gpio4 7 0>; - snps,reset-active-low; - - assigned-clocks = <&cru SCLK_MAC>; - assigned-clock-parents = <&ext_gmac>; - tx_delay = <0x30>; - rx_delay = <0x10>; - -}; diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml new file mode 100644 index 000000000000..5acddb6171bf --- /dev/null +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml @@ -0,0 +1,120 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/rockchip-dwmac.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Rockchip 10/100/1000 Ethernet driver(GMAC) + +maintainers: + - David Wu <david.wu@rock-chips.com> + +# We need a select here so we don't match all nodes with 'snps,dwmac' +select: + properties: + compatible: + contains: + enum: + - rockchip,px30-gmac + - rockchip,rk3128-gmac + - rockchip,rk3228-gmac + - rockchip,rk3288-gmac + - rockchip,rk3328-gmac + - rockchip,rk3366-gmac + - rockchip,rk3368-gmac + - rockchip,rk3399-gmac + - rockchip,rv1108-gmac + required: + - compatible + +allOf: + - $ref: "snps,dwmac.yaml#" + +properties: + compatible: + items: + - enum: + - rockchip,px30-gmac + - rockchip,rk3128-gmac + - rockchip,rk3228-gmac + - rockchip,rk3288-gmac + - rockchip,rk3328-gmac + - rockchip,rk3366-gmac + - rockchip,rk3368-gmac + - rockchip,rk3399-gmac + - rockchip,rv1108-gmac + + clocks: + minItems: 5 + maxItems: 8 + + clock-names: + contains: + enum: + - stmmaceth + - mac_clk_tx + - mac_clk_rx + - aclk_mac + - pclk_mac + - clk_mac_ref + - clk_mac_refout + - clk_mac_speed + + clock_in_out: + description: + For RGMII, it must be "input", means main clock(125MHz) + is not sourced from SoC's PLL, but input from PHY. + For RMII, "input" means PHY provides the reference clock(50MHz), + "output" means GMAC provides the reference clock. + $ref: /schemas/types.yaml#/definitions/string + enum: [input, output] + + rockchip,grf: + description: The phandle of the syscon node for the general register file. + $ref: /schemas/types.yaml#/definitions/phandle + + tx_delay: + description: Delay value for TXD timing. Range value is 0~0x7F, 0x30 as default. + $ref: /schemas/types.yaml#/definitions/uint32 + + rx_delay: + description: Delay value for RXD timing. Range value is 0~0x7F, 0x10 as default. + $ref: /schemas/types.yaml#/definitions/uint32 + + phy-supply: + description: PHY regulator + +required: + - compatible + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/rk3288-cru.h> + + gmac: ethernet@ff290000 { + compatible = "rockchip,rk3288-gmac"; + reg = <0xff290000 0x10000>; + interrupts = <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + clocks = <&cru SCLK_MAC>, + <&cru SCLK_MAC_RX>, <&cru SCLK_MAC_TX>, + <&cru SCLK_MACREF>, <&cru SCLK_MACREF_OUT>, + <&cru ACLK_GMAC>, <&cru PCLK_GMAC>; + clock-names = "stmmaceth", + "mac_clk_rx", "mac_clk_tx", + "clk_mac_ref", "clk_mac_refout", + "aclk_mac", "pclk_mac"; + assigned-clocks = <&cru SCLK_MAC>; + assigned-clock-parents = <&ext_gmac>; + + rockchip,grf = <&grf>; + phy-mode = "rgmii"; + clock_in_out = "input"; + tx_delay = <0x30>; + rx_delay = <0x10>; + }; diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 0642b0f59491..2edd8bea993e 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -56,6 +56,15 @@ properties: - amlogic,meson8m2-dwmac - amlogic,meson-gxbb-dwmac - amlogic,meson-axg-dwmac + - rockchip,px30-gmac + - rockchip,rk3128-gmac + - rockchip,rk3228-gmac + - rockchip,rk3288-gmac + - rockchip,rk3328-gmac + - rockchip,rk3366-gmac + - rockchip,rk3368-gmac + - rockchip,rk3399-gmac + - rockchip,rv1108-gmac - snps,dwmac - snps,dwmac-3.50a - snps,dwmac-3.610 @@ -89,7 +98,7 @@ properties: clocks: minItems: 1 - maxItems: 5 + maxItems: 8 additionalItems: true items: - description: GMAC main clock @@ -101,7 +110,7 @@ properties: clock-names: minItems: 1 - maxItems: 5 + maxItems: 8 additionalItems: true contains: enum: diff --git a/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml b/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml new file mode 100644 index 000000000000..c11f23b20c4c --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/wireless/brcm,bcm4329-fmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM4329 family fullmac wireless SDIO devices + +maintainers: + - Arend van Spriel <arend@broadcom.com> + +description: + The Broadcom Single chip MAC part for the BCM4329 family and + later Cypress chips in the same family named CYW4373 and similar. + These chips also have a Bluetooth portion described in a separate + binding. + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm43143-fmac + - brcm,bcm4341b0-fmac + - brcm,bcm4341b4-fmac + - brcm,bcm4341b5-fmac + - brcm,bcm4329-fmac + - brcm,bcm4330-fmac + - brcm,bcm4334-fmac + - brcm,bcm43340-fmac + - brcm,bcm4335-fmac + - brcm,bcm43362-fmac + - brcm,bcm4339-fmac + - brcm,bcm43430a0-fmac + - brcm,bcm43430a1-fmac + - brcm,bcm43455-fmac + - brcm,bcm43456-fmac + - brcm,bcm4354-fmac + - brcm,bcm4356-fmac + - brcm,bcm4359-fmac + - cypress,cyw4373-fmac + - cypress,cyw43012-fmac + - const: brcm,bcm4329-fmac + - const: brcm,bcm4329-fmac + + reg: + description: SDIO function number for the device, for most cases + this will be 1. + + interrupts: + maxItems: 1 + description: Out-of-band (OOB) IRQ line for waking up the host + in response to WLAN activity. This corresponds to the HOST_WAKE + line into the chip. + + interrupt-names: + description: Name for the OOB IRQ, this must be set to "host-wake". + const: host-wake + + brcm,drive-strength: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Drive strength used for the SDIO pins on the device in mA. + minimum: 0 + maximum: 32 + + reset-gpios: + maxItems: 1 + description: A GPIO line connected to the WL_RST line, if present + this shall be flagged as active low. + + brcm,ccode-map: + $ref: /schemas/types.yaml#/definitions/string-array + description: Multiple strings for translating ISO3166 country code to + brcmfmac firmware country code and revision. + items: + pattern: '^[A-Z][A-Z]-[A-Z][0-9A-Z]-[0-9]+$' + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + mmc@80118000 { + compatible = "arm,pl18x", "arm,primecell"; + reg = <0x80118000 0x1000>; + clocks = <&clk 0>, <&clk 1>; + clock-names = "mclk", "apb_pclk"; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + bus-width = <4>; + non-removable; + vmmc-supply = <&wl_bt_reg>; + #address-cells = <1>; + #size-cells = <0>; + + wifi@1 { + compatible = "brcm,bcm4334-fmac", "brcm,bcm4329-fmac"; + reg = <1>; + interrupt-parent = <&gpio>; + interrupts = <24 IRQ_TYPE_EDGE_FALLING>; + interrupt-names = "host-wake"; + reset-gpios = <&gpio 23 GPIO_ACTIVE_LOW>; + brcm,ccode-map = "JP-JP-78", "US-Q2-86"; + }; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt b/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt deleted file mode 100644 index cffb2d6876e3..000000000000 --- a/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt +++ /dev/null @@ -1,38 +0,0 @@ -Broadcom BCM43xx Fullmac wireless SDIO devices - -This node provides properties for controlling the Broadcom wireless device. The -node is expected to be specified as a child node to the SDIO controller that -connects the device to the system. - -Required properties: - - - compatible : Should be "brcm,bcm4329-fmac". - -Optional properties: - - brcm,drive-strength : drive strength used for SDIO pins on device in mA - (default = 6). - - interrupts : specifies attributes for the out-of-band interrupt (host-wake). - When not specified the device will use in-band SDIO interrupts. - - interrupt-names : name of the out-of-band interrupt, which must be set - to "host-wake". - -Example: - -mmc3: mmc@1c12000 { - #address-cells = <1>; - #size-cells = <0>; - - pinctrl-names = "default"; - pinctrl-0 = <&mmc3_pins_a>; - vmmc-supply = <®_vmmc3>; - bus-width = <4>; - non-removable; - - brcmf: wifi@1 { - reg = <1>; - compatible = "brcm,bcm4329-fmac"; - interrupt-parent = <&pio>; - interrupts = <10 8>; /* PH10 / EINT10 */ - interrupt-names = "host-wake"; - }; -}; diff --git a/Documentation/devicetree/bindings/net/wireless/ieee80211.txt b/Documentation/devicetree/bindings/net/wireless/ieee80211.txt deleted file mode 100644 index f6442b1397f5..000000000000 --- a/Documentation/devicetree/bindings/net/wireless/ieee80211.txt +++ /dev/null @@ -1,24 +0,0 @@ -Common IEEE 802.11 properties - -This provides documentation of common properties that are valid for all wireless -devices. - -Optional properties: - - ieee80211-freq-limit : list of supported frequency ranges in KHz. This can be - used for devices that in a given config support less channels than - normally. It may happen chipset supports a wide wireless band but it is - limited to some part of it due to used antennas or power amplifier. - An example case for this can be tri-band wireless router with two - identical chipsets used for two different 5 GHz subbands. Using them - incorrectly could not work or decrease performance noticeably. - -Example: - -pcie@0,0 { - reg = <0x0000 0 0 0 0>; - wifi@0,0 { - reg = <0x0000 0 0 0 0>; - ieee80211-freq-limit = <2402000 2482000>, - <5170000 5250000>; - }; -}; diff --git a/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml b/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml new file mode 100644 index 000000000000..d58e1571df9b --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. + +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/wireless/ieee80211.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common IEEE 802.11 Binding + +maintainers: + - Lorenzo Bianconi <lorenzo@kernel.org> + +description: | + This provides documentation of common properties that are valid for + all wireless devices + +properties: + ieee80211-freq-limit: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + minItems: 2 + maxItems: 2 + description: + List of supported frequency ranges in KHz. This can be used for devices + that in a given config support less channels than normally. It may happen + chipset supports a wide wireless band but it is limited to some part of + it due to used antennas or power amplifier. An example case for this + can be tri-band wireless router with two identical chipsets used for two + different 5 GHz subbands. Using them incorrectly could not work or + decrease performance noticeably + +additionalProperties: true + +examples: + - | + pcie0 { + #address-cells = <3>; + #size-cells = <2>; + wifi@0,0 { + reg = <0x0000 0 0 0 0>; + ieee80211-freq-limit = <2402000 2482000>, + <5170000 5250000>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt deleted file mode 100644 index ab7e7a00e534..000000000000 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt +++ /dev/null @@ -1,78 +0,0 @@ -* MediaTek mt76xx devices - -This node provides properties for configuring the MediaTek mt76xx wireless -device. The node is expected to be specified as a child node of the PCI -controller to which the wireless chip is connected. - -Alternatively, it can specify the wireless part of the MT7628/MT7688 or -MT7622 SoC. For SoC, use the following compatible strings: - -compatible: -- "mediatek,mt7628-wmac" for MT7628/MT7688 -- "mediatek,mt7622-wmac" for MT7622 - -properties: -- reg: Address and length of the register set for the device. -- interrupts: Main device interrupt - -MT7622 specific properties: -- power-domains: phandle to the power domain that the WMAC is part of -- mediatek,infracfg: phandle to the infrastructure bus fabric syscon node - -Optional properties: - -- ieee80211-freq-limit: See ieee80211.txt -- mediatek,mtd-eeprom: Specify a MTD partition + offset containing EEPROM data -- big-endian: if the radio eeprom partition is written in big-endian, specify - this property -- mediatek,eeprom-merge-otp: Merge EEPROM data with OTP data. Can be used on - boards where the flash calibration data is generic and specific calibration - data should be pulled from the OTP ROM - -The MAC address can as well be set with corresponding optional properties -defined in net/ethernet.txt. - -Optional nodes: -- led: Properties for a connected LED - Optional properties: - - led-sources: See Documentation/devicetree/bindings/leds/common.txt - -&pcie { - pcie0 { - wifi@0,0 { - compatible = "mediatek,mt76"; - reg = <0x0000 0 0 0 0>; - ieee80211-freq-limit = <5000000 6000000>; - mediatek,mtd-eeprom = <&factory 0x8000>; - big-endian; - - led { - led-sources = <2>; - }; - }; - }; -}; - -MT7628 example: - -wmac: wmac@10300000 { - compatible = "mediatek,mt7628-wmac"; - reg = <0x10300000 0x100000>; - - interrupt-parent = <&cpuintc>; - interrupts = <6>; - - mediatek,mtd-eeprom = <&factory 0x0000>; -}; - -MT7622 example: - -wmac: wmac@18000000 { - compatible = "mediatek,mt7622-wmac"; - reg = <0 0x18000000 0 0x100000>; - interrupts = <GIC_SPI 211 IRQ_TYPE_LEVEL_LOW>; - - mediatek,infracfg = <&infracfg>; - - power-domains = <&scpsys MT7622_POWER_DOMAIN_WB>; -}; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml new file mode 100644 index 000000000000..3e2c2e43175e --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml @@ -0,0 +1,228 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. + +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/wireless/mediatek,mt76.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek mt76 wireless devices Generic Binding + +maintainers: + - Felix Fietkau <nbd@nbd.name> + - Lorenzo Bianconi <lorenzo@kernel.org> + - Ryder Lee <ryder.lee@mediatek.com> + +description: | + This node provides properties for configuring the MediaTek mt76xx + wireless device. The node is expected to be specified as a child + node of the PCI controller to which the wireless chip is connected. + Alternatively, it can specify the wireless part of the MT7628/MT7688 + or MT7622 SoC. + +allOf: + - $ref: ieee80211.yaml# + +properties: + compatible: + enum: + - mediatek,mt76 + - mediatek,mt7628-wmac + - mediatek,mt7622-wmac + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + power-domains: + maxItems: 1 + + mediatek,infracfg: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the infrastructure bus fabric syscon node. + This property is MT7622 specific + + ieee80211-freq-limit: true + + mediatek,mtd-eeprom: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Phandle to a MTD partition + offset containing EEPROM data + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + Specify if the radio eeprom partition is written in big-endian + + mediatek,eeprom-merge-otp: + type: boolean + description: + Merge EEPROM data with OTP data. Can be used on boards where the flash + calibration data is generic and specific calibration data should be + pulled from the OTP ROM + + led: + type: object + $ref: /schemas/leds/common.yaml# + additionalProperties: false + properties: + led-sources: + maxItems: 1 + + power-limits: + type: object + additionalProperties: false + patternProperties: + "^r[0-9]+": + type: object + additionalProperties: false + properties: + regdomain: + $ref: /schemas/types.yaml#/definitions/string + description: + Regdomain refers to a legal regulatory region. Different + countries define different levels of allowable transmitter + power, time that a channel can be occupied, and different + available channels + enum: + - FCC + - ETSI + - JP + + patternProperties: + "^txpower-[256]g$": + type: object + additionalProperties: false + patternProperties: + "^b[0-9]+$": + type: object + additionalProperties: false + properties: + channels: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 2 + maxItems: 2 + description: + Pairs of first and last channel number of the selected + band + + rates-cck: + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 4 + maxItems: 4 + description: + 4 half-dBm per-rate power limit values + + rates-ofdm: + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 8 + maxItems: 8 + description: + 8 half-dBm per-rate power limit values + + rates-mcs: + $ref: /schemas/types.yaml#/definitions/uint8-matrix + description: + Sets of per-rate power limit values for 802.11n/802.11ac + rates for multiple channel bandwidth settings. + Each set starts with the number of channel bandwidth + settings for which the rate set applies, followed by + either 8 or 10 power limit values. The order of the + channel bandwidth settings is 20, 40, 80 and 160 MHz. + maxItems: 4 + items: + minItems: 9 + maxItems: 11 + + rates-ru: + $ref: /schemas/types.yaml#/definitions/uint8-matrix + description: + Sets of per-rate power limit values for 802.11ax rates + for multiple channel bandwidth or resource unit settings. + Each set starts with the number of channel bandwidth or + resource unit settings for which the rate set applies, + followed by 12 power limit values. The order of the + channel resource unit settings is RU26, RU52, RU106, + RU242/SU20, RU484/SU40, RU996/SU80 and RU2x996/SU160. + items: + minItems: 13 + maxItems: 13 + + txs-delta: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Half-dBm power delta for different numbers of antennas + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pcie0 { + #address-cells = <3>; + #size-cells = <2>; + wifi@0,0 { + compatible = "mediatek,mt76"; + reg = <0x0000 0 0 0 0>; + ieee80211-freq-limit = <5000000 6000000>; + mediatek,mtd-eeprom = <&factory 0x8000>; + big-endian; + + led { + led-sources = <2>; + }; + + power-limits { + r0 { + regdomain = "FCC"; + txpower-5g { + b0 { + 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>; + 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>; + }; + b1 { + channels = <100 181>; + rates-ofdm = /bits/ 8 <14 14 14 14 14 14 14 14>; + rates-mcs = /bits/ 8 <4 14 14 14 14 14 14 14 14 14 14>; + txs-delta = <12 9 6>; + rates-ru = /bits/ 8 <7 14 14 14 14 14 14 14 14 14 14 14 14>; + }; + }; + }; + }; + }; + }; + + - | + wifi@10300000 { + compatible = "mediatek,mt7628-wmac"; + reg = <0x10300000 0x100000>; + + interrupt-parent = <&cpuintc>; + interrupts = <6>; + + mediatek,mtd-eeprom = <&factory 0x0>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + wifi@18000000 { + compatible = "mediatek,mt7622-wmac"; + reg = <0x10300000 0x100000>; + interrupts = <GIC_SPI 211 IRQ_TYPE_LEVEL_LOW>; + + mediatek,infracfg = <&infracfg>; + + power-domains = <&scpsys 3>; + }; diff --git a/Documentation/devicetree/bindings/net/xilinx_axienet.txt b/Documentation/devicetree/bindings/net/xilinx_axienet.txt index 2cd452419ed0..b8e4894bc634 100644 --- a/Documentation/devicetree/bindings/net/xilinx_axienet.txt +++ b/Documentation/devicetree/bindings/net/xilinx_axienet.txt @@ -42,11 +42,23 @@ Optional properties: support both 1000BaseX and SGMII modes. If set, the phy-mode should be set to match the mode selected on core reset (i.e. by the basex_or_sgmii core input line). -- clocks : AXI bus clock for the device. Refer to common clock bindings. - Used to calculate MDIO clock divisor. If not specified, it is - auto-detected from the CPU clock (but only on platforms where - this is possible). New device trees should specify this - the - auto detection is only for backward compatibility. +- clock-names: Tuple listing input clock names. Possible clocks: + s_axi_lite_clk: Clock for AXI register slave interface + axis_clk: AXI4-Stream clock for TXD RXD TXC and RXS interfaces + ref_clk: Ethernet reference clock, used by signal delay + primitives and transceivers + mgt_clk: MGT reference clock (used by optional internal + PCS/PMA PHY) + + Note that if s_axi_lite_clk is not specified by name, the + first clock of any name is used for this. If that is also not + specified, the clock rate is auto-detected from the CPU clock + (but only on platforms where this is possible). New device + trees should specify all applicable clocks by name - the + fallbacks to an unnamed clock or to CPU clock are only for + backward compatibility. +- clocks: Phandles to input clocks matching clock-names. Refer to common + clock bindings. - axistream-connected: Reference to another node which contains the resources for the AXI DMA controller used by this device. If this is specified, the DMA-related resources from that @@ -62,7 +74,8 @@ Example: device_type = "network"; interrupt-parent = <µblaze_0_axi_intc>; interrupts = <2 0 1>; - clocks = <&axi_clk>; + clock-names = "s_axi_lite_clk", "axis_clk", "ref_clk", "mgt_clk"; + clocks = <&axi_clk>, <&axi_clk>, <&pl_enet_ref_clk>, <&mgt_clk>; phy-mode = "mii"; reg = <0x40c00000 0x40000 0x50c00000 0x40000>; xlnx,rxcsum = <0x2>; diff --git a/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml new file mode 100644 index 000000000000..58ff6b0bdb1a --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/brcm,nvram.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom's NVRAM + +description: | + Broadcom's NVRAM is a structure containing device specific environment + variables. It is used for storing device configuration, booting parameters + and calibration data. + + NVRAM can be accessed on Broadcom BCM47xx MIPS and Northstar ARM Cortex-A9 + devices usiong I/O mapped memory. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + const: brcm,nvram + +unevaluatedProperties: false + +examples: + - | + nvram@1eff0000 { + compatible = "brcm,nvram"; + reg = <0x1eff0000 0x10000>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt index ef93c3b95424..b6791702bcfc 100644 --- a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt @@ -7,6 +7,7 @@ Required properties: "mediatek,mt7622-efuse", "mediatek,efuse": for MT7622 "mediatek,mt7623-efuse", "mediatek,efuse": for MT7623 "mediatek,mt8173-efuse" or "mediatek,efuse": for MT8173 + "mediatek,mt8192-efuse", "mediatek,efuse": for MT8192 "mediatek,mt8516-efuse", "mediatek,efuse": for MT8516 - reg: Should contain registers location and length diff --git a/Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml b/Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml index d5d7f113bade..b1da238c8bcb 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml @@ -2,7 +2,7 @@ %YAML 1.2 --- $id: http://devicetree.org/schemas/nvmem/nvmem-consumer.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# +$schema: http://devicetree.org/meta-schemas/base.yaml# title: NVMEM (Non Volatile Memory) Consumer Device Tree Bindings @@ -23,12 +23,10 @@ properties: List of phandle to the nvmem data cells. nvmem-names: - $ref: /schemas/types.yaml#/definitions/string-array description: Names for the each nvmem provider. nvmem-cell-names: - $ref: /schemas/types.yaml#/definitions/string-array description: Names for each nvmem-cells specified. diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 7481a9e48f19..b8dc3d2b6e92 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -20,9 +20,6 @@ description: | storage device. properties: - $nodename: - pattern: "^(eeprom|efuse|nvram)(@.*|-[0-9a-f])*$" - "#address-cells": const: 1 diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 992777c90a0b..861b205016b1 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -24,6 +24,7 @@ properties: - qcom,msm8998-qfprom - qcom,qcs404-qfprom - qcom,sc7180-qfprom + - qcom,sc7280-qfprom - qcom,sdm845-qfprom - const: qcom,qfprom diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt deleted file mode 100644 index d6796ef54ea1..000000000000 --- a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt +++ /dev/null @@ -1,43 +0,0 @@ -HiSilicon Hip05 and Hip06 PCIe host bridge DT description - -HiSilicon PCIe host controller is based on the Synopsys DesignWare PCI core. -It shares common functions with the PCIe DesignWare core driver and inherits -common properties defined in -Documentation/devicetree/bindings/pci/designware-pcie.txt. - -Additional properties are described here: - -Required properties -- compatible: Should contain "hisilicon,hip05-pcie" or "hisilicon,hip06-pcie". -- reg: Should contain rc_dbi, config registers location and length. -- reg-names: Must include the following entries: - "rc_dbi": controller configuration registers; - "config": PCIe configuration space registers. -- msi-parent: Should be its_pcie which is an ITS receiving MSI interrupts. -- port-id: Should be 0, 1, 2 or 3. - -Optional properties: -- status: Either "ok" or "disabled". -- dma-coherent: Present if DMA operations are coherent. - -Hip05 Example (note that Hip06 is the same except compatible): - pcie@b0080000 { - compatible = "hisilicon,hip05-pcie", "snps,dw-pcie"; - reg = <0 0xb0080000 0 0x10000>, <0x220 0x00000000 0 0x2000>; - reg-names = "rc_dbi", "config"; - bus-range = <0 15>; - msi-parent = <&its_pcie>; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - dma-coherent; - ranges = <0x82000000 0 0x00000000 0x220 0x00000000 0 0x10000000>; - num-lanes = <8>; - port-id = <1>; - #interrupt-cells = <1>; - interrupt-map-mask = <0xf800 0 0 7>; - interrupt-map = <0x0 0 0 1 &mbigen_pcie 1 10 - 0x0 0 0 2 &mbigen_pcie 2 11 - 0x0 0 0 3 &mbigen_pcie 3 12 - 0x0 0 0 4 &mbigen_pcie 4 13>; - }; diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml new file mode 100644 index 000000000000..e7b1f9892da4 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml @@ -0,0 +1,181 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/mediatek-pcie-gen3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Gen3 PCIe controller on MediaTek SoCs + +maintainers: + - Jianjun Wang <jianjun.wang@mediatek.com> + +description: |+ + PCIe Gen3 MAC controller for MediaTek SoCs, it supports Gen3 speed + and compatible with Gen2, Gen1 speed. + + This PCIe controller supports up to 256 MSI vectors, the MSI hardware + block diagram is as follows: + + +-----+ + | GIC | + +-----+ + ^ + | + port->irq + | + +-+-+-+-+-+-+-+-+ + |0|1|2|3|4|5|6|7| (PCIe intc) + +-+-+-+-+-+-+-+-+ + ^ ^ ^ + | | ... | + +-------+ +------+ +-----------+ + | | | + +-+-+---+--+--+ +-+-+---+--+--+ +-+-+---+--+--+ + |0|1|...|30|31| |0|1|...|30|31| |0|1|...|30|31| (MSI sets) + +-+-+---+--+--+ +-+-+---+--+--+ +-+-+---+--+--+ + ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ + | | | | | | | | | | | | (MSI vectors) + | | | | | | | | | | | | + + (MSI SET0) (MSI SET1) ... (MSI SET7) + + With 256 MSI vectors supported, the MSI vectors are composed of 8 sets, + each set has its own address for MSI message, and supports 32 MSI vectors + to generate interrupt. + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: mediatek,mt8192-pcie + + reg: + maxItems: 1 + + reg-names: + items: + - const: pcie-mac + + interrupts: + maxItems: 1 + + ranges: + minItems: 1 + maxItems: 8 + + resets: + minItems: 1 + maxItems: 2 + + reset-names: + minItems: 1 + maxItems: 2 + items: + - const: phy + - const: mac + + clocks: + maxItems: 6 + + clock-names: + items: + - const: pl_250m + - const: tl_26m + - const: tl_96m + - const: tl_32k + - const: peri_26m + - const: top_133m + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + phys: + maxItems: 1 + + '#interrupt-cells': + const: 1 + + interrupt-controller: + description: Interrupt controller node for handling legacy PCI interrupts. + type: object + properties: + '#address-cells': + const: 0 + '#interrupt-cells': + const: 1 + interrupt-controller: true + + required: + - '#address-cells' + - '#interrupt-cells' + - interrupt-controller + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + - interrupts + - ranges + - clocks + - '#interrupt-cells' + - interrupt-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + pcie: pcie@11230000 { + compatible = "mediatek,mt8192-pcie"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + reg = <0x00 0x11230000 0x00 0x4000>; + reg-names = "pcie-mac"; + interrupts = <GIC_SPI 251 IRQ_TYPE_LEVEL_HIGH 0>; + bus-range = <0x00 0xff>; + ranges = <0x82000000 0x00 0x12000000 0x00 + 0x12000000 0x00 0x1000000>; + clocks = <&infracfg 44>, + <&infracfg 40>, + <&infracfg 43>, + <&infracfg 97>, + <&infracfg 99>, + <&infracfg 111>; + clock-names = "pl_250m", "tl_26m", "tl_96m", + "tl_32k", "peri_26m", "top_133m"; + assigned-clocks = <&topckgen 50>; + assigned-clock-parents = <&topckgen 91>; + + phys = <&pciephy>; + phy-names = "pcie-phy"; + + resets = <&infracfg_rst 2>, + <&infracfg_rst 3>; + reset-names = "phy", "mac"; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0x7>; + interrupt-map = <0 0 0 1 &pcie_intc 0>, + <0 0 0 2 &pcie_intc 1>, + <0 0 0 3 &pcie_intc 2>, + <0 0 0 4 &pcie_intc 3>; + pcie_intc: interrupt-controller { + #address-cells = <0>; + #interrupt-cells = <1>; + interrupt-controller; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/rcar-pci-host.yaml b/Documentation/devicetree/bindings/pci/rcar-pci-host.yaml index 4a2bcc0158e2..8fdfbc763d70 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/rcar-pci-host.yaml @@ -17,6 +17,7 @@ allOf: properties: compatible: oneOf: + - const: renesas,pcie-r8a7779 # R-Car H1 - items: - enum: - renesas,pcie-r8a7742 # RZ/G1H @@ -74,7 +75,16 @@ required: - clocks - clock-names - power-domains - - resets + +if: + not: + properties: + compatible: + contains: + const: renesas,pcie-r8a7779 +then: + required: + - resets unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml new file mode 100644 index 000000000000..b03cbb9b6602 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/sifive,fu740-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SiFive FU740 PCIe host controller + +description: |+ + SiFive FU740 PCIe host controller is based on the Synopsys DesignWare + PCI core. It shares common features with the PCIe DesignWare core and + inherits common properties defined in + Documentation/devicetree/bindings/pci/designware-pcie.txt. + +maintainers: + - Paul Walmsley <paul.walmsley@sifive.com> + - Greentime Hu <greentime.hu@sifive.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: sifive,fu740-pcie + + reg: + maxItems: 3 + + reg-names: + items: + - const: dbi + - const: config + - const: mgmt + + num-lanes: + const: 8 + + msi-parent: true + + interrupt-names: + items: + - const: msi + - const: inta + - const: intb + - const: intc + - const: intd + + resets: + description: A phandle to the PCIe power up reset line. + maxItems: 1 + + pwren-gpios: + description: Should specify the GPIO for controlling the PCI bus device power on. + maxItems: 1 + + reset-gpios: + maxItems: 1 + +required: + - dma-coherent + - num-lanes + - interrupts + - interrupt-names + - interrupt-parent + - interrupt-map-mask + - interrupt-map + - clock-names + - clocks + - resets + - pwren-gpios + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + #include <dt-bindings/clock/sifive-fu740-prci.h> + + pcie@e00000000 { + compatible = "sifive,fu740-pcie"; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + reg = <0xe 0x00000000 0x0 0x80000000>, + <0xd 0xf0000000 0x0 0x10000000>, + <0x0 0x100d0000 0x0 0x1000>; + reg-names = "dbi", "config", "mgmt"; + device_type = "pci"; + dma-coherent; + bus-range = <0x0 0xff>; + ranges = <0x81000000 0x0 0x60080000 0x0 0x60080000 0x0 0x10000>, /* I/O */ + <0x82000000 0x0 0x60090000 0x0 0x60090000 0x0 0xff70000>, /* mem */ + <0x82000000 0x0 0x70000000 0x0 0x70000000 0x0 0x1000000>, /* mem */ + <0xc3000000 0x20 0x00000000 0x20 0x00000000 0x20 0x00000000>; /* mem prefetchable */ + num-lanes = <0x8>; + interrupts = <56>, <57>, <58>, <59>, <60>, <61>, <62>, <63>, <64>; + interrupt-names = "msi", "inta", "intb", "intc", "intd"; + interrupt-parent = <&plic0>; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0x0 0x0 0x0 0x1 &plic0 57>, + <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>; + reset-gpios = <&gpio 8 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/tango-pcie.txt b/Documentation/devicetree/bindings/pci/tango-pcie.txt deleted file mode 100644 index 244683836a79..000000000000 --- a/Documentation/devicetree/bindings/pci/tango-pcie.txt +++ /dev/null @@ -1,29 +0,0 @@ -Sigma Designs Tango PCIe controller - -Required properties: - -- compatible: "sigma,smp8759-pcie" -- reg: address/size of PCI configuration space, address/size of register area -- bus-range: defined by size of PCI configuration space -- device_type: "pci" -- #size-cells: <2> -- #address-cells: <3> -- msi-controller -- ranges: translation from system to bus addresses -- interrupts: spec for misc interrupts, spec for MSI - -Example: - - pcie@2e000 { - compatible = "sigma,smp8759-pcie"; - reg = <0x50000000 0x400000>, <0x2e000 0x100>; - bus-range = <0 3>; - device_type = "pci"; - #size-cells = <2>; - #address-cells = <3>; - msi-controller; - ranges = <0x02000000 0x0 0x00400000 0x50400000 0x0 0x3c00000>; - interrupts = - <54 IRQ_TYPE_LEVEL_HIGH>, /* misc interrupts */ - <55 IRQ_TYPE_LEVEL_HIGH>; /* MSI */ - }; diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml index d06f0c4464c6..aed437dac363 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml @@ -16,12 +16,14 @@ allOf: properties: compatible: oneOf: - - description: PCIe EP controller in J7200 + - const: ti,j721e-pcie-ep + - description: PCIe EP controller in AM64 items: - - const: ti,j7200-pcie-ep + - const: ti,am64-pcie-ep - const: ti,j721e-pcie-ep - - description: PCIe EP controller in J721E + - description: PCIe EP controller in J7200 items: + - const: ti,j7200-pcie-ep - const: ti,j721e-pcie-ep reg: @@ -66,7 +68,6 @@ required: - power-domains - clocks - clock-names - - dma-coherent - max-functions - phys - phy-names diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml index 0880a613ece6..cc900202df29 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml @@ -16,12 +16,14 @@ allOf: properties: compatible: oneOf: - - description: PCIe controller in J7200 + - const: ti,j721e-pcie-host + - description: PCIe controller in AM64 items: - - const: ti,j7200-pcie-host + - const: ti,am64-pcie-host - const: ti,j721e-pcie-host - - description: PCIe controller in J721E + - description: PCIe controller in J7200 items: + - const: ti,j7200-pcie-host - const: ti,j721e-pcie-host reg: @@ -46,12 +48,17 @@ properties: maxItems: 1 clocks: - maxItems: 1 - description: clock-specifier to represent input to the PCIe + minItems: 1 + maxItems: 2 + description: |+ + clock-specifier to represent input to the PCIe for 1 item. + 2nd item if present represents reference clock to the connector. clock-names: + minItems: 1 items: - const: fck + - const: pcie_refclk vendor-id: const: 0x104c @@ -62,6 +69,8 @@ properties: - const: 0xb00d - items: - const: 0xb00f + - items: + - const: 0xb010 msi-map: true @@ -78,7 +87,6 @@ required: - vendor-id - device-id - msi-map - - dma-coherent - dma-ranges - ranges - reset-gpios diff --git a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt index 01bf7fdf4c19..2d677e90a7e2 100644 --- a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt +++ b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt @@ -33,6 +33,8 @@ Required properties: - #address-cells: specifies the number of cells needed to encode an address. The value must be 0. +Optional properties: +- dma-coherent: present if DMA operations are coherent Example: ++++++++ diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt deleted file mode 100644 index a7aee9ea8926..000000000000 --- a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt +++ /dev/null @@ -1,21 +0,0 @@ -Driver for Broadcom Northstar USB 2.0 PHY - -Required properties: -- compatible: brcm,ns-usb2-phy -- reg: iomem address range of DMU (Device Management Unit) -- reg-names: "dmu", the only needed & supported reg right now -- clocks: USB PHY reference clock -- clock-names: "phy-ref-clk", the only needed & supported clock right now - -To initialize USB 2.0 PHY driver needs to setup PLL correctly. To do this it -requires passing phandle to the USB PHY reference clock. - -Example: - usb2-phy { - compatible = "brcm,ns-usb2-phy"; - reg = <0x1800c000 0x1000>; - reg-names = "dmu"; - #phy-cells = <0>; - clocks = <&genpll BCM_NSP_GENPLL_USB_PHY_REF_CLK>; - clock-names = "phy-ref-clk"; - }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml new file mode 100644 index 000000000000..05b4dcd80019 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.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/bcm-ns-usb2-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Northstar USB 2.0 PHY + +description: > + To initialize USB 2.0 PHY driver needs to setup PLL correctly. + To do this it requires passing phandle to the USB PHY reference clock. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + const: brcm,ns-usb2-phy + + reg: + items: + - description: iomem address range of DMU (Device Management Unit) + + reg-names: + items: + - const: dmu + + clocks: + items: + - description: USB PHY reference clock + + clock-names: + items: + - const: phy-ref-clk + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm-nsp.h> + phy@1800c000 { + compatible = "brcm,ns-usb2-phy"; + reg = <0x1800c000 0x1000>; + reg-names = "dmu"; + clocks = <&genpll BCM_NSP_GENPLL_USB_PHY_REF_CLK>; + clock-names = "phy-ref-clk"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt deleted file mode 100644 index 32f057260351..000000000000 --- a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt +++ /dev/null @@ -1,34 +0,0 @@ -Driver for Broadcom Northstar USB 3.0 PHY - -Required properties: - -- compatible: one of: "brcm,ns-ax-usb3-phy", "brcm,ns-bx-usb3-phy". -- reg: address of MDIO bus device -- usb3-dmp-syscon: phandle to syscon with DMP (Device Management Plugin) - registers -- #phy-cells: must be 0 - -Initialization of USB 3.0 PHY depends on Northstar version. There are currently -three known series: Ax, Bx and Cx. -Known A0: BCM4707 rev 0 -Known B0: BCM4707 rev 4, BCM53573 rev 2 -Known B1: BCM4707 rev 6 -Known C0: BCM47094 rev 0 - -Example: - mdio: mdio@0 { - reg = <0x0>; - #size-cells = <1>; - #address-cells = <0>; - - usb3-phy@10 { - compatible = "brcm,ns-ax-usb3-phy"; - reg = <0x10>; - usb3-dmp-syscon = <&usb3_dmp>; - #phy-cells = <0>; - }; - }; - - usb3_dmp: syscon@18105000 { - reg = <0x18105000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml new file mode 100644 index 000000000000..7fd419db45d0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/bcm-ns-usb3-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Northstar USB 3.0 PHY + +description: | + Initialization of USB 3.0 PHY depends on Northstar version. There are currently + three known series: Ax, Bx and Cx. + Known A0: BCM4707 rev 0 + Known B0: BCM4707 rev 4, BCM53573 rev 2 + Known B1: BCM4707 rev 6 + Known C0: BCM47094 rev 0 + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + enum: + - brcm,ns-ax-usb3-phy + - brcm,ns-bx-usb3-phy + + reg: + description: address of MDIO bus device + maxItems: 1 + + usb3-dmp-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the DMP (Device Management Plugin) syscon + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - usb3-dmp-syscon + - "#phy-cells" + +additionalProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + usb3-phy@10 { + compatible = "brcm,ns-ax-usb3-phy"; + reg = <0x10>; + usb3-dmp-syscon = <&usb3_dmp>; + #phy-cells = <0>; + }; + }; + + usb3_dmp: syscon@18105000 { + reg = <0x18105000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml index 0497368d1fca..5f9e91bfb5ff 100644 --- a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml +++ b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml @@ -42,6 +42,9 @@ properties: - const: usb_mdio - const: bdc_ec + power-domains: + maxItems: 1 + clocks: minItems: 1 maxItems: 2 diff --git a/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml new file mode 100644 index 000000000000..2437c3683326 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/marvell,armada-3700-utmi-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Marvell Armada UTMI/UTMI+ PHY + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +description: + On Armada 3700, there are two USB controllers, one is compatible with + the USB2 and USB3 specifications and supports OTG. The other one is USB2 + compliant and only supports host mode. Both of these controllers come with + a slightly different UTMI PHY. + +properties: + compatible: + enum: + - marvell,a3700-utmi-host-phy + - marvell,a3700-utmi-otg-phy + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + marvell,usb-misc-reg: + description: + Phandle on the "USB miscellaneous registers" shared region + covering registers related to both the host controller and + the PHY. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - reg + - "#phy-cells" + - marvell,usb-misc-reg + +additionalProperties: false + +examples: + - | + usb2_utmi_host_phy: phy@5f000 { + compatible = "marvell,armada-3700-utmi-host-phy"; + reg = <0x5f000 0x800>; + marvell,usb-misc-reg = <&usb2_syscon>; + #phy-cells = <0>; + }; + + usb2_syscon: system-controller@5f800 { + compatible = "marvell,armada-3700-usb2-host-misc", "syscon"; + reg = <0x5f800 0x800>; + }; diff --git a/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml new file mode 100644 index 000000000000..30f3b5f32a95 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/marvell,armada-cp110-utmi-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Marvell Armada CP110/CP115 UTMI PHY + +maintainers: + - Konstantin Porotchkin <kostap@marvell.com> + +description: + On Armada 7k/8k and CN913x, there are two host and one device USB controllers. + Each of two exiting UTMI PHYs could be connected to either USB host or USB device + controller. + The USB device controller can only be connected to a single UTMI PHY port + 0.H----- USB HOST0 + UTMI PHY0 --------/ + 0.D-----0 + \------ USB DEVICE + 1.D-----1 + UTMI PHY1 --------\ + 1.H----- USB HOST1 + +properties: + compatible: + const: marvell,cp110-utmi-phy + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + marvell,system-controller: + description: + Phandle to the system controller node + $ref: /schemas/types.yaml#/definitions/phandle + +#Required child nodes: + +patternProperties: + "^usb-phy@[0|1]$": + type: object + description: + Each UTMI PHY port must be represented as a sub-node. + + properties: + reg: + description: phy port index. + maxItems: 1 + + "#phy-cells": + const: 0 + + required: + - reg + - "#phy-cells" + + additionalProperties: false + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - marvell,system-controller + +additionalProperties: false + +examples: + - | + cp0_utmi: utmi@580000 { + compatible = "marvell,cp110-utmi-phy"; + reg = <0x580000 0x2000>; + marvell,system-controller = <&cp0_syscon0>; + #address-cells = <1>; + #size-cells = <0>; + + cp0_utmi0: usb-phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + cp0_utmi1: usb-phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + }; + + cp0_usb3_0 { + usb-phy = <&cp0_usb3_0_phy0>; + phys = <&cp0_utmi0>; + phy-names = "utmi"; + /* UTMI0 is connected to USB host controller (default mode) */ + dr_mode = "host"; + }; + + cp0_usb3_1 { + usb-phy = <&cp0_usb3_0_phy1>; + phys = <&cp0_utmi1>; + phy-names = "utmi"; + /* UTMI1 is connected to USB device controller */ + dr_mode = "peripheral"; + }; diff --git a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml index 71d4acea1f66..6e4d795f9b02 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml @@ -19,11 +19,14 @@ properties: pattern: "^dsi-phy@[0-9a-f]+$" compatible: - enum: - - mediatek,mt2701-mipi-tx - - mediatek,mt7623-mipi-tx - - mediatek,mt8173-mipi-tx - - mediatek,mt8183-mipi-tx + oneOf: + - items: + - enum: + - mediatek,mt7623-mipi-tx + - const: mediatek,mt2701-mipi-tx + - const: mediatek,mt2701-mipi-tx + - const: mediatek,mt8173-mipi-tx + - const: mediatek,mt8183-mipi-tx reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml index 4752517a1446..0d94950b84ca 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml @@ -21,10 +21,13 @@ properties: pattern: "^hdmi-phy@[0-9a-f]+$" compatible: - enum: - - mediatek,mt2701-hdmi-phy - - mediatek,mt7623-hdmi-phy - - mediatek,mt8173-hdmi-phy + oneOf: + - items: + - enum: + - mediatek,mt7623-hdmi-phy + - const: mediatek,mt2701-hdmi-phy + - const: mediatek,mt2701-hdmi-phy + - const: mediatek,mt8173-hdmi-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml index 602e6ff45785..b8a7651a3d9a 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml @@ -79,6 +79,7 @@ properties: - mediatek,mt2712-tphy - mediatek,mt7629-tphy - mediatek,mt8183-tphy + - mediatek,mt8195-tphy - const: mediatek,generic-tphy-v2 - const: mediatek,mt2701-u3phy deprecated: true @@ -117,7 +118,7 @@ properties: # Required child node: patternProperties: - "^usb-phy@[0-9a-f]+$": + "^(usb|pcie|sata)-phy@[0-9a-f]+$": type: object description: A sub-node is required for each port the controller provides. diff --git a/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml index 3a9be82e7f13..74cc32c1d2e8 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml @@ -22,7 +22,12 @@ properties: pattern: "^ufs-phy@[0-9a-f]+$" compatible: - const: mediatek,mt8183-ufsphy + oneOf: + - items: + - enum: + - mediatek,mt8195-ufsphy + - const: mediatek,mt8183-ufsphy + - const: mediatek,mt8183-ufsphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml b/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml new file mode 100644 index 000000000000..bdbdb3bbddbe --- /dev/null +++ b/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/microchip,sparx5-serdes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Sparx5 Serdes controller + +maintainers: + - Steen Hegelund <steen.hegelund@microchip.com> + +description: | + The Sparx5 SERDES interfaces share the same basic functionality, but + support different operating modes and line rates. + + The following list lists the SERDES features: + + * RX Adaptive Decision Feedback Equalizer (DFE) + * Programmable continuous time linear equalizer (CTLE) + * Rx variable gain control + * Rx built-in fault detector (loss-of-lock/loss-of-signal) + * Adjustable tx de-emphasis (FFE) + * Tx output amplitude control + * Supports rx eye monitor + * Multiple loopback modes + * Prbs generator and checker + * Polarity inversion control + + SERDES6G: + + The SERDES6G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 100 Mbps (100BASE-FX) + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + + SERDES10G + + The SERDES10G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 100 Mbps (100BASE-FX) + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5 Gbps (QSGMII/USGMII) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + * 10 Gbps (10G-USGMII) + * 10.3125 Gbps (10GBASE-R/10GBASE-KR/USXGMII) + + SERDES25G + + The SERDES25G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5 Gbps (QSGMII/USGMII) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + * 10 Gbps (10G-USGMII) + * 10.3125 Gbps (10GBASE-R/10GBASE-KR/USXGMII) + * 25.78125 Gbps (25GBASE-KR/25GBASE-CR/25GBASE-SR/25GBASE-LR/25GBASE-ER) + +properties: + $nodename: + pattern: "^serdes@[0-9a-f]+$" + + compatible: + const: microchip,sparx5-serdes + + reg: + minItems: 1 + + '#phy-cells': + const: 1 + description: | + - The main serdes input port + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - '#phy-cells' + - clocks + +additionalProperties: false + +examples: + - | + serdes: serdes@10808000 { + compatible = "microchip,sparx5-serdes"; + #phy-cells = <1>; + clocks = <&sys_clk>; + reg = <0x10808000 0x5d0000>; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt index 38c5fa21f435..b62397d2bb0c 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt @@ -54,6 +54,7 @@ For Tegra210: - avdd-pll-uerefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. - dvdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. - hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 1.8 V. +- nvidia,pmc: phandle and specifier referring to the Tegra210 PMC node. For Tegra186: - avdd-pll-erefeut-supply: UPHY brick and reference clock as well as UTMI PHY diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml index d210843863df..84383e2e0b34 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml @@ -26,6 +26,9 @@ properties: '#size-cells': const: 0 + '#clock-cells': + const: 1 + resets: minItems: 1 maxItems: 2 @@ -49,12 +52,24 @@ properties: const: serdes clocks: - maxItems: 2 + minItems: 2 + maxItems: 4 clock-names: + minItems: 2 items: - const: cmn_refclk_dig_div - const: cmn_refclk1_dig_div + - const: pll0_refclk + - const: pll1_refclk + + assigned-clocks: + minItems: 1 + maxItems: 2 + + assigned-clock-parents: + minItems: 1 + maxItems: 2 cdns,autoconf: type: boolean diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml index e266ade53d87..320a232c7208 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml @@ -28,13 +28,27 @@ properties: '#size-cells': const: 0 + '#clock-cells': + const: 1 + clocks: - maxItems: 1 + minItems: 1 + maxItems: 2 description: - PHY reference clock. Must contain an entry in clock-names. + PHY reference clock for 1 item. Must contain an entry in clock-names. + Optional Parent to enable output reference clock. clock-names: - const: refclk + minItems: 1 + items: + - const: refclk + - const: phy_en_refclk + + assigned-clocks: + maxItems: 3 + + assigned-clock-parents: + maxItems: 3 reg: minItems: 1 @@ -104,7 +118,7 @@ patternProperties: 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-torrent.h for the constants to be used. + 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: 0 @@ -170,7 +184,7 @@ examples: }; - | #include <dt-bindings/phy/phy.h> - #include <dt-bindings/phy/phy-cadence-torrent.h> + #include <dt-bindings/phy/phy-cadence.h> bus { #address-cells = <2>; diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt deleted file mode 100644 index aa99ceec73b0..000000000000 --- a/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt +++ /dev/null @@ -1,38 +0,0 @@ -MVEBU A3700 UTMI PHY --------------------- - -USB2 UTMI+ PHY controllers can be found on the following Marvell MVEBU SoCs: -* Armada 3700 - -On Armada 3700, there are two USB controllers, one is compatible with the USB2 -and USB3 specifications and supports OTG. The other one is USB2 compliant and -only supports host mode. Both of these controllers come with a slightly -different UTMI PHY. - -Required Properties: - -- compatible: Should be one of: - * "marvell,a3700-utmi-host-phy" for the PHY connected to - the USB2 host-only controller. - * "marvell,a3700-utmi-otg-phy" for the PHY connected to - the USB3 and USB2 OTG capable controller. -- reg: PHY IP register range. -- marvell,usb-misc-reg: handle on the "USB miscellaneous registers" shared - region covering registers related to both the host - controller and the PHY. -- #phy-cells: Standard property (Documentation: phy-bindings.txt) Should be 0. - - -Example: - - usb2_utmi_host_phy: phy@5f000 { - compatible = "marvell,armada-3700-utmi-host-phy"; - reg = <0x5f000 0x800>; - marvell,usb-misc-reg = <&usb2_syscon>; - #phy-cells = <0>; - }; - - usb2_syscon: system-controller@5f800 { - compatible = "marvell,armada-3700-usb2-host-misc", "syscon"; - reg = <0x5f800 0x800>; - }; diff --git a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml index 46df6786727a..018cc1246ee1 100644 --- a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml +++ b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml @@ -51,6 +51,10 @@ properties: vdda1v8-supply: description: regulator providing 1V8 power supply to the PLL block + '#clock-cells': + description: number of clock cells for ck_usbo_48m consumer + const: 0 + #Required child nodes: patternProperties: @@ -120,6 +124,7 @@ examples: vdda1v8-supply = <®18>; #address-cells = <1>; #size-cells = <0>; + #clock-cells = <0>; usbphyc_port0: usb-phy@0 { reg = <0>; diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index 626447fee092..7808ec8bc712 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -25,11 +25,13 @@ properties: - qcom,msm8998-qmp-pcie-phy - qcom,msm8998-qmp-ufs-phy - qcom,msm8998-qmp-usb3-phy + - qcom,sc7180-qmp-usb3-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8180x-qmp-usb3-phy - qcom,sdm845-qhp-pcie-phy - qcom,sdm845-qmp-pcie-phy - qcom,sdm845-qmp-ufs-phy + - qcom,sdm845-qmp-usb3-phy - qcom,sdm845-qmp-usb3-uni-phy - qcom,sm8150-qmp-ufs-phy - qcom,sm8150-qmp-usb3-phy diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml index 33974ad10afe..217aa6c91893 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml @@ -14,9 +14,8 @@ properties: compatible: enum: - qcom,sc7180-qmp-usb3-dp-phy - - qcom,sc7180-qmp-usb3-phy - qcom,sdm845-qmp-usb3-dp-phy - - qcom,sdm845-qmp-usb3-phy + - qcom,sm8250-qmp-usb3-dp-phy reg: items: - description: Address and length of PHY's USB serdes block. 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 ee77c6458326..20203a8a9e41 100644 --- a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - qcom,usb-snps-hs-7nm-phy + - qcom,sc7280-usb-hs-phy - qcom,sm8150-usb-hs-phy - qcom,sm8250-usb-hs-phy - qcom,sm8350-usb-hs-phy diff --git a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml index bbbd85501ada..5272b6f284ba 100644 --- a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml +++ b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml @@ -15,6 +15,7 @@ properties: enum: - ti,j721e-wiz-16g - ti,j721e-wiz-10g + - ti,am64-wiz-10g power-domains: maxItems: 1 @@ -42,6 +43,9 @@ properties: "#reset-cells": const: 1 + "#clock-cells": + const: 1 + ranges: true assigned-clocks: @@ -218,7 +222,7 @@ examples: }; serdes@5000000 { - compatible = "cdns,ti,sierra-phy-t0"; + compatible = "ti,sierra-phy-t0"; reg-names = "serdes"; reg = <0x5000000 0x10000>; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml new file mode 100644 index 000000000000..08995a4f854b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-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/brcm,bcm6318-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6318 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM6318 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm6318-pinctrl + + reg: + maxItems: 2 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ ephy0_spd_led, ephy1_spd_led, ephy2_spd_led, ephy3_spd_led, + ephy0_act_led, ephy1_act_led, ephy2_act_led, ephy3_act_led, + serial_led_data, serial_led_clk, inet_act_led, inet_fail_led, + dsl_led, post_fail_led, wlan_wps_led, usb_pwron, + usb_device_led, usb_active ] + + pins: + enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, + gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio40 ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@18 { + compatible = "brcm,bcm6318-pinctrl"; + reg = <0x18 0x10>, <0x54 0x18>; + + pinctrl_ephy0_spd_led: ephy0_spd_led-pins { + function = "ephy0_spd_led"; + pins = "gpio0"; + }; + + pinctrl_ephy1_spd_led: ephy1_spd_led-pins { + function = "ephy1_spd_led"; + pins = "gpio1"; + }; + + pinctrl_ephy2_spd_led: ephy2_spd_led-pins { + function = "ephy2_spd_led"; + pins = "gpio2"; + }; + + pinctrl_ephy3_spd_led: ephy3_spd_led-pins { + function = "ephy3_spd_led"; + pins = "gpio3"; + }; + + pinctrl_ephy0_act_led: ephy0_act_led-pins { + function = "ephy0_act_led"; + pins = "gpio4"; + }; + + pinctrl_ephy1_act_led: ephy1_act_led-pins { + function = "ephy1_act_led"; + pins = "gpio5"; + }; + + pinctrl_ephy2_act_led: ephy2_act_led-pins { + function = "ephy2_act_led"; + pins = "gpio6"; + }; + + pinctrl_ephy3_act_led: ephy3_act_led-pins { + function = "ephy3_act_led"; + pins = "gpio7"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio6"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio7"; + }; + }; + + pinctrl_inet_act_led: inet_act_led-pins { + function = "inet_act_led"; + pins = "gpio8"; + }; + + pinctrl_inet_fail_led: inet_fail_led-pins { + function = "inet_fail_led"; + pins = "gpio9"; + }; + + pinctrl_dsl_led: dsl_led-pins { + function = "dsl_led"; + pins = "gpio10"; + }; + + pinctrl_post_fail_led: post_fail_led-pins { + function = "post_fail_led"; + pins = "gpio11"; + }; + + pinctrl_wlan_wps_led: wlan_wps_led-pins { + function = "wlan_wps_led"; + pins = "gpio12"; + }; + + pinctrl_usb_pwron: usb_pwron-pins { + function = "usb_pwron"; + pins = "gpio13"; + }; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio13"; + }; + + pinctrl_usb_active: usb_active-pins { + function = "usb_active"; + pins = "gpio40"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml new file mode 100644 index 000000000000..58ffed44b3c4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml @@ -0,0 +1,164 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm63268-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM63268 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM63268 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm63268-pinctrl + + reg: + maxItems: 3 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ serial_led_clk, serial_led_data, hsspi_cs4, hsspi_cs5, + hsspi_cs6, hsspi_cs7, adsl_spi_miso, adsl_spi_mosi, + vreq_clk, pcie_clkreq_b, robosw_led_clk, robosw_led_data, + nand, gpio35_alt, dectpd, vdsl_phy_override_0, + vdsl_phy_override_1, vdsl_phy_override_2, + vdsl_phy_override_3, dsl_gpio8, dsl_gpio9 ] + + pins: + enum: [ gpio0, gpio1, gpio16, gpio17, gpio8, gpio9, gpio18, gpio19, + gpio22, gpio23, gpio30, gpio31, nand_grp, gpio35 + dectpd_grp, vdsl_phy_override_0_grp, + vdsl_phy_override_1_grp, vdsl_phy_override_2_grp, + vdsl_phy_override_3_grp, dsl_gpio8, dsl_gpio9 ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@10 { + compatible = "brcm,bcm63268-pinctrl"; + reg = <0x10 0x4>, <0x18 0x8>, <0x38 0x4>; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio0"; + }; + + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio1"; + }; + }; + + pinctrl_hsspi_cs4: hsspi_cs4-pins { + function = "hsspi_cs4"; + pins = "gpio16"; + }; + + pinctrl_hsspi_cs5: hsspi_cs5-pins { + function = "hsspi_cs5"; + pins = "gpio17"; + }; + + pinctrl_hsspi_cs6: hsspi_cs6-pins { + function = "hsspi_cs6"; + pins = "gpio8"; + }; + + pinctrl_hsspi_cs7: hsspi_cs7-pins { + function = "hsspi_cs7"; + pins = "gpio9"; + }; + + pinctrl_adsl_spi: adsl_spi-pins { + pinctrl_adsl_spi_miso: adsl_spi_miso-pins { + function = "adsl_spi_miso"; + pins = "gpio18"; + }; + + pinctrl_adsl_spi_mosi: adsl_spi_mosi-pins { + function = "adsl_spi_mosi"; + pins = "gpio19"; + }; + }; + + pinctrl_vreq_clk: vreq_clk-pins { + function = "vreq_clk"; + pins = "gpio22"; + }; + + pinctrl_pcie_clkreq_b: pcie_clkreq_b-pins { + function = "pcie_clkreq_b"; + pins = "gpio23"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio30"; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio31"; + }; + + pinctrl_nand: nand-pins { + function = "nand"; + group = "nand_grp"; + }; + + pinctrl_gpio35_alt: gpio35_alt-pins { + function = "gpio35_alt"; + pin = "gpio35"; + }; + + pinctrl_dectpd: dectpd-pins { + function = "dectpd"; + group = "dectpd_grp"; + }; + + pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins { + function = "vdsl_phy_override_0"; + group = "vdsl_phy_override_0_grp"; + }; + + pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins { + function = "vdsl_phy_override_1"; + group = "vdsl_phy_override_1_grp"; + }; + + pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins { + function = "vdsl_phy_override_2"; + group = "vdsl_phy_override_2_grp"; + }; + + pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins { + function = "vdsl_phy_override_3"; + group = "vdsl_phy_override_3_grp"; + }; + + pinctrl_dsl_gpio8: dsl_gpio8-pins { + function = "dsl_gpio8"; + group = "dsl_gpio8"; + }; + + pinctrl_dsl_gpio9: dsl_gpio9-pins { + function = "dsl_gpio9"; + group = "dsl_gpio9"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml new file mode 100644 index 000000000000..0fd24f40afb1 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm6328-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6328 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM6328 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm6328-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ serial_led_data, serial_led_clk, inet_act_led, pcie_clkreq, + led, ephy0_act_led, ephy1_act_led, ephy2_act_led, + ephy3_act_led, hsspi_cs1, usb_device_port, usb_host_port ] + + pins: + enum: [ gpio6, gpio7, gpio11, gpio16, gpio17, gpio18, gpio19, + gpio20, gpio25, gpio26, gpio27, gpio28, hsspi_cs1, + usb_port1 ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@18 { + compatible = "brcm,bcm6328-pinctrl"; + reg = <0x18 0x10>; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio6"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio7"; + }; + }; + + pinctrl_inet_act_led: inet_act_led-pins { + function = "inet_act_led"; + pins = "gpio11"; + }; + + pinctrl_pcie_clkreq: pcie_clkreq-pins { + function = "pcie_clkreq"; + pins = "gpio16"; + }; + + pinctrl_ephy0_spd_led: ephy0_spd_led-pins { + function = "led"; + pins = "gpio17"; + }; + + pinctrl_ephy1_spd_led: ephy1_spd_led-pins { + function = "led"; + pins = "gpio18"; + }; + + pinctrl_ephy2_spd_led: ephy2_spd_led-pins { + function = "led"; + pins = "gpio19"; + }; + + pinctrl_ephy3_spd_led: ephy3_spd_led-pins { + function = "led"; + pins = "gpio20"; + }; + + pinctrl_ephy0_act_led: ephy0_act_led-pins { + function = "ephy0_act_led"; + pins = "gpio25"; + }; + + pinctrl_ephy1_act_led: ephy1_act_led-pins { + function = "ephy1_act_led"; + pins = "gpio26"; + }; + + pinctrl_ephy2_act_led: ephy2_act_led-pins { + function = "ephy2_act_led"; + pins = "gpio27"; + }; + + pinctrl_ephy3_act_led: ephy3_act_led-pins { + function = "ephy3_act_led"; + pins = "gpio28"; + }; + + pinctrl_hsspi_cs1: hsspi_cs1-pins { + function = "hsspi_cs1"; + pins = "hsspi_cs1"; + }; + + pinctrl_usb_port1_device: usb_port1_device-pins { + function = "usb_device_port"; + pins = "usb_port1"; + }; + + pinctrl_usb_port1_host: usb_port1_host-pins { + function = "usb_host_port"; + pins = "usb_port1"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml new file mode 100644 index 000000000000..0c3ce256aa78 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm6358-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6358 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM6358 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm6358-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ ebi_cs, uart1, serial_led, legacy_led, led, spi_cs, utopia, + pwm_syn_clk, sys_irq ] + + pins: + 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 ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@18 { + compatible = "brcm,bcm6358-pinctrl"; + reg = <0x18 0x4>; + + pinctrl_ebi_cs: ebi_cs-pins { + function = "ebi_cs"; + groups = "ebi_cs_grp"; + }; + + pinctrl_uart1: uart1-pins { + function = "uart1"; + groups = "uart1_grp"; + }; + + pinctrl_serial_led: serial_led-pins { + function = "serial_led"; + groups = "serial_led_grp"; + }; + + pinctrl_legacy_led: legacy_led-pins { + function = "legacy_led"; + groups = "legacy_led_grp"; + }; + + pinctrl_led: led-pins { + function = "led"; + groups = "led_grp"; + }; + + pinctrl_spi_cs_23: spi_cs-pins { + function = "spi_cs"; + groups = "spi_cs_grp"; + }; + + pinctrl_utopia: utopia-pins { + function = "utopia"; + groups = "utopia_grp"; + }; + + pinctrl_pwm_syn_clk: pwm_syn_clk-pins { + function = "pwm_syn_clk"; + groups = "pwm_syn_clk_grp"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + groups = "sys_irq_grp"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml new file mode 100644 index 000000000000..6f68fee373bd --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml @@ -0,0 +1,206 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm6362-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6362 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM6362 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm6362-pinctrl + + reg: + maxItems: 2 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ usb_device_led, sys_irq, serial_led_clk, serial_led_data, + robosw_led_data, robosw_led_clk, robosw_led0, robosw_led1, + inet_led, spi_cs2, spi_cs3, ntr_pulse, uart1_scts, + uart1_srts, uart1_sdin, uart1_sdout, adsl_spi_miso, + adsl_spi_mosi, adsl_spi_clk, adsl_spi_cs, ephy0_led, + ephy1_led, ephy2_led, ephy3_led, ext_irq0, ext_irq1, + ext_irq2, ext_irq3, nand ] + + pins: + enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, + gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio14, + gpio15, gpio16, gpio17, gpio18, gpio19, gpio20, gpio21, + gpio22, gpio23, gpio24, gpio25, gpio26, gpio27, nand_grp ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@18 { + compatible = "brcm,bcm6362-pinctrl"; + reg = <0x18 0x10>, <0x38 0x4>; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio0"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + pins = "gpio1"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio2"; + }; + + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio3"; + }; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio4"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio5"; + }; + + pinctrl_robosw_led0: robosw_led0-pins { + function = "robosw_led0"; + pins = "gpio6"; + }; + + pinctrl_robosw_led1: robosw_led1-pins { + function = "robosw_led1"; + pins = "gpio7"; + }; + + pinctrl_inet_led: inet_led-pins { + function = "inet_led"; + pins = "gpio8"; + }; + + pinctrl_spi_cs2: spi_cs2-pins { + function = "spi_cs2"; + pins = "gpio9"; + }; + + pinctrl_spi_cs3: spi_cs3-pins { + function = "spi_cs3"; + pins = "gpio10"; + }; + + pinctrl_ntr_pulse: ntr_pulse-pins { + function = "ntr_pulse"; + pins = "gpio11"; + }; + + pinctrl_uart1_scts: uart1_scts-pins { + function = "uart1_scts"; + pins = "gpio12"; + }; + + pinctrl_uart1_srts: uart1_srts-pins { + function = "uart1_srts"; + pins = "gpio13"; + }; + + pinctrl_uart1: uart1-pins { + pinctrl_uart1_sdin: uart1_sdin-pins { + function = "uart1_sdin"; + pins = "gpio14"; + }; + + pinctrl_uart1_sdout: uart1_sdout-pins { + function = "uart1_sdout"; + pins = "gpio15"; + }; + }; + + pinctrl_adsl_spi: adsl_spi-pins { + pinctrl_adsl_spi_miso: adsl_spi_miso-pins { + function = "adsl_spi_miso"; + pins = "gpio16"; + }; + + pinctrl_adsl_spi_mosi: adsl_spi_mosi-pins { + function = "adsl_spi_mosi"; + pins = "gpio17"; + }; + + pinctrl_adsl_spi_clk: adsl_spi_clk-pins { + function = "adsl_spi_clk"; + pins = "gpio18"; + }; + + pinctrl_adsl_spi_cs: adsl_spi_cs-pins { + function = "adsl_spi_cs"; + pins = "gpio19"; + }; + }; + + pinctrl_ephy0_led: ephy0_led-pins { + function = "ephy0_led"; + pins = "gpio20"; + }; + + pinctrl_ephy1_led: ephy1_led-pins { + function = "ephy1_led"; + pins = "gpio21"; + }; + + pinctrl_ephy2_led: ephy2_led-pins { + function = "ephy2_led"; + pins = "gpio22"; + }; + + pinctrl_ephy3_led: ephy3_led-pins { + function = "ephy3_led"; + pins = "gpio23"; + }; + + pinctrl_ext_irq0: ext_irq0-pins { + function = "ext_irq0"; + pins = "gpio24"; + }; + + pinctrl_ext_irq1: ext_irq1-pins { + function = "ext_irq1"; + pins = "gpio25"; + }; + + pinctrl_ext_irq2: ext_irq2-pins { + function = "ext_irq2"; + pins = "gpio26"; + }; + + pinctrl_ext_irq3: ext_irq3-pins { + function = "ext_irq3"; + pins = "gpio27"; + }; + + pinctrl_nand: nand-pins { + function = "nand"; + group = "nand_grp"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml new file mode 100644 index 000000000000..f4168b9f4460 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml @@ -0,0 +1,217 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm6368-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6368 pin controller + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: + Bindings for Broadcom's BCM6368 memory-mapped pin controller. + +properties: + compatible: + const: brcm,bcm6368-pinctrl + + reg: + maxItems: 2 + +patternProperties: + '-pins$': + type: object + $ref: pinmux-node.yaml# + + properties: + function: + enum: [ analog_afe_0, analog_afe_1, sys_irq, serial_led_data, + serial_led_clk, inet_led, ephy0_led, ephy1_led, ephy2_led, + ephy3_led, robosw_led_data, robosw_led_clk, robosw_led0, + robosw_led1, usb_device_led, pci_req1, pci_gnt1, pci_intb, + pci_req0, pci_gnt0, pcmcia_cd1, pcmcia_cd2, pcmcia_vs1, + pcmcia_vs2, ebi_cs2, ebi_cs3, spi_cs2, spi_cs3, spi_cs4, + spi_cs5, uart1 ] + + pins: + enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, + gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio14, + gpio16, gpio17, gpio18, gpio19, gpio20, gpio22, gpio23, + gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, + gpio31, uart1_grp ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@18 { + compatible = "brcm,bcm6368-pinctrl"; + reg = <0x18 0x4>, <0x38 0x4>; + + pinctrl_analog_afe_0: analog_afe_0-pins { + function = "analog_afe_0"; + pins = "gpio0"; + }; + + pinctrl_analog_afe_1: analog_afe_1-pins { + function = "analog_afe_1"; + pins = "gpio1"; + }; + + pinctrl_sys_irq: sys_irq-pins { + function = "sys_irq"; + pins = "gpio2"; + }; + + pinctrl_serial_led: serial_led-pins { + pinctrl_serial_led_data: serial_led_data-pins { + function = "serial_led_data"; + pins = "gpio3"; + }; + + pinctrl_serial_led_clk: serial_led_clk-pins { + function = "serial_led_clk"; + pins = "gpio4"; + }; + }; + + pinctrl_inet_led: inet_led-pins { + function = "inet_led"; + pins = "gpio5"; + }; + + pinctrl_ephy0_led: ephy0_led-pins { + function = "ephy0_led"; + pins = "gpio6"; + }; + + pinctrl_ephy1_led: ephy1_led-pins { + function = "ephy1_led"; + pins = "gpio7"; + }; + + pinctrl_ephy2_led: ephy2_led-pins { + function = "ephy2_led"; + pins = "gpio8"; + }; + + pinctrl_ephy3_led: ephy3_led-pins { + function = "ephy3_led"; + pins = "gpio9"; + }; + + pinctrl_robosw_led_data: robosw_led_data-pins { + function = "robosw_led_data"; + pins = "gpio10"; + }; + + pinctrl_robosw_led_clk: robosw_led_clk-pins { + function = "robosw_led_clk"; + pins = "gpio11"; + }; + + pinctrl_robosw_led0: robosw_led0-pins { + function = "robosw_led0"; + pins = "gpio12"; + }; + + pinctrl_robosw_led1: robosw_led1-pins { + function = "robosw_led1"; + pins = "gpio13"; + }; + + pinctrl_usb_device_led: usb_device_led-pins { + function = "usb_device_led"; + pins = "gpio14"; + }; + + pinctrl_pci: pci-pins { + pinctrl_pci_req1: pci_req1-pins { + function = "pci_req1"; + pins = "gpio16"; + }; + + pinctrl_pci_gnt1: pci_gnt1-pins { + function = "pci_gnt1"; + pins = "gpio17"; + }; + + pinctrl_pci_intb: pci_intb-pins { + function = "pci_intb"; + pins = "gpio18"; + }; + + pinctrl_pci_req0: pci_req0-pins { + function = "pci_req0"; + pins = "gpio19"; + }; + + pinctrl_pci_gnt0: pci_gnt0-pins { + function = "pci_gnt0"; + pins = "gpio20"; + }; + }; + + pinctrl_pcmcia: pcmcia-pins { + pinctrl_pcmcia_cd1: pcmcia_cd1-pins { + function = "pcmcia_cd1"; + pins = "gpio22"; + }; + + pinctrl_pcmcia_cd2: pcmcia_cd2-pins { + function = "pcmcia_cd2"; + pins = "gpio23"; + }; + + pinctrl_pcmcia_vs1: pcmcia_vs1-pins { + function = "pcmcia_vs1"; + pins = "gpio24"; + }; + + pinctrl_pcmcia_vs2: pcmcia_vs2-pins { + function = "pcmcia_vs2"; + pins = "gpio25"; + }; + }; + + pinctrl_ebi_cs2: ebi_cs2-pins { + function = "ebi_cs2"; + pins = "gpio26"; + }; + + pinctrl_ebi_cs3: ebi_cs3-pins { + function = "ebi_cs3"; + pins = "gpio27"; + }; + + pinctrl_spi_cs2: spi_cs2-pins { + function = "spi_cs2"; + pins = "gpio28"; + }; + + pinctrl_spi_cs3: spi_cs3-pins { + function = "spi_cs3"; + pins = "gpio29"; + }; + + pinctrl_spi_cs4: spi_cs4-pins { + function = "spi_cs4"; + pins = "gpio30"; + }; + + pinctrl_spi_cs5: spi_cs5-pins { + function = "spi_cs5"; + pins = "gpio31"; + }; + + pinctrl_uart1: uart1-pins { + function = "uart1"; + group = "uart1_grp"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml index 44c04d11ae4c..a4846d78111c 100644 --- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml @@ -17,10 +17,12 @@ description: > naming scheme "PxN" where x is a character identifying the GPIO port with which the pin is associated and N is an integer from 0 to 31 identifying the pin within that GPIO port. For example PA0 is the first pin in GPIO port A, - and PB31 is the last pin in GPIO port B. The JZ4740, the X1000 and the X1830 - contains 4 GPIO ports, PA to PD, for a total of 128 pins. The JZ4760, the - JZ4770 and the JZ4780 contains 6 GPIO ports, PA to PF, for a total of 192 - pins. + and PB31 is the last pin in GPIO port B. The JZ4730, the JZ4740, the JZ4725B, + the X1000 and the X1830 contains 4 GPIO ports, PA to PD, for a total of 128 + pins. The X2000 contains 5 GPIO ports, PA to PE, for a total of 160 pins. + The JZ4750, the JZ4755 the JZ4760, the JZ4770 and the JZ4780 contains 6 GPIO + ports, PA to PF, for a total of 192 pins. The JZ4775 contains 7 GPIO ports, + PA to PG, for a total of 224 pins. maintainers: - Paul Cercueil <paul@crapouillou.net> @@ -32,20 +34,28 @@ properties: compatible: oneOf: - enum: + - ingenic,jz4730-pinctrl - ingenic,jz4740-pinctrl - ingenic,jz4725b-pinctrl + - ingenic,jz4750-pinctrl + - ingenic,jz4755-pinctrl - ingenic,jz4760-pinctrl - ingenic,jz4770-pinctrl + - ingenic,jz4775-pinctrl - ingenic,jz4780-pinctrl - ingenic,x1000-pinctrl - ingenic,x1500-pinctrl - ingenic,x1830-pinctrl + - ingenic,x2000-pinctrl - items: - const: ingenic,jz4760b-pinctrl - const: ingenic,jz4760-pinctrl - items: - const: ingenic,x1000e-pinctrl - const: ingenic,x1000-pinctrl + - items: + - const: ingenic,x2000e-pinctrl + - const: ingenic,x2000-pinctrl reg: maxItems: 1 @@ -62,14 +72,19 @@ patternProperties: properties: compatible: enum: + - ingenic,jz4730-gpio - ingenic,jz4740-gpio - ingenic,jz4725b-gpio + - ingenic,jz4750-gpio + - ingenic,jz4755-gpio - ingenic,jz4760-gpio - ingenic,jz4770-gpio + - ingenic,jz4775-gpio - ingenic,jz4780-gpio - ingenic,x1000-gpio - ingenic,x1500-gpio - ingenic,x1830-gpio + - ingenic,x2000-gpio reg: items: diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml new file mode 100644 index 000000000000..2f12ec59eee5 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8195.yaml @@ -0,0 +1,151 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/pinctrl-mt8195.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT8195 Pin Controller + +maintainers: + - Sean Wang <sean.wang@mediatek.com> + +description: | + The Mediatek's Pin controller is used to control SoC pins. + +properties: + compatible: + const: mediatek,mt8195-pinctrl + + gpio-controller: true + + '#gpio-cells': + description: | + Number of cells in GPIO specifier. Since the generic GPIO binding is used, + the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + const: 2 + + gpio-ranges: + description: gpio valid number range. + maxItems: 1 + + reg: + description: | + Physical address base for gpio base registers. There are 8 GPIO + physical address base in mt8195. + maxItems: 8 + + reg-names: + description: | + Gpio base register names. + maxItems: 8 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + interrupts: + description: The interrupt outputs to sysirq. + maxItems: 1 + +#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: + description: | + It can support some arguments which is from 0 to 7. It can only support + 2/4/6/8/10/12/14/16mA in mt8195. + enum: [0, 1, 2, 3, 4, 5, 6, 7] + + bias-pull-down: true + + bias-pull-up: true + + 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 + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + - gpio-ranges + +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; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt index 7648ab00f4e2..f6a9760558a6 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -27,8 +27,15 @@ PMIC's from Qualcomm. "qcom,pm660l-gpio" "qcom,pm8150-gpio" "qcom,pm8150b-gpio" + "qcom,pm8350-gpio" + "qcom,pm8350b-gpio" + "qcom,pm8350c-gpio" + "qcom,pmk8350-gpio" + "qcom,pmr735a-gpio" + "qcom,pmr735b-gpio" "qcom,pm6150-gpio" "qcom,pm6150l-gpio" + "qcom,pm8008-gpio" "qcom,pmx55-gpio" And must contain either "qcom,spmi-gpio" or "qcom,ssbi-gpio" @@ -109,8 +116,15 @@ to specify in a pin configuration subnode: and gpio8) gpio1-gpio12 for pm8150b (holes on gpio3, gpio4, gpio7) gpio1-gpio12 for pm8150l (hole on gpio7) + gpio1-gpio10 for pm8350 + gpio1-gpio8 for pm8350b + gpio1-gpio9 for pm8350c + gpio1-gpio4 for pmk8350 + gpio1-gpio4 for pmr735a + gpio1-gpio4 for pmr735b gpio1-gpio10 for pm6150 gpio1-gpio12 for pm6150l + gpio1-gpio2 for pm8008 gpio1-gpio11 for pmx55 (holes on gpio3, gpio7, gpio10 and gpio11) diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index d3eae61a340d..84c4111293bd 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -33,6 +33,7 @@ Required properties for iomux controller: "rockchip,rk3328-pinctrl": for Rockchip RK3328 "rockchip,rk3368-pinctrl": for Rockchip RK3368 "rockchip,rk3399-pinctrl": for Rockchip RK3399 + "rockchip,rk3568-pinctrl": for Rockchip RK3568 - rockchip,grf: phandle referencing a syscon providing the "general register files" @@ -50,23 +51,7 @@ Deprecated properties for iomux controller: Use rockchip,grf and rockchip,pmu described above instead. Required properties for gpio sub nodes: - - compatible: "rockchip,gpio-bank" - - reg: register of the gpio bank (different than the iomux registerset) - - interrupts: base interrupt of the gpio bank in the interrupt controller - - clocks: clock that drives this bank - - gpio-controller: identifies the node as a gpio controller and pin bank. - - #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO - binding is used, the amount of cells must be specified as 2. See generic - GPIO binding documentation for description of particular cells. - - interrupt-controller: identifies the controller node as interrupt-parent. - - #interrupt-cells: the value of this property should be 2 and the interrupt - cells should use the standard two-cell scheme described in - bindings/interrupt-controller/interrupts.txt - -Deprecated properties for gpio sub nodes: - - compatible: "rockchip,rk3188-gpio-bank0" - - reg: second element: separate pull register for rk3188 bank0, use - rockchip,pmu described above instead +See rockchip,gpio-bank.yaml Required properties for pin configuration node: - rockchip,pins: 3 integers array, represents a group of pins mux and config @@ -127,43 +112,3 @@ uart2: serial@20064000 { pinctrl-names = "default"; pinctrl-0 = <&uart2_xfer>; }; - -Example for rk3188: - - pinctrl@20008000 { - compatible = "rockchip,rk3188-pinctrl"; - rockchip,grf = <&grf>; - rockchip,pmu = <&pmu>; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - gpio0: gpio0@2000a000 { - compatible = "rockchip,rk3188-gpio-bank0"; - reg = <0x2000a000 0x100>; - interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clk_gates8 9>; - - gpio-controller; - #gpio-cells = <2>; - - interrupt-controller; - #interrupt-cells = <2>; - }; - - gpio1: gpio1@2003c000 { - compatible = "rockchip,gpio-bank"; - reg = <0x2003c000 0x100>; - interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clk_gates8 10>; - - gpio-controller; - #gpio-cells = <2>; - - interrupt-controller; - #interrupt-cells = <2>; - }; - - ... - - }; diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml new file mode 100644 index 000000000000..8ef0d07d35fe --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml @@ -0,0 +1,336 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/xlnx,zynqmp-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx ZynqMP Pinctrl + +maintainers: + - Sai Krishna Potthuri <lakshmi.sai.krishna.potthuri@xilinx.com> + - Rajan Vaja <rajan.vaja@xilinx.com> + +description: | + Please refer to pinctrl-bindings.txt in this directory for details of the + common pinctrl bindings used by client devices, including the meaning of the + phrase "pin configuration node". + + ZynqMP's pin configuration nodes act as a container for an arbitrary number of + subnodes. Each of these subnodes represents some desired configuration for a + pin, a group, or a list of pins or groups. This configuration can include the + mux function to select on those pin(s)/group(s), and various pin configuration + parameters, such as pull-up, slew rate, etc. + + Each configuration node can consist of multiple nodes describing the pinmux and + pinconf options. Those nodes can be pinmux nodes or pinconf nodes. + + The name of each subnode is not important; all subnodes should be enumerated + and processed purely based on their content. + +properties: + compatible: + const: xlnx,zynqmp-pinctrl + +patternProperties: + '^(.*-)?(default|gpio)$': + type: object + patternProperties: + '^mux': + type: object + description: + Pinctrl node's client devices use subnodes for pin muxes, + which in turn use below standard properties. + $ref: pinmux-node.yaml# + + properties: + groups: + description: + List of groups to select (either this or "pins" must be + specified), available groups for this subnode. + items: + enum: [ethernet0_0_grp, ethernet1_0_grp, ethernet2_0_grp, + ethernet3_0_grp, gemtsu0_0_grp, gemtsu0_1_grp, + gemtsu0_2_grp, mdio0_0_grp, mdio1_0_grp, + mdio1_1_grp, mdio2_0_grp, mdio3_0_grp, + qspi0_0_grp, qspi_ss_0_grp, qspi_fbclk_0_grp, + spi0_0_grp, spi0_ss_0_grp, spi0_ss_1_grp, + spi0_ss_2_grp, spi0_1_grp, spi0_ss_3_grp, + spi0_ss_4_grp, spi0_ss_5_grp, spi0_2_grp, + spi0_ss_6_grp, spi0_ss_7_grp, spi0_ss_8_grp, + spi0_3_grp, spi0_ss_9_grp, spi0_ss_10_grp, + spi0_ss_11_grp, spi0_4_grp, spi0_ss_12_grp, + spi0_ss_13_grp, spi0_ss_14_grp, spi0_5_grp, + spi0_ss_15_grp, spi0_ss_16_grp, spi0_ss_17_grp, + spi1_0_grp, spi1_ss_0_grp, spi1_ss_1_grp, + spi1_ss_2_grp, spi1_1_grp, spi1_ss_3_grp, + spi1_ss_4_grp, spi1_ss_5_grp, spi1_2_grp, + spi1_ss_6_grp, spi1_ss_7_grp, spi1_ss_8_grp, + spi1_3_grp, spi1_ss_9_grp, spi1_ss_10_grp, + spi1_ss_11_grp, spi1_4_grp, spi1_ss_12_grp, + spi1_ss_13_grp, spi1_ss_14_grp, spi1_5_grp, + spi1_ss_15_grp, spi1_ss_16_grp, spi1_ss_17_grp, + sdio0_0_grp, sdio0_1_grp, sdio0_2_grp, + sdio0_3_grp, sdio0_4_grp, sdio0_5_grp, + sdio0_6_grp, sdio0_7_grp, sdio0_8_grp, + sdio0_9_grp, sdio0_10_grp, sdio0_11_grp, + sdio0_12_grp, sdio0_13_grp, sdio0_14_grp, + sdio0_15_grp, sdio0_16_grp, sdio0_17_grp, + sdio0_18_grp, sdio0_19_grp, sdio0_20_grp, + sdio0_21_grp, sdio0_22_grp, sdio0_23_grp, + sdio0_24_grp, sdio0_25_grp, sdio0_26_grp, + sdio0_27_grp, sdio0_28_grp, sdio0_29_grp, + sdio0_30_grp, sdio0_31_grp, sdio0_32_grp, + sdio0_pc_0_grp, sdio0_cd_0_grp, sdio0_wp_0_grp, + sdio0_pc_1_grp, sdio0_cd_1_grp, sdio0_wp_1_grp, + sdio0_pc_2_grp, sdio0_cd_2_grp, sdio0_wp_2_grp, + sdio1_0_grp, sdio1_1_grp, sdio1_2_grp, + sdio1_3_grp, sdio1_4_grp, sdio1_5_grp, + sdio1_6_grp, sdio1_7_grp, sdio1_8_grp, + sdio1_9_grp, sdio1_10_grp, sdio1_11_grp, + sdio1_12_grp, sdio1_13_grp, sdio1_14_grp, + sdio1_15_grp, sdio1_pc_0_grp, sdio1_cd_0_grp, + sdio1_wp_0_grp, sdio1_pc_1_grp, sdio1_cd_1_grp, + sdio1_wp_1_grp, nand0_0_grp, nand0_ce_0_grp, + nand0_rb_0_grp, nand0_dqs_0_grp, nand0_ce_1_grp, + nand0_rb_1_grp, nand0_dqs_1_grp, can0_0_grp, + can0_1_grp, can0_2_grp, can0_3_grp, + can0_4_grp, can0_5_grp, can0_6_grp, + can0_7_grp, can0_8_grp, can0_9_grp, + can0_10_grp, can0_11_grp, can0_12_grp, + can0_13_grp, can0_14_grp, can0_15_grp, + can0_16_grp, can0_17_grp, can0_18_grp, + can1_0_grp, can1_1_grp, can1_2_grp, + can1_3_grp, can1_4_grp, can1_5_grp, + can1_6_grp, can1_7_grp, can1_8_grp, + can1_9_grp, can1_10_grp, can1_11_grp, + can1_12_grp, can1_13_grp, can1_14_grp, + can1_15_grp, can1_16_grp, can1_17_grp, + can1_18_grp, can1_19_grp, uart0_0_grp, + uart0_1_grp, uart0_2_grp, uart0_3_grp, + uart0_4_grp, uart0_5_grp, uart0_6_grp, + uart0_7_grp, uart0_8_grp, uart0_9_grp, + uart0_10_grp, uart0_11_grp, uart0_12_grp, + uart0_13_grp, uart0_14_grp, uart0_15_grp, + uart0_16_grp, uart0_17_grp, uart0_18_grp, + uart1_0_grp, uart1_1_grp, uart1_2_grp, + uart1_3_grp, uart1_4_grp, uart1_5_grp, + uart1_6_grp, uart1_7_grp, uart1_8_grp, + uart1_9_grp, uart1_10_grp, uart1_11_grp, + uart1_12_grp, uart1_13_grp, uart1_14_grp, + uart1_15_grp, uart1_16_grp, uart1_17_grp, + uart1_18_grp, i2c0_0_grp, i2c0_1_grp, + i2c0_2_grp, i2c0_3_grp, i2c0_4_grp, + i2c0_5_grp, i2c0_6_grp, i2c0_7_grp, + i2c0_8_grp, i2c0_9_grp, i2c0_10_grp, + i2c0_11_grp, i2c0_12_grp, i2c0_13_grp, + i2c0_14_grp, i2c0_15_grp, i2c0_16_grp, + i2c0_17_grp, i2c0_18_grp, i2c1_0_grp, + i2c1_1_grp, i2c1_2_grp, i2c1_3_grp, + i2c1_4_grp, i2c1_5_grp, i2c1_6_grp, + i2c1_7_grp, i2c1_8_grp, i2c1_9_grp, + i2c1_10_grp, i2c1_11_grp, i2c1_12_grp, + i2c1_13_grp, i2c1_14_grp, i2c1_15_grp, + i2c1_16_grp, i2c1_17_grp, i2c1_18_grp, + i2c1_19_grp, ttc0_clk_0_grp, ttc0_wav_0_grp, + ttc0_clk_1_grp, ttc0_wav_1_grp, ttc0_clk_2_grp, + ttc0_wav_2_grp, ttc0_clk_3_grp, ttc0_wav_3_grp, + ttc0_clk_4_grp, ttc0_wav_4_grp, ttc0_clk_5_grp, + ttc0_wav_5_grp, ttc0_clk_6_grp, ttc0_wav_6_grp, + ttc0_clk_7_grp, ttc0_wav_7_grp, ttc0_clk_8_grp, + ttc0_wav_8_grp, ttc1_clk_0_grp, ttc1_wav_0_grp, + ttc1_clk_1_grp, ttc1_wav_1_grp, ttc1_clk_2_grp, + ttc1_wav_2_grp, ttc1_clk_3_grp, ttc1_wav_3_grp, + ttc1_clk_4_grp, ttc1_wav_4_grp, ttc1_clk_5_grp, + ttc1_wav_5_grp, ttc1_clk_6_grp, ttc1_wav_6_grp, + ttc1_clk_7_grp, ttc1_wav_7_grp, ttc1_clk_8_grp, + ttc1_wav_8_grp, ttc2_clk_0_grp, ttc2_wav_0_grp, + ttc2_clk_1_grp, ttc2_wav_1_grp, ttc2_clk_2_grp, + ttc2_wav_2_grp, ttc2_clk_3_grp, ttc2_wav_3_grp, + ttc2_clk_4_grp, ttc2_wav_4_grp, ttc2_clk_5_grp, + ttc2_wav_5_grp, ttc2_clk_6_grp, ttc2_wav_6_grp, + ttc2_clk_7_grp, ttc2_wav_7_grp, ttc2_clk_8_grp, + ttc2_wav_8_grp, ttc3_clk_0_grp, ttc3_wav_0_grp, + ttc3_clk_1_grp, ttc3_wav_1_grp, ttc3_clk_2_grp, + ttc3_wav_2_grp, ttc3_clk_3_grp, ttc3_wav_3_grp, + ttc3_clk_4_grp, ttc3_wav_4_grp, ttc3_clk_5_grp, + ttc3_wav_5_grp, ttc3_clk_6_grp, ttc3_wav_6_grp, + ttc3_clk_7_grp, ttc3_wav_7_grp, ttc3_clk_8_grp, + ttc3_wav_8_grp, swdt0_clk_0_grp, swdt0_rst_0_grp, + swdt0_clk_1_grp, swdt0_rst_1_grp, swdt0_clk_2_grp, + swdt0_rst_2_grp, swdt0_clk_3_grp, swdt0_rst_3_grp, + swdt0_clk_4_grp, swdt0_rst_4_grp, swdt0_clk_5_grp, + swdt0_rst_5_grp, swdt0_clk_6_grp, swdt0_rst_6_grp, + swdt0_clk_7_grp, swdt0_rst_7_grp, swdt0_clk_8_grp, + swdt0_rst_8_grp, swdt0_clk_9_grp, swdt0_rst_9_grp, + swdt0_clk_10_grp, swdt0_rst_10_grp, swdt0_clk_11_grp, + swdt0_rst_11_grp, swdt0_clk_12_grp, swdt0_rst_12_grp, + swdt1_clk_0_grp, swdt1_rst_0_grp, swdt1_clk_1_grp, + swdt1_rst_1_grp, swdt1_clk_2_grp, swdt1_rst_2_grp, + swdt1_clk_3_grp, swdt1_rst_3_grp, swdt1_clk_4_grp, + swdt1_rst_4_grp, swdt1_clk_5_grp, swdt1_rst_5_grp, + swdt1_clk_6_grp, swdt1_rst_6_grp, swdt1_clk_7_grp, + swdt1_rst_7_grp, swdt1_clk_8_grp, swdt1_rst_8_grp, + swdt1_clk_9_grp, swdt1_rst_9_grp, swdt1_clk_10_grp, + swdt1_rst_10_grp, swdt1_clk_11_grp, swdt1_rst_11_grp, + swdt1_clk_12_grp, swdt1_rst_12_grp, gpio0_0_grp, + gpio0_1_grp, gpio0_2_grp, gpio0_3_grp, + gpio0_4_grp, gpio0_5_grp, gpio0_6_grp, + gpio0_7_grp, gpio0_8_grp, gpio0_9_grp, + gpio0_10_grp, gpio0_11_grp, gpio0_12_grp, + gpio0_13_grp, gpio0_14_grp, gpio0_15_grp, + gpio0_16_grp, gpio0_17_grp, gpio0_18_grp, + gpio0_19_grp, gpio0_20_grp, gpio0_21_grp, + gpio0_22_grp, gpio0_23_grp, gpio0_24_grp, + gpio0_25_grp, gpio0_26_grp, gpio0_27_grp, + gpio0_28_grp, gpio0_29_grp, gpio0_30_grp, + gpio0_31_grp, gpio0_32_grp, gpio0_33_grp, + gpio0_34_grp, gpio0_35_grp, gpio0_36_grp, + gpio0_37_grp, gpio0_38_grp, gpio0_39_grp, + gpio0_40_grp, gpio0_41_grp, gpio0_42_grp, + gpio0_43_grp, gpio0_44_grp, gpio0_45_grp, + gpio0_46_grp, gpio0_47_grp, gpio0_48_grp, + gpio0_49_grp, gpio0_50_grp, gpio0_51_grp, + gpio0_52_grp, gpio0_53_grp, gpio0_54_grp, + gpio0_55_grp, gpio0_56_grp, gpio0_57_grp, + gpio0_58_grp, gpio0_59_grp, gpio0_60_grp, + gpio0_61_grp, gpio0_62_grp, gpio0_63_grp, + gpio0_64_grp, gpio0_65_grp, gpio0_66_grp, + gpio0_67_grp, gpio0_68_grp, gpio0_69_grp, + gpio0_70_grp, gpio0_71_grp, gpio0_72_grp, + gpio0_73_grp, gpio0_74_grp, gpio0_75_grp, + gpio0_76_grp, gpio0_77_grp, usb0_0_grp, + usb1_0_grp, pmu0_0_grp, pmu0_1_grp, + pmu0_2_grp, pmu0_3_grp, pmu0_4_grp, + pmu0_5_grp, pmu0_6_grp, pmu0_7_grp, + pmu0_8_grp, pmu0_9_grp, pmu0_10_grp, + pmu0_11_grp, pcie0_0_grp, pcie0_1_grp, + pcie0_2_grp, pcie0_3_grp, pcie0_4_grp, + pcie0_5_grp, pcie0_6_grp, pcie0_7_grp, + csu0_0_grp, csu0_1_grp, csu0_2_grp, + csu0_3_grp, csu0_4_grp, csu0_5_grp, + csu0_6_grp, csu0_7_grp, csu0_8_grp, + csu0_9_grp, csu0_10_grp, csu0_11_grp, + dpaux0_0_grp, dpaux0_1_grp, dpaux0_2_grp, + dpaux0_3_grp, pjtag0_0_grp, pjtag0_1_grp, + pjtag0_2_grp, pjtag0_3_grp, pjtag0_4_grp, + pjtag0_5_grp, trace0_0_grp, trace0_clk_0_grp, + trace0_1_grp, trace0_clk_1_grp, trace0_2_grp, + trace0_clk_2_grp, testscan0_0_grp] + maxItems: 78 + + function: + description: + Specify the alternative function to be configured for the + given pin groups. + enum: [ethernet0, ethernet1, ethernet2, ethernet3, gemtsu0, usb0, usb1, mdio0, + mdio1, mdio2, mdio3, qspi0, qspi_fbclk, qspi_ss, spi0, spi1, spi0_ss, + spi1_ss, sdio0, sdio0_pc, sdio0_wp, sdio0_cd, sdio1, sdio1_pc, sdio1_wp, + sdio1_cd, nand0, nand0_ce, nand0_rb, nand0_dqs, can0, can1, uart0, uart1, + i2c0, i2c1, ttc0_clk, ttc0_wav, ttc1_clk, ttc1_wav, ttc2_clk, ttc2_wav, + ttc3_clk, ttc3_wav, swdt0_clk, swdt0_rst, swdt1_clk, swdt1_rst, gpio0, pmu0, + pcie0, csu0, dpaux0, pjtag0, trace0, trace0_clk, testscan0] + + required: + - groups + - function + + additionalProperties: false + + '^conf': + type: object + description: + Pinctrl node's client devices use subnodes for pin configurations, + which in turn use the standard properties below. + $ref: pincfg-node.yaml# + + properties: + groups: + description: + List of pin groups as mentioned above. + + pins: + description: + List of pin names to select in this subnode. + items: + pattern: '^MIO([0-9]|[1-6][0-9]|7[0-7])$' + maxItems: 78 + + bias-pull-up: true + + bias-pull-down: true + + bias-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + bias-high-impedance: true + + low-power-enable: true + + low-power-disable: true + + slew-rate: + enum: [0, 1] + + drive-strength: + description: + Selects the drive strength for MIO pins, in mA. + enum: [2, 4, 8, 12] + + power-source: + enum: [0, 1] + + oneOf: + - required: [ groups ] + - required: [ pins ] + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/pinctrl-zynqmp.h> + zynqmp_firmware: zynqmp-firmware { + pinctrl0: pinctrl { + compatible = "xlnx,zynqmp-pinctrl"; + + pinctrl_uart1_default: uart1-default { + mux { + groups = "uart0_4_grp", "uart0_5_grp"; + function = "uart0"; + }; + + conf { + groups = "uart0_4_grp"; + slew-rate = <SLEW_RATE_SLOW>; + power-source = <IO_STANDARD_LVCMOS18>; + }; + + conf-rx { + pins = "MIO18"; + bias-pull-up; + }; + + conf-tx { + pins = "MIO19"; + bias-disable; + input-schmitt-disable; + }; + }; + }; + }; + + uart1 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart1_default>; + }; + +... diff --git a/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml index 40b08d83c80b..f8e7ddbd2705 100644 --- a/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml +++ b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - brcm,bcm4908-pmb + - brcm,bcm63138-pmb reg: description: register space of one or more buses diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 1ea21acbbd55..ff21bfef8204 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -25,10 +25,12 @@ properties: - qcom,qcs404-rpmpd - qcom,sdm660-rpmpd - qcom,sc7180-rpmhpd + - qcom,sc7280-rpmhpd - qcom,sdm845-rpmhpd - qcom,sdx55-rpmhpd - qcom,sm8150-rpmhpd - qcom,sm8250-rpmhpd + - qcom,sm8350-rpmhpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt index cd2d7f58a9d7..38e54b3fd9f3 100644 --- a/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt @@ -17,6 +17,9 @@ Optional properties: chip's trigger line. If this property is not set, the trigger function is ignored and the chip is kept alive until an explicit kill signal is received +- trigger-delay-ms The number of milliseconds to wait after trigger line + assertion before executing shut down procedure. + The default is 2500ms. Example: @@ -24,6 +27,7 @@ ltc2952 { compatible = "lltc,ltc2952"; trigger-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>; + trigger-delay-ms = <2000>; watchdog-gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; kill-gpios = <&gpio0 2 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt b/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt deleted file mode 100644 index f181e46d8e07..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt +++ /dev/null @@ -1,16 +0,0 @@ -=== AB8500 Battery Temperature Monitor Driver === - -The properties below describes the node for btemp driver. - -Required Properties: -- compatible = Shall be: "stericsson,ab8500-btemp" -- battery = Shall be battery specific information - - Example: - ab8500_btemp { - compatible = "stericsson,ab8500-btemp"; - battery = <&ab8500_battery>; - }; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power/supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt b/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt deleted file mode 100644 index 56636f927203..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt +++ /dev/null @@ -1,16 +0,0 @@ -=== AB8500 Charging Algorithm Driver === - -The properties below describes the node for chargalg driver. - -Required Properties: -- compatible = Shall be: "stericsson,ab8500-chargalg" -- battery = Shall be battery specific information - -Example: -ab8500_chargalg { - compatible = "stericsson,ab8500-chargalg"; - battery = <&ab8500_battery>; -}; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power/supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt b/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt deleted file mode 100644 index 24ada03e07b4..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt +++ /dev/null @@ -1,25 +0,0 @@ -=== AB8500 Charger Driver === - -Required Properties: -- compatible = Shall be "stericsson,ab8500-charger" -- battery = Shall be battery specific information - Example: - ab8500_charger { - compatible = "stericsson,ab8500-charger"; - battery = <&ab8500_battery>; - }; - -- vddadc-supply: Supply for USB and Main charger - Example: - ab8500-charger { - vddadc-supply = <&ab8500_ldo_tvout_reg>; - } -- autopower_cfg: - Boolean value depicting the presence of 'automatic poweron after powerloss' - Example: - ab8500-charger { - autopower_cfg; - }; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power/supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt b/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt deleted file mode 100644 index cb737a9e1f16..000000000000 --- a/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt +++ /dev/null @@ -1,44 +0,0 @@ -Device-Tree bindings for charger of Active-semi ACT8945A Multi-Function Device - -Required properties: - - compatible: "active-semi,act8945a-charger". - - active-semi,chglev-gpios: charge current level phandle with args - as described in ../gpio/gpio.txt. - - active-semi,lbo-gpios: specify the low battery voltage detect phandle - with args as as described in ../gpio/gpio.txt. - - interrupts: <a b> where a is the interrupt number and b is a - field that represents an encoding of the sense and level - information for the interrupt. - -Optional properties: - - active-semi,input-voltage-threshold-microvolt: unit: mV; - Specifies the charger's input over-voltage threshold value; - The value can be: 6600, 7000, 7500, 8000; default: 6600 - - active-semi,precondition-timeout: unit: minutes; - Specifies the charger's PRECONDITION safety timer setting value; - The value can be: 40, 60, 80, 0; If 0, it means to disable this timer; - default: 40. - - active-semi,total-timeout: unit: hours; - Specifies the charger's total safety timer setting value; - The value can be: 3, 4, 5, 0; If 0, it means to disable this timer; - default: 3. - -Example: - pmic@5b { - compatible = "active-semi,act8945a"; - reg = <0x5b>; - - charger { - compatible = "active-semi,act8945a-charger"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_charger_chglev &pinctrl_charger_lbo &pinctrl_charger_irq>; - interrupt-parent = <&pioA>; - interrupts = <45 IRQ_TYPE_LEVEL_LOW>; - - active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; - active-semi,lbo-gpios = <&pioA 72 GPIO_ACTIVE_LOW>; - active-semi,input-voltage-threshold-microvolt = <6600>; - active-semi,precondition-timeout = <40>; - active-semi,total-timeout = <3>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/active-semi,act8945a-charger.yaml b/Documentation/devicetree/bindings/power/supply/active-semi,act8945a-charger.yaml new file mode 100644 index 000000000000..3f74bc19415d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/active-semi,act8945a-charger.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/active-semi,act8945a-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Active-semi ACT8945A Charger Function + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: active-semi,act8945a-charger + + interrupts: + maxItems: 1 + + active-semi,chglev-gpios: + maxItems: 1 + description: charge current level GPIO + + active-semi,lbo-gpios: + maxItems: 1 + description: low battery voltage detect GPIO + + active-semi,input-voltage-threshold-microvolt: + description: | + Specifies the charger's input over-voltage threshold value. + Despite the name, specified values are in millivolt (mV). + Defaults to 6.6 V + enum: [ 6600, 7000, 7500, 8000 ] + + active-semi,precondition-timeout: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specifies the charger's PRECONDITION safety timer setting value in minutes. + If 0, it means to disable this timer. + Defaults to 40 minutes. + enum: [ 0, 40, 60, 80 ] + + active-semi,total-timeout: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specifies the charger's total safety timer setting value in hours; + If 0, it means to disable this timer; + Defaults to 3 hours. + enum: [ 0, 3, 4, 5 ] + +required: + - compatible + - interrupts + - active-semi,chglev-gpios + - active-semi,lbo-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + charger { + compatible = "active-semi,act8945a-charger"; + interrupt-parent = <&pioA>; + interrupts = <45 IRQ_TYPE_LEVEL_LOW>; + active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,lbo-gpios = <&pioA 72 GPIO_ACTIVE_LOW>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt b/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt deleted file mode 100644 index 7a1fb532abe5..000000000000 --- a/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt +++ /dev/null @@ -1,25 +0,0 @@ -AXP20X and AXP22X PMICs' AC power supply - -Required Properties: - - compatible: One of: - "x-powers,axp202-ac-power-supply" - "x-powers,axp221-ac-power-supply" - "x-powers,axp813-ac-power-supply" - -This node is a subnode of the axp20x PMIC. - -The AXP20X can read the current current and voltage supplied by AC by -reading ADC channels from the AXP20X ADC. - -The AXP22X is only able to tell if an AC power supply is present and -usable. - -AXP813/AXP803 are able to limit current and supply voltage - -Example: - -&axp209 { - ac_power_supply: ac-power-supply { - compatible = "x-powers,axp202-ac-power-supply"; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt b/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt deleted file mode 100644 index 41916f69902c..000000000000 --- a/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt +++ /dev/null @@ -1,20 +0,0 @@ -AXP20x and AXP22x battery power supply - -Required Properties: - - compatible, one of: - "x-powers,axp209-battery-power-supply" - "x-powers,axp221-battery-power-supply" - "x-powers,axp813-battery-power-supply" - -This node is a subnode of its respective PMIC DT node. - -The supported devices can read the battery voltage, charge and discharge -currents of the battery by reading ADC channels from the ADC. - -Example: - -&axp209 { - battery_power_supply: battery-power-supply { - compatible = "x-powers,axp209-battery-power-supply"; - } -}; diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt b/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt deleted file mode 100644 index b2d4968fde7d..000000000000 --- a/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt +++ /dev/null @@ -1,41 +0,0 @@ -AXP20x USB power supply - -Required Properties: --compatible: One of: "x-powers,axp202-usb-power-supply" - "x-powers,axp221-usb-power-supply" - "x-powers,axp223-usb-power-supply" - "x-powers,axp813-usb-power-supply" - -The AXP223 PMIC shares most of its behaviour with the AXP221 but has slight -variations such as the former being able to set the VBUS power supply max -current to 100mA, unlike the latter. - -This node is a subnode of the axp20x PMIC. - -Example: - -axp209: pmic@34 { - compatible = "x-powers,axp209"; - reg = <0x34>; - interrupt-parent = <&nmi_intc>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <1>; - - regulators { - x-powers,dcdc-freq = <1500>; - - vdd_cpu: dcdc2 { - regulator-always-on; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1450000>; - regulator-name = "vdd-cpu"; - }; - - ... - }; - - usb-power-supply: usb-power-supply { - compatible = "x-powers,axp202-usb-power-supply"; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt deleted file mode 100644 index a9f80cc49068..000000000000 --- a/Documentation/devicetree/bindings/power/supply/battery.txt +++ /dev/null @@ -1,3 +0,0 @@ -The contents of this file has been moved to battery.yaml - -Please note that not all charger drivers respect all of the properties. diff --git a/Documentation/devicetree/bindings/power/supply/bq2415x.txt b/Documentation/devicetree/bindings/power/supply/bq2415x.txt deleted file mode 100644 index d0327f0b59ad..000000000000 --- a/Documentation/devicetree/bindings/power/supply/bq2415x.txt +++ /dev/null @@ -1,47 +0,0 @@ -Binding for TI bq2415x Li-Ion Charger - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq24150" - * "ti,bq24150" - * "ti,bq24150a" - * "ti,bq24151" - * "ti,bq24151a" - * "ti,bq24152" - * "ti,bq24153" - * "ti,bq24153a" - * "ti,bq24155" - * "ti,bq24156" - * "ti,bq24156a" - * "ti,bq24158" -- reg: integer, i2c address of the device. -- ti,current-limit: integer, initial maximum current charger can pull - from power supply in mA. -- ti,weak-battery-voltage: integer, weak battery voltage threshold in mV. - The chip will use slow precharge if battery voltage - is below this value. -- ti,battery-regulation-voltage: integer, maximum charging voltage in mV. -- ti,charge-current: integer, maximum charging current in mA. -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in mA). -- ti,resistor-sense: integer, value of sensing resistor in milliohm. - -Optional properties: -- ti,usb-charger-detection: phandle to usb charger detection device. - (required for auto mode) - -Example from Nokia N900: - -bq24150a { - compatible = "ti,bq24150a"; - reg = <0x6b>; - - ti,current-limit = <100>; - ti,weak-battery-voltage = <3400>; - ti,battery-regulation-voltage = <4200>; - ti,charge-current = <650>; - ti,termination-current = <100>; - ti,resistor-sense = <68>; - - ti,usb-charger-detection = <&isp1704>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/bq2415x.yaml b/Documentation/devicetree/bindings/power/supply/bq2415x.yaml new file mode 100644 index 000000000000..f8461f06e6f4 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq2415x.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq2415x.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for TI bq2415x Li-Ion Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq24150 + - ti,bq24150 + - ti,bq24150a + - ti,bq24151 + - ti,bq24151a + - ti,bq24152 + - ti,bq24153 + - ti,bq24153a + - ti,bq24155 + - ti,bq24156 + - ti,bq24156a + - ti,bq24158 + + reg: + maxItems: 1 + + ti,current-limit: + $ref: /schemas/types.yaml#/definitions/uint32 + description: initial maximum current charger can pull from power supply in mA. + + ti,weak-battery-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + weak battery voltage threshold in mV. + The chip will use slow precharge if battery voltage is below this value. + + ti,battery-regulation-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging voltage in mV. + + ti,charge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging current in mA. + + ti,termination-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + charge will be terminated when current in constant-voltage phase drops + below this value (in mA). + + ti,resistor-sense: + $ref: /schemas/types.yaml#/definitions/uint32 + description: value of sensing resistor in milliohm. + + ti,usb-charger-detection: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to usb charger detection device (required for auto mode) + +required: + - compatible + - reg + - ti,current-limit + - ti,weak-battery-voltage + - ti,battery-regulation-voltage + - ti,charge-current + - ti,termination-current + - ti,resistor-sense + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@6b { + compatible = "ti,bq24150a"; + reg = <0x6b>; + + ti,current-limit = <100>; + ti,weak-battery-voltage = <3400>; + ti,battery-regulation-voltage = <4200>; + ti,charge-current = <650>; + ti,termination-current = <100>; + ti,resistor-sense = <68>; + + ti,usb-charger-detection = <&isp1704>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq24190.txt b/Documentation/devicetree/bindings/power/supply/bq24190.txt deleted file mode 100644 index ffe2be408bb6..000000000000 --- a/Documentation/devicetree/bindings/power/supply/bq24190.txt +++ /dev/null @@ -1,61 +0,0 @@ -TI BQ24190 Li-Ion Battery Charger - -Required properties: -- compatible: contains one of the following: - * "ti,bq24190" - * "ti,bq24192" - * "ti,bq24192i" - * "ti,bq24196" -- reg: integer, I2C address of the charger. -- interrupts[-extended]: configuration for charger INT pin. - -Optional properties: -- monitored-battery: phandle of battery characteristics devicetree node - The charger uses the following battery properties: - + precharge-current-microamp: maximum charge current during precharge - phase (typically 20% of battery capacity). - + charge-term-current-microamp: a charge cycle terminates when the - battery voltage is above recharge threshold, and the current is below - this setting (typically 10% of battery capacity). - See also Documentation/devicetree/bindings/power/supply/battery.txt -- ti,system-minimum-microvolt: when power is connected and the battery is below - minimum system voltage, the system will be regulated above this setting. - -child nodes: -- usb-otg-vbus: - Usage: optional - Description: Regulator that is used to control the VBUS voltage direction for - either USB host mode or for charging on the OTG port. - -Notes: -- Some circuit boards wire the chip's "OTG" pin high (enabling 500mA default - charge current on USB SDP ports, among other features). To simulate this on - boards that wire the pin to a GPIO, set a gpio-hog. - -Example: - - bat: battery { - compatible = "simple-battery"; - precharge-current-microamp = <256000>; - charge-term-current-microamp = <128000>; - // etc. - }; - - bq24190: charger@6a { - compatible = "ti,bq24190"; - reg = <0x6a>; - interrupts-extended = <&gpiochip 10 IRQ_TYPE_EDGE_FALLING>; - monitored-battery = <&bat>; - ti,system-minimum-microvolt = <3200000>; - - usb_otg_vbus: usb-otg-vbus { }; - }; - - &twl_gpio { - otg { - gpio-hog; - gpios = <6 0>; - output-high; - line-name = "otg-gpio"; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/bq24190.yaml b/Documentation/devicetree/bindings/power/supply/bq24190.yaml new file mode 100644 index 000000000000..0d7cbbdf808b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq24190.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq24190.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for TI BQ2419x Li-Ion Battery Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq24190 + - ti,bq24192 + - ti,bq24192i + - ti,bq24196 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + usb-otg-vbus: + type: object + description: | + Regulator that is used to control the VBUS voltage direction for + either USB host mode or for charging on the OTG port + + ti,system-minimum-microvolt: + description: | + when power is connected and the battery is below minimum system voltage, + the system will be regulated above this setting. + + omit-battery-class: + type: boolean + description: | + If this property is set, the operating system does not try to create a + battery device. + + monitored-battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: | + phandle to a "simple-battery" compatible node. + + This property must be a phandle to a node using the format described + in battery.yaml, with the following properties being required: + - precharge-current-microamp: maximum charge current during precharge phase + (typically 20% of battery capacity). + - charge-term-current-microamp: a charge cycle terminates when the battery voltage is + above recharge threshold, and the current is below this + setting (typically 10% of battery capacity). + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + bat: battery { + compatible = "simple-battery"; + precharge-current-microamp = <256000>; + charge-term-current-microamp = <128000>; + }; + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@6a { + compatible = "ti,bq24190"; + reg = <0x6a>; + interrupt-parent = <&gpiochip>; + interrupts = <10 IRQ_TYPE_EDGE_FALLING>; + monitored-battery = <&bat>; + ti,system-minimum-microvolt = <3200000>; + + usb_otg_vbus: usb-otg-vbus { }; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq24257.txt b/Documentation/devicetree/bindings/power/supply/bq24257.txt deleted file mode 100644 index f8f5a1685bb9..000000000000 --- a/Documentation/devicetree/bindings/power/supply/bq24257.txt +++ /dev/null @@ -1,62 +0,0 @@ -Binding for TI bq24250/bq24251/bq24257 Li-Ion Charger - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq24250" - * "ti,bq24251" - * "ti,bq24257" -- reg: integer, i2c address of the device. -- interrupts: Interrupt mapping for GPIO IRQ (configure for both edges). Use in - conjunction with "interrupt-parent". -- ti,battery-regulation-voltage: integer, maximum charging voltage in uV. -- ti,charge-current: integer, maximum charging current in uA. -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in uA). - -Optional properties: -- pg-gpios: GPIO used for connecting the bq2425x device PG (Power Good) pin. - This pin is not available on all devices however it should be used if - possible as this is the recommended way to obtain the charger's input PG - state. If this pin is not specified a software-based approach for PG - detection is used. -- ti,current-limit: The maximum current to be drawn from the charger's input - (in uA). If this property is not specified, the input limit current is - set automatically using USB D+/D- signal based charger type detection. - If the hardware does not support the D+/D- based detection, a default - of 500,000 is used (=500mA) instead. -- ti,ovp-voltage: Configures the over voltage protection voltage (in uV). If - not specified a default of 6,5000,000 (=6.5V) is used. -- ti,in-dpm-voltage: Configures the threshold input voltage for the dynamic - power path management (in uV). If not specified a default of 4,360,000 - (=4.36V) is used. - -Example: - -bq24257 { - compatible = "ti,bq24257"; - reg = <0x6a>; - interrupt-parent = <&gpio1>; - interrupts = <16 IRQ_TYPE_EDGE_BOTH>; - - pg-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <1000000>; - ti,termination-current = <50000>; -}; - -Example: - -bq24250 { - compatible = "ti,bq24250"; - reg = <0x6a>; - interrupt-parent = <&gpio1>; - interrupts = <16 IRQ_TYPE_EDGE_BOTH>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <500000>; - ti,termination-current = <50000>; - ti,current-limit = <900000>; - ti,ovp-voltage = <9500000>; - ti,in-dpm-voltage = <4440000>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/bq24257.yaml b/Documentation/devicetree/bindings/power/supply/bq24257.yaml new file mode 100644 index 000000000000..3a0f6cd9015a --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq24257.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq24257.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for bq24250, bq24251 and bq24257 Li-Ion Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq24250 + - ti,bq24251 + - ti,bq24257 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + ti,battery-regulation-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging voltage in uV + + ti,charge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging current in uA + + ti,termination-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + charge will be terminated when current in constant-voltage phase + drops below this value (in uA) + + pg-gpios: + description: | + GPIO used for connecting the bq2425x device PG (Power Good) pin. + This pin is not available on all devices however it should be used if + possible as this is the recommended way to obtain the charger's input PG + state. If this pin is not specified a software-based approach for PG + detection is used. + maxItems: 1 + + ti,current-limit: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + The maximum current to be drawn from the charger's input (in uA). + If this property is not specified, the input limit current is set + automatically using USB D+/D- signal based charger type detection. + If the hardware does not support the D+/D- based detection, a default + of 500,000 is used (=500mA) instead. + + ti,ovp-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Configures the over voltage protection voltage (in uV). + If not specified a default of 6,5000,000 (=6.5V) is used. + + ti,in-dpm-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Configures the threshold input voltage for the dynamic power path management (in uV). + If not specified a default of 4,360,000 (=4.36V) is used. + +required: + - compatible + - reg + - interrupts + - ti,battery-regulation-voltage + - ti,charge-current + - ti,termination-current + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@6a { + compatible = "ti,bq24257"; + reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + pg-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <1000000>; + ti,termination-current = <50000>; + }; + }; + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@6a { + compatible = "ti,bq24250"; + reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <500000>; + ti,termination-current = <50000>; + ti,current-limit = <900000>; + ti,ovp-voltage = <9500000>; + ti,in-dpm-voltage = <4440000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq24735.yaml b/Documentation/devicetree/bindings/power/supply/bq24735.yaml new file mode 100644 index 000000000000..131be6782c4b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq24735.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq24735.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for TI BQ24735 Li-Ion Battery Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: ti,bq24735 + + reg: + maxItems: 1 + + interrupts: + description: AC adapter plug event interrupt + maxItems: 1 + + ti,ac-detect-gpios: + maxItems: 1 + description: | + This GPIO is optionally used to read the AC adapter status. This is a Host GPIO + that is configured as an input and connected to the ACOK pin on the bq24735. + Note: for backwards compatibility reasons, the GPIO must be active on AC adapter + absence despite ACOK being active (high) on AC adapter presence. + + ti,charge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Used to control and set the charging current. + This value must be between 128mA and 8.128A with a 64mA step resolution. + The POR value is 0x0000h. This number is in mA (e.g. 8192). + See spec for more information about the ChargeCurrent (0x14h) register. + + ti,charge-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Used to control and set the charging voltage. + This value must be between 1.024V and 19.2V with a 16mV step resolution. + The POR value is 0x0000h. This number is in mV (e.g. 19200). + See spec for more information about the ChargeVoltage (0x15h) register. + + ti,input-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Used to control and set the charger input current. + This value must be between 128mA and 8.064A with a 128mA step resolution. + The POR value is 0x1000h. This number is in mA (e.g. 8064). + See the spec for more information about the InputCurrent (0x3fh) register. + + ti,external-control: + type: boolean + description: | + Indicates that the charger is configured externally and that the host should not + attempt to enable/disable charging or set the charge voltage/current. + + poll-interval: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + If 'interrupts' is not specified, poll AC adapter presence with this interval (milliseconds). + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@9 { + compatible = "ti,bq24735"; + reg = <0x9>; + ti,ac-detect-gpios = <&gpio 72 0x1>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq256xx.yaml b/Documentation/devicetree/bindings/power/supply/bq256xx.yaml index 18b54783e11a..92ec7ed25668 100644 --- a/Documentation/devicetree/bindings/power/supply/bq256xx.yaml +++ b/Documentation/devicetree/bindings/power/supply/bq256xx.yaml @@ -39,7 +39,6 @@ properties: maxItems: 1 ti,watchdog-timeout-ms: - $ref: /schemas/types.yaml#/definitions/uint32 default: 0 description: | Watchdog timer in ms. 0 (default) disables the watchdog diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.txt b/Documentation/devicetree/bindings/power/supply/bq25890.txt deleted file mode 100644 index 805040c6fff9..000000000000 --- a/Documentation/devicetree/bindings/power/supply/bq25890.txt +++ /dev/null @@ -1,60 +0,0 @@ -Binding for TI bq25890 Li-Ion Charger - -This driver will support the bq25892, the bq25896 and the bq25890. There are -other ICs in the same family but those have not been tested. - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq25890" - * "ti,bq25892" - * "ti,bq25895" - * "ti,bq25896" -- reg: integer, i2c address of the device. -- interrupts: interrupt line; -- ti,battery-regulation-voltage: integer, maximum charging voltage (in uV); -- ti,charge-current: integer, maximum charging current (in uA); -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in uA); -- ti,precharge-current: integer, maximum charge current during precharge - phase (in uA); -- ti,minimum-sys-voltage: integer, when battery is charging and it is below - minimum system voltage, the system will be regulated above - minimum-sys-voltage setting (in uV); -- ti,boost-voltage: integer, VBUS voltage level in boost mode (in uV); -- ti,boost-max-current: integer, maximum allowed current draw in boost mode - (in uA). - -Optional properties: -- ti,boost-low-freq: boolean, if present boost mode frequency will be 500kHz, - otherwise 1.5MHz; -- ti,use-ilim-pin: boolean, if present the ILIM resistor will be used and the - input current will be the lower between the resistor setting and the IINLIM - register setting; -- ti,thermal-regulation-threshold: integer, temperature above which the charge - current is lowered, to avoid overheating (in degrees Celsius). If omitted, - the default setting will be used (120 degrees); -- ti,ibatcomp-micro-ohms: integer, value of a resistor in series with - the battery; -- ti,ibatcomp-clamp-microvolt: integer, maximum charging voltage adjustment due - to expected voltage drop on in-series resistor; - -Example: - -bq25890 { - compatible = "ti,bq25890"; - reg = <0x6a>; - - interrupt-parent = <&gpio1>; - interrupts = <16 IRQ_TYPE_EDGE_FALLING>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <1000000>; - ti,termination-current = <50000>; - ti,precharge-current = <128000>; - ti,minimum-sys-voltage = <3600000>; - ti,boost-voltage = <5000000>; - ti,boost-max-current = <1000000>; - - ti,use-ilim-pin; - ti,thermal-regulation-threshold = <120>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.yaml b/Documentation/devicetree/bindings/power/supply/bq25890.yaml new file mode 100644 index 000000000000..bf823b615439 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq25890.yaml @@ -0,0 +1,123 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq25890.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for bq25890, bq25892, bq25895 and bq25896 Li-Ion Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq25890 + - ti,bq25892 + - ti,bq25895 + - ti,bq25896 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + ti,battery-regulation-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging voltage (in uV) + + ti,charge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charging current (in uA) + + ti,termination-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + charge will be terminated when current in constant-voltage phase + drops below this value (in uA) + + ti,precharge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum charge current during precharge phase (in uA) + + ti,minimum-sys-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + when battery is charging and it is below minimum system voltage, + the system will be regulated above minimum-sys-voltage setting (in uV) + + ti,boost-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: VBUS voltage level in boost mode (in uV) + + ti,boost-max-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum allowed current draw in boost mode (in uA) + + ti,boost-low-freq: + description: boost mode frequency will be 500kHz, otherwise 1.5MHz + type: boolean + + ti,use-ilim-pin: + description: | + ILIM resistor will be used and the input current will be the lower + between the resistor setting and the IINLIM register setting + type: boolean + + ti,thermal-regulation-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + temperature above which the charge current is lowered, to avoid overheating + (in degrees Celsius). If omitted, the default setting will be used (120 degrees) + + ti,ibatcomp-micro-ohms: + description: value of a resistor in series with the battery (in Micro Ohms) + + ti,ibatcomp-clamp-microvolt: + description: max. charging voltage adjustment due to expected voltage drop on in-series resistor + +required: + - compatible + - reg + - interrupts + - ti,battery-regulation-voltage + - ti,charge-current + - ti,termination-current + - ti,precharge-current + - ti,minimum-sys-voltage + - ti,boost-voltage + - ti,boost-max-current + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@6a { + compatible = "ti,bq25890"; + reg = <0x6a>; + + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_FALLING>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <1000000>; + ti,termination-current = <50000>; + ti,precharge-current = <128000>; + ti,minimum-sys-voltage = <3600000>; + ti,boost-voltage = <5000000>; + ti,boost-max-current = <1000000>; + + ti,use-ilim-pin; + ti,thermal-regulation-threshold = <120>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml index 45beefccf31a..6af41da3e055 100644 --- a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml +++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml @@ -52,6 +52,7 @@ properties: - ti,bq27z561 - ti,bq28z610 - ti,bq34z100 + - ti,bq78z100 reg: maxItems: 1 @@ -65,7 +66,7 @@ properties: - charge-full-design-microamp-hours - voltage-min-design-microvolt Both or neither of the *-full-design-*-hours properties must be set. - See Documentation/devicetree/bindings/power/supply/battery.txt + See Documentation/devicetree/bindings/power/supply/battery.yaml power-supplies: true diff --git a/Documentation/devicetree/bindings/power/supply/cpcap-battery.txt b/Documentation/devicetree/bindings/power/supply/cpcap-battery.txt deleted file mode 100644 index a04efa22da01..000000000000 --- a/Documentation/devicetree/bindings/power/supply/cpcap-battery.txt +++ /dev/null @@ -1,31 +0,0 @@ -Motorola CPCAP PMIC battery driver binding - -Required properties: -- compatible: Shall be "motorola,cpcap-battery" -- interrupts: Interrupt specifier for each name in interrupt-names -- interrupt-names: Should contain the following entries: - "lowbph", "lowbpl", "chrgcurr1", "battdetb" -- io-channels: IIO ADC channel specifier for each name in io-channel-names -- io-channel-names: Should contain the following entries: - "battdetb", "battp", "chg_isense", "batti" -- power-supplies: List of phandles for power-supplying devices, as - described in power_supply.txt. Typically a reference - to cpcap_charger. - -Example: - -cpcap_battery: battery { - compatible = "motorola,cpcap-battery"; - interrupts-extended = < - &cpcap 5 0 &cpcap 3 0 - &cpcap 20 0 &cpcap 54 0 - >; - interrupt-names = - "lowbph", "lowbpl", - "chrgcurr1", "battdetb"; - io-channels = <&cpcap_adc 0 &cpcap_adc 1 - &cpcap_adc 5 &cpcap_adc 6>; - io-channel-names = "battdetb", "battp", - "chg_isense", "batti"; - power-supplies = <&cpcap_charger>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/cpcap-battery.yaml b/Documentation/devicetree/bindings/power/supply/cpcap-battery.yaml new file mode 100644 index 000000000000..7153fd4ce55f --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/cpcap-battery.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/cpcap-battery.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Motorola CPCAP PMIC battery + +maintainers: + - Tony Lindgren <tony@atomide.com> + - Sebastian Reichel <sre@kernel.org> + +description: | + Motorola CPCAP is a PMIC found in some mobile phones, e.g. + the Droid 4. This binding describes its battery fuel gauge + sub-function. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: motorola,cpcap-battery + + interrupts: + items: + - description: eol interrupt + - description: low battery percentage interrupt + - description: critical battery percentage interrupt + - description: charger detect interrupt + - description: battery detect interrupt + - description: coulomb counter calibration interrupt + + interrupt-names: + items: + - const: eol + - const: lowbph + - const: lowbpl + - const: chrgcurr1 + - const: battdetb + - const: cccal + + io-channels: + items: + - description: battery temperature + - description: battery voltage + - description: battery charge current + - description: battery current + + io-channel-names: + items: + - const: battdetb + - const: battp + - const: chg_isense + - const: batti + + power-supplies: true + +required: + - compatible + - interrupts + - interrupt-names + - io-channels + - io-channel-names + - power-supplies + +additionalProperties: false + +examples: + - | + cpcap { + battery { + compatible = "motorola,cpcap-battery"; + interrupts-extended = + <&cpcap 6 0>, <&cpcap 5 0>, <&cpcap 3 0>, + <&cpcap 20 0>, <&cpcap 54 0>, <&cpcap 57 0>; + interrupt-names = + "eol", "lowbph", "lowbpl", + "chrgcurr1", "battdetb", "cccal"; + io-channels = <&cpcap_adc 0>, <&cpcap_adc 1>, + <&cpcap_adc 5>, <&cpcap_adc 6>; + io-channel-names = "battdetb", "battp", + "chg_isense", "batti"; + power-supplies = <&cpcap_charger>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt b/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt deleted file mode 100644 index 6048f636783f..000000000000 --- a/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt +++ /dev/null @@ -1,40 +0,0 @@ -Motorola CPCAP PMIC battery charger binding - -Required properties: -- compatible: Shall be "motorola,mapphone-cpcap-charger" -- interrupts: Interrupt specifier for each name in interrupt-names -- interrupt-names: Should contain the following entries: - "chrg_det", "rvrs_chrg", "chrg_se1b", "se0conn", - "rvrs_mode", "chrgcurr2", "chrgcurr1", "vbusvld", - "battdetb" -- io-channels: IIO ADC channel specifier for each name in io-channel-names -- io-channel-names: Should contain the following entries: - "battdetb", "battp", "vbus", "chg_isense", "batti" - -Optional properties: -- mode-gpios: Optionally CPCAP charger can have a companion wireless - charge controller that is controlled with two GPIOs - that are active low. - -Example: - -cpcap_charger: charger { - compatible = "motorola,mapphone-cpcap-charger"; - interrupts-extended = < - &cpcap 13 0 &cpcap 12 0 &cpcap 29 0 &cpcap 28 0 - &cpcap 22 0 &cpcap 21 0 &cpcap 20 0 &cpcap 19 0 - &cpcap 54 0 - >; - interrupt-names = - "chrg_det", "rvrs_chrg", "chrg_se1b", "se0conn", - "rvrs_mode", "chrgcurr2", "chrgcurr1", "vbusvld", - "battdetb"; - mode-gpios = <&gpio3 29 GPIO_ACTIVE_LOW - &gpio3 23 GPIO_ACTIVE_LOW>; - io-channels = <&cpcap_adc 0 &cpcap_adc 1 - &cpcap_adc 2 &cpcap_adc 5 - &cpcap_adc 6>; - io-channel-names = "battdetb", "battp", - "vbus", "chg_isense", - "batti"; -}; diff --git a/Documentation/devicetree/bindings/power/supply/cpcap-charger.yaml b/Documentation/devicetree/bindings/power/supply/cpcap-charger.yaml new file mode 100644 index 000000000000..cb6353683d7b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/cpcap-charger.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/cpcap-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Motorola CPCAP PMIC charger + +maintainers: + - Tony Lindgren <tony@atomide.com> + - Sebastian Reichel <sre@kernel.org> + +description: | + Motorola CPCAP is a PMIC found in some mobile phones, e.g. + the Droid 4. This binding describes its battery charger + sub-function. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: motorola,mapphone-cpcap-charger + + interrupts: + items: + - description: charger detection interrupt + - description: reverse charge interrupt + - description: SE1 charger detection interrupt + - description: SE0 charger detection interrupt + - description: reverse mode interrupt + - description: charge current 2 interrupt + - description: charge current 1 interrupt + - description: VBUS valid interrupt + - description: battery detect interrupt + + interrupt-names: + items: + - const: chrg_det + - const: rvrs_chrg + - const: chrg_se1b + - const: se0conn + - const: rvrs_mode + - const: chrgcurr2 + - const: chrgcurr1 + - const: vbusvld + - const: battdetb + + io-channels: + items: + - description: battery temperature + - description: battery voltage + - description: VBUS voltage + - description: battery charge current + - description: battery current + + io-channel-names: + items: + - const: battdetb + - const: battp + - const: vbus + - const: chg_isense + - const: batti + + mode-gpios: + description: | + Optionally CPCAP charger can have a companion wireless + charge controller that is controlled with two GPIOs + that are active low. + minItems: 2 + maxItems: 2 + +required: + - compatible + - interrupts + - interrupt-names + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + cpcap { + charger { + compatible = "motorola,mapphone-cpcap-charger"; + interrupts-extended = + <&cpcap 13 0>, <&cpcap 12 0>, <&cpcap 29 0>, <&cpcap 28 0>, + <&cpcap 22 0>, <&cpcap 21 0>, <&cpcap 20 0>, <&cpcap 19 0>, + <&cpcap 54 0>; + interrupt-names = + "chrg_det", "rvrs_chrg", "chrg_se1b", "se0conn", + "rvrs_mode", "chrgcurr2", "chrgcurr1", "vbusvld", + "battdetb"; + mode-gpios = <&gpio3 29 GPIO_ACTIVE_LOW>, + <&gpio3 23 GPIO_ACTIVE_LOW>; + io-channels = <&cpcap_adc 0>, <&cpcap_adc 1>, + <&cpcap_adc 2>, <&cpcap_adc 5>, + <&cpcap_adc 6>; + io-channel-names = "battdetb", "battp", + "vbus", "chg_isense", + "batti"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml b/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml index 5fcdf5801536..c73abb2ff513 100644 --- a/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml +++ b/Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml @@ -61,7 +61,7 @@ examples: #size-cells = <0>; cw2015@62 { - compatible = "cellwise,cw201x"; + compatible = "cellwise,cw2015"; reg = <0x62>; cellwise,battery-profile = /bits/ 8 < 0x17 0x67 0x80 0x73 0x6E 0x6C 0x6B 0x63 diff --git a/Documentation/devicetree/bindings/power/supply/da9150-charger.txt b/Documentation/devicetree/bindings/power/supply/da9150-charger.txt deleted file mode 100644 index f3906663c454..000000000000 --- a/Documentation/devicetree/bindings/power/supply/da9150-charger.txt +++ /dev/null @@ -1,26 +0,0 @@ -Dialog Semiconductor DA9150 Charger Power Supply bindings - -Required properties: -- compatible: "dlg,da9150-charger" for DA9150 Charger Power Supply - -Optional properties: -- io-channels: List of phandle and IIO specifier pairs -- io-channel-names: List of channel names used by charger - ["CHAN_IBUS", "CHAN_VBUS", "CHAN_TJUNC", "CHAN_VBAT"] - (See Documentation/devicetree/bindings/iio/iio-bindings.txt for further info) - - -Example: - - da9150-charger { - compatible = "dlg,da9150-charger"; - - io-channels = <&gpadc 0>, - <&gpadc 2>, - <&gpadc 8>, - <&gpadc 5>; - io-channel-names = "CHAN_IBUS", - "CHAN_VBUS", - "CHAN_TJUNC", - "CHAN_VBAT"; - }; diff --git a/Documentation/devicetree/bindings/power/supply/da9150-fg.txt b/Documentation/devicetree/bindings/power/supply/da9150-fg.txt deleted file mode 100644 index 00236fe3ea31..000000000000 --- a/Documentation/devicetree/bindings/power/supply/da9150-fg.txt +++ /dev/null @@ -1,23 +0,0 @@ -Dialog Semiconductor DA9150 Fuel-Gauge Power Supply bindings - -Required properties: -- compatible: "dlg,da9150-fuel-gauge" for DA9150 Fuel-Gauge Power Supply - -Optional properties: -- dlg,update-interval: Interval time (milliseconds) between battery level checks. -- dlg,warn-soc-level: Battery discharge level (%) where warning event raised. - [1 - 100] -- dlg,crit-soc-level: Battery discharge level (%) where critical event raised. - This value should be lower than the warning level. - [1 - 100] - - -Example: - - fuel-gauge { - compatible = "dlg,da9150-fuel-gauge"; - - dlg,update-interval = <10000>; - dlg,warn-soc-level = /bits/ 8 <15>; - dlg,crit-soc-level = /bits/ 8 <5>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/dlg,da9150-charger.yaml b/Documentation/devicetree/bindings/power/supply/dlg,da9150-charger.yaml new file mode 100644 index 000000000000..96336b05d76d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/dlg,da9150-charger.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/dlg,da9150-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Dialog Semiconductor DA9150 Charger Power Supply bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: dlg,da9150-charger + + io-channels: + items: + - description: ADC channel for current + - description: ADC channel for bus voltage + - description: ADC channel for junction temperature + - description: ADC channel for battery voltage + + io-channel-names: + items: + - const: CHAN_IBUS + - const: CHAN_VBUS + - const: CHAN_TJUNC + - const: CHAN_VBAT + +required: + - compatible + +additionalProperties: false + +examples: + - | + pmic { + charger { + compatible = "dlg,da9150-charger"; + io-channels = <&gpadc 0>, + <&gpadc 2>, + <&gpadc 8>, + <&gpadc 5>; + io-channel-names = "CHAN_IBUS", + "CHAN_VBUS", + "CHAN_TJUNC", + "CHAN_VBAT"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/dlg,da9150-fuel-gauge.yaml b/Documentation/devicetree/bindings/power/supply/dlg,da9150-fuel-gauge.yaml new file mode 100644 index 000000000000..30c2fff7cf92 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/dlg,da9150-fuel-gauge.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/dlg,da9150-fuel-gauge.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Dialog Semiconductor DA9150 Fuel-Gauge Power Supply bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: dlg,da9150-fuel-gauge + + dlg,update-interval: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Interval time (milliseconds) between battery level checks. + + dlg,warn-soc-level: + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 100 + description: Battery discharge level (%) where warning event raised. + + dlg,crit-soc-level: + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 100 + description: | + Battery discharge level (%) where critical event raised. + This value should be lower than the warning level. + +required: + - compatible + +additionalProperties: false + +examples: + - | + pmic { + battery { + compatible = "dlg,da9150-fuel-gauge"; + dlg,update-interval = <10000>; + dlg,warn-soc-level = /bits/ 8 <15>; + dlg,crit-soc-level = /bits/ 8 <5>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/isp1704.txt b/Documentation/devicetree/bindings/power/supply/isp1704.txt deleted file mode 100644 index fa3596907967..000000000000 --- a/Documentation/devicetree/bindings/power/supply/isp1704.txt +++ /dev/null @@ -1,17 +0,0 @@ -Binding for NXP ISP1704 USB Charger Detection - -Required properties: -- compatible: Should contain one of the following: - * "nxp,isp1704" -- nxp,enable-gpio: Should contain a phandle + gpio-specifier - to the GPIO pin connected to the chip's enable pin. -- usb-phy: Should contain a phandle to the USB PHY - the ISP1704 is connected to. - -Example: - -isp1704 { - compatible = "nxp,isp1704"; - nxp,enable-gpio = <&gpio3 3 GPIO_ACTIVE_LOW>; - usb-phy = <&usb2_phy>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/isp1704.yaml b/Documentation/devicetree/bindings/power/supply/isp1704.yaml new file mode 100644 index 000000000000..4c91da70011d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/isp1704.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/isp1704.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for NXP ISP1704 USB Charger Detection + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: nxp,isp1704 + + nxp,enable-gpio: + maxItems: 1 + description: GPIO connected to the chip's enable pin + + usb-phy: + $ref: /schemas/types.yaml#/definitions/phandle + description: USB PHY the ISP1704 is connected to + +required: + - compatible + - nxp,enable-gpio + - usb-phy + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + charger-detect { + compatible = "nxp,isp1704"; + nxp,enable-gpio = <&gpio3 3 GPIO_ACTIVE_LOW>; + usb-phy = <&usb2_phy>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/lego,ev3-battery.yaml b/Documentation/devicetree/bindings/power/supply/lego,ev3-battery.yaml new file mode 100644 index 000000000000..518eabb63588 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/lego,ev3-battery.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/lego,ev3-battery.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: LEGO MINDSTORMS EV3 Battery + +maintainers: + - David Lechner <david@lechnology.com> + - Sebastian Reichel <sre@kernel.org> + +description: | + LEGO MINDSTORMS EV3 has some built-in capability for monitoring the battery. + It uses 6 AA batteries or a special Li-ion rechargeable battery pack that is + detected by a key switch in the battery compartment. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: lego,ev3-battery + + io-channels: + items: + - description: ADC channel for battery voltage + - description: ADC channel for battery current + + io-channel-names: + items: + - const: voltage + - const: current + + rechargeable-gpios: + maxItems: 1 + description: Rechargeable battery indication gpio + +required: + - compatible + - io-channels + - io-channel-names + - rechargeable-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + battery { + compatible = "lego,ev3-battery"; + io-channels = <&adc 4>, <&adc 3>; + io-channel-names = "voltage", "current"; + rechargeable-gpios = <&gpio 136 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt b/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt deleted file mode 100644 index 5485633b1faa..000000000000 --- a/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt +++ /dev/null @@ -1,21 +0,0 @@ -LEGO MINDSTORMS EV3 Battery -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -LEGO MINDSTORMS EV3 has some built-in capability for monitoring the battery. -It uses 6 AA batteries or a special Li-ion rechargeable battery pack that is -detected by a key switch in the battery compartment. - -Required properties: - - compatible: Must be "lego,ev3-battery" - - io-channels: phandles to analog inputs for reading voltage and current - - io-channel-names: Must be "voltage", "current" - - rechargeable-gpios: phandle to the rechargeable battery indication gpio - -Example: - - battery { - compatible = "lego,ev3-battery"; - io-channels = <&adc 4>, <&adc 3>; - io-channel-names = "voltage", "current"; - rechargeable-gpios = <&gpio 136 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/lltc,lt3651-charger.yaml b/Documentation/devicetree/bindings/power/supply/lltc,lt3651-charger.yaml new file mode 100644 index 000000000000..e2d8d2aebb73 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/lltc,lt3651-charger.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/lltc,lt3651-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Analog Devices LT3651 Charger Power Supply bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - lltc,lt3651-charger + - lltc,ltc3651-charger # deprecated, use lltc,lt3651-charger + + lltc,acpr-gpios: + maxItems: 1 + + lltc,fault-gpios: + maxItems: 1 + + lltc,chrg-gpios: + maxItems: 1 + +required: + - compatible + - lltc,acpr-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + charger { + compatible = "lltc,lt3651-charger"; + lltc,acpr-gpios = <&gpio0 68 GPIO_ACTIVE_LOW>; + lltc,fault-gpios = <&gpio0 64 GPIO_ACTIVE_LOW>; + lltc,chrg-gpios = <&gpio0 63 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/lltc,ltc294x.yaml b/Documentation/devicetree/bindings/power/supply/lltc,ltc294x.yaml new file mode 100644 index 000000000000..043bf378040f --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/lltc,ltc294x.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/lltc,ltc294x.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for LTC2941, LTC2942, LTC2943 and LTC2944 battery fuel gauges + +description: | + All chips measure battery capacity. + The LTC2942 is pin compatible with the LTC2941, it adds voltage and + temperature monitoring, and is runtime detected. LTC2943 and LTC2944 + are software compatible, uses a slightly different conversion formula + for the charge counter and adds voltage, current and temperature monitoring. + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - lltc,ltc2941 + - lltc,ltc2942 + - lltc,ltc2943 + - lltc,ltc2944 + + reg: + maxItems: 1 + + lltc,resistor-sense: + $ref: /schemas/types.yaml#/definitions/int32 + description: | + Sense resistor value in milli-ohms. + Can be negative value when the battery has been connected to the wrong end of the resistor. + + lltc,prescaler-exponent: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + The prescaler exponent as explained in the datasheet. + This determines the range and accuracy of the gauge. + The value is programmed into the chip only if it differs from the current setting. + The setting is lost when the battery is disconnected. + +required: + - compatible + - reg + - lltc,resistor-sense + - lltc,prescaler-exponent + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + battery@64 { + compatible = "lltc,ltc2943"; + reg = <0x64>; + lltc,resistor-sense = <15>; + lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt b/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt deleted file mode 100644 index 0355a4b68f79..000000000000 --- a/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt +++ /dev/null @@ -1,43 +0,0 @@ -Binding for TI/National Semiconductor LP8727 Charger - -Required properties: -- compatible: "ti,lp8727" -- reg: I2C slave address 27h - -Optional properties: -- interrupts: interrupt specifier (see interrupt binding[0]) -- debounce-ms: interrupt debounce time. (u32) - -AC and USB charging parameters -- charger-type: "ac" or "usb" (string) -- eoc-level: value of 'enum lp8727_eoc_level' (u8) -- charging-current: value of 'enum lp8727_ichg' (u8) - -[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - -Example) - -lp8727@27 { - compatible = "ti,lp8727"; - reg = <0x27>; - - /* GPIO 134 is used for LP8728 interrupt pin */ - interrupt-parent = <&gpio5>; /* base = 128 */ - interrupts = <6 0x2>; /* offset = 6, falling edge type */ - - debounce-ms = <300>; - - /* AC charger: 5% EOC and 500mA charging current */ - ac { - charger-type = "ac"; - eoc-level = /bits/ 8 <0>; - charging-current = /bits/ 8 <4>; - }; - - /* USB charger: 10% EOC and 400mA charging current */ - usb { - charger-type = "usb"; - eoc-level = /bits/ 8 <1>; - charging-current = /bits/ 8 <2>; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/lt3651-charger.txt b/Documentation/devicetree/bindings/power/supply/lt3651-charger.txt deleted file mode 100644 index 40811ff8de10..000000000000 --- a/Documentation/devicetree/bindings/power/supply/lt3651-charger.txt +++ /dev/null @@ -1,29 +0,0 @@ -Analog Devices LT3651 Charger Power Supply bindings: lt3651-charger - -Required properties: -- compatible: Should contain one of the following: - * "lltc,ltc3651-charger", (DEPRECATED: Use "lltc,lt3651-charger") - * "lltc,lt3651-charger" - - lltc,acpr-gpios: Connect to ACPR output. See remark below. - -Optional properties: - - lltc,fault-gpios: Connect to FAULT output. See remark below. - - lltc,chrg-gpios: Connect to CHRG output. See remark below. - -The lt3651 outputs are open-drain type and active low. The driver assumes the -GPIO reports "active" when the output is asserted, so if the pins have been -connected directly, the GPIO flags should be set to active low also. - -The driver will attempt to aquire interrupts for all GPIOs to detect changes in -line state. If the system is not capabale of providing interrupts, the driver -cannot report changes and userspace will need to periodically read the sysfs -attributes to detect changes. - -Example: - - charger: battery-charger { - compatible = "lltc,lt3651-charger"; - lltc,acpr-gpios = <&gpio0 68 GPIO_ACTIVE_LOW>; - lltc,fault-gpios = <&gpio0 64 GPIO_ACTIVE_LOW>; - lltc,chrg-gpios = <&gpio0 63 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/ltc2941.txt b/Documentation/devicetree/bindings/power/supply/ltc2941.txt deleted file mode 100644 index 3b9ba147b041..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ltc2941.txt +++ /dev/null @@ -1,28 +0,0 @@ -binding for LTC2941, LTC2942, LTC2943 and LTC2944 battery gauges - -All chips measure battery capacity. -The LTC2942 is pin compatible with the LTC2941, it adds voltage and -temperature monitoring, and is runtime detected. LTC2943 and LTC2944 -is software compatible, uses a slightly different conversion formula -for the charge counter and adds voltage, current and temperature monitoring. - -Required properties: -- compatible: Should contain "lltc,ltc2941", "lltc,ltc2942", "lltc,ltc2943" - or "lltc,ltc2944" which also indicates the type of I2C chip attached. -- reg: The 7-bit I2C address. -- lltc,resistor-sense: The sense resistor value in milli-ohms. Can be a 32-bit - negative value when the battery has been connected to the wrong end of the - resistor. -- lltc,prescaler-exponent: The prescaler exponent as explained in the datasheet. - This determines the range and accuracy of the gauge. The value is programmed - into the chip only if it differs from the current setting. The setting is - lost when the battery is disconnected. - -Example from the Topic Miami Florida board: - - fuelgauge: ltc2943@64 { - compatible = "lltc,ltc2943"; - reg = <0x64>; - lltc,resistor-sense = <15>; - lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ - }; diff --git a/Documentation/devicetree/bindings/power/supply/ltc4162-l.yaml b/Documentation/devicetree/bindings/power/supply/ltc4162-l.yaml index 1f88c9e013f4..6d7aa97a6475 100644 --- a/Documentation/devicetree/bindings/power/supply/ltc4162-l.yaml +++ b/Documentation/devicetree/bindings/power/supply/ltc4162-l.yaml @@ -29,12 +29,10 @@ properties: description: I2C address of the charger. lltc,rsnsb-micro-ohms: - $ref: /schemas/types.yaml#/definitions/uint32 description: Battery sense resistor in microohm. minimum: 1000 lltc,rsnsi-micro-ohms: - $ref: /schemas/types.yaml#/definitions/uint32 description: Input current sense resistor in microohm. minimum: 1000 diff --git a/Documentation/devicetree/bindings/power/supply/max17040_battery.txt b/Documentation/devicetree/bindings/power/supply/max17040_battery.txt deleted file mode 100644 index c802f664b508..000000000000 --- a/Documentation/devicetree/bindings/power/supply/max17040_battery.txt +++ /dev/null @@ -1,52 +0,0 @@ -max17040_battery -~~~~~~~~~~~~~~~~ - -Required properties : - - compatible : "maxim,max17040", "maxim,max17041", "maxim,max17043", - "maxim,max17044", "maxim,max17048", "maxim,max17049", - "maxim,max17058", "maxim,max17059" or "maxim,max77836-battery" - - reg: i2c slave address - -Optional properties : -- maxim,alert-low-soc-level : The alert threshold that sets the state of - charge level (%) where an interrupt is - generated. Can be configured from 1 up to 32 - (%). If skipped the power up default value of - 4 (%) will be used. -- maxim,double-soc : Certain devices return double the capacity. - Specify this boolean property to divide the - reported value in 2 and thus normalize it. - SOC == State of Charge == Capacity. -- maxim,rcomp : A value to compensate readings for various - battery chemistries and operating temperatures. - max17040,41 have 2 byte rcomp, default to - 0x97 0x00. All other devices have one byte - rcomp, default to 0x97. -- interrupts : Interrupt line see Documentation/devicetree/ - bindings/interrupt-controller/interrupts.txt -- wakeup-source : This device has wakeup capabilities. Use this - property to use alert low SOC level interrupt - as wake up source. - -Optional properties support interrupt functionality for alert low state of -charge level, present in some ICs in the same family, and should be used with -compatible "maxim,max77836-battery". - -Example: - - battery-fuel-gauge@36 { - compatible = "maxim,max77836-battery"; - reg = <0x36>; - maxim,alert-low-soc-level = <10>; - interrupt-parent = <&gpio7>; - interrupts = <2 IRQ_TYPE_EDGE_FALLING>; - wakeup-source; - }; - - battery-fuel-gauge@36 { - compatible = "maxim,max17048"; - reg = <0x36>; - maxim,rcomp = /bits/ 8 <0x56>; - maxim,alert-low-soc-level = <10>; - maxim,double-soc; - }; diff --git a/Documentation/devicetree/bindings/power/supply/max17042_battery.txt b/Documentation/devicetree/bindings/power/supply/max17042_battery.txt deleted file mode 100644 index f34c5daae9af..000000000000 --- a/Documentation/devicetree/bindings/power/supply/max17042_battery.txt +++ /dev/null @@ -1,35 +0,0 @@ -max17042_battery -~~~~~~~~~~~~~~~~ - -Required properties : - - compatible : one of the following - * "maxim,max17042" - * "maxim,max17047" - * "maxim,max17050" - * "maxim,max17055" - -Optional properties : - - maxim,rsns-microohm : Resistance of rsns resistor in micro Ohms - (datasheet-recommended value is 10000). - Defining this property enables current-sense functionality. - -Optional threshold properties : - If skipped the condition won't be reported. - - maxim,cold-temp : Temperature threshold to report battery - as cold (in tenths of degree Celsius). - - maxim,over-heat-temp : Temperature threshold to report battery - as over heated (in tenths of degree Celsius). - - maxim,dead-volt : Voltage threshold to report battery - as dead (in mV). - - maxim,over-volt : Voltage threshold to report battery - as over voltage (in mV). - -Example: - - battery-charger@36 { - compatible = "maxim,max17042"; - reg = <0x36>; - maxim,rsns-microohm = <10000>; - maxim,over-heat-temp = <600>; - maxim,over-volt = <4300>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/max8903-charger.txt b/Documentation/devicetree/bindings/power/supply/max8903-charger.txt deleted file mode 100644 index bab947fef025..000000000000 --- a/Documentation/devicetree/bindings/power/supply/max8903-charger.txt +++ /dev/null @@ -1,24 +0,0 @@ -Maxim Semiconductor MAX8903 Battery Charger bindings - -Required properties: -- compatible: "maxim,max8903" for MAX8903 Battery Charger -- dok-gpios: Valid DC power has been detected (active low, input), optional if uok-gpios is provided -- uok-gpios: Valid USB power has been detected (active low, input), optional if dok-gpios is provided - -Optional properties: -- cen-gpios: Charge enable pin (active low, output) -- chg-gpios: Charger status pin (active low, input) -- flt-gpios: Fault pin (active low, output) -- dcm-gpios: Current limit mode setting (DC=1 or USB=0, output) -- usus-gpios: USB suspend pin (active high, output) - - -Example: - - max8903-charger { - compatible = "maxim,max8903"; - dok-gpios = <&gpio2 3 GPIO_ACTIVE_LOW>; - flt-gpios = <&gpio2 2 GPIO_ACTIVE_LOW>; - chg-gpios = <&gpio3 15 GPIO_ACTIVE_LOW>; - cen-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,ds2760.txt b/Documentation/devicetree/bindings/power/supply/maxim,ds2760.txt deleted file mode 100644 index 55967a0bee11..000000000000 --- a/Documentation/devicetree/bindings/power/supply/maxim,ds2760.txt +++ /dev/null @@ -1,26 +0,0 @@ -Devicetree bindings for Maxim DS2760 -==================================== - -The ds2760 is a w1 slave device and must hence have its sub-node in DT -under a w1 bus master node. - -The device exposes a power supply, so the details described in -Documentation/devicetree/bindings/power/supply/power_supply.txt apply. - -Required properties: -- compatible: must be "maxim,ds2760" - -Optional properties: -- power-supplies: Refers to one or more power supplies connected to - this battery. -- maxim,pmod-enabled: This boolean property enables the DS2760 to enter - sleep mode when the DQ line goes low for greater - than 2 seconds and leave sleep Mode when the DQ - line goes high. -- maxim,cache-time-ms: Time im milliseconds to cache the data for. When - this time expires, the values are read again from - the hardware. Defaults to 1000. -- rated-capacity-microamp-hours: - The rated capacity of the battery, in mAh. - If not specified, the value stored in the - non-volatile chip memory is used. diff --git a/Documentation/devicetree/bindings/power/supply/maxim,ds2760.yaml b/Documentation/devicetree/bindings/power/supply/maxim,ds2760.yaml new file mode 100644 index 000000000000..818647edf63d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,ds2760.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/maxim,ds2760.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Maxim DS2760 DT bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: | + The ds2760 is a w1 slave device and must hence have its sub-node in + DT under a w1 bus master node. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,ds2760 + + maxim,pmod-enabled: + description: | + Allow the DS2760 to enter sleep mode when the DQ line goes low for more than 2 seconds + and leave sleep Mode when the DQ line goes high. + type: boolean + + maxim,cache-time-ms: + description: | + Time im milliseconds to cache the data for. + When this time expires, the values are read again from the hardware. + Defaults to 1000. + + rated-capacity-microamp-hours: + description: | + The rated capacity of the battery, in mAh. + If not specified, the value stored in the non-volatile chip memory is used. + +required: + - compatible + +unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max14656.txt b/Documentation/devicetree/bindings/power/supply/maxim,max14656.txt deleted file mode 100644 index f956247d493e..000000000000 --- a/Documentation/devicetree/bindings/power/supply/maxim,max14656.txt +++ /dev/null @@ -1,23 +0,0 @@ -Maxim MAX14656 / AL32 USB Charger Detector - -Required properties : -- compatible : "maxim,max14656"; -- reg: i2c slave address -- interrupts: interrupt line - -Example: - -&i2c2 { - clock-frequency = <50000>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_i2c2>; - - max14656@35 { - compatible = "maxim,max14656"; - reg = <0x35>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_charger_detect>; - interrupt-parent = <&gpio6>; - interrupts = <26 IRQ_TYPE_LEVEL_HIGH>; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max14656.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max14656.yaml new file mode 100644 index 000000000000..0a41078ebd99 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max14656.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/maxim,max14656.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Maxim MAX14656 DT bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,max14656 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger-detector@35 { + compatible = "maxim,max14656"; + reg = <0x35>; + interrupt-parent = <&gpio6>; + interrupts = <26 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml new file mode 100644 index 000000000000..de91cf3f058c --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/maxim,max17040.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Maxim 17040 fuel gauge series + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - maxim,max17040 + - maxim,max17041 + - maxim,max17043 + - maxim,max17044 + - maxim,max17048 + - maxim,max17049 + - maxim,max17058 + - maxim,max17059 + - maxim,max77836-battery + + reg: + maxItems: 1 + + maxim,alert-low-soc-level: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 32 + description: | + The alert threshold that sets the state of charge level (%) where an interrupt is generated. + If skipped the power up default value of 4 (%) will be used. + + maxim,double-soc: + type: boolean + description: | + Certain devices return double the capacity. + Specify this to divide the reported value in 2 and thus normalize it. + SoC == State of Charge == Capacity. + + maxim,rcomp: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + A value to compensate readings for various battery chemistries and operating temperatures. + max17040,41 have 2 byte rcomp, default to 0x97 0x00. + All other devices have one byte rcomp, default to 0x97. + + interrupts: + maxItems: 1 + + wakeup-source: + type: boolean + description: | + Use this property to use alert low SoC level interrupt as wake up source. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + battery@36 { + compatible = "maxim,max17048"; + reg = <0x36>; + maxim,rcomp = /bits/ 8 <0x56>; + maxim,alert-low-soc-level = <10>; + maxim,double-soc; + }; + }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + battery@36 { + compatible = "maxim,max77836-battery"; + reg = <0x36>; + maxim,alert-low-soc-level = <10>; + interrupt-parent = <&gpio7>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + wakeup-source; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml new file mode 100644 index 000000000000..c70f05ea6d27 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/maxim,max17042.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Maxim 17042 fuel gauge series + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - maxim,max17042 + - maxim,max17047 + - maxim,max17050 + - maxim,max17055 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + maxim,rsns-microohm: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Resistance of rsns resistor in micro Ohms (datasheet-recommended value is 10000). + Defining this property enables current-sense functionality. + + maxim,cold-temp: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Temperature threshold to report battery as cold (in tenths of degree Celsius). + Default is not to report cold events. + + maxim,over-heat-temp: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Temperature threshold to report battery as over heated (in tenths of degree Celsius). + Default is not to report over heating events. + + maxim,dead-volt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Voltage threshold to report battery as dead (in mV). + Default is not to report dead battery events. + + maxim,over-volt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Voltage threshold to report battery as over voltage (in mV). + Default is not to report over-voltage events. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + battery@36 { + compatible = "maxim,max17042"; + reg = <0x36>; + maxim,rsns-microohm = <10000>; + maxim,over-heat-temp = <600>; + maxim,over-volt = <4300>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max8903.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max8903.yaml new file mode 100644 index 000000000000..4828ca0842ae --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max8903.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/maxim,max8903.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Maxim Semiconductor MAX8903 Battery Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,max8903 + + dok-gpios: + maxItems: 1 + description: Valid DC power has been detected (active low, input) + + uok-gpios: + maxItems: 1 + description: Valid USB power has been detected (active low, input) + + cen-gpios: + maxItems: 1 + description: Charge enable pin (active low, output) + + chg-gpios: + maxItems: 1 + description: Charger status pin (active low, input) + + flt-gpios: + maxItems: 1 + description: Fault pin (active low, output) + + dcm-gpios: + maxItems: 1 + description: Current limit mode setting (DC=1 or USB=0, output) + + usus-gpios: + maxItems: 1 + description: USB suspend pin (active high, output) + +required: + - compatible + +anyOf: + - required: + - dok-gpios + - required: + - uok-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + charger { + compatible = "maxim,max8903"; + dok-gpios = <&gpio2 3 GPIO_ACTIVE_LOW>; + flt-gpios = <&gpio2 2 GPIO_ACTIVE_LOW>; + chg-gpios = <&gpio3 15 GPIO_ACTIVE_LOW>; + cen-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.txt b/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.txt deleted file mode 100644 index 1d284ad816bf..000000000000 --- a/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.txt +++ /dev/null @@ -1,27 +0,0 @@ -Microchip UCS1002 USB Port Power Controller - -Required properties: -- compatible : Should be "microchip,ucs1002"; -- reg : I2C slave address - -Optional properties: -- interrupts : A list of interrupts lines present (could be either - corresponding to A_DET# pin, ALERT# pin, or both) -- interrupt-names : A list of interrupt names. Should contain (if - present): - - "a_det" for line connected to A_DET# pin - - "alert" for line connected to ALERT# pin - Both are expected to be IRQ_TYPE_EDGE_BOTH -Example: - -&i2c3 { - charger@32 { - compatible = "microchip,ucs1002"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_ucs1002_pins>; - reg = <0x32>; - interrupts-extended = <&gpio5 2 IRQ_TYPE_EDGE_BOTH>, - <&gpio3 21 IRQ_TYPE_EDGE_BOTH>; - interrupt-names = "a_det", "alert"; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.yaml b/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.yaml new file mode 100644 index 000000000000..b9bd1591ed7e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/microchip,ucs1002.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/microchip,ucs1002.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip UCS1002 USB Port Power Controller + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +properties: + compatible: + const: microchip,ucs1002 + + reg: + maxItems: 1 + + interrupts: + maxItems: 2 + + interrupt-names: + oneOf: + - items: + - const: a_det + - const: alert + - const: a_det + - const: alert + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@32 { + compatible = "microchip,ucs1002"; + reg = <0x32>; + interrupts-extended = <&gpio5 2 IRQ_TYPE_EDGE_BOTH>, + <&gpio3 21 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "a_det", "alert"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/nokia,n900-battery.yaml b/Documentation/devicetree/bindings/power/supply/nokia,n900-battery.yaml new file mode 100644 index 000000000000..4a1489f2b28d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/nokia,n900-battery.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/nokia,n900-battery.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Nokia N900 battery + +maintainers: + - Pali Rohár <pali@kernel.org> + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: nokia,n900-battery + + io-channels: + items: + - description: ADC channel for temperature reading + - description: ADC channel for battery size identification + - description: ADC channel to measure the battery voltage + + io-channel-names: + items: + - const: temp + - const: bsi + - const: vbat + +required: + - compatible + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + battery { + compatible = "nokia,n900-battery"; + io-channels = <&twl4030_madc 0>, + <&twl4030_madc 4>, + <&twl4030_madc 12>; + io-channel-names = "temp", + "bsi", + "vbat"; + }; diff --git a/Documentation/devicetree/bindings/power/supply/olpc-battery.yaml b/Documentation/devicetree/bindings/power/supply/olpc-battery.yaml new file mode 100644 index 000000000000..0bd7bf3b8e1b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/olpc-battery.yaml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/olpc-battery.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: OLPC Battery + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + oneOf: + - items: + - const: olpc,xo1.5-battery + - const: olpc,xo1-battery + - items: + - const: olpc,xo1-battery + +required: + - compatible + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/olpc_battery.txt b/Documentation/devicetree/bindings/power/supply/olpc_battery.txt deleted file mode 100644 index 8d87d6b35a98..000000000000 --- a/Documentation/devicetree/bindings/power/supply/olpc_battery.txt +++ /dev/null @@ -1,5 +0,0 @@ -OLPC battery -~~~~~~~~~~~~ - -Required properties: - - compatible : "olpc,xo1-battery" or "olpc,xo1.5-battery" diff --git a/Documentation/devicetree/bindings/power/supply/power-supply.yaml b/Documentation/devicetree/bindings/power/supply/power-supply.yaml index c5c55f627251..259760167759 100644 --- a/Documentation/devicetree/bindings/power/supply/power-supply.yaml +++ b/Documentation/devicetree/bindings/power/supply/power-supply.yaml @@ -18,25 +18,3 @@ properties: additionalProperties: true -examples: - - | - power { - #address-cells = <1>; - #size-cells = <0>; - - usb_charger:charger@e { - compatible = "some,usb-charger"; - reg = <0xe>; - }; - - ac_charger:charger@c { - compatible = "some,ac-charger"; - reg = <0xc>; - }; - - battery:battery@b { - compatible = "some,battery"; - reg = <0xb>; - power-supplies = <&usb_charger>, <&ac_charger>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/power_supply.txt b/Documentation/devicetree/bindings/power/supply/power_supply.txt deleted file mode 100644 index d9693e054509..000000000000 --- a/Documentation/devicetree/bindings/power/supply/power_supply.txt +++ /dev/null @@ -1,2 +0,0 @@ -This binding has been converted to yaml please see power-supply.yaml in this -directory. diff --git a/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt b/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt deleted file mode 100644 index 747899223262..000000000000 --- a/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt +++ /dev/null @@ -1,48 +0,0 @@ -Qualcomm Coincell Charger: - -The hardware block controls charging for a coincell or capacitor that is -used to provide power backup for certain features of the power management -IC (PMIC) - -- compatible: - Usage: required - Value type: <string> - Definition: must be: "qcom,pm8941-coincell" - -- reg: - Usage: required - Value type: <u32> - Definition: base address of the coincell charger registers - -- qcom,rset-ohms: - Usage: required - Value type: <u32> - Definition: resistance (in ohms) for current-limiting resistor - must be one of: 800, 1200, 1700, 2100 - -- qcom,vset-millivolts: - Usage: required - Value type: <u32> - Definition: voltage (in millivolts) to apply for charging - must be one of: 2500, 3000, 3100, 3200 - -- qcom,charger-disable: - Usage: optional - Value type: <boolean> - Definition: defining this property disables charging - -This charger is a sub-node of one of the 8941 PMIC blocks, and is specified -as a child node in DTS of that node. See ../mfd/qcom,spmi-pmic.txt and -../mfd/qcom-pm8xxx.txt - -Example: - - pm8941@0 { - coincell@2800 { - compatible = "qcom,pm8941-coincell"; - reg = <0x2800>; - - qcom,rset-ohms = <2100>; - qcom,vset-millivolts = <3000>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml new file mode 100644 index 000000000000..bc8904872d1b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml @@ -0,0 +1,169 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8941-charger.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Switch-Mode Battery Charger and Boost + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +properties: + compatible: + const: qcom,pm8941-charger + + reg: + maxItems: 1 + + interrupts: + items: + - description: charge done + - description: charge fast mode + - description: charge trickle mode + - description: battery temperature ok + - description: battery present + - description: charger disconnected + - description: USB-in valid + - description: DC-in valid + + interrupt-names: + items: + - const: chg-done + - const: chg-fast + - const: chg-trkl + - const: bat-temp-ok + - const: bat-present + - const: chg-gone + - const: usb-valid + - const: dc-valid + + qcom,fast-charge-current-limit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 100000 + maximum: 3000000 + description: Maximum charge current in uA; May be clamped to safety limits; Defaults to 1A + + qcom,fast-charge-low-threshold-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 2100000 + maximum: 3600000 + description: | + Battery voltage limit in uV above which fast charging may operate; Defaults to 3.2V + Below this value linear or switch-mode auto-trickle-charging will operate. + + qcom,fast-charge-high-threshold-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 3240000 + maximum: 5000000 + description: | + Battery voltage limit in uV below which fast charging may operate; Defaults to 4.2V + The fast charger will attempt to charge the battery to this voltage. + May be clamped to safety limits. + + qcom,fast-charge-safe-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 3240000 + maximum: 5000000 + description: | + Maximum safe battery voltage in uV; May be pre-set by bootloader, in which case, + setting this will harmlessly fail. The property 'fast-charge-high-watermark' will + be clamped by this value. Defaults to 4.2V. + + qcom,fast-charge-safe-current: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 100000 + maximum: 3000000 + description: | + Maximum safe battery charge current in uA; May pre-set by bootloader, in which case, + setting this will harmlessly fail. The property 'qcom,fast-charge-current-limit' + will be clamped by this value. Defaults to 1A. + + qcom,auto-recharge-threshold-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 3240000 + maximum: 5000000 + description: | + Battery voltage limit in uV below which auto-recharge functionality will restart charging + after end-of-charge; The high cutoff limit for auto-recharge is 5% above this value. + Defaults to 4.1V. + + qcom,minimum-input-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 4200000 + maximum: 9600000 + description: | + Input voltage level in uV above which charging may operate. Defaults to 4.3V. + + qcom,dc-current-limit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 100000 + maximum: 2500000 + description: | + Default DC charge current limit in uA. Defaults to 100mA. + + qcom,disable-dc: + type: boolean + description: Disable DC charger + + qcom,jeita-extended-temp-range: + type: boolean + description: | + Enable JEITA extended temperature range; This does *not* adjust the maximum charge + voltage or current in the extended temperature range. It only allows charging when + the battery is in the extended temperature range. Voltage/current regulation must + be done externally to fully comply with the JEITA safety guidelines if this flag + is set. + + usb-otg-in-supply: + description: Reference to the regulator supplying power to the USB_OTG_IN pin. + + otg-vbus: + type: object + description: | + This node defines a regulator used to control the direction of VBUS voltage. + Specifically whether to supply voltage to VBUS for host mode operation of the OTG port, + or allow input voltage from external VBUS for charging. In the hardware, the supply for + this regulator comes from usb_otg_in-supply. + +required: + - compatible + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + charger@1000 { + compatible = "qcom,pm8941-charger"; + reg = <0x1000>; + interrupts = <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 4 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x14 1 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "chg-done", + "chg-fast", + "chg-trkl", + "bat-temp-ok", + "bat-present", + "chg-gone", + "usb-valid", + "dc-valid"; + qcom,fast-charge-current-limit = <1000000>; + qcom,dc-current-limit = <1000000>; + usb-otg-in-supply = <&pm8941_5vs1>; + + otg-vbus {}; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-coincell.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-coincell.yaml new file mode 100644 index 000000000000..0450f4dd4e51 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-coincell.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8941-coincell.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Coincell Charger + +description: | + The hardware block controls charging for a coincell or capacitor that is + used to provide power backup for certain features of the power management + IC (PMIC) + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +properties: + compatible: + const: qcom,pm8941-coincell + + reg: + maxItems: 1 + + qcom,rset-ohms: + description: resistance (in ohms) for current-limiting resistor + enum: [ 800, 1200, 1700, 2100 ] + + qcom,vset-millivolts: + $ref: /schemas/types.yaml#/definitions/uint32 + description: voltage (in millivolts) to apply for charging + enum: [ 2500, 3000, 3100, 3200 ] + + qcom,charger-disable: + type: boolean + description: defining this property disables charging + +required: + - compatible + - reg + - qcom,rset-ohms + - qcom,vset-millivolts + +additionalProperties: false + +examples: + - | + pmic { + #address-cells = <1>; + #size-cells = <0>; + + charger@2800 { + compatible = "qcom,pm8941-coincell"; + reg = <0x2800>; + qcom,rset-ohms = <2100>; + qcom,vset-millivolts = <3000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt b/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt deleted file mode 100644 index 06f8a5ddb68e..000000000000 --- a/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt +++ /dev/null @@ -1,150 +0,0 @@ -Qualcomm Switch-Mode Battery Charger and Boost - -PROPERTIES -- compatible: - Usage: required - Value type: <stringlist> - Description: Must be one of: - - "qcom,pm8941-charger" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Description: Base address of registers for SMBB block - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Description: The format of the specifier is defined by the binding document - describing the node's interrupt parent. Must contain one - specifier for each of the following interrupts, in order: - - charge done - - charge fast mode - - charge trickle mode - - battery temperature ok - - battery present - - charger disconnected - - USB-in valid - - DC-in valid - -- interrupt-names: - Usage: required - Value type: <stringlist> - Description: Must contain the following list, strictly ordered: - "chg-done", - "chg-fast", - "chg-trkl", - "bat-temp-ok", - "bat-present", - "chg-gone", - "usb-valid", - "dc-valid" - -- qcom,fast-charge-current-limit: - Usage: optional (default: 1A, or pre-configured value) - Value type: <u32>; uA; range [100mA : 3A] - Description: Maximum charge current; May be clamped to safety limits. - -- qcom,fast-charge-low-threshold-voltage: - Usage: optional (default: 3.2V, or pre-configured value) - Value type: <u32>; uV; range [2.1V : 3.6V] - Description: Battery voltage limit above which fast charging may operate; - Below this value linear or switch-mode auto-trickle-charging - will operate. - -- qcom,fast-charge-high-threshold-voltage: - Usage: optional (default: 4.2V, or pre-configured value) - Value type: <u32>; uV; range [3.24V : 5V] - Description: Battery voltage limit below which fast charging may operate; - The fast charger will attempt to charge the battery to this - voltage. May be clamped to safety limits. - -- qcom,fast-charge-safe-voltage: - Usage: optional (default: 4.2V, or pre-configured value) - Value type: <u32>; uV; range [3.24V : 5V] - Description: Maximum safe battery voltage; May be pre-set by bootloader, in - which case, setting this will harmlessly fail. The property - 'fast-charge-high-watermark' will be clamped by this value. - -- qcom,fast-charge-safe-current: - Usage: optional (default: 1A, or pre-configured value) - Value type: <u32>; uA; range [100mA : 3A] - Description: Maximum safe battery charge current; May pre-set by bootloader, - in which case, setting this will harmlessly fail. The property - 'qcom,fast-charge-current-limit' will be clamped by this value. - -- qcom,auto-recharge-threshold-voltage: - Usage: optional (default: 4.1V, or pre-configured value) - Value type: <u32>; uV; range [3.24V : 5V] - Description: Battery voltage limit below which auto-recharge functionality - will restart charging after end-of-charge; The high cutoff - limit for auto-recharge is 5% above this value. - -- qcom,minimum-input-voltage: - Usage: optional (default: 4.3V, or pre-configured value) - Value type: <u32>; uV; range [4.2V : 9.6V] - Description: Input voltage level above which charging may operate - -- qcom,dc-current-limit: - Usage: optional (default: 100mA, or pre-configured value) - Value type: <u32>; uA; range [100mA : 2.5A] - Description: Default DC charge current limit - -- qcom,disable-dc: - Usage: optional (default: false) - Value type: boolean: <u32> or <empty> - Description: Disable DC charger - -- qcom,jeita-extended-temp-range: - Usage: optional (default: false) - Value type: boolean: <u32> or <empty> - Description: Enable JEITA extended temperature range; This does *not* - adjust the maximum charge voltage or current in the extended - temperature range. It only allows charging when the battery - is in the extended temperature range. Voltage/current - regulation must be done externally to fully comply with - the JEITA safety guidelines if this flag is set. - -- usb_otg_in-supply: - Usage: optional - Value type: <phandle> - Description: Reference to the regulator supplying power to the USB_OTG_IN - pin. - -child nodes: -- otg-vbus: - Usage: optional - Description: This node defines a regulator used to control the direction - of VBUS voltage - specifically: whether to supply voltage - to VBUS for host mode operation of the OTG port, or allow - input voltage from external VBUS for charging. In the - hardware, the supply for this regulator comes from - usb_otg_in-supply. - -EXAMPLE -charger@1000 { - compatible = "qcom,pm8941-charger"; - reg = <0x1000 0x700>; - interrupts = <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x10 4 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x14 1 IRQ_TYPE_EDGE_BOTH>; - interrupt-names = "chg-done", - "chg-fast", - "chg-trkl", - "bat-temp-ok", - "bat-present", - "chg-gone", - "usb-valid", - "dc-valid"; - - qcom,fast-charge-current-limit = <1000000>; - qcom,dc-charge-current-limit = <1000000>; - usb_otg_in-supply = <&pm8941_5vs1>; - - otg-vbus {}; -}; diff --git a/Documentation/devicetree/bindings/power/supply/richtek,rt9455.yaml b/Documentation/devicetree/bindings/power/supply/richtek,rt9455.yaml new file mode 100644 index 000000000000..e1c233462f29 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/richtek,rt9455.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/richtek,rt9455.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Binding for Richtek rt9455 battery charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: richtek,rt9455 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + richtek,output-charge-current: + $ref: /schemas/types.yaml#/definitions/uint32 + description: output current from the charger to the battery, in uA. + + richtek,end-of-charge-percentage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + percent of the output charge current. When the current in constant-voltage phase drops + below output_charge_current x end-of-charge-percentage, charge is terminated. + + richtek,battery-regulation-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum battery voltage in uV. + + richtek,boost-output-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + maximum voltage provided to consumer devices, when the charger is in boost mode, in uV. + + richtek,min-input-voltage-regulation: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + input voltage level in uV, used to decrease voltage level when the over current of the + input power source occurs. This prevents input voltage drop due to insufficient + current provided by the power source. Defaults to 4500000 uV (4.5V). + + richtek,avg-input-current-regulation: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + input current value in uA drained by the charger from the power source. + Defaults to 500000 uA (500mA). + +required: + - compatible + - reg + - interrupts + - richtek,output-charge-current + - richtek,end-of-charge-percentage + - richtek,battery-regulation-voltage + - richtek,boost-output-voltage + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + charger@22 { + compatible = "richtek,rt9455"; + reg = <0x22>; + + interrupt-parent = <&gpio1>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + + richtek,output-charge-current = <500000>; + richtek,end-of-charge-percentage = <10>; + richtek,battery-regulation-voltage = <4200000>; + richtek,boost-output-voltage = <5050000>; + + richtek,min-input-voltage-regulation = <4500000>; + richtek,avg-input-current-regulation = <500000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml b/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml index 9852d2febf65..24b06957b4ca 100644 --- a/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml +++ b/Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml @@ -110,7 +110,7 @@ properties: # multipleOf: 64000 # a charge cycle terminates when the battery voltage is above recharge # threshold, and the current is below this setting (7 in above chart) -# See also Documentation/devicetree/bindings/power/supply/battery.txt +# See also Documentation/devicetree/bindings/power/supply/battery.yaml reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt b/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt deleted file mode 100644 index 1e6107c7578e..000000000000 --- a/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt +++ /dev/null @@ -1,46 +0,0 @@ -Binding for Richtek rt9455 battery charger - -Required properties: -- compatible: it should contain one of the following: - "richtek,rt9455". -- reg: integer, i2c address of the device. -- interrupts: interrupt mapping for GPIO IRQ, it should be - configured with IRQ_TYPE_LEVEL_LOW flag. -- richtek,output-charge-current: integer, output current from the charger to the - battery, in uA. -- richtek,end-of-charge-percentage: integer, percent of the output charge current. - When the current in constant-voltage phase drops - below output_charge_current x end-of-charge-percentage, - charge is terminated. -- richtek,battery-regulation-voltage: integer, maximum battery voltage in uV. -- richtek,boost-output-voltage: integer, maximum voltage provided to consumer - devices, when the charger is in boost mode, in uV. - -Optional properties: -- richtek,min-input-voltage-regulation: integer, input voltage level in uV, used to - decrease voltage level when the over current - of the input power source occurs. - This prevents input voltage drop due to insufficient - current provided by the power source. - Default: 4500000 uV (4.5V) -- richtek,avg-input-current-regulation: integer, input current value in uA drained by the - charger from the power source. - Default: 500000 uA (500mA) - -Example: - -rt9455@22 { - compatible = "richtek,rt9455"; - reg = <0x22>; - - interrupt-parent = <&gpio1>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - - richtek,output-charge-current = <500000>; - richtek,end-of-charge-percentage = <10>; - richtek,battery-regulation-voltage = <4200000>; - richtek,boost-output-voltage = <5050000>; - - richtek,min-input-voltage-regulation = <4500000>; - richtek,avg-input-current-regulation = <500000>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/rx51-battery.txt b/Documentation/devicetree/bindings/power/supply/rx51-battery.txt deleted file mode 100644 index 90438453db58..000000000000 --- a/Documentation/devicetree/bindings/power/supply/rx51-battery.txt +++ /dev/null @@ -1,25 +0,0 @@ -Binding for Nokia N900 battery - -The Nokia N900 battery status can be read via the TWL4030's A/D converter. - -Required properties: -- compatible: Should contain one of the following: - * "nokia,n900-battery" -- io-channels: Should contain IIO channel specifiers - for each element in io-channel-names. -- io-channel-names: Should contain the following values: - * "temp" - The ADC channel for temperature reading - * "bsi" - The ADC channel for battery size identification - * "vbat" - The ADC channel to measure the battery voltage - -Example from Nokia N900: - -battery: n900-battery { - compatible = "nokia,n900-battery"; - io-channels = <&twl4030_madc 0>, - <&twl4030_madc 4>, - <&twl4030_madc 12>; - io-channel-names = "temp", - "bsi", - "vbat"; -}; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml index a90b3601e695..90b9d3d882a4 100644 --- a/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml @@ -12,12 +12,15 @@ maintainers: description: | Battery compatible with the smart battery system specifications -properties: +allOf: + - $ref: power-supply.yaml# +properties: compatible: oneOf: - items: - enum: + - ti,bq20z45 - ti,bq20z65 - ti,bq20z75 - enum: @@ -60,7 +63,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-charger.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-charger.yaml new file mode 100644 index 000000000000..cb73ffa4778e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-charger.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/sbs,sbs-charger.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SBS compliant charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: | + Charger compatible with the smart battery system specifications + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - lltc,ltc4100 + - enum: + - sbs,sbs-charger + - items: + - const: sbs,sbs-charger + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@9 { + compatible = "lltc,ltc4100", "sbs,sbs-charger"; + reg = <0x9>; + interrupt-parent = <&gpio6>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.txt b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.txt deleted file mode 100644 index 4b2195571a49..000000000000 --- a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.txt +++ /dev/null @@ -1,66 +0,0 @@ -Binding for sbs-manager - -Required properties: -- compatible: "<vendor>,<part-number>", "sbs,sbs-charger" as fallback. The part - number compatible string might be used in order to take care of vendor - specific registers. -- reg: integer, i2c address of the device. Should be <0xa>. -Optional properties: -- gpio-controller: Marks the port as GPIO controller. - See "gpio-specifier" in .../devicetree/bindings/gpio/gpio.txt. -- #gpio-cells: Should be <2>. The first cell is the pin number, the second cell - is used to specify optional parameters: - See "gpio-specifier" in .../devicetree/bindings/gpio/gpio.txt. - -From OS view the device is basically an i2c-mux used to communicate with up to -four smart battery devices at address 0xb. The driver actually implements this -behaviour. So standard i2c-mux nodes can be used to register up to four slave -batteries. Channels will be numerated starting from 1 to 4. - -Example: - -batman@a { - compatible = "lltc,ltc1760", "sbs,sbs-manager"; - reg = <0x0a>; - #address-cells = <1>; - #size-cells = <0>; - - gpio-controller; - #gpio-cells = <2>; - - i2c@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <1>; - - battery@b { - compatible = "ti,bq2060", "sbs,sbs-battery"; - reg = <0x0b>; - sbs,battery-detect-gpios = <&batman 1 1>; - }; - }; - - i2c@2 { - #address-cells = <1>; - #size-cells = <0>; - reg = <2>; - - battery@b { - compatible = "ti,bq2060", "sbs,sbs-battery"; - reg = <0x0b>; - sbs,battery-detect-gpios = <&batman 2 1>; - }; - }; - - i2c@3 { - #address-cells = <1>; - #size-cells = <0>; - reg = <3>; - - battery@b { - compatible = "ti,bq2060", "sbs,sbs-battery"; - reg = <0x0b>; - sbs,battery-detect-gpios = <&batman 3 1>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml new file mode 100644 index 000000000000..72e8f274c791 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/sbs,sbs-manager.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SBS compliant manger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - lltc,ltc1760 + - enum: + - sbs,sbs-manager + - items: + - const: sbs,sbs-manager + + reg: + const: 0xa + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + gpio-controller: true + + "#gpio-cells": + const: 2 + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + "^i2c@[1-4]$": + type: object + + allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + batman: battery-manager@a { + compatible = "lltc,ltc1760", "sbs,sbs-manager"; + reg = <0x0a>; + #address-cells = <1>; + #size-cells = <0>; + + gpio-controller; + #gpio-cells = <2>; + + i2c@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + battery@b { + compatible = "ti,bq20z65", "sbs,sbs-battery"; + reg = <0x0b>; + sbs,battery-detect-gpios = <&batman 1 1>; + }; + }; + + i2c@2 { + #address-cells = <1>; + #size-cells = <0>; + reg = <2>; + + battery@b { + compatible = "ti,bq20z65", "sbs,sbs-battery"; + reg = <0x0b>; + sbs,battery-detect-gpios = <&batman 2 1>; + }; + }; + + i2c@3 { + #address-cells = <1>; + #size-cells = <0>; + reg = <3>; + + battery@b { + compatible = "ti,bq20z65", "sbs,sbs-battery"; + reg = <0x0b>; + sbs,battery-detect-gpios = <&batman 3 1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs_sbs-charger.txt b/Documentation/devicetree/bindings/power/supply/sbs_sbs-charger.txt deleted file mode 100644 index 84e74151eef2..000000000000 --- a/Documentation/devicetree/bindings/power/supply/sbs_sbs-charger.txt +++ /dev/null @@ -1,21 +0,0 @@ -SBS sbs-charger -~~~~~~~~~~ - -Required properties: - - compatible: "<vendor>,<part-number>", "sbs,sbs-charger" as fallback. The part - number compatible string might be used in order to take care of vendor - specific registers. - -Optional properties: -- interrupts: Interrupt mapping for GPIO IRQ. Use in conjunction with - "interrupt-parent". If an interrupt is not provided the driver will switch - automatically to polling. - -Example: - - ltc4100@9 { - compatible = "lltc,ltc4100", "sbs,sbs-charger"; - reg = <0x9>; - interrupt-parent = <&gpio6>; - interrupts = <7 IRQ_TYPE_LEVEL_LOW>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/sc2731-charger.yaml b/Documentation/devicetree/bindings/power/supply/sc2731-charger.yaml new file mode 100644 index 000000000000..b62c2431f94e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sc2731-charger.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/sc2731-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Spreadtrum SC2731 PMICs battery charger binding + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: sprd,sc2731-charger + + reg: + maxItems: 1 + + phys: + maxItems: 1 + description: phandle to the USB phy + + monitored-battery: + description: | + The charger uses the following battery properties + - charge-term-current-microamp: current for charge termination phase. + - constant-charge-voltage-max-microvolt: maximum constant input voltage. + See Documentation/devicetree/bindings/power/supply/battery.yaml + +additionalProperties: false + +examples: + - | + bat: battery { + compatible = "simple-battery"; + charge-term-current-microamp = <120000>; + constant-charge-voltage-max-microvolt = <4350000>; + }; + + pmic { + #address-cells = <1>; + #size-cells = <0>; + + battery@a00 { + compatible = "sprd,sc2731-charger"; + reg = <0x0>; + phys = <&ssphy>; + monitored-battery = <&bat>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sc2731_charger.txt b/Documentation/devicetree/bindings/power/supply/sc2731_charger.txt deleted file mode 100644 index 5266fab16575..000000000000 --- a/Documentation/devicetree/bindings/power/supply/sc2731_charger.txt +++ /dev/null @@ -1,40 +0,0 @@ -Spreadtrum SC2731 PMIC battery charger binding - -Required properties: - - compatible: Should be "sprd,sc2731-charger". - - reg: Address offset of charger register. - - phys: Contains a phandle to the USB phy. - -Optional Properties: -- monitored-battery: phandle of battery characteristics devicetree node. - The charger uses the following battery properties: -- charge-term-current-microamp: current for charge termination phase. -- constant-charge-voltage-max-microvolt: maximum constant input voltage. - See Documentation/devicetree/bindings/power/supply/battery.txt - -Example: - - bat: battery { - compatible = "simple-battery"; - charge-term-current-microamp = <120000>; - constant-charge-voltage-max-microvolt = <4350000>; - ...... - }; - - sc2731_pmic: pmic@0 { - compatible = "sprd,sc2731"; - reg = <0>; - spi-max-frequency = <26000000>; - interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <2>; - #address-cells = <1>; - #size-cells = <0>; - - charger@0 { - compatible = "sprd,sc2731-charger"; - reg = <0x0>; - phys = <&ssphy>; - monitored-battery = <&bat>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt deleted file mode 100644 index b6359b590383..000000000000 --- a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt +++ /dev/null @@ -1,59 +0,0 @@ -Spreadtrum SC27XX PMICs Fuel Gauge Unit Power Supply Bindings - -Required properties: -- compatible: Should be one of the following: - "sprd,sc2720-fgu", - "sprd,sc2721-fgu", - "sprd,sc2723-fgu", - "sprd,sc2730-fgu", - "sprd,sc2731-fgu". -- reg: The address offset of fuel gauge unit. -- battery-detect-gpios: GPIO for battery detection. -- io-channels: Specify the IIO ADC channels to get temperature and charge voltage. -- io-channel-names: Should be "bat-temp" or "charge-vol". -- nvmem-cells: A phandle to the calibration cells provided by eFuse device. -- nvmem-cell-names: Should be "fgu_calib". -- sprd,calib-resistance-micro-ohms: Specify the real resistance of coulomb counter - chip in micro Ohms. -- monitored-battery: Phandle of battery characteristics devicetree node. - See Documentation/devicetree/bindings/power/supply/battery.txt - -Example: - - bat: battery { - compatible = "simple-battery"; - charge-full-design-microamp-hours = <1900000>; - constant-charge-voltage-max-microvolt = <4350000>; - ocv-capacity-celsius = <20>; - ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, - <4022000 85>, <3983000 80>, <3949000 75>, - <3917000 70>, <3889000 65>, <3864000 60>, - <3835000 55>, <3805000 50>, <3787000 45>, - <3777000 40>, <3773000 35>, <3770000 30>, - <3765000 25>, <3752000 20>, <3724000 15>, - <3680000 10>, <3605000 5>, <3400000 0>; - ...... - }; - - sc2731_pmic: pmic@0 { - compatible = "sprd,sc2731"; - reg = <0>; - spi-max-frequency = <26000000>; - interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <2>; - #address-cells = <1>; - #size-cells = <0>; - - fgu@a00 { - compatible = "sprd,sc2731-fgu"; - reg = <0xa00>; - battery-detect-gpios = <&pmic_eic 9 GPIO_ACTIVE_HIGH>; - io-channels = <&pmic_adc 5>, <&pmic_adc 14>; - io-channel-names = "bat-temp", "charge-vol"; - nvmem-cells = <&fgu_calib>; - nvmem-cell-names = "fgu_calib"; - monitored-battery = <&bat>; - sprd,calib-resistance-micro-ohms = <21500>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.yaml b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.yaml new file mode 100644 index 000000000000..e019cffd1f38 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/sc27xx-fg.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Spreadtrum SC27XX PMICs Fuel Gauge Unit Power Supply Bindings + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - sprd,sc2720-fgu + - sprd,sc2721-fgu + - sprd,sc2723-fgu + - sprd,sc2730-fgu + - sprd,sc2731-fgu + + reg: + maxItems: 1 + + battery-detect-gpios: + maxItems: 1 + + io-channels: + items: + - description: Battery Temperature ADC + - description: Battery Charge Voltage ADC + + io-channel-names: + items: + - const: bat-temp + - const: charge-vol + + nvmem-cells: + maxItems: 1 + description: Calibration cells provided by eFuse device + + nvmem-cell-names: + const: fgu_calib + + sprd,calib-resistance-micro-ohms: + description: real resistance of coulomb counter chip in micro Ohms + + monitored-battery: true + +required: + - compatible + - reg + - battery-detect-gpios + - io-channels + - io-channel-names + - nvmem-cells + - nvmem-cell-names + - sprd,calib-resistance-micro-ohms + - monitored-battery + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + bat: battery { + compatible = "simple-battery"; + charge-full-design-microamp-hours = <1900000>; + constant-charge-voltage-max-microvolt = <4350000>; + ocv-capacity-celsius = <20>; + ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, + <4022000 85>, <3983000 80>, <3949000 75>, + <3917000 70>, <3889000 65>, <3864000 60>, + <3835000 55>, <3805000 50>, <3787000 45>, + <3777000 40>, <3773000 35>, <3770000 30>, + <3765000 25>, <3752000 20>, <3724000 15>, + <3680000 10>, <3605000 5>, <3400000 0>; + // ... + }; + + pmic { + #address-cells = <1>; + #size-cells = <0>; + + battery@a00 { + compatible = "sprd,sc2731-fgu"; + reg = <0xa00>; + battery-detect-gpios = <&pmic_eic 9 GPIO_ACTIVE_HIGH>; + io-channels = <&pmic_adc 5>, <&pmic_adc 14>; + io-channel-names = "bat-temp", "charge-vol"; + nvmem-cells = <&fgu_calib>; + nvmem-cell-names = "fgu_calib"; + monitored-battery = <&bat>; + sprd,calib-resistance-micro-ohms = <21500>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/fg.txt b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt index ccafcb9112fb..ee125cb0e46d 100644 --- a/Documentation/devicetree/bindings/power/supply/ab8500/fg.txt +++ b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt @@ -1,32 +1,9 @@ -=== AB8500 Fuel Gauge Driver === - -AB8500 is a mixed signal multimedia and power management -device comprising: power and energy-management-module, -wall-charger, usb-charger, audio codec, general purpose adc, -tvout, clock management and sim card interface. - -Fuelgauge support is part of energy-management-modules, other -components of this module are: -main-charger, usb-combo-charger and battery-temperature-monitoring. - -The properties below describes the node for fuelgauge driver. - -Required Properties: -- compatible = This shall be: "stericsson,ab8500-fg" -- battery = Shall be battery specific information - Example: - ab8500_fg { - compatible = "stericsson,ab8500-fg"; - battery = <&ab8500_battery>; - }; - -dependent node: - ab8500_battery: ab8500_battery { - }; - This node will provide information on 'thermistor interface' and - 'battery technology type' used. +AB85000 PMIC contains a node, which contains shared +information about the battery connected to the PMIC. +The node has no compatible property. Properties of this node are: + thermistor-on-batctrl: A boolean value indicating thermistor interface to battery @@ -55,4 +32,3 @@ battery-type: ab8500_battery: ab8500_battery { stericsson,battery-type = "LIPO"; } - diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-btemp.yaml b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-btemp.yaml new file mode 100644 index 000000000000..2f57aa5a5f4e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-btemp.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/stericsson,ab8500-btemp.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AB8500 Battery Temperature Monitor + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: stericsson,ab8500-btemp + + battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to battery node + + interrupts: + maxItems: 5 + + interrupt-names: + items: + - const: BAT_CTRL_INDB + - const: BTEMP_LOW + - const: BTEMP_HIGH + - const: BTEMP_LOW_MEDIUM + - const: BTEMP_MEDIUM_HIGH + + io-channels: + maxItems: 2 + + io-channel-names: + items: + - const: btemp_ball + - const: bat_ctrl + +required: + - compatible + - battery + - interrupts + - interrupt-names + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + battery-temperature { + compatible = "stericsson,ab8500-btemp"; + battery = <&ab8500_battery>; + interrupts = <20 IRQ_TYPE_LEVEL_HIGH>, + <80 IRQ_TYPE_LEVEL_HIGH>, + <83 IRQ_TYPE_LEVEL_HIGH>, + <81 IRQ_TYPE_LEVEL_HIGH>, + <82 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "BAT_CTRL_INDB", + "BTEMP_LOW", + "BTEMP_HIGH", + "BTEMP_LOW_MEDIUM", + "BTEMP_MEDIUM_HIGH"; + io-channels = <&gpadc 0x02>, <&gpadc 0x01>; + io-channel-names = "btemp_ball", "bat_ctrl"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-chargalg.yaml b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-chargalg.yaml new file mode 100644 index 000000000000..0897231c2f6e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-chargalg.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/stericsson,ab8500-chargalg.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AB8500 Charging Algorithm + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: stericsson,ab8500-chargalg + + battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to battery node + +required: + - compatible + - battery + +additionalProperties: false + +examples: + - | + pmic { + charging-algorithm { + compatible = "stericsson,ab8500-chargalg"; + battery = <&ab8500_battery>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-charger.yaml b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-charger.yaml new file mode 100644 index 000000000000..e13305afea69 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-charger.yaml @@ -0,0 +1,123 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/stericsson,ab8500-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AB8500 Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: stericsson,ab8500-charger + + battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to battery node + + vddadc-supply: + description: Supply for USB and Main charger + + autopower_cfg: + type: boolean + description: automatic poweron after powerloss + + interrupts: + maxItems: 14 + + interrupt-names: + items: + - const: MAIN_CH_UNPLUG_DET + - const: MAIN_CHARGE_PLUG_DET + - const: MAIN_EXT_CH_NOT_OK + - const: MAIN_CH_TH_PROT_R + - const: MAIN_CH_TH_PROT_F + - const: VBUS_DET_F + - const: VBUS_DET_R + - const: USB_LINK_STATUS + - const: USB_CH_TH_PROT_R + - const: USB_CH_TH_PROT_F + - const: USB_CHARGER_NOT_OKR + - const: VBUS_OVV + - const: CH_WD_EXP + - const: VBUS_CH_DROP_END + + io-channels: + minItems: 2 + maxItems: 4 + + io-channel-names: + oneOf: + - items: + - const: main_charger_v + - const: main_charger_c + - const: vbus_v + - const: usb_charger_c + - items: + - const: vbus_v + - const: usb_charger_c + + +required: + - compatible + - battery + - vddadc-supply + - interrupts + - interrupt-names + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + charger { + compatible = "stericsson,ab8500-charger"; + battery = <&ab8500_battery>; + vddadc-supply = <&ab8500_ldo_tvout_reg>; + interrupts = <10 IRQ_TYPE_LEVEL_HIGH>, + <11 IRQ_TYPE_LEVEL_HIGH>, + <0 IRQ_TYPE_LEVEL_HIGH>, + <107 IRQ_TYPE_LEVEL_HIGH>, + <106 IRQ_TYPE_LEVEL_HIGH>, + <14 IRQ_TYPE_LEVEL_HIGH>, + <15 IRQ_TYPE_LEVEL_HIGH>, + <79 IRQ_TYPE_LEVEL_HIGH>, + <105 IRQ_TYPE_LEVEL_HIGH>, + <104 IRQ_TYPE_LEVEL_HIGH>, + <89 IRQ_TYPE_LEVEL_HIGH>, + <22 IRQ_TYPE_LEVEL_HIGH>, + <21 IRQ_TYPE_LEVEL_HIGH>, + <16 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "MAIN_CH_UNPLUG_DET", + "MAIN_CHARGE_PLUG_DET", + "MAIN_EXT_CH_NOT_OK", + "MAIN_CH_TH_PROT_R", + "MAIN_CH_TH_PROT_F", + "VBUS_DET_F", + "VBUS_DET_R", + "USB_LINK_STATUS", + "USB_CH_TH_PROT_R", + "USB_CH_TH_PROT_F", + "USB_CHARGER_NOT_OKR", + "VBUS_OVV", + "CH_WD_EXP", + "VBUS_CH_DROP_END"; + io-channels = <&gpadc 0x03>, + <&gpadc 0x0a>, + <&gpadc 0x09>, + <&gpadc 0x0b>; + io-channel-names = "main_charger_v", + "main_charger_c", + "vbus_v", + "usb_charger_c"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-fg.yaml b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-fg.yaml new file mode 100644 index 000000000000..db342e5ac0d1 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-fg.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2021 Sebastian Reichel +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/stericsson,ab8500-fg.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AB8500 Fuel Gauge + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: stericsson,ab8500-fg + + battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to battery node + + interrupts: + maxItems: 5 + + interrupt-names: + items: + - const: NCONV_ACCU + - const: BATT_OVV + - const: LOW_BAT_F + - const: CC_INT_CALIB + - const: CCEOC + + io-channels: + maxItems: 1 + + io-channel-names: + items: + - const: main_bat_v + +required: + - compatible + - battery + - interrupts + - interrupt-names + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + fuel-gauge { + compatible = "stericsson,ab8500-fg"; + battery = <&ab8500_battery>; + interrupts = <24 IRQ_TYPE_LEVEL_HIGH>, + <8 IRQ_TYPE_LEVEL_HIGH>, + <28 IRQ_TYPE_LEVEL_HIGH>, + <27 IRQ_TYPE_LEVEL_HIGH>, + <26 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "NCONV_ACCU", + "BATT_OVV", + "LOW_BAT_F", + "CC_INT_CALIB", + "CCEOC"; + io-channels = <&gpadc 0x08>; + io-channel-names = "main_bat_v"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt b/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt deleted file mode 100644 index de45e1a2a4d9..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt +++ /dev/null @@ -1,39 +0,0 @@ -TI BQ24735 Charge Controller -~~~~~~~~~~ - -Required properties : - - compatible : "ti,bq24735" - -Optional properties : - - interrupts : Specify the interrupt to be used to trigger when the AC - adapter is either plugged in or removed. - - ti,ac-detect-gpios : This GPIO is optionally used to read the AC adapter - status. This is a Host GPIO that is configured as an input and connected - to the ACOK pin on the bq24735. Note: for backwards compatibility reasons, - the GPIO must be active on AC adapter absence despite ACOK being active - (high) on AC adapter presence. - - ti,charge-current : Used to control and set the charging current. This value - must be between 128mA and 8.128A with a 64mA step resolution. The POR value - is 0x0000h. This number is in mA (e.g. 8192), see spec for more information - about the ChargeCurrent (0x14h) register. - - ti,charge-voltage : Used to control and set the charging voltage. This value - must be between 1.024V and 19.2V with a 16mV step resolution. The POR value - is 0x0000h. This number is in mV (e.g. 19200), see spec for more information - about the ChargeVoltage (0x15h) register. - - ti,input-current : Used to control and set the charger input current. This - value must be between 128mA and 8.064A with a 128mA step resolution. The - POR value is 0x1000h. This number is in mA (e.g. 8064), see the spec for - more information about the InputCurrent (0x3fh) register. - - ti,external-control : Indicates that the charger is configured externally - and that the host should not attempt to enable/disable charging or set the - charge voltage/current. - - poll-interval : In case 'interrupts' is not specified, poll AC adapter - presence with this interval (milliseconds). - -Example: - - bq24735@9 { - compatible = "ti,bq24735"; - reg = <0x9>; - ti,ac-detect-gpios = <&gpio 72 0x1>; - } diff --git a/Documentation/devicetree/bindings/power/supply/ti,lp8727.yaml b/Documentation/devicetree/bindings/power/supply/ti,lp8727.yaml new file mode 100644 index 000000000000..a23f6653f332 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ti,lp8727.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/ti,lp8727.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for TI/National Semiconductor LP8727 Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: ti,lp8727 + + reg: + const: 0x27 + + interrupts: + maxItems: 1 + + debounce-ms: + description: interrupt debounce time in ms + +patternProperties: + '^(ac|usb)$': + type: object + description: USB/AC charging parameters + properties: + charger-type: + enum: + - ac + - usb + + eoc-level: + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 0 + maximum: 6 + description: | + End of Charge Percentage with the following mapping: + 0 = 5%, 1 = 10%, 2 = 16%, 3 = 20%, 4 = 25%, 5 = 33%, 6 = 50% + + charging-current: + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 0 + maximum: 9 + description: | + Charging current with the following mapping: + 0 = 90mA, 1 = 100mA, 2 = 400mA, 3 = 450mA, 4 = 500mA, 5 = 600mA, + 6 = 700mA, 7 = 800mA, 8 = 900mA, 9 = 1000mA + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + lp8727: charger@27 { + compatible = "ti,lp8727"; + reg = <0x27>; + interrupt-parent = <&gpio5>; + interrupts = <6 IRQ_TYPE_EDGE_FALLING>; + debounce-ms = <300>; + + /* AC charger: 5% EOC and 500mA charging current */ + ac { + charger-type = "ac"; + eoc-level = /bits/ 8 <0>; + charging-current = /bits/ 8 <4>; + }; + + /* USB charger: 10% EOC and 400mA charging current */ + usb { + charger-type = "usb"; + eoc-level = /bits/ 8 <1>; + charging-current = /bits/ 8 <2>; + }; + }; + }; + diff --git a/Documentation/devicetree/bindings/power/supply/tps65090-charger.yaml b/Documentation/devicetree/bindings/power/supply/tps65090-charger.yaml new file mode 100644 index 000000000000..f2dd38bf078c --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/tps65090-charger.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/tps65090-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TPS65090 Frontend PMU with Switchmode Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: ti,tps65090-charger + + ti,enable-low-current-chrg: + type: boolean + description: | + Enables charging when a low current is detected while the default logic is to stop charging. + +required: + - compatible + +additionalProperties: false + +examples: + - | + pmic { + charger { + compatible = "ti,tps65090-charger"; + ti,enable-low-current-chrg; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/tps65090.txt b/Documentation/devicetree/bindings/power/supply/tps65090.txt deleted file mode 100644 index 8e5e0d3910df..000000000000 --- a/Documentation/devicetree/bindings/power/supply/tps65090.txt +++ /dev/null @@ -1,17 +0,0 @@ -TPS65090 Frontend PMU with Switchmode Charger - -Required Properties: --compatible: "ti,tps65090-charger" - -Optional Properties: --ti,enable-low-current-chrg: Enables charging when a low current is detected - while the default logic is to stop charging. - -This node is a subnode of the tps65090 PMIC. - -Example: - - tps65090-charger { - compatible = "ti,tps65090-charger"; - ti,enable-low-current-chrg; - }; diff --git a/Documentation/devicetree/bindings/power/supply/tps65217-charger.yaml b/Documentation/devicetree/bindings/power/supply/tps65217-charger.yaml new file mode 100644 index 000000000000..a33408c3a407 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/tps65217-charger.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/tps65217-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TPS65217 Charger + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: ti,tps65217-charger + + interrupts: + minItems: 2 + maxItems: 2 + + interrupt-names: + items: + - const: USB + - const: AC + +required: + - compatible + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + pmic { + charger { + compatible = "ti,tps65217-charger"; + interrupts = <0>, <1>; + interrupt-names = "USB", "AC"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt b/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt deleted file mode 100644 index a11072c5a866..000000000000 --- a/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt +++ /dev/null @@ -1,17 +0,0 @@ -TPS65217 Charger - -Required Properties: --compatible: "ti,tps65217-charger" --interrupts: TPS65217 interrupt numbers for the AC and USB charger input change. - Should be <0> for the USB charger and <1> for the AC adapter. --interrupt-names: Should be "USB" and "AC" - -This node is a subnode of the tps65217 PMIC. - -Example: - - tps65217-charger { - compatible = "ti,tps65217-charger"; - interrupts = <0>, <1>; - interrupt-names = "USB", "AC"; - }; diff --git a/Documentation/devicetree/bindings/power/supply/twl-charger.txt b/Documentation/devicetree/bindings/power/supply/twl-charger.txt deleted file mode 100644 index 3b4ea1b73b38..000000000000 --- a/Documentation/devicetree/bindings/power/supply/twl-charger.txt +++ /dev/null @@ -1,30 +0,0 @@ -TWL BCI (Battery Charger Interface) - -The battery charger needs to interact with the USB phy in order -to know when charging is permissible, and when there is a connection -or disconnection. - -The choice of phy cannot be configured at a hardware level, so there -is no value in explicit configuration in device-tree. Rather -if there is a sibling of the BCI node which is compatible with -"ti,twl4030-usb", then that is used to determine when and how -use USB power for charging. - -Required properties: -- compatible: - - "ti,twl4030-bci" -- interrupts: two interrupt lines from the TWL SIH (secondary - interrupt handler) - interrupts 9 and 2. - -Optional properties: -- ti,bb-uvolt: microvolts for charging the backup battery. -- ti,bb-uamp: microamps for charging the backup battery. - -Examples: - -bci { - compatible = "ti,twl4030-bci"; - interrupts = <9>, <2>; - ti,bb-uvolt = <3200000>; - ti,bb-uamp = <150>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/twl4030-charger.yaml b/Documentation/devicetree/bindings/power/supply/twl4030-charger.yaml new file mode 100644 index 000000000000..fe3f32a0ea79 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/twl4030-charger.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/twl4030-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TWL4030 BCI (Battery Charger Interface) + +description: | + The battery charger needs to interact with the USB phy in order to know when + charging is permissible, and when there is a connection or disconnection. + + The choice of phy cannot be configured at a hardware level, so there is no + value in explicit configuration in device-tree. Rather if there is a sibling + of the BCI node which is compatible with "ti,twl4030-usb", then that is used + to determine when and how use USB power for charging. + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: ti,twl4030-bci + + interrupts: + minItems: 2 + maxItems: 2 + + ti,bb-uvolt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: microvolts for charging the backup battery + + ti,bb-uamp: + $ref: /schemas/types.yaml#/definitions/uint32 + description: microamps for charging the backup battery + + io-channels: + items: + - description: Accessory Charger Voltage Channel + + io-channel-names: + items: + - const: vac + + bci3v1-supply: + description: 3.1V USB regulator + +required: + - compatible + - interrupts + +additionalProperties: false + +examples: + - | + pmic { + charger { + compatible = "ti,twl4030-bci"; + interrupts = <9>, <2>; + ti,bb-uvolt = <3200000>; + ti,bb-uamp = <150>; + io-channels = <&twl_madc 11>; + io-channel-names = "vac"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml new file mode 100644 index 000000000000..dcda6660b8ed --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/x-powers,axp20x-ac-power-supply.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AXP20x AC power-supply + +description: | + The AXP20X can read the current current and voltage supplied by AC by + reading ADC channels from the AXP20X ADC. The AXP22X is only able to + tell if an AC power supply is present and usable. AXP813/AXP803 are + able to limit current and supply voltage + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - x-powers,axp202-ac-power-supply + - x-powers,axp221-ac-power-supply + - x-powers,axp813-ac-power-supply + +required: + - compatible + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml new file mode 100644 index 000000000000..86e8a713d4e2 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/x-powers,axp20x-battery-power-supply.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AXP20x Battery power-supply + +description: | + The supported devices can read the battery voltage, charge and discharge + currents of the battery by reading ADC channels from the ADC. + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - x-powers,axp209-battery-power-supply + - x-powers,axp221-battery-power-supply + - x-powers,axp813-battery-power-supply + +required: + - compatible + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml new file mode 100644 index 000000000000..61f1b320c157 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/x-powers,axp20x-usb-power-supply.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AXP20x USB power-supply + +description: | + The AXP223 PMIC shares most of its behaviour with the AXP221 but has slight + variations such as the former being able to set the VBUS power supply max + current to 100mA, unlike the latter. + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Sebastian Reichel <sre@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - x-powers,axp202-usb-power-supply + - x-powers,axp221-usb-power-supply + - x-powers,axp223-usb-power-supply + - x-powers,axp813-usb-power-supply + + +required: + - compatible + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt b/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt deleted file mode 100644 index f70956dea77b..000000000000 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt +++ /dev/null @@ -1,27 +0,0 @@ -Rockchip PWM controller - -Required properties: - - compatible: should be "rockchip,<name>-pwm" - "rockchip,rk2928-pwm": found on RK29XX,RK3066 and RK3188 SoCs - "rockchip,rk3288-pwm": found on RK3288 SOC - "rockchip,rv1108-pwm", "rockchip,rk3288-pwm": found on RV1108 SoC - "rockchip,vop-pwm": found integrated in VOP on RK3288 SoC - - reg: physical base address and length of the controller's registers - - clocks: See ../clock/clock-bindings.txt - - For older hardware (rk2928, rk3066, rk3188, rk3228, rk3288, rk3399): - - There is one clock that's used both to derive the functional clock - for the device and as the bus clock. - - For newer hardware (rk3328 and future socs): specified by name - - "pwm": This is used to derive the functional clock. - - "pclk": This is the APB bus clock. - - #pwm-cells: must be 2 (rk2928) or 3 (rk3288). See pwm.yaml in this directory - for a description of the cell format. - -Example: - - pwm0: pwm@20030000 { - compatible = "rockchip,rk2928-pwm"; - reg = <0x20030000 0x10>; - clocks = <&cru PCLK_PWM01>; - #pwm-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml new file mode 100644 index 000000000000..5596bee70509 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/pwm-rockchip.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip PWM controller + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + oneOf: + - const: rockchip,rk2928-pwm + - const: rockchip,rk3288-pwm + - const: rockchip,rk3328-pwm + - const: rockchip,vop-pwm + - items: + - const: rockchip,rk3036-pwm + - const: rockchip,rk2928-pwm + - items: + - enum: + - rockchip,rk3368-pwm + - rockchip,rk3399-pwm + - rockchip,rv1108-pwm + - const: rockchip,rk3288-pwm + - items: + - enum: + - rockchip,px30-pwm + - rockchip,rk3308-pwm + - const: rockchip,rk3328-pwm + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + maxItems: 2 + + "#pwm-cells": + enum: [2, 3] + description: + Must be 2 (rk2928) or 3 (rk3288 and later). + See pwm.yaml for a description of the cell format. + +required: + - compatible + - reg + - "#pwm-cells" + +if: + properties: + compatible: + contains: + enum: + - rockchip,rk3328-pwm + - rockchip,rv1108-pwm + +then: + properties: + clocks: + items: + - description: Used to derive the functional clock for the device. + - description: Used as the APB bus clock. + + clock-names: + items: + - const: pwm + - const: pclk + + required: + - clocks + - clock-names + +else: + properties: + clocks: + maxItems: 1 + description: + Used both to derive the functional clock + for the device and as the bus clock. + + required: + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/rk3188-cru-common.h> + pwm0: pwm@20030000 { + compatible = "rockchip,rk2928-pwm"; + reg = <0x20030000 0x10>; + clocks = <&cru PCLK_PWM01>; + #pwm-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml b/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml new file mode 100644 index 000000000000..d350f5edfb67 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.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/toshiba,pwm-visconti.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba Visconti PWM Controller + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +properties: + compatible: + items: + - const: toshiba,visconti-pwm + + reg: + maxItems: 1 + + '#pwm-cells': + const: 2 + +required: + - compatible + - reg + - '#pwm-cells' + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + pwm: pwm@241c0000 { + compatible = "toshiba,visconti-pwm"; + reg = <0 0x241c0000 0 0x1000>; + pinctrl-names = "default"; + pinctrl-0 = <&pwm_mux>; + #pwm-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fan53555.txt b/Documentation/devicetree/bindings/regulator/fan53555.txt index e7fc045281d1..013f096ac0aa 100644 --- a/Documentation/devicetree/bindings/regulator/fan53555.txt +++ b/Documentation/devicetree/bindings/regulator/fan53555.txt @@ -1,8 +1,8 @@ Binding for Fairchild FAN53555 regulators Required properties: - - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827" or - "silergy,syr828" + - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827", + "silergy,syr828" or "tcs,tcs4525". - reg: I2C address Optional properties: diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt deleted file mode 100644 index ce1e04354006..000000000000 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt +++ /dev/null @@ -1,180 +0,0 @@ -Qualcomm Technologies, Inc. RPMh Regulators - -rpmh-regulator devices support PMIC regulator management via the Voltage -Regulator Manager (VRM) and Oscillator Buffer (XOB) RPMh accelerators. The APPS -processor communicates with these hardware blocks via a Resource State -Coordinator (RSC) using command packets. The VRM allows changing three -parameters for a given regulator: enable state, output voltage, and operating -mode. The XOB allows changing only a single parameter for a given regulator: -its enable state. Despite its name, the XOB is capable of controlling the -enable state of any PMIC peripheral. It is used for clock buffers, low-voltage -switches, and LDO/SMPS regulators which have a fixed voltage and mode. - -======================= -Required Node Structure -======================= - -RPMh regulators must be described in two levels of device nodes. The first -level describes the PMIC containing the regulators and must reside within an -RPMh device node. The second level describes each regulator within the PMIC -which is to be used on the board. Each of these regulators maps to a single -RPMh resource. - -The names used for regulator nodes must match those supported by a given PMIC. -Supported regulator node names: - PM8005: smps1 - smps4 - PM8009: smps1 - smps2, ldo1 - ldo7 - PM8150: smps1 - smps10, ldo1 - ldo18 - PM8150L: smps1 - smps8, ldo1 - ldo11, bob, flash, rgb - PM8350: smps1 - smps12, ldo1 - ldo10, - PM8350C: smps1 - smps10, ldo1 - ldo13, bob - PM8998: smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 - PMI8998: bob - PM6150: smps1 - smps5, ldo1 - ldo19 - PM6150L: smps1 - smps8, ldo1 - ldo11, bob - PMX55: smps1 - smps7, ldo1 - ldo16 - -======================== -First Level Nodes - PMIC -======================== - -- compatible - Usage: required - Value type: <string> - Definition: Must be one of below: - "qcom,pm8005-rpmh-regulators" - "qcom,pm8009-rpmh-regulators" - "qcom,pm8009-1-rpmh-regulators" - "qcom,pm8150-rpmh-regulators" - "qcom,pm8150l-rpmh-regulators" - "qcom,pm8350-rpmh-regulators" - "qcom,pm8350c-rpmh-regulators" - "qcom,pm8998-rpmh-regulators" - "qcom,pmc8180-rpmh-regulators" - "qcom,pmc8180c-rpmh-regulators" - "qcom,pmi8998-rpmh-regulators" - "qcom,pm6150-rpmh-regulators" - "qcom,pm6150l-rpmh-regulators" - "qcom,pmx55-rpmh-regulators" - -- qcom,pmic-id - Usage: required - Value type: <string> - Definition: RPMh resource name suffix used for the regulators found on - this PMIC. Typical values: "a", "b", "c", "d", "e", "f". - -- vdd-s1-supply -- vdd-s2-supply -- vdd-s3-supply -- vdd-s4-supply - Usage: optional (PM8998 and PM8005 only) - Value type: <phandle> - Definition: phandle of the parent supply regulator of one or more of the - regulators for this PMIC. - -- vdd-s5-supply -- vdd-s6-supply -- vdd-s7-supply -- vdd-s8-supply -- vdd-s9-supply -- vdd-s10-supply -- vdd-s11-supply -- vdd-s12-supply -- vdd-s13-supply -- vdd-l1-l27-supply -- vdd-l2-l8-l17-supply -- vdd-l3-l11-supply -- vdd-l4-l5-supply -- vdd-l6-supply -- vdd-l7-l12-l14-l15-supply -- vdd-l9-supply -- vdd-l10-l23-l25-supply -- vdd-l13-l19-l21-supply -- vdd-l16-l28-supply -- vdd-l18-l22-supply -- vdd-l20-l24-supply -- vdd-l26-supply -- vin-lvs-1-2-supply - Usage: optional (PM8998 only) - Value type: <phandle> - Definition: phandle of the parent supply regulator of one or more of the - regulators for this PMIC. - -- vdd-bob-supply - Usage: optional (PMI8998 only) - Value type: <phandle> - Definition: BOB regulator parent supply phandle - -=============================== -Second Level Nodes - Regulators -=============================== - -- qcom,always-wait-for-ack - Usage: optional - Value type: <empty> - Definition: Boolean flag which indicates that the application processor - must wait for an ACK or a NACK from RPMh for every request - sent for this regulator including those which are for a - strictly lower power state. - -Other properties defined in Documentation/devicetree/bindings/regulator/regulator.txt -may also be used. regulator-initial-mode and regulator-allowed-modes may be -specified for VRM regulators using mode values from -include/dt-bindings/regulator/qcom,rpmh-regulator.h. regulator-allow-bypass -may be specified for BOB type regulators managed via VRM. -regulator-allow-set-load may be specified for LDO type regulators managed via -VRM. - -======== -Examples -======== - -#include <dt-bindings/regulator/qcom,rpmh-regulator.h> - -&apps_rsc { - pm8998-rpmh-regulators { - compatible = "qcom,pm8998-rpmh-regulators"; - qcom,pmic-id = "a"; - - vdd-l7-l12-l14-l15-supply = <&pm8998_s5>; - - smps2 { - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - }; - - pm8998_s5: smps5 { - regulator-min-microvolt = <1904000>; - regulator-max-microvolt = <2040000>; - }; - - ldo7 { - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-initial-mode = <RPMH_REGULATOR_MODE_HPM>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_LPM - RPMH_REGULATOR_MODE_HPM>; - regulator-allow-set-load; - }; - - lvs1 { - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - }; - }; - - pmi8998-rpmh-regulators { - compatible = "qcom,pmi8998-rpmh-regulators"; - qcom,pmic-id = "b"; - - bob { - regulator-min-microvolt = <3312000>; - regulator-max-microvolt = <3600000>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_AUTO - RPMH_REGULATOR_MODE_HPM>; - regulator-initial-mode = <RPMH_REGULATOR_MODE_AUTO>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml new file mode 100644 index 000000000000..e561a5b941e4 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,rpmh-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. RPMh Regulators + +maintainers: + - David Collins <collinsd@codeaurora.org> + +description: | + rpmh-regulator devices support PMIC regulator management via the Voltage + Regulator Manager (VRM) and Oscillator Buffer (XOB) RPMh accelerators. + The APPS processor communicates with these hardware blocks via a + Resource State Coordinator (RSC) using command packets. The VRM allows + changing three parameters for a given regulator, enable state, output + voltage, and operating mode. The XOB allows changing only a single + parameter for a given regulator, its enable state. Despite its name, + the XOB is capable of controlling the enable state of any PMIC peripheral. + It is used for clock buffers, low-voltage switches, and LDO/SMPS regulators + which have a fixed voltage and mode. + + ======================= + Required Node Structure + ======================= + + RPMh regulators must be described in two levels of device nodes. The first + level describes the PMIC containing the regulators and must reside within an + RPMh device node. The second level describes each regulator within the PMIC + which is to be used on the board. Each of these regulators maps to a single + RPMh resource. + + The names used for regulator nodes must match those supported by a given + PMIC. Supported regulator node names are + For PM8005, smps1 - smps4 + For PM8009, smps1 - smps2, ldo1 - ldo7 + For PM8150, smps1 - smps10, ldo1 - ldo18 + For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb + For PM8350, smps1 - smps12, ldo1 - ldo10 + For PM8350C, smps1 - smps10, ldo1 - ldo13, bob + For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 + For PMI8998, bob + For PM6150, smps1 - smps5, ldo1 - ldo19 + For PM6150L, smps1 - smps8, ldo1 - ldo11, bob + For PMX55, smps1 - smps7, ldo1 - ldo16 + For PM7325, smps1 - smps8, ldo1 - ldo19 + For PMR735A, smps1 - smps3, ldo1 - ldo7 + +properties: + compatible: + enum: + - qcom,pm8005-rpmh-regulators + - qcom,pm8009-rpmh-regulators + - qcom,pm8009-1-rpmh-regulators + - qcom,pm8150-rpmh-regulators + - qcom,pm8150l-rpmh-regulators + - qcom,pm8350-rpmh-regulators + - qcom,pm8350c-rpmh-regulators + - qcom,pm8998-rpmh-regulators + - qcom,pmi8998-rpmh-regulators + - qcom,pm6150-rpmh-regulators + - qcom,pm6150l-rpmh-regulators + - qcom,pmx55-rpmh-regulators + - qcom,pm7325-rpmh-regulators + - qcom,pmr735a-rpmh-regulators + + qcom,pmic-id: + description: | + RPMh resource name suffix used for the regulators found + on this PMIC. + $ref: /schemas/types.yaml#/definitions/string + enum: [a, b, c, d, e, f] + + qcom,always-wait-for-ack: + description: | + Boolean flag which indicates that the application processor + must wait for an ACK or a NACK from RPMh for every request + sent for this regulator including those which are for a + strictly lower power state. + $ref: /schemas/types.yaml#/definitions/flag + + vdd-flash-supply: + description: Input supply phandle of flash. + + vdd-rgb-supply: + description: Input supply phandle of rgb. + + vin-lvs-1-2-supply: + description: Input supply phandle of one or more regulators. + + vdd-bob-supply: + description: BOB regulator parent supply phandle. + + bob: + type: object + $ref: "regulator.yaml#" + description: BOB regulator node. + +patternProperties: + "^vdd-s([0-9]+)-supply$": + description: Input supply phandle(s) of one or more regulators. + + "^vdd-(l[0-9]+[-]){1,5}supply$": + description: Input supply phandle(s) of one or more regulators. + + "^(smps|ldo|lvs)[0-9]+$": + type: object + $ref: "regulator.yaml#" + description: smps/ldo regulator nodes(s). + +additionalProperties: false + +required: + - compatible + - qcom,pmic-id + +examples: + - | + #include <dt-bindings/regulator/qcom,rpmh-regulator.h> + + pm8998-rpmh-regulators { + compatible = "qcom,pm8998-rpmh-regulators"; + qcom,pmic-id = "a"; + + vdd-l7-l12-l14-l15-supply = <&pm8998_s5>; + + smps2 { + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + }; + + ldo7 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-initial-mode = <RPMH_REGULATOR_MODE_HPM>; + regulator-allowed-modes = + <RPMH_REGULATOR_MODE_LPM + RPMH_REGULATOR_MODE_HPM>; + regulator-allow-set-load; + }; + + lvs1 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + }; + + pmi8998-rpmh-regulators { + compatible = "qcom,pmi8998-rpmh-regulators"; + qcom,pmic-id = "b"; + + bob { + regulator-min-microvolt = <3312000>; + regulator-max-microvolt = <3600000>; + regulator-allowed-modes = + <RPMH_REGULATOR_MODE_AUTO + RPMH_REGULATOR_MODE_HPM>; + regulator-initial-mode = <RPMH_REGULATOR_MODE_AUTO>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml index cf784bd1f5e5..1ddc1efd19e2 100644 --- a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml @@ -23,7 +23,6 @@ properties: properties: qcom,soft-start-us: - $ref: /schemas/types.yaml#/definitions/uint32 description: Regulator soft start time in microseconds. enum: [200, 400, 600, 800] default: 200 diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml new file mode 100644 index 000000000000..7d0adb74a396 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/rohm,bd71815-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD71815 Power Management Integrated Circuit regulators + +maintainers: + - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com> + +description: | + This module is part of the ROHM BD718215 MFD device. For more details + see Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml. + + The regulator controller is represented as a sub-node of the PMIC node + on the device tree. + + The valid names for BD71815 regulator nodes are + buck1, buck2, buck3, buck4, buck5, + ldo1, ldo2, ldo3, ldo4, ldo5, + ldodvref, ldolpsr, wled + +properties: + wled: + type: object + description: + properties for wled regulator + $ref: regulator.yaml# + + properties: + regulator-name: + const: wled + +patternProperties: + "^((ldo|buck)[1-5]|ldolpsr|ldodvref)$": + type: object + description: + Properties for single LDO/BUCK regulator. + $ref: regulator.yaml# + + properties: + regulator-name: + pattern: "^((ldo|buck)[1-5]|ldolpsr|ldodvref)$" + description: + should be "ldo1", ..., "ldo5", "buck1", ..., "buck5" and "ldolpsr" + for ldolpsr regulator, "ldodvref" for ldodvref reglator. + + rohm,vsel-gpios: + description: + GPIO used to control ldo4 state (when ldo4 is controlled by GPIO). + + rohm,dvs-run-voltage: + description: + PMIC "RUN" state voltage in uV when PMIC HW states are used. See + comments below for bucks/LDOs which support this. 0 means + regulator should be disabled at RUN state. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 3300000 + + rohm,dvs-snvs-voltage: + description: + Whether to keep regulator enabled at "SNVS" state or not. + 0 means regulator should be disabled at SNVS state, non zero voltage + keeps regulator enabled. BD71815 does not change voltage level + when PMIC transitions to SNVS.SNVS voltage depends on the previous + state (from which the PMIC transitioned to SNVS). + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 3300000 + + rohm,dvs-suspend-voltage: + description: + PMIC "SUSPEND" state voltage in uV when PMIC HW states are used. See + comments below for bucks/LDOs which support this. 0 means + regulator should be disabled at SUSPEND state. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 3300000 + + rohm,dvs-lpsr-voltage: + description: + PMIC "LPSR" state voltage in uV when PMIC HW states are used. See + comments below for bucks/LDOs which support this. 0 means + regulator should be disabled at LPSR state. + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 0 + maximum: 3300000 + + # Bucks 1 and 2 support giving separate voltages for operational states + # (RUN /CLEAN according to data-sheet) and non operational states + # (LPSR/SUSPEND). The voltage is automatically changed when HW + # state changes. Omitting these properties from bucks 1 and 2 leave + # buck voltages to not be toggled by HW state. Enable status may still + # be toggled by state changes depending on HW default settings. + # + # Bucks 3-5 and ldos 1-5 support setting the RUN state voltage here. + # Given RUN voltage is used at all states if regulator is enabled at + # given state. + # Values given for other states are regarded as enable/disable at + # given state (see below). + # + # All regulators except WLED support specifying enable/disable status + # for each of the HW states (RUN/SNVS/SUSPEND/LPSR). HW defaults can + # be overridden by setting voltage to 0 (regulator disabled at given + # state) or non-zero (regulator enabled at given state). Please note + # that setting non zero voltages for bucks 1/2 will also enable voltage + # changes according to state change. + + required: + - regulator-name + + unevaluatedProperties: false + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml new file mode 100644 index 000000000000..208a628f8d6c --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/remoteproc/fsl,imx-rproc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NXP i.MX Co-Processor Bindings + +description: + This binding provides support for ARM Cortex M4 Co-processor found on some NXP iMX SoCs. + +maintainers: + - Peng Fan <peng.fan@nxp.com> + +properties: + compatible: + enum: + - fsl,imx8mq-cm4 + - fsl,imx8mm-cm4 + - fsl,imx7d-cm4 + - fsl,imx6sx-cm4 + + clocks: + maxItems: 1 + + syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to syscon block which provide access to System Reset Controller + + mbox-names: + items: + - const: tx + - const: rx + - const: rxdb + + mboxes: + description: + This property is required only if the rpmsg/virtio functionality is used. + List of <&phandle type channel> - 1 channel for TX, 1 channel for RX, 1 channel for RXDB. + (see mailbox/fsl,mu.yaml) + minItems: 1 + maxItems: 3 + + memory-region: + description: + If present, a phandle for a reserved memory area that used for vdev buffer, + resource table, vring region and others used by remote processor. + minItems: 1 + maxItems: 32 + +required: + - compatible + - clocks + - syscon + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7d-clock.h> + m4_reserved_sysmem1: cm4@80000000 { + reg = <0x80000000 0x80000>; + }; + + m4_reserved_sysmem2: cm4@81000000 { + reg = <0x81000000 0x80000>; + }; + + imx7d-cm4 { + compatible = "fsl,imx7d-cm4"; + memory-region = <&m4_reserved_sysmem1>, <&m4_reserved_sysmem2>; + syscon = <&src>; + clocks = <&clks IMX7D_ARM_M4_ROOT_CLK>; + }; + + - | + #include <dt-bindings/clock/imx8mm-clock.h> + + imx8mm-cm4 { + compatible = "fsl,imx8mm-cm4"; + clocks = <&clk IMX8MM_CLK_M4_DIV>; + mbox-names = "tx", "rx", "rxdb"; + mboxes = <&mu 0 1 + &mu 1 1 + &mu 3 1>; + memory-region = <&vdev0buffer>, <&vdev0vring0>, <&vdev0vring1>, <&rsc_table>; + syscon = <&src>; + }; +... diff --git a/Documentation/devicetree/bindings/remoteproc/imx-rproc.txt b/Documentation/devicetree/bindings/remoteproc/imx-rproc.txt deleted file mode 100644 index fbcefd965dc4..000000000000 --- a/Documentation/devicetree/bindings/remoteproc/imx-rproc.txt +++ /dev/null @@ -1,33 +0,0 @@ -NXP iMX6SX/iMX7D Co-Processor Bindings ----------------------------------------- - -This binding provides support for ARM Cortex M4 Co-processor found on some -NXP iMX SoCs. - -Required properties: -- compatible Should be one of: - "fsl,imx7d-cm4" - "fsl,imx6sx-cm4" -- clocks Clock for co-processor (See: ../clock/clock-bindings.txt) -- syscon Phandle to syscon block which provide access to - System Reset Controller - -Optional properties: -- memory-region list of phandels to the reserved memory regions. - (See: ../reserved-memory/reserved-memory.txt) - -Example: - m4_reserved_sysmem1: cm4@80000000 { - reg = <0x80000000 0x80000>; - }; - - m4_reserved_sysmem2: cm4@81000000 { - reg = <0x81000000 0x80000>; - }; - - imx7d-cm4 { - compatible = "fsl,imx7d-cm4"; - memory-region = <&m4_reserved_sysmem1>, <&m4_reserved_sysmem2>; - syscon = <&src>; - clocks = <&clks IMX7D_ARM_M4_ROOT_CLK>; - }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt index 1c330a8941f9..229f908fd831 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt @@ -18,6 +18,7 @@ on the Qualcomm ADSP Hexagon core. "qcom,sc7180-mpss-pas" "qcom,sdm845-adsp-pas" "qcom,sdm845-cdsp-pas" + "qcom,sdx55-mpss-pas" "qcom,sm8150-adsp-pas" "qcom,sm8150-cdsp-pas" "qcom,sm8150-mpss-pas" @@ -61,6 +62,7 @@ on the Qualcomm ADSP Hexagon core. must be "wdog", "fatal", "ready", "handover", "stop-ack" qcom,qcs404-wcss-pas: qcom,sc7180-mpss-pas: + qcom,sdx55-mpss-pas: qcom,sm8150-mpss-pas: qcom,sm8350-mpss-pas: must be "wdog", "fatal", "ready", "handover", "stop-ack", @@ -128,6 +130,8 @@ on the Qualcomm ADSP Hexagon core. qcom,sm8150-mpss-pas: qcom,sm8350-mpss-pas: must be "cx", "load_state", "mss" + qcom,sdx55-mpss-pas: + must be "cx", "mss" qcom,sm8250-adsp-pas: qcom,sm8350-adsp-pas: qcom,sm8150-slpi-pas: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt index 7ccd5534b0ae..69c49c7b2cff 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt @@ -9,6 +9,7 @@ on the Qualcomm Hexagon core. Definition: must be one of: "qcom,q6v5-pil", "qcom,ipq8074-wcss-pil" + "qcom,qcs404-wcss-pil" "qcom,msm8916-mss-pil", "qcom,msm8974-mss-pil" "qcom,msm8996-mss-pil" @@ -39,6 +40,7 @@ on the Qualcomm Hexagon core. string: qcom,q6v5-pil: qcom,ipq8074-wcss-pil: + qcom,qcs404-wcss-pil: qcom,msm8916-mss-pil: qcom,msm8974-mss-pil: must be "wdog", "fatal", "ready", "handover", "stop-ack" @@ -67,6 +69,11 @@ on the Qualcomm Hexagon core. Definition: The clocks needed depend on the compatible string: qcom,ipq8074-wcss-pil: no clock names required + qcom,qcs404-wcss-pil: + must be "xo", "gcc_abhs_cbcr", "gcc_abhs_cbcr", + "gcc_axim_cbcr", "lcc_ahbfabric_cbc", "tcsr_lcc_cbc", + "lcc_abhs_cbc", "lcc_tcm_slave_cbc", "lcc_abhm_cbc", + "lcc_axim_cbc", "lcc_bcr_sleep" qcom,q6v5-pil: qcom,msm8916-mss-pil: qcom,msm8974-mss-pil: @@ -133,6 +140,14 @@ For the compatible string below the following supplies are required: booting of the Hexagon core For the compatible string below the following supplies are required: + "qcom,qcs404-wcss-pil" +- cx-supply: + Usage: required + Value type: <phandle> + Definition: reference to the regulators to be held on behalf of the + booting of the Hexagon core + +For the compatible string below the following supplies are required: "qcom,msm8996-mss-pil" - pll-supply: Usage: required diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt b/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt index da09c0d79ac0..a83080b8905c 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt @@ -34,6 +34,12 @@ on the Qualcomm WCNSS core. Definition: should be "wdog", "fatal", optionally followed by "ready", "handover", "stop-ack" +- firmware-name: + Usage: optional + Value type: <string> + Definition: must list the relative firmware image path for the + WCNSS core. Defaults to "wcnss.mdt". + - vddmx-supply: (deprecated for qcom,pronto-v1/2-pil) - vddcx-supply: (deprecated for qcom,pronto-v1/2-pil) - vddpx-supply: diff --git a/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml index a1171dfba024..64afdcfb613d 100644 --- a/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml @@ -65,16 +65,23 @@ properties: Unidirectional channel: - from local to remote, where ACK from the remote means that it is ready for shutdown + - description: | + A channel (d) used by the local proc to notify the remote proc that it + has to stop interprocessor communnication. + Unidirectional channel: + - from local to remote, where ACK from the remote means that communnication + as been stopped on the remote side. minItems: 1 - maxItems: 3 + maxItems: 4 mbox-names: items: - const: vq0 - const: vq1 - const: shutdown + - const: detach minItems: 1 - maxItems: 3 + maxItems: 4 memory-region: description: diff --git a/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml index 1a1159097a2a..73400bc6e91d 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml @@ -93,7 +93,7 @@ properties: # The following are the optional properties: memory-region: - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 description: | phandle to the reserved memory node to be associated with the remoteproc device. The reserved memory node diff --git a/Documentation/devicetree/bindings/reserved-memory/ramoops.txt b/Documentation/devicetree/bindings/reserved-memory/ramoops.txt index b7886fea368c..b571ef6dab0f 100644 --- a/Documentation/devicetree/bindings/reserved-memory/ramoops.txt +++ b/Documentation/devicetree/bindings/reserved-memory/ramoops.txt @@ -42,8 +42,14 @@ Optional properties: - pmsg-size: size in bytes of log buffer reserved for userspace messages (defaults to 0: disabled) -- unbuffered: if present, use unbuffered mappings to map the reserved region - (defaults to buffered mappings) +- mem-type: if present, sets the type of mapping is to be used to map the + reserved region. mem-type: 0 = write-combined (default), 1 = unbuffered, + 2 = cached. + +- unbuffered: deprecated, use mem_type instead. If present, and mem_type is + not specified, it is equivalent to mem_type = 1 and uses unbuffered mappings + to map the reserved region (defaults to buffered mappings mem_type = 0). If + both are specified -- "mem_type" overrides "unbuffered". - max-reason: if present, sets maximum type of kmsg dump reasons to store (defaults to 2: log Oopses and Panics). This can be set to INT_MAX to diff --git a/Documentation/devicetree/bindings/riscv/microchip.yaml b/Documentation/devicetree/bindings/riscv/microchip.yaml new file mode 100644 index 000000000000..3f981e897126 --- /dev/null +++ b/Documentation/devicetree/bindings/riscv/microchip.yaml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/riscv/microchip.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip PolarFire SoC-based boards device tree bindings + +maintainers: + - Cyril Jean <Cyril.Jean@microchip.com> + - Lewis Hanly <lewis.hanly@microchip.com> + +description: + Microchip PolarFire SoC-based boards + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - microchip,mpfs-icicle-kit + - const: microchip,mpfs + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml b/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml index c147900f9041..6da674666d45 100644 --- a/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml +++ b/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml @@ -28,6 +28,12 @@ properties: clock-names: const: ipsec + resets: + maxItems: 1 + + reset-names: + const: ipsec + interrupts: maxItems: 1 @@ -35,6 +41,18 @@ required: - compatible - reg +if: + properties: + compatible: + enum: + - brcm,bcm6368-rng +then: + required: + - clocks + - clock-names + - resets + - reset-names + additionalProperties: false examples: @@ -58,4 +76,7 @@ examples: clocks = <&periph_clk 18>; clock-names = "ipsec"; + + resets = <&periph_rst 4>; + reset-names = "ipsec"; }; diff --git a/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml new file mode 100644 index 000000000000..4fba6dba16f3 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/qcom-pm8xxx-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8xxx PMIC RTC device + +maintainers: + - Satya Priya <skakit@codeaurora.org> + +properties: + compatible: + enum: + - qcom,pm8058-rtc + - qcom,pm8921-rtc + - qcom,pm8941-rtc + - qcom,pm8018-rtc + - qcom,pmk8350-rtc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + allow-set-time: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that the setting of RTC time is allowed by the host CPU. + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/spmi/spmi.h> + spmi_bus: spmi@c440000 { + reg = <0x0c440000 0x1100>; + #address-cells = <2>; + #size-cells = <0>; + pmicintc: pmic@0 { + reg = <0x0 SPMI_USID>; + compatible = "qcom,pm8921"; + interrupts = <104 8>; + #interrupt-cells = <2>; + interrupt-controller; + #address-cells = <1>; + #size-cells = <0>; + + pm8921_rtc: rtc@11d { + compatible = "qcom,pm8921-rtc"; + reg = <0x11d>; + interrupts = <0x27 0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/serial/8250.yaml b/Documentation/devicetree/bindings/serial/8250.yaml index f54cae9ff7b2..41f57c448621 100644 --- a/Documentation/devicetree/bindings/serial/8250.yaml +++ b/Documentation/devicetree/bindings/serial/8250.yaml @@ -12,8 +12,13 @@ maintainers: allOf: - $ref: /schemas/serial.yaml# - if: - required: - - aspeed,sirq-polarity-sense + anyOf: + - required: + - aspeed,lpc-io-reg + - required: + - aspeed,lpc-interrupts + - required: + - aspeed,sirq-polarity-sense then: properties: compatible: @@ -55,6 +60,7 @@ properties: - const: aspeed,ast2500-vuart - const: intel,xscale-uart - const: mrvl,pxa-uart + - const: nuvoton,wpcm450-uart - const: nuvoton,npcm750-uart - const: nvidia,tegra20-uart - const: nxp,lpc3220-uart @@ -94,11 +100,6 @@ properties: - mediatek,mt7623-btif - const: mediatek,mtk-btif - items: - - enum: - - mediatek,mt7622-btif - - mediatek,mt7623-btif - - const: mediatek,mtk-btif - - items: - const: mrvl,mmp-uart - const: intel,xscale-uart - items: @@ -165,7 +166,6 @@ properties: property. tx-threshold: - $ref: /schemas/types.yaml#/definitions/uint32 description: | Specify the TX FIFO low water indication for parts with programmable TX FIFO thresholds. @@ -188,6 +188,21 @@ properties: offset and bit number to identify how the SIRQ polarity should be configured. One possible data source is the LPC/eSPI mode bit. Only applicable to aspeed,ast2500-vuart. + deprecated: true + + aspeed,lpc-io-reg: + $ref: '/schemas/types.yaml#/definitions/uint32' + description: | + The VUART LPC address. Only applicable to aspeed,ast2500-vuart. + + aspeed,lpc-interrupts: + $ref: "/schemas/types.yaml#/definitions/uint32-array" + minItems: 2 + maxItems: 2 + description: | + A 2-cell property describing the VUART SIRQ number and SIRQ + polarity (IRQ_TYPE_LEVEL_LOW or IRQ_TYPE_LEVEL_HIGH). Only + applicable to aspeed,ast2500-vuart. required: - reg @@ -220,6 +235,7 @@ examples: }; - | #include <dt-bindings/clock/aspeed-clock.h> + #include <dt-bindings/interrupt-controller/irq.h> serial@1e787000 { compatible = "aspeed,ast2500-vuart"; reg = <0x1e787000 0x40>; @@ -227,7 +243,8 @@ examples: interrupts = <8>; clocks = <&syscon ASPEED_CLK_APB>; no-loopback-test; - aspeed,sirq-polarity-sense = <&syscon 0x70 25>; + aspeed,lpc-io-reg = <0x3f8>; + aspeed,lpc-interrupts = <4 IRQ_TYPE_LEVEL_LOW>; }; ... diff --git a/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml b/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml new file mode 100644 index 000000000000..46c62745f901 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/brcm,bcm7271-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom 8250 based serial port devicetree bindings + +maintainers: + - Al Cooper <alcooperx@gmail.com> + +allOf: + - $ref: /schemas/serial.yaml# + +description: |+ + The Broadcom UART is based on the basic 8250 UART but with + enhancements for more accurate high speed baud rates and support + for DMA. + +properties: + compatible: + items: + - enum: + - brcm,bcm7271-uart + - brcm,bcm7278-uart + + reg: + minItems: 1 + maxItems: 5 + + reg-names: + description: The UART register block and optionally the DMA register blocks. + oneOf: + - items: + - const: uart + - items: + - const: uart + - const: dma_arb + - const: dma_rx + - const: dma_tx + - const: dma_intr2 + + clocks: + minItems: 1 + + clock-names: + const: sw_baud + + interrupts: + minItems: 1 + maxItems: 2 + + interrupt-names: + description: The UART interrupt and optionally the DMA interrupt. + minItems: 1 + items: + - const: uart + - const: dma + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - interrupts + - interrupt-names + +unevaluatedProperties: false + +examples: + - | + serial@840d000 { + compatible = "brcm,bcm7271-uart"; + reg = <0x840d000 0x20>; + reg-names = "uart"; + interrupts = <0x0 0x62 0x4>; + interrupt-names = "uart"; + clocks = <&scmi_clk 190>; + clock-names = "sw_baud"; + }; + + serial@840e000 { + compatible = "brcm,bcm7271-uart"; + reg = <0x840e000 0x20>, + <0x840e080 0x8>, + <0x840e100 0xa8>, + <0x840e200 0x4c>, + <0x840e300 0x30>; + reg-names = "uart", "dma_arb", "dma_rx", "dma_tx", "dma_intr2"; + interrupts = <0x0 0x62 0x4>, <0x0 0x75 0x4>; + interrupt-names = "uart", "dma"; + clocks = <&scmi_clk 190>; + clock-names = "sw_baud"; + }; diff --git a/Documentation/devicetree/bindings/serial/ingenic,uart.yaml b/Documentation/devicetree/bindings/serial/ingenic,uart.yaml index 559213899d73..7748d8c3bab8 100644 --- a/Documentation/devicetree/bindings/serial/ingenic,uart.yaml +++ b/Documentation/devicetree/bindings/serial/ingenic,uart.yaml @@ -91,7 +91,7 @@ examples: bluetooth { compatible = "brcm,bcm4330-bt"; reset-gpios = <&gpf 8 GPIO_ACTIVE_HIGH>; - vcc-supply = <&wlan0_power>; + vbat-supply = <&wlan0_power>; device-wakeup-gpios = <&gpf 5 GPIO_ACTIVE_HIGH>; host-wakeup-gpios = <&gpf 6 GPIO_ACTIVE_HIGH>; shutdown-gpios = <&gpf 4 GPIO_ACTIVE_LOW>; diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 647b5aee86f3..64c4fb59acd1 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -20,6 +20,7 @@ Required properties: * "mediatek,mt8173-uart" for MT8173 compatible UARTS * "mediatek,mt8183-uart", "mediatek,mt6577-uart" for MT8183 compatible UARTS * "mediatek,mt8192-uart", "mediatek,mt6577-uart" for MT8192 compatible UARTS + * "mediatek,mt8195-uart", "mediatek,mt6577-uart" for MT8195 compatible UARTS * "mediatek,mt8516-uart" for MT8516 compatible UARTS * "mediatek,mt6577-uart" for MT6577 and all of the above diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index 21ee627b2ced..97ec8a093bf3 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/serial/samsung_uart.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Samsung S3C, S5P and Exynos SoC UART Controller +title: Samsung S3C, S5P, Exynos, and S5L (Apple SoC) SoC UART Controller maintainers: - Krzysztof Kozlowski <krzk@kernel.org> @@ -19,6 +19,7 @@ properties: compatible: items: - enum: + - apple,s5l-uart - samsung,s3c2410-uart - samsung,s3c2412-uart - samsung,s3c2440-uart @@ -51,6 +52,16 @@ properties: - pattern: '^clk_uart_baud[0-3]$' - pattern: '^clk_uart_baud[0-3]$' + dmas: + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX + + dma-names: + items: + - const: rx + - const: tx + interrupts: description: RX interrupt and optionally TX interrupt. minItems: 1 @@ -68,9 +79,11 @@ required: - interrupts - reg -additionalProperties: false +unevaluatedProperties: false allOf: + - $ref: /schemas/serial.yaml# + - if: properties: compatible: @@ -96,6 +109,7 @@ allOf: compatible: contains: enum: + - apple,s5l-uart - samsung,exynos4210-uart then: properties: diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml index 65e75d040521..2fdf4ed198da 100644 --- a/Documentation/devicetree/bindings/serial/serial.yaml +++ b/Documentation/devicetree/bindings/serial/serial.yaml @@ -75,6 +75,16 @@ properties: type: boolean description: CTS and RTS pins are swapped. + rx-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + RX FIFO threshold configuration (in bytes). + + tx-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + TX FIFO threshold configuration (in bytes). + if: required: - uart-has-rtscts @@ -134,7 +144,7 @@ examples: interrupts = <1>; bluetooth { - compatible = "brcm,bcm43341-bt"; + compatible = "brcm,bcm4330-bt"; interrupt-parent = <&gpio>; interrupts = <10>; }; diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 8631678283f9..71a6426bc558 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -9,9 +9,6 @@ maintainers: title: STMicroelectronics STM32 USART bindings -allOf: - - $ref: rs485.yaml - properties: compatible: enum: @@ -40,6 +37,8 @@ properties: uart-has-rtscts: true + rx-tx-swap: true + dmas: minItems: 1 maxItems: 2 @@ -66,13 +65,46 @@ properties: linux,rs485-enabled-at-boot-time: true rs485-rx-during-tx: true -if: - required: - - st,hw-flow-ctrl -then: - properties: - cts-gpios: false - rts-gpios: false + rx-threshold: + description: + If value is set to 1, RX FIFO threshold is disabled. + enum: [1, 2, 4, 8, 12, 14, 16] + default: 8 + + tx-threshold: + description: + If value is set to 1, TX FIFO threshold is disabled. + enum: [1, 2, 4, 8, 12, 14, 16] + default: 8 + +allOf: + - $ref: rs485.yaml# + - $ref: serial.yaml# + - if: + required: + - st,hw-flow-ctrl + then: + properties: + cts-gpios: false + rts-gpios: false + - if: + properties: + compatible: + const: st,stm32-uart + then: + properties: + rx-tx-swap: false + - if: + properties: + compatible: + contains: + enum: + - st,stm32-uart + - st,stm32f7-uart + then: + properties: + rx-threshold: false + tx-threshold: false required: - compatible @@ -80,19 +112,22 @@ required: - interrupts - clocks -additionalProperties: false +additionalProperties: + type: object examples: - | #include <dt-bindings/clock/stm32mp1-clks.h> usart1: serial@40011000 { - compatible = "st,stm32-uart"; + compatible = "st,stm32h7-uart"; reg = <0x40011000 0x400>; interrupts = <37>; clocks = <&rcc 0 164>; dmas = <&dma2 2 4 0x414 0x0>, <&dma2 7 4 0x414 0x0>; dma-names = "rx", "tx"; + rx-threshold = <4>; + tx-threshold = <4>; rs485-rts-active-low; }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt index ecac2bbeae45..8051c17e640e 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt @@ -22,6 +22,7 @@ Required properties in pwrap device node. "mediatek,mt6765-pwrap" for MT6765 SoCs "mediatek,mt6779-pwrap" for MT6779 SoCs "mediatek,mt6797-pwrap" for MT6797 SoCs + "mediatek,mt6873-pwrap" for MT6873/8192 SoCs "mediatek,mt7622-pwrap" for MT7622 SoCs "mediatek,mt8135-pwrap" for MT8135 SoCs "mediatek,mt8173-pwrap" for MT8173 SoCs diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt index 19c059e44681..783dc81b0f26 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt @@ -17,6 +17,7 @@ power-domains. Value type: <string> Definition: must be one of: "qcom,sc7180-aoss-qmp" + "qcom,sc7280-aoss-qmp" "qcom,sdm845-aoss-qmp" "qcom,sm8150-aoss-qmp" "qcom,sm8250-aoss-qmp" diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt index 042a2e4159bd..1382b64e1381 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt @@ -24,6 +24,13 @@ block and a BT, WiFi and FM radio block, all using SMD as command channels. "qcom,riva", "qcom,pronto" +- firmware-name: + Usage: optional + Value type: <string> + Definition: specifies the relative firmware image path for the WLAN NV + blob. Defaults to "wlan/prima/WCNSS_qcom_wlan_nv.bin" if + not specified. + = SUBNODES The subnodes of the wcnss node are optional and describe the individual blocks in the WCNSS. diff --git a/Documentation/devicetree/bindings/sound/ak4642.yaml b/Documentation/devicetree/bindings/sound/ak4642.yaml index 6cd213be2266..1e2caa29790e 100644 --- a/Documentation/devicetree/bindings/sound/ak4642.yaml +++ b/Documentation/devicetree/bindings/sound/ak4642.yaml @@ -29,11 +29,9 @@ properties: clock-frequency: description: common clock binding; frequency of MCKO - $ref: /schemas/types.yaml#/definitions/uint32 clock-output-names: description: common clock name - $ref: /schemas/types.yaml#/definitions/string required: - compatible diff --git a/Documentation/devicetree/bindings/sound/ak5558.txt b/Documentation/devicetree/bindings/sound/ak5558.txt index 36934098170c..e28708db6686 100644 --- a/Documentation/devicetree/bindings/sound/ak5558.txt +++ b/Documentation/devicetree/bindings/sound/ak5558.txt @@ -4,7 +4,7 @@ This device supports I2C mode only. Required properties: -- compatible : "asahi-kasei,ak5558" +- compatible : "asahi-kasei,ak5558" or "asahi-kasei,ak5552". - reg : The I2C address of the device. Optional properties: diff --git a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml index db61f0731a20..2e35aeaa8781 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml @@ -57,7 +57,7 @@ patternProperties: rate sound-dai: - $ref: /schemas/types.yaml#/definitions/phandle + $ref: /schemas/types.yaml#/definitions/phandle-array description: phandle of the CPU DAI patternProperties: @@ -71,7 +71,7 @@ patternProperties: properties: sound-dai: - $ref: /schemas/types.yaml#/definitions/phandle + $ref: /schemas/types.yaml#/definitions/phandle-array description: phandle of the codec DAI required: diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index 766e9109b2f7..43e7f86e3b23 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -11,71 +11,59 @@ maintainers: select: false +allOf: + - $ref: /schemas/graph.yaml#/$defs/port-base + properties: - port: - description: single OF-Graph subnode - type: object + prefix: + description: "device name prefix" + $ref: /schemas/types.yaml#/definitions/string + convert-rate: + description: CPU to Codec rate convert. + $ref: /schemas/types.yaml#/definitions/uint32 + convert-channels: + description: CPU to Codec rate channels. + $ref: /schemas/types.yaml#/definitions/uint32 +patternProperties: + "^endpoint(@[0-9a-f]+)?": + $ref: /schemas/graph.yaml#/$defs/endpoint-base properties: - reg: - maxItems: 1 - prefix: - description: "device name prefix" - $ref: /schemas/types.yaml#/definitions/string + mclk-fs: + description: | + Multiplication factor between stream rate and codec mclk. + When defined, mclk-fs property defined in dai-link sub nodes are + ignored. + $ref: /schemas/types.yaml#/definitions/uint32 + frame-inversion: + description: dai-link uses frame clock inversion + $ref: /schemas/types.yaml#/definitions/flag + bitclock-inversion: + description: dai-link uses bit clock inversion + $ref: /schemas/types.yaml#/definitions/flag + frame-master: + description: Indicates dai-link frame master. + $ref: /schemas/types.yaml#/definitions/phandle + bitclock-master: + description: Indicates dai-link bit clock master + $ref: /schemas/types.yaml#/definitions/phandle + dai-format: + description: audio format. + items: + enum: + - i2s + - right_j + - left_j + - dsp_a + - dsp_b + - ac97 + - pdm + - msb + - lsb convert-rate: description: CPU to Codec rate convert. $ref: /schemas/types.yaml#/definitions/uint32 convert-channels: description: CPU to Codec rate channels. $ref: /schemas/types.yaml#/definitions/uint32 - patternProperties: - "^endpoint(@[0-9a-f]+)?": - type: object - properties: - remote-endpoint: - maxItems: 1 - mclk-fs: - description: | - Multiplication factor between stream rate and codec mclk. - When defined, mclk-fs property defined in dai-link sub nodes are - ignored. - $ref: /schemas/types.yaml#/definitions/uint32 - frame-inversion: - description: dai-link uses frame clock inversion - $ref: /schemas/types.yaml#/definitions/flag - bitclock-inversion: - description: dai-link uses bit clock inversion - $ref: /schemas/types.yaml#/definitions/flag - frame-master: - description: Indicates dai-link frame master. - $ref: /schemas/types.yaml#/definitions/phandle - bitclock-master: - description: Indicates dai-link bit clock master - $ref: /schemas/types.yaml#/definitions/phandle - dai-format: - description: audio format. - items: - enum: - - i2s - - right_j - - left_j - - dsp_a - - dsp_b - - ac97 - - pdm - - msb - - lsb - convert-rate: - description: CPU to Codec rate convert. - $ref: /schemas/types.yaml#/definitions/uint32 - convert-channels: - description: CPU to Codec rate channels. - $ref: /schemas/types.yaml#/definitions/uint32 - - ports: - description: multi OF-Graph subnode - type: object - patternProperties: - "^port(@[0-9a-f]+)?": - $ref: "#/properties/port" additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml new file mode 100644 index 000000000000..61802a11baf4 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/fsl,rpmsg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP Audio RPMSG CPU DAI Controller + +maintainers: + - Shengjiu Wang <shengjiu.wang@nxp.com> + +description: | + fsl_rpmsg is a virtual audio device. Mapping to real hardware devices + are SAI, DMA controlled by Cortex M core. What we see from Linux + side is a device which provides audio service by rpmsg channel. + +properties: + compatible: + enum: + - fsl,imx7ulp-rpmsg-audio + - fsl,imx8mn-rpmsg-audio + - fsl,imx8mm-rpmsg-audio + - fsl,imx8mp-rpmsg-audio + + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + + clocks: + items: + - description: Peripheral clock for register access + - description: Master clock + - description: DMA clock for DMA register access + - description: Parent clock for multiple of 8kHz sample rates + - description: Parent clock for multiple of 11kHz sample rates + + clock-names: + items: + - const: ipg + - const: mclk + - const: dma + - const: pll8k + - const: pll11k + + power-domains: + description: + List of phandle and PM domain specifier as documented in + Documentation/devicetree/bindings/power/power_domain.txt + maxItems: 1 + + memory-region: + maxItems: 1 + description: + phandle to a node describing reserved memory (System RAM memory) + The M core can't access all the DDR memory space on some platform, + So reserved a specific memory for dma buffer which M core can + access. + (see bindings/reserved-memory/reserved-memory.txt) + + audio-codec: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle to a node of audio codec + + 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. + + fsl,enable-lpa: + $ref: /schemas/types.yaml#/definitions/flag + description: enable low power audio path. + + fsl,rpmsg-out: + $ref: /schemas/types.yaml#/definitions/flag + description: | + This is a boolean property. If present, the transmitting function + will be enabled. + + fsl,rpmsg-in: + $ref: /schemas/types.yaml#/definitions/flag + description: | + This is a boolean property. If present, the receiving function + will be enabled. + +required: + - compatible + - model + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mn-clock.h> + + rpmsg_audio: rpmsg_audio { + compatible = "fsl,imx8mn-rpmsg-audio"; + model = "wm8524-audio"; + fsl,enable-lpa; + fsl,rpmsg-out; + clocks = <&clk IMX8MN_CLK_SAI3_IPG>, + <&clk IMX8MN_CLK_SAI3_ROOT>, + <&clk IMX8MN_CLK_SDMA3_ROOT>, + <&clk IMX8MN_AUDIO_PLL1_OUT>, + <&clk IMX8MN_AUDIO_PLL2_OUT>; + clock-names = "ipg", "mclk", "dma", "pll8k", "pll11k"; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt index 90d9e9d81624..23d83fa7609f 100644 --- a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt @@ -42,6 +42,8 @@ The compatible list for this generic sound card currently: "fsl,imx-audio-si476x" + "fsl,imx-audio-wm8958" + Required properties: - compatible : Contains one of entries in the compatible list. diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml index acfb9db021dc..77adbebed824 100644 --- a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml +++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml @@ -32,7 +32,7 @@ properties: The last one integer is the length of the shared memory. memory-region: - $ref: '/schemas/types.yaml#/definitions/phandle' + maxItems: 1 description: | Shared memory region to EC. A "shared-dma-pool". See ../reserved-memory/reserved-memory.txt for details. diff --git a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml index 6f71294909a5..803627e984f6 100644 --- a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml @@ -81,6 +81,6 @@ examples: interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; clock-names = "osc", "apb_clk"; clocks = <&scmi_clk KEEM_BAY_PSS_AUX_I2S3>, <&scmi_clk KEEM_BAY_PSS_I2S3>; - dmas = <&axi_dma0 29 &axi_dma0 33>; + dmas = <&axi_dma0 29>, <&axi_dma0 33>; dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml b/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml index 234f64a32184..81f266d66ec5 100644 --- a/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml +++ b/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml @@ -9,9 +9,6 @@ title: Marvel SSPA Digital Audio Interface Bindings maintainers: - Lubomir Rintel <lkundrak@v3.sk> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^audio-controller(@.*)?$" @@ -54,7 +51,8 @@ properties: - const: rx port: - type: object + $ref: audio-graph-port.yaml# + unevaluatedProperties: false properties: endpoint: diff --git a/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml b/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml new file mode 100644 index 000000000000..0481315cb5f2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mchp,i2s-mcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip I2S Multi-Channel Controller + +maintainers: + - Codrin Ciubotariu <codrin.ciubotariu@microchip.com> + +description: + The I2SMCC complies with the Inter-IC Sound (I2S) bus specification and + supports a Time Division Multiplexed (TDM) interface with external + multi-channel audio codecs. It consists of a receiver, a transmitter and a + common clock generator that can be enabled separately to provide Adapter, + Client or Controller modes with receiver and/or transmitter active. + On later I2SMCC versions (starting with Microchip's SAMA7G5) I2S + multi-channel is supported by using multiple data pins, output and + input, without TDM. + +properties: + "#sound-dai-cells": + const: 0 + + compatible: + enum: + - microchip,sam9x60-i2smcc + - microchip,sama7g5-i2smcc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Peripheral Bus Clock + - description: Generic Clock (Optional). Should be set mostly when Master + Mode is required. + minItems: 1 + + clock-names: + items: + - const: pclk + - const: gclk + minItems: 1 + + dmas: + items: + - description: TX DMA Channel + - description: RX DMA Channel + + dma-names: + items: + - const: tx + - const: rx + + microchip,tdm-data-pair: + description: + Represents the DIN/DOUT pair pins that are used to receive/send + TDM data. It is optional and it is only needed if the controller + uses the TDM mode. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2, 3] + default: 0 + +if: + properties: + compatible: + const: microchip,sam9x60-i2smcc +then: + properties: + microchip,tdm-data-pair: false + +required: + - "#sound-dai-cells" + - compatible + - reg + - interrupts + - clocks + - clock-names + - dmas + - dma-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/dma/at91.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + i2s@f001c000 { + #sound-dai-cells = <0>; + compatible = "microchip,sam9x60-i2smcc"; + reg = <0xf001c000 0x100>; + interrupts = <34 IRQ_TYPE_LEVEL_HIGH 7>; + dmas = <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(36))>, + <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(37))>; + dma-names = "tx", "rx"; + clocks = <&i2s_clk>, <&i2s_gclk>; + clock-names = "pclk", "gclk"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2s_default>; + }; diff --git a/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt b/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt deleted file mode 100644 index 91ec83a6faed..000000000000 --- a/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt +++ /dev/null @@ -1,43 +0,0 @@ -* Microchip I2S Multi-Channel Controller - -Required properties: -- compatible: Should be "microchip,sam9x60-i2smcc". -- reg: Should be the physical base address of the controller and the - length of memory mapped region. -- interrupts: Should contain the interrupt for the controller. -- dmas: Should be one per channel name listed in the dma-names property, - as described in atmel-dma.txt and dma.txt files. -- dma-names: Identifier string for each DMA request line in the dmas property. - Two dmas have to be defined, "tx" and "rx". -- clocks: Must contain an entry for each entry in clock-names. - Please refer to clock-bindings.txt. -- clock-names: Should be one of each entry matching the clocks phandles list: - - "pclk" (peripheral clock) Required. - - "gclk" (generated clock) Optional (1). - -Optional properties: -- pinctrl-0: Should specify pin control groups used for this controller. -- princtrl-names: Should contain only one value - "default". - - -(1) : Only the peripheral clock is required. The generated clock is optional - and should be set mostly when Master Mode is required. - -Example: - - i2s@f001c000 { - compatible = "microchip,sam9x60-i2smcc"; - reg = <0xf001c000 0x100>; - interrupts = <34 IRQ_TYPE_LEVEL_HIGH 7>; - dmas = <&dma0 - (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | - AT91_XDMAC_DT_PERID(36))>, - <&dma0 - (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | - AT91_XDMAC_DT_PERID(37))>; - dma-names = "tx", "rx"; - clocks = <&i2s_clk>, <&i2s_gclk>; - clock-names = "pclk", "gclk"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_i2s_default>; - }; diff --git a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt index 235eac8aea7b..ecd46ed8eb98 100644 --- a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt +++ b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt @@ -4,6 +4,7 @@ Required properties: - compatible : "mediatek,mt8183_mt6358_ts3a227_max98357" for MAX98357A codec "mediatek,mt8183_mt6358_ts3a227_max98357b" for MAX98357B codec "mediatek,mt8183_mt6358_ts3a227_rt1015" for RT1015 codec + "mediatek,mt8183_mt6358_ts3a227_rt1015p" for RT1015P codec - mediatek,platform: the phandle of MT8183 ASoC platform Optional properties: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml index b8645d9c38ac..5f6b37c251a8 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml @@ -17,9 +17,6 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^dspk@[0-9a-f]*$" @@ -59,14 +56,18 @@ properties: available instances on a Tegra SoC. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | DSPK ACIF (Audio Client Interface) port connected to the corresponding AHUB (Audio Hub) ACIF port. port@1: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | DSPK DAP (Digital Audio Port) interface which can be connected to external audio codec for playback. @@ -80,7 +81,7 @@ required: - assigned-clock-parents - sound-name-prefix -unevaluatedProperties: false +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml index 7cee7722df41..19eaacc3f12a 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml @@ -17,9 +17,6 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^admaif@[0-9a-f]*$" @@ -41,6 +38,7 @@ properties: dma-names: true ports: + $ref: /schemas/graph.yaml#/properties/ports description: | Contains list of ACIF (Audio CIF) port nodes for ADMAIF channels. The number of port nodes depends on the number of ADMAIF channels @@ -48,6 +46,11 @@ properties: in AHUB (Audio Hub). Each port is capable of data transfers in both directions. + patternProperties: + '^port@[0-9]': + $ref: audio-graph-port.yaml# + unevaluatedProperties: false + if: properties: compatible: @@ -92,7 +95,7 @@ required: - dmas - dma-names -unevaluatedProperties: false +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml index 31f3e51974bb..1118a9488345 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml @@ -17,9 +17,6 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^ahub@[0-9a-f]*$" @@ -60,12 +57,34 @@ properties: ranges: true ports: + $ref: /schemas/graph.yaml#/properties/ports description: | Contains list of ACIF (Audio CIF) port nodes for AHUB (Audio Hub). These are connected to ACIF interfaces of AHUB clients. Thus the number of port nodes depend on the number of clients that AHUB may have depending on the SoC revision. + patternProperties: + '^port@[0-9]': + $ref: audio-graph-port.yaml# + unevaluatedProperties: false + +patternProperties: + '^i2s@[0-9a-f]+$': + type: object + + '^dmic@[0-9a-f]+$': + type: object + $ref: nvidia,tegra210-dmic.yaml# + + '^admaif@[0-9a-f]+$': + type: object + $ref: nvidia,tegra210-admaif.yaml# + + '^dspk@[0-9a-f]+$': + type: object + $ref: nvidia,tegra186-dspk.yaml# + required: - compatible - reg @@ -77,7 +96,7 @@ required: - "#size-cells" - ranges -unevaluatedProperties: false +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml index 89f4f471be24..fd275a575055 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml @@ -16,9 +16,6 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^dmic@[0-9a-f]*$" @@ -60,14 +57,18 @@ properties: on the maximum available instances on a Tegra SoC. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | DMIC ACIF (Audio Client Interface) port connected to the corresponding AHUB (Audio Hub) ACIF port. port@1: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | DMIC DAP (Digital Audio Port) interface which can be connected to external audio codec for capture. @@ -80,7 +81,7 @@ required: - assigned-clocks - assigned-clock-parents -unevaluatedProperties: false +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml index 556460332ffb..38e52e7dbb40 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml @@ -16,9 +16,6 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> -allOf: - - $ref: audio-graph-port.yaml# - properties: $nodename: pattern: "^i2s@[0-9a-f]*$" @@ -78,14 +75,18 @@ properties: on the maximum available instances on a Tegra SoC. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | I2S ACIF (Audio Client Interface) port connected to the corresponding AHUB (Audio Hub) ACIF port. port@1: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false description: | I2S DAP (Digital Audio Port) interface which can be connected to external audio codec for playback or capture. @@ -98,7 +99,7 @@ required: - assigned-clocks - assigned-clock-parents -unevaluatedProperties: false +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index 2e1046513603..605de3a5847f 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -78,7 +78,6 @@ properties: clock-frequency: description: for audio_clkout0/1/2/3 - $ref: /schemas/types.yaml#/definitions/uint32-array clkout-lr-asynchronous: description: audio_clkoutn is asynchronizes with lr-clock. @@ -111,7 +110,9 @@ properties: - pattern: '^dvc\.[0-1]$' - pattern: '^clk_(a|b|c|i)$' - port: true + port: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false # use patternProperties to avoid naming "xxx,yyy" issue patternProperties: @@ -257,7 +258,6 @@ required: allOf: - $ref: audio-graph.yaml# - - $ref: audio-graph-port.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/rt1019.yaml b/Documentation/devicetree/bindings/sound/rt1019.yaml new file mode 100644 index 000000000000..3d5a91a942f4 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt1019.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/rt1019.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RT1019 Mono Class-D Audio Amplifier + +maintainers: + - jack.yu@realtek.com + +properties: + compatible: + const: realtek,rt1019 + + reg: + maxItems: 1 + description: I2C address of the device. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + rt1019: codec@28 { + compatible = "realtek,rt1019"; + reg = <0x28>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/rt5682.txt b/Documentation/devicetree/bindings/sound/rt5682.txt index 9c5fadb6ac82..cd8c53d8497e 100644 --- a/Documentation/devicetree/bindings/sound/rt5682.txt +++ b/Documentation/devicetree/bindings/sound/rt5682.txt @@ -44,7 +44,7 @@ Optional properties: - realtek,dmic-delay-ms : Set the delay time (ms) for the requirement of the particular DMIC. -- realtek,dmic-clk-driving-high : Set the high drving of the DMIC clock out. +- realtek,dmic-clk-driving-high : Set the high driving of the DMIC clock out. Pins on the device (for linking into audio routes) for RT5682: diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml index 4987eb91f2ab..55ae198220f4 100644 --- a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml @@ -46,11 +46,9 @@ properties: patternProperties: "^port@[0-9]$": - type: object - properties: - endpoint: true - required: - - endpoint + description: FIXME, Need to define what each port is. + $ref: audio-graph-port.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml index 228168f685cf..48ddfcbbcbae 100644 --- a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml @@ -40,11 +40,9 @@ properties: patternProperties: "^port@[0-9]$": - type: object - properties: - endpoint: true - required: - - endpoint + description: FIXME, Need to define what each port is. + $ref: audio-graph-port.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt index 9796c4639262..20931a63fd64 100644 --- a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt @@ -1,6 +1,6 @@ Texas Instruments - tlv320aic3x Codec module -The tlv320aic3x serial control bus communicates through I2C protocols +The tlv320aic3x serial control bus communicates through both I2C and SPI bus protocols Required properties: @@ -63,7 +63,7 @@ CODEC input pins for other compatible codecs: The pins can be used in referring sound node's audio-routing property. -Example: +I2C example: #include <dt-bindings/gpio/gpio.h> @@ -78,3 +78,20 @@ tlv320aic3x: tlv320aic3x@1b { DRVDD-supply = <®ulator>; DVDD-supply = <®ulator>; }; + +SPI example: + +spi0: spi@f0000000 { + tlv320aic3x: codec@0 { + compatible = "ti,tlv320aic3x"; + reg = <0>; /* CS number */ + #sound-dai-cells = <0>; + spi-max-frequency = <1000000>; + + AVDD-supply = <®ulator>; + IOVDD-supply = <®ulator>; + DRVDD-supply = <®ulator>; + DVDD-supply = <®ulator>; + ai3x-ocmv = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt index b104be131235..b93a2b3e029d 100644 --- a/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt +++ b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt @@ -54,6 +54,8 @@ board specific bus parameters. Value type: <prop-encoded-array> Definition: should specify payload transport window offset1 of each data port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-offset2: @@ -61,6 +63,8 @@ board specific bus parameters. Value type: <prop-encoded-array> Definition: should specify payload transport window offset2 of each data port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-sinterval-low: @@ -69,12 +73,16 @@ board specific bus parameters. Definition: should be sample interval low of each data port. Out ports followed by In ports. Used for Sample Interval calculation. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-word-length: Usage: optional Value type: <prop-encoded-array> Definition: should be size of payload channel sample. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-block-pack-mode: @@ -84,6 +92,8 @@ board specific bus parameters. 0 to indicate Blocks are per Channel 1 to indicate Blocks are per Port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-block-group-count: @@ -92,6 +102,8 @@ board specific bus parameters. Definition: should be in range 1 to 4 to indicate how many sample intervals are combined into a payload. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-lane-control: @@ -100,6 +112,8 @@ board specific bus parameters. Definition: should be in range 0 to 7 to identify which data lane the data port uses. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-hstart: @@ -109,6 +123,8 @@ board specific bus parameters. SoundWire Frame, i.e. left edge of the Transport sub-frame for each port. Values between 0 and 15 are valid. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-hstop: @@ -118,6 +134,8 @@ board specific bus parameters. SoundWire Frame, i.e. the right edge of the Transport sub-frame for each port. Values between 0 and 15 are valid. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,dports-type: @@ -128,6 +146,8 @@ board specific bus parameters. 1 for simple ports 2 for full port Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. Note: diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml index 667dedefd69f..e3fb553d9180 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml @@ -90,8 +90,8 @@ examples: #address-cells = <1>; #size-cells = <0>; - ethernet-switch@0 { - compatible = "micrel,ks8995m"; + display@0 { + compatible = "lg,lg4573"; spi-max-frequency = <1000000>; reg = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt deleted file mode 100644 index d99a9cf3336b..000000000000 --- a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt +++ /dev/null @@ -1,245 +0,0 @@ -Broadcom SPI controller - -The Broadcom SPI controller is a SPI master found on various SOCs, including -BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits -of : - MSPI : SPI master controller can read and write to a SPI slave device - BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration - for flash reads and be configured to do single, double, quad lane - io with 3-byte and 4-byte addressing support. - - Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. - MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance - of a MSPI master without the BSPI to use with non flash slave devices that - use SPI protocol. - -Required properties: - -- #address-cells: - Must be <1>, as required by generic SPI binding. - -- #size-cells: - Must be <0>, also as required by generic SPI binding. - -- compatible: - Must be one of : - "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi" : MSPI+BSPI on BRCMSTB SoCs - "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7425-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7429-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7435-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7445-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7216-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7278-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi" : MSPI+BSPI on Cygnus, NSP - "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi" : NS2 SoCs - -- reg: - Define the bases and ranges of the associated I/O address spaces. - The required range is MSPI controller registers. - -- reg-names: - First name does not matter, but must be reserved for the MSPI controller - register range as mentioned in 'reg' above, and will typically contain - - "bspi_regs": BSPI register range, not required with compatible - "spi-brcmstb-mspi" - - "mspi_regs": MSPI register range is required for compatible strings - - "intr_regs", "intr_status_reg" : Interrupt and status register for - NSP, NS2, Cygnus SoC - -- interrupts - The interrupts used by the MSPI and/or BSPI controller. - -- interrupt-names: - Names of interrupts associated with MSPI - - "mspi_halted" : - - "mspi_done": Indicates that the requested SPI operation is complete. - - "spi_lr_fullness_reached" : Linear read BSPI pipe full - - "spi_lr_session_aborted" : Linear read BSPI pipe aborted - - "spi_lr_impatient" : Linear read BSPI requested when pipe empty - - "spi_lr_session_done" : Linear read BSPI session done - -- clocks: - A phandle to the reference clock for this block. - -Optional properties: - - -- native-endian - Defined when using BE SoC and device uses BE register read/write - -Recommended optional m25p80 properties: -- spi-rx-bus-width: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Examples: - -BRCMSTB SoC Example: - - SPI Master (MSPI+BSPI) for SPI-NOR access: - - spi@f03e3400 { - #address-cells = <0x1>; - #size-cells = <0x0>; - compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; - reg = <0xf03e0920 0x4 0xf03e3400 0x188 0xf03e3200 0x50>; - reg-names = "cs_reg", "mspi", "bspi"; - interrupts = <0x6 0x5 0x4 0x3 0x2 0x1 0x0>; - interrupt-parent = <0x1c>; - interrupt-names = "mspi_halted", - "mspi_done", - "spi_lr_overread", - "spi_lr_session_done", - "spi_lr_impatient", - "spi_lr_session_aborted", - "spi_lr_fullness_reached"; - - clocks = <&hif_spi>; - clock-names = "sw_spi"; - - m25p80@0 { - #size-cells = <0x2>; - #address-cells = <0x2>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <0x2625a00>; - spi-cpol; - spi-cpha; - m25p,fast-read; - - flash0.bolt@0 { - reg = <0x0 0x0 0x0 0x100000>; - }; - - flash0.macadr@100000 { - reg = <0x0 0x100000 0x0 0x10000>; - }; - - flash0.nvram@110000 { - reg = <0x0 0x110000 0x0 0x10000>; - }; - - flash0.kernel@120000 { - reg = <0x0 0x120000 0x0 0x400000>; - }; - - flash0.devtree@520000 { - reg = <0x0 0x520000 0x0 0x10000>; - }; - - flash0.splash@530000 { - reg = <0x0 0x530000 0x0 0x80000>; - }; - - flash0@0 { - reg = <0x0 0x0 0x0 0x4000000>; - }; - }; - }; - - - MSPI master for any SPI device : - - spi@f0416000 { - #address-cells = <1>; - #size-cells = <0>; - clocks = <&upg_fixed>; - compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; - reg = <0xf0416000 0x180>; - reg-names = "mspi"; - interrupts = <0x14>; - interrupt-parent = <&irq0_aon_intc>; - interrupt-names = "mspi_done"; - }; - -iProc SoC Example: - - qspi: spi@18027200 { - compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; - reg = <0x18027200 0x184>, - <0x18027000 0x124>, - <0x1811c408 0x004>, - <0x180273a0 0x01c>; - reg-names = "mspi_regs", "bspi_regs", "intr_regs", "intr_status_reg"; - interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = - "spi_lr_fullness_reached", - "spi_lr_session_aborted", - "spi_lr_impatient", - "spi_lr_session_done", - "mspi_done", - "mspi_halted"; - clocks = <&iprocmed>; - clock-names = "iprocmed"; - num-cs = <2>; - #address-cells = <1>; - #size-cells = <0>; - }; - - - NS2 SoC Example: - - qspi: spi@66470200 { - compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; - reg = <0x66470200 0x184>, - <0x66470000 0x124>, - <0x67017408 0x004>, - <0x664703a0 0x01c>; - reg-names = "mspi", "bspi", "intr_regs", - "intr_status_reg"; - interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "spi_l1_intr"; - clocks = <&iprocmed>; - clock-names = "iprocmed"; - num-cs = <2>; - #address-cells = <1>; - #size-cells = <0>; - }; - - - m25p80 node for NSP, NS2 - - &qspi { - flash: m25p80@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <12500000>; - m25p,fast-read; - spi-cpol; - spi-cpha; - - partition@0 { - label = "boot"; - reg = <0x00000000 0x000a0000>; - }; - - partition@a0000 { - label = "env"; - reg = <0x000a0000 0x00060000>; - }; - - partition@100000 { - label = "system"; - reg = <0x00100000 0x00600000>; - }; - - partition@700000 { - label = "rootfs"; - reg = <0x00700000 0x01900000>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml new file mode 100644 index 000000000000..6ee19d49fd3c --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml @@ -0,0 +1,198 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/brcm,spi-bcm-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom SPI controller + +maintainers: + - Kamal Dasu <kdasu.kdev@gmail.com> + - Rafał Miłecki <rafal@milecki.pl> + +description: | + The Broadcom SPI controller is a SPI master found on various SOCs, including + BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits + of: + MSPI : SPI master controller can read and write to a SPI slave device + BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration + for flash reads and be configured to do single, double, quad lane + io with 3-byte and 4-byte addressing support. + + Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. + MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance + of a MSPI master without the BSPI to use with non flash slave devices that + use SPI protocol. + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - description: Second Instance of MSPI BRCMSTB SoCs + items: + - enum: + - brcm,spi-bcm7425-qspi + - brcm,spi-bcm7429-qspi + - brcm,spi-bcm7435-qspi + - brcm,spi-bcm7445-qspi + - brcm,spi-bcm7216-qspi + - brcm,spi-bcm7278-qspi + - const: brcm,spi-bcm-qspi + - const: brcm,spi-brcmstb-mspi + - description: Second Instance of MSPI BRCMSTB SoCs + items: + - enum: + - brcm,spi-brcmstb-qspi + - brcm,spi-brcmstb-mspi + - brcm,spi-nsp-qspi + - brcm,spi-ns2-qspi + - const: brcm,spi-bcm-qspi + + reg: + minItems: 1 + maxItems: 5 + + reg-names: + minItems: 1 + maxItems: 5 + items: + - const: mspi + - const: bspi + - enum: [ intr_regs, intr_status_reg, cs_reg ] + - enum: [ intr_regs, intr_status_reg, cs_reg ] + - enum: [ intr_regs, intr_status_reg, cs_reg ] + + interrupts: + minItems: 1 + maxItems: 7 + + interrupt-names: + oneOf: + - minItems: 1 + maxItems: 7 + items: + - const: mspi_done + - const: mspi_halted + - const: spi_lr_fullness_reached + - const: spi_lr_session_aborted + - const: spi_lr_impatient + - const: spi_lr_session_done + - const: spi_lr_overread + - const: spi_l1_intr + + clocks: + maxItems: 1 + description: reference clock for this block + + native-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: Defined when using BE SoC and device uses BE register read/write + +unevaluatedProperties: false + +required: + - reg + - reg-names + - interrupts + - interrupt-names + +examples: + - | # BRCMSTB SoC: SPI Master (MSPI+BSPI) for SPI-NOR access + spi@f03e3400 { + compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; + reg = <0xf03e3400 0x188>, <0xf03e3200 0x50>, <0xf03e0920 0x4>; + reg-names = "mspi", "bspi", "cs_reg"; + interrupts = <0x5>, <0x6>, <0x1>, <0x2>, <0x3>, <0x4>, <0x0>; + interrupt-parent = <&gic>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done", + "spi_lr_overread"; + clocks = <&hif_spi>; + #address-cells = <0x1>; + #size-cells = <0x0>; + + flash@0 { + #size-cells = <0x2>; + #address-cells = <0x2>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <0x2625a00>; + spi-cpol; + spi-cpha; + }; + }; + - | # BRCMSTB SoC: MSPI master for any SPI device + spi@f0416000 { + clocks = <&upg_fixed>; + compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; + reg = <0xf0416000 0x180>; + reg-names = "mspi"; + interrupts = <0x14>; + interrupt-parent = <&irq0_aon_intc>; + interrupt-names = "mspi_done"; + #address-cells = <1>; + #size-cells = <0>; + }; + - | # iProc SoC + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@18027200 { + compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; + reg = <0x18027200 0x184>, + <0x18027000 0x124>, + <0x1811c408 0x004>, + <0x180273a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + }; + - | # NS2 SoC + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@66470200 { + compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; + reg = <0x66470200 0x184>, + <0x66470000 0x124>, + <0x67017408 0x004>, + <0x664703a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "spi_l1_intr"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <12500000>; + spi-cpol; + spi-cpha; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/cadence-quadspi.txt b/Documentation/devicetree/bindings/spi/cadence-quadspi.txt deleted file mode 100644 index 8ace832a2d80..000000000000 --- a/Documentation/devicetree/bindings/spi/cadence-quadspi.txt +++ /dev/null @@ -1,68 +0,0 @@ -* Cadence Quad SPI controller - -Required properties: -- compatible : should be one of the following: - Generic default - "cdns,qspi-nor". - For TI 66AK2G SoC - "ti,k2g-qspi", "cdns,qspi-nor". - For TI AM654 SoC - "ti,am654-ospi", "cdns,qspi-nor". - For Intel LGM SoC - "intel,lgm-qspi", "cdns,qspi-nor". -- reg : Contains two entries, each of which is a tuple consisting of a - physical address and length. The first entry is the address and - length of the controller register set. The second entry is the - address and length of the QSPI Controller data area. -- interrupts : Unit interrupt specifier for the controller interrupt. -- clocks : phandle to the Quad SPI clock. -- cdns,fifo-depth : Size of the data FIFO in words. -- cdns,fifo-width : Bus width of the data FIFO in bytes. -- cdns,trigger-address : 32-bit indirect AHB trigger address. - -Optional properties: -- cdns,is-decoded-cs : Flag to indicate whether decoder is used or not. -- cdns,rclk-en : Flag to indicate that QSPI return clock is used to latch - the read data rather than the QSPI clock. Make sure that QSPI return - clock is populated on the board before using this property. - -Optional subnodes: -Subnodes of the Cadence Quad SPI controller are spi slave nodes with additional -custom properties: -- cdns,read-delay : Delay for read capture logic, in clock cycles -- cdns,tshsl-ns : Delay in nanoseconds for the length that the master - mode chip select outputs are de-asserted between - transactions. -- cdns,tsd2d-ns : Delay in nanoseconds between one chip select being - de-activated and the activation of another. -- cdns,tchsh-ns : Delay in nanoseconds between last bit of current - transaction and deasserting the device chip select - (qspi_n_ss_out). -- cdns,tslch-ns : Delay in nanoseconds between setting qspi_n_ss_out low - and first bit transfer. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include either "qspi" and/or "qspi-ocp". - -Example: - - qspi: spi@ff705000 { - compatible = "cdns,qspi-nor"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0xff705000 0x1000>, - <0xffa00000 0x1000>; - interrupts = <0 151 4>; - clocks = <&qspi_clk>; - cdns,is-decoded-cs; - cdns,fifo-depth = <128>; - cdns,fifo-width = <4>; - cdns,trigger-address = <0x00000000>; - resets = <&rst QSPI_RESET>, <&rst QSPI_OCP_RESET>; - reset-names = "qspi", "qspi-ocp"; - - flash0: n25q00@0 { - ... - cdns,read-delay = <4>; - cdns,tshsl-ns = <50>; - cdns,tsd2d-ns = <50>; - cdns,tchsh-ns = <4>; - cdns,tslch-ns = <4>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml new file mode 100644 index 000000000000..0e7087cc8bf9 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -0,0 +1,143 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/cdns,qspi-nor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence Quad SPI controller + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,k2g-qspi + - ti,am654-ospi + - intel,lgm-qspi + - const: cdns,qspi-nor + - const: cdns,qspi-nor + + reg: + items: + - description: the controller register set + - description: the controller data area + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + cdns,fifo-depth: + description: + Size of the data FIFO in words. + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 128, 256 ] + default: 128 + + cdns,fifo-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Bus width of the data FIFO in bytes. + default: 4 + + cdns,trigger-address: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + 32-bit indirect AHB trigger address. + + cdns,is-decoded-cs: + type: boolean + description: + Flag to indicate whether decoder is used to select different chip select + for different memory regions. + + cdns,rclk-en: + type: boolean + description: + Flag to indicate that QSPI return clock is used to latch the read + data rather than the QSPI clock. Make sure that QSPI return clock + is populated on the board before using this property. + + resets: + maxItems: 2 + + reset-names: + minItems: 1 + maxItems: 2 + 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 + - interrupts + - clocks + - cdns,fifo-depth + - cdns,fifo-width + - cdns,trigger-address + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + qspi: spi@ff705000 { + compatible = "cdns,qspi-nor"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xff705000 0x1000>, + <0xffa00000 0x1000>; + interrupts = <0 151 4>; + clocks = <&qspi_clk>; + cdns,fifo-depth = <128>; + cdns,fifo-width = <4>; + cdns,trigger-address = <0x00000000>; + resets = <&rst 0x1>, <&rst 0x2>; + reset-names = "qspi", "qspi-ocp"; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0x0>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml new file mode 100644 index 000000000000..e58644558412 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/fsl,spi-fsl-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Quad Serial Peripheral Interface (QuadSPI) + +maintainers: + - Han Xu <han.xu@nxp.com> + +allOf: + - $ref: "spi-controller.yaml#" + +properties: + compatible: + oneOf: + - enum: + - fsl,vf610-qspi + - fsl,imx6sx-qspi + - fsl,imx7d-qspi + - fsl,imx6ul-qspi + - fsl,ls1021a-qspi + - fsl,ls2080a-qspi + - items: + - enum: + - fsl,ls1043a-qspi + - const: fsl,ls1021a-qspi + - items: + - enum: + - fsl,imx8mq-qspi + - const: fsl,imx7d-qspi + + reg: + items: + - description: registers + - description: memory mapping + + reg-names: + items: + - const: QuadSPI + - const: QuadSPI-memory + + interrupts: + maxItems: 1 + + clocks: + items: + - description: SoC SPI qspi_en clock + - description: SoC SPI qspi clock + + clock-names: + items: + - const: qspi_en + - const: qspi + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/fsl,qoriq-clockgen.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + spi@1550000 { + compatible = "fsl,ls1021a-qspi"; + reg = <0x0 0x1550000 0x0 0x100000>, + <0x0 0x40000000 0x0 0x10000000>; + reg-names = "QuadSPI", "QuadSPI-memory"; + interrupts = <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&clockgen QORIQ_CLK_PLATFORM_PLL QORIQ_CLK_PLL_DIV(2)>, + <&clockgen QORIQ_CLK_PLATFORM_PLL QORIQ_CLK_PLL_DIV(2)>; + clock-names = "qspi_en", "qspi"; + + 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/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 55c239446a5b..7393f30535df 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -31,6 +31,7 @@ properties: - mediatek,mt7623-nor - mediatek,mt7629-nor - mediatek,mt8192-nor + - mediatek,mt8195-nor - enum: - mediatek,mt8173-nor - items: diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 06786f1b43d2..0477396e4945 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -181,22 +181,23 @@ additionalProperties: true examples: - | - spi@f00 { + spi@80010000 { #address-cells = <1>; #size-cells = <0>; - compatible = "fsl,mpc5200b-spi","fsl,mpc5200-spi"; - reg = <0xf00 0x20>; - interrupts = <2 13 0 2 14 0>; - interrupt-parent = <&mpc5200_pic>; - - ethernet-switch@0 { - compatible = "micrel,ks8995m"; + compatible = "fsl,imx28-spi"; + reg = <0x80010000 0x2000>; + interrupts = <96>; + dmas = <&dma_apbh 0>; + dma-names = "rx-tx"; + + display@0 { + compatible = "lg,lg4573"; spi-max-frequency = <1000000>; reg = <0>; }; - codec@1 { - compatible = "ti,tlv320aic26"; + sensor@1 { + compatible = "bosch,bme680"; spi-max-frequency = <100000>; reg = <1>; }; diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt deleted file mode 100644 index 69dc5d57b1ef..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt +++ /dev/null @@ -1,66 +0,0 @@ -* Freescale Quad Serial Peripheral Interface(QuadSPI) - -Required properties: - - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi", - "fsl,imx7d-qspi", "fsl,imx6ul-qspi", - "fsl,ls1021a-qspi", "fsl,ls2080a-qspi" - or - "fsl,ls1043a-qspi" followed by "fsl,ls1021a-qspi" - - reg : the first contains the register location and length, - the second contains the memory mapping address and length - - reg-names: Should contain the reg names "QuadSPI" and "QuadSPI-memory" - - interrupts : Should contain the interrupt for the device - - clocks : The clocks needed by the QuadSPI controller - - clock-names : Should contain the name of the clocks: "qspi_en" and "qspi". - -Required SPI slave node properties: - - reg: There are two buses (A and B) with two chip selects each. - This encodes to which bus and CS the flash is connected: - <0>: Bus A, CS 0 - <1>: Bus A, CS 1 - <2>: Bus B, CS 0 - <3>: Bus B, CS 1 - -Example: - -qspi0: quadspi@40044000 { - compatible = "fsl,vf610-qspi"; - reg = <0x40044000 0x1000>, <0x20000000 0x10000000>; - reg-names = "QuadSPI", "QuadSPI-memory"; - interrupts = <0 24 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks VF610_CLK_QSPI0_EN>, - <&clks VF610_CLK_QSPI0>; - clock-names = "qspi_en", "qspi"; - - flash0: s25fl128s@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "spansion,s25fl128s", "jedec,spi-nor"; - spi-max-frequency = <50000000>; - reg = <0>; - }; -}; - -Example showing the usage of two SPI NOR devices on bus A: - -&qspi2 { - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_qspi2>; - status = "okay"; - - flash0: n25q256a@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "micron,n25q256a", "jedec,spi-nor"; - spi-max-frequency = <29000000>; - reg = <0>; - }; - - flash1: n25q256a@1 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "micron,n25q256a", "jedec,spi-nor"; - spi-max-frequency = <29000000>; - reg = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 9e43721fa7d6..4d0e4c15c4ea 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -12,7 +12,9 @@ Required properties: - mediatek,mt8173-spi: for mt8173 platforms - mediatek,mt8183-spi: for mt8183 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. diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml index 6c21a132b51f..51c7622dc20b 100644 --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml @@ -72,19 +72,15 @@ examples: mux-controls = <&mux>; - spi-flash@0 { + flash@0 { compatible = "jedec,spi-nor"; reg = <0>; - #address-cells = <1>; - #size-cells = <0>; spi-max-frequency = <40000000>; }; - spi-device@1 { - compatible = "lineartechnology,ltc2488"; + sensor@1 { + compatible = "bosch,bme680"; reg = <1>; - #address-cells = <1>; - #size-cells = <0>; spi-max-frequency = <10000000>; }; }; diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt index 7ac60d9fe357..8f34a7c7d8b8 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt @@ -4,6 +4,8 @@ Required properties: - compatible : Should be "nxp,lx2160a-fspi" "nxp,imx8qxp-fspi" "nxp,imx8mm-fspi" + "nxp,imx8mp-fspi" + "nxp,imx8dxl-fspi" - reg : First contains the register location and length, Second contains the memory mapping address and length diff --git a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt b/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt index c37e5a179b21..9192724540fd 100644 --- a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt @@ -3,6 +3,7 @@ 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. diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index d11806b1ede3..2d9af4c506bb 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -96,12 +96,6 @@ examples: dma-names = "rx", "tx"; cs-gpios = <&gpioa 11 0>; - aardvark@0 { - compatible = "totalphase,aardvark"; - reg = <0>; - spi-max-frequency = <4000000>; - st,spi-midi-ns = <4000>; - }; }; ... diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 68129ff09967..104fa8fb2c17 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ========================================== -Submitting devicetree (DT) binding patches +Submitting Devicetree (DT) binding patches ========================================== I. For patch submitters @@ -25,7 +25,7 @@ I. For patch submitters make dt_binding_check - See Documentation/devicetree/writing-schema.rst for more details about + See Documentation/devicetree/bindings/writing-schema.rst for more details about schema and tools setup. 3) DT binding files should be dual licensed. The preferred license tag is @@ -75,8 +75,8 @@ II. For kernel maintainers binding, and it hasn't received an Acked-by from the devicetree maintainers after a few weeks, go ahead and take it. - Subsystem bindings (anything affecting more than a single device) - then getting a devicetree maintainer to review it is required. + For subsystem bindings (anything affecting more than a single device), + getting a devicetree maintainer to review it is required. 3) For a series going though multiple trees, the binding patch should be kept with the driver using the binding. @@ -84,7 +84,7 @@ II. For kernel maintainers III. Notes ========== - 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI. + 0) Please see :doc:`ABI` for details regarding devicetree ABI. 1) This document is intended as a general familiarization with the process as decided at the 2013 Kernel Summit. When in doubt, the current word of the diff --git a/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.txt b/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.txt deleted file mode 100644 index 68e047170039..000000000000 --- a/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.txt +++ /dev/null @@ -1,37 +0,0 @@ -* Broadcom Northstar Thermal - -This binding describes thermal sensor that is part of Northstar's DMU (Device -Management Unit). - -Required properties: -- compatible : Must be "brcm,ns-thermal" -- reg : iomem address range of PVTMON registers -- #thermal-sensor-cells : Should be <0> - -Example: - -thermal: thermal@1800c2c0 { - compatible = "brcm,ns-thermal"; - reg = <0x1800c2c0 0x10>; - #thermal-sensor-cells = <0>; -}; - -thermal-zones { - cpu_thermal: cpu-thermal { - polling-delay-passive = <0>; - polling-delay = <1000>; - coefficients = <(-556) 418000>; - thermal-sensors = <&thermal>; - - trips { - cpu-crit { - temperature = <125000>; - hysteresis = <0>; - type = "critical"; - }; - }; - - cooling-maps { - }; - }; -}; diff --git a/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.yaml b/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.yaml new file mode 100644 index 000000000000..fdeb333e010d --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/brcm,ns-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Northstar Thermal + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +description: + Thermal sensor that is part of Northstar's DMU (Device Management Unit). + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + const: brcm,ns-thermal + + reg: + description: PVTMON registers range + maxItems: 1 + + "#thermal-sensor-cells": + const: 0 + +unevaluatedProperties: false + +required: + - reg + +examples: + - | + thermal: thermal@1800c2c0 { + compatible = "brcm,ns-thermal"; + reg = <0x1800c2c0 0x10>; + #thermal-sensor-cells = <0>; + }; + + thermal-zones { + cpu-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + coefficients = <(-556) 418000>; + thermal-sensors = <&thermal>; + + trips { + cpu-crit { + temperature = <125000>; + hysteresis = <0>; + type = "critical"; + }; + }; + + cooling-maps { + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml index 7cd364430573..3ea8c0c1f45f 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml @@ -59,7 +59,6 @@ patternProperties: properties: reg: - $ref: /schemas/types.yaml#/definitions/uint32 description: Specify the sensor channel. There are 8 channels in PMIC5's ADC TM minimum: 0 maximum: 7 @@ -78,7 +77,6 @@ patternProperties: also known as absolute calibration. qcom,hw-settle-time-us: - $ref: /schemas/types.yaml#/definitions/uint32 description: Time between AMUX getting configured and the ADC starting conversion. enum: [15, 100, 200, 300, 400, 500, 600, 700, 1000, 2000, 4000, 8000, 16000, 32000, 64000, 128000] diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 95462e071ab4..0242fd91b622 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -19,9 +19,15 @@ description: | properties: compatible: oneOf: + - description: msm9860 TSENS based + items: + - enum: + - qcom,ipq8064-tsens + - description: v0.1 of TSENS items: - enum: + - qcom,mdm9607-tsens - qcom,msm8916-tsens - qcom,msm8939-tsens - qcom,msm8974-tsens @@ -43,6 +49,7 @@ properties: - qcom,sdm845-tsens - qcom,sm8150-tsens - qcom,sm8250-tsens + - qcom,sm8350-tsens - const: qcom,tsens-v2 reg: @@ -73,7 +80,9 @@ properties: maxItems: 2 items: - const: calib - - const: calib_sel + - enum: + - calib_backup + - calib_sel "#qcom,sensors": description: @@ -88,12 +97,21 @@ properties: Number of cells required to uniquely identify the thermal sensors. Since we have multiple sensors this is set to 1 +required: + - compatible + - interrupts + - interrupt-names + - "#thermal-sensor-cells" + - "#qcom,sensors" + allOf: - if: properties: compatible: contains: enum: + - qcom,ipq8064-tsens + - qcom,mdm9607-tsens - qcom,msm8916-tsens - qcom,msm8974-tsens - qcom,msm8976-tsens @@ -114,19 +132,44 @@ allOf: interrupt-names: minItems: 2 -required: - - compatible - - reg - - "#qcom,sensors" - - interrupts - - interrupt-names - - "#thermal-sensor-cells" + - if: + properties: + compatible: + contains: + enum: + - qcom,tsens-v0_1 + - qcom,tsens-v1 + - qcom,tsens-v2 + + then: + required: + - reg additionalProperties: false examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> + // Example msm9860 based SoC (ipq8064): + gcc: clock-controller { + + /* ... */ + + tsens: thermal-sensor { + compatible = "qcom,ipq8064-tsens"; + + nvmem-cells = <&tsens_calib>, <&tsens_calib_backup>; + nvmem-cell-names = "calib", "calib_backup"; + interrupts = <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow"; + + #qcom,sensors = <11>; + #thermal-sensor-cells = <1>; + }; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> // Example 1 (legacy: for pre v1 IP): tsens1: thermal-sensor@900000 { compatible = "qcom,msm8916-tsens", "qcom,tsens-v0_1"; diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml index b33a76eeac4e..f963204e0b16 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml @@ -28,14 +28,7 @@ properties: - renesas,r8a77980-thermal # R-Car V3H - renesas,r8a779a0-thermal # R-Car V3U - reg: - minItems: 2 - maxItems: 4 - items: - - description: TSC1 registers - - description: TSC2 registers - - description: TSC3 registers - - description: TSC4 registers + reg: true interrupts: items: @@ -71,8 +64,25 @@ if: enum: - renesas,r8a779a0-thermal then: + properties: + reg: + minItems: 2 + maxItems: 3 + items: + - description: TSC1 registers + - description: TSC2 registers + - description: TSC3 registers required: - interrupts +else: + properties: + reg: + items: + - description: TSC0 registers + - description: TSC1 registers + - description: TSC2 registers + - description: TSC3 registers + - description: TSC4 registers additionalProperties: false @@ -111,3 +121,20 @@ examples: }; }; }; + - | + #include <dt-bindings/clock/r8a779a0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779a0-sysc.h> + + tsc_r8a779a0: thermal@e6190000 { + compatible = "renesas,r8a779a0-thermal"; + reg = <0xe6190000 0x200>, + <0xe6198000 0x200>, + <0xe61a0000 0x200>, + <0xe61a8000 0x200>, + <0xe61b0000 0x200>; + clocks = <&cpg CPG_MOD 919>; + power-domains = <&sysc R8A779A0_PD_ALWAYS_ON>; + resets = <&cpg 919>; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml index 9f747921e851..4bd345c71eb8 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml @@ -36,6 +36,9 @@ properties: containing several internal sensors. enum: [0, 1] +required: + - "#thermal-sensor-cells" + additionalProperties: true examples: diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml index 2c75105c1398..7f5e3af58255 100644 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml @@ -34,11 +34,30 @@ properties: - arm,armv8-timer interrupts: + minItems: 1 + maxItems: 5 items: - description: secure timer irq - description: non-secure timer irq - description: virtual timer irq - description: hypervisor timer irq + - description: hypervisor virtual timer irq + + interrupt-names: + oneOf: + - minItems: 2 + items: + - const: phys + - const: virt + - const: hyp-phys + - const: hyp-virt + - minItems: 3 + items: + - const: sec-phys + - const: phys + - const: virt + - const: hyp-phys + - const: hyp-virt clock-frequency: description: The frequency of the main counter, in Hz. Should be present diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index 024bcad75101..8165df4599cf 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -20,6 +20,8 @@ select: enum: - ingenic,jz4740-tcu - ingenic,jz4725b-tcu + - ingenic,jz4760-tcu + - ingenic,jz4760b-tcu - ingenic,jz4770-tcu - ingenic,jz4780-tcu - ingenic,x1000-tcu @@ -52,12 +54,15 @@ properties: - enum: - ingenic,jz4740-tcu - ingenic,jz4725b-tcu - - ingenic,jz4770-tcu + - ingenic,jz4760-tcu - ingenic,x1000-tcu - const: simple-mfd - items: - - const: ingenic,jz4780-tcu - - const: ingenic,jz4770-tcu + - enum: + - ingenic,jz4780-tcu + - ingenic,jz4770-tcu + - ingenic,jz4760b-tcu + - const: ingenic,jz4760-tcu - const: simple-mfd reg: @@ -118,6 +123,8 @@ patternProperties: - items: - enum: - ingenic,jz4770-watchdog + - ingenic,jz4760b-watchdog + - ingenic,jz4760-watchdog - ingenic,jz4725b-watchdog - const: ingenic,jz4740-watchdog @@ -147,6 +154,8 @@ patternProperties: - ingenic,jz4725b-pwm - items: - enum: + - ingenic,jz4760-pwm + - ingenic,jz4760b-pwm - ingenic,jz4770-pwm - ingenic,jz4780-pwm - const: ingenic,jz4740-pwm @@ -183,10 +192,15 @@ patternProperties: oneOf: - enum: - ingenic,jz4725b-ost - - ingenic,jz4770-ost + - ingenic,jz4760b-ost - items: - - const: ingenic,jz4780-ost - - const: ingenic,jz4770-ost + - const: ingenic,jz4760-ost + - const: ingenic,jz4725b-ost + - items: + - enum: + - ingenic,jz4780-ost + - ingenic,jz4770-ost + - const: ingenic,jz4760b-ost reg: maxItems: 1 @@ -226,7 +240,7 @@ examples: #include <dt-bindings/clock/jz4770-cgu.h> #include <dt-bindings/clock/ingenic,tcu.h> tcu: timer@10002000 { - compatible = "ingenic,jz4770-tcu", "simple-mfd"; + compatible = "ingenic,jz4770-tcu", "ingenic,jz4760-tcu", "simple-mfd"; reg = <0x10002000 0x1000>; #address-cells = <1>; #size-cells = <1>; @@ -272,7 +286,7 @@ examples: }; ost: timer@e0 { - compatible = "ingenic,jz4770-ost"; + compatible = "ingenic,jz4770-ost", "ingenic,jz4760b-ost"; reg = <0xe0 0x20>; clocks = <&tcu TCU_CLK_OST>; diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 690a9c0966ac..e5c57d6e0186 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -23,6 +23,7 @@ Required properties: For those SoCs that use SYST * "mediatek,mt8183-timer" for MT8183 compatible timers (SYST) * "mediatek,mt8192-timer" for MT8192 compatible timers (SYST) + * "mediatek,mt8195-timer" for MT8195 compatible timers (SYST) * "mediatek,mt7629-timer" for MT7629 compatible timers (SYST) * "mediatek,mt6765-timer" for MT6765 and all above compatible timers (SYST) diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt index 97258f1a1505..ac3a5e887455 100644 --- a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt @@ -4,7 +4,8 @@ Nuvoton NPCM7xx have three timer modules, each timer module provides five 24-bit timer counters. Required properties: -- compatible : "nuvoton,npcm750-timer" for Poleg NPCM750. +- compatible : "nuvoton,npcm750-timer" for Poleg NPCM750, or + "nuvoton,wpcm450-timer" for Hermon WPCM450. - reg : Offset and length of the register set for the device. - interrupts : Contain the timer interrupt of timer 0. - clocks : phandle of timer reference clock (usually a 25 MHz clock). diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml index 428db3a21bb9..53dd6d9f518f 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml @@ -74,11 +74,13 @@ properties: - renesas,r8a774e1-cmt0 # 32-bit CMT0 on RZ/G2H - renesas,r8a7795-cmt0 # 32-bit CMT0 on R-Car H3 - renesas,r8a7796-cmt0 # 32-bit CMT0 on R-Car M3-W + - renesas,r8a77961-cmt0 # 32-bit CMT0 on R-Car M3-W+ - renesas,r8a77965-cmt0 # 32-bit CMT0 on R-Car M3-N - renesas,r8a77970-cmt0 # 32-bit CMT0 on R-Car V3M - renesas,r8a77980-cmt0 # 32-bit CMT0 on R-Car V3H - renesas,r8a77990-cmt0 # 32-bit CMT0 on R-Car E3 - renesas,r8a77995-cmt0 # 32-bit CMT0 on R-Car D3 + - renesas,r8a779a0-cmt0 # 32-bit CMT0 on R-Car V3U - const: renesas,rcar-gen3-cmt0 # 32-bit CMT0 on R-Car Gen3 and RZ/G2 - items: @@ -89,11 +91,13 @@ properties: - renesas,r8a774e1-cmt1 # 48-bit CMT on RZ/G2H - renesas,r8a7795-cmt1 # 48-bit CMT on R-Car H3 - renesas,r8a7796-cmt1 # 48-bit CMT on R-Car M3-W + - renesas,r8a77961-cmt1 # 48-bit CMT on R-Car M3-W+ - renesas,r8a77965-cmt1 # 48-bit CMT on R-Car M3-N - renesas,r8a77970-cmt1 # 48-bit CMT on R-Car V3M - renesas,r8a77980-cmt1 # 48-bit CMT on R-Car V3H - renesas,r8a77990-cmt1 # 48-bit CMT on R-Car E3 - renesas,r8a77995-cmt1 # 48-bit CMT on R-Car D3 + - renesas,r8a779a0-cmt1 # 48-bit CMT on R-Car V3U - const: renesas,rcar-gen3-cmt1 # 48-bit CMT on R-Car Gen3 and RZ/G2 reg: diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml index c54188731a1b..f0f0f121c355 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml @@ -28,8 +28,14 @@ properties: - renesas,tmu-r8a774e1 # RZ/G2H - renesas,tmu-r8a7778 # R-Car M1A - renesas,tmu-r8a7779 # R-Car H1 + - renesas,tmu-r8a7795 # R-Car H3 + - renesas,tmu-r8a7796 # R-Car M3-W + - renesas,tmu-r8a77961 # R-Car M3-W+ + - renesas,tmu-r8a77965 # R-Car M3-N - renesas,tmu-r8a77970 # R-Car V3M - renesas,tmu-r8a77980 # R-Car V3H + - renesas,tmu-r8a77990 # R-Car E3 + - renesas,tmu-r8a77995 # R-Car D3 - const: renesas,tmu reg: diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 706aa102d96d..99ef911eacec 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -23,6 +23,9 @@ properties: maxItems: 1 interrupts: maxItems: 1 + + spi-max-frequency: true + compatible: items: - enum: @@ -50,6 +53,8 @@ properties: - atmel,atsha204a # i2c h/w elliptic curve crypto module - atmel,atecc508a + # BPA-RS600: Power Supply + - blutek,bpa-rs600 # Bosch Sensortec pressure, temperature, humididty and VOC sensor - bosch,bme680 # CM32181: Ambient Light Sensor @@ -102,6 +107,8 @@ properties: - mps,mp2975 # G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface - gmt,g751 + # Infineon IR36021 digital POL buck controller + - infineon,ir36021 # Infineon IR38064 Voltage Regulator - infineon,ir38064 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) @@ -290,6 +297,8 @@ properties: - ti,tmp103 # Digital Temperature Sensor - ti,tmp275 + # 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 diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index 415ccdd7442d..d8fd4df81743 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -14,6 +14,8 @@ Required properties: "qcom,msm8998-ufshc", "qcom,ufshc", "jedec,ufs-2.0" "qcom,sdm845-ufshc", "qcom,ufshc", "jedec,ufs-2.0" "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" - interrupts : <interrupt mapping for UFS host controller IRQ> - reg : <registers mapping> diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt index a668f43bedf5..04813a46e5d0 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt @@ -1,32 +1,56 @@ Xilinx SuperSpeed DWC3 USB SoC controller Required properties: -- compatible: Should contain "xlnx,zynqmp-dwc3" +- 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>; - interrupts = <0x0 0x41 0x4>; + 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/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml index cb4c6f6d3a33..974032b1fda0 100644 --- a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -52,11 +52,8 @@ properties: # Required child node: patternProperties: - "^dwc3@[0-9a-f]+$": - type: object - description: - A child node must exist to represent the core DWC3 IP block - The content of the node is defined in dwc3.txt. + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# required: - compatible @@ -87,7 +84,7 @@ examples: dma-ranges = <0x40000000 0x40000000 0xc0000000>; ranges; - dwc3@38100000 { + usb@38100000 { compatible = "snps,dwc3"; reg = <0x38100000 0x10000>; clocks = <&clk IMX8MP_CLK_HSIO_AXI>, diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index cf83f2d9afac..8089dc956ba3 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -122,6 +122,12 @@ properties: description: Set this flag to force EHCI reset after resume. + spurious-oc: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag to indicate that the hardware sometimes turns on + the OC bit when an over-current isn't actually present. + companion: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml index 14f40efb3b22..240882b12565 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -30,6 +30,7 @@ properties: - mediatek,mt7629-xhci - mediatek,mt8173-xhci - mediatek,mt8183-xhci + - mediatek,mt8192-xhci - const: mediatek,mtk-xhci reg: @@ -45,7 +46,18 @@ properties: - const: ippc # optional, only needed for case 1. interrupts: - maxItems: 1 + description: + use "interrupts-extended" when the interrupts are connected to the + separate interrupt controllers + minItems: 1 + items: + - description: xHCI host controller interrupt + - description: optional, wakeup interrupt used to support runtime PM + + interrupt-names: + items: + - const: host + - const: wakeup power-domains: description: A phandle to USB power domain node to control USB's MTCMOS @@ -99,9 +111,9 @@ properties: vbus-supply: description: Regulator of USB VBUS5v - usb3-lpm-capable: - description: supports USB3.0 LPM - type: boolean + usb3-lpm-capable: true + + usb2-lpm-disable: true imod-interval-ns: description: @@ -127,10 +139,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index f5c04b9d2de9..dbc7876e0a0b 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -24,6 +24,7 @@ properties: - mediatek,mt2712-mtu3 - mediatek,mt8173-mtu3 - mediatek,mt8183-mtu3 + - mediatek,mt8192-mtu3 - const: mediatek,mtu3 reg: @@ -126,7 +127,7 @@ properties: 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. See graph.txt - type: object + $ref: /schemas/graph.yaml#/properties/port enable-manual-drd: $ref: /schemas/types.yaml#/definitions/flag @@ -152,10 +153,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 with following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index c3cbd1fa9944..413299b5fe2b 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -16,6 +16,7 @@ properties: - qcom,msm8996-dwc3 - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 + - qcom,sc7280-dwc3 - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sm8150-dwc3 diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 2247da77eac1..41416fbd92aa 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -87,13 +87,19 @@ properties: minItems: 1 snps,usb2-lpm-disable: - description: Indicate if we don't want to enable USB2 HW LPM + description: Indicate if we don't want to enable USB2 HW LPM for host + mode. type: boolean snps,usb3_lpm_capable: description: Determines if platform is USB3 LPM capable type: boolean + snps,usb2-gadget-lpm-disable: + description: Indicate if we don't want to enable USB2 HW LPM for gadget + mode. + type: boolean + snps,dis-start-transfer-quirk: description: When set, disable isoc START TRANSFER command failure SW work-around diff --git a/Documentation/devicetree/bindings/usb/usb-device.yaml b/Documentation/devicetree/bindings/usb/usb-device.yaml index d4c99809ee9a..b77960a7a37b 100644 --- a/Documentation/devicetree/bindings/usb/usb-device.yaml +++ b/Documentation/devicetree/bindings/usb/usb-device.yaml @@ -82,9 +82,9 @@ required: additionalProperties: true examples: - #hub connected to port 1 - #device connected to port 2 - #device connected to port 3 + # hub connected to port 1 + # device connected to port 2 + # device connected to port 3 # interface 0 of configuration 1 # interface 0 of configuration 2 - | diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt deleted file mode 100644 index 4dc6a8ee3071..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt +++ /dev/null @@ -1,43 +0,0 @@ -USB NOP PHY - -Required properties: -- compatible: should be usb-nop-xceiv -- #phy-cells: Must be 0 - -Optional properties: -- clocks: phandle to the PHY clock. Use as per Documentation/devicetree - /bindings/clock/clock-bindings.txt - This property is required if clock-frequency is specified. - -- clock-names: Should be "main_clk" - -- clock-frequency: the clock frequency (in Hz) that the PHY clock must - be configured to. - -- vcc-supply: phandle to the regulator that provides power to the PHY. - -- reset-gpios: Should specify the GPIO for reset. - -- vbus-detect-gpio: should specify the GPIO detecting a VBus insertion - (see Documentation/devicetree/bindings/gpio/gpio.txt) -- vbus-regulator : should specifiy the regulator supplying current drawn from - the VBus line (see Documentation/devicetree/bindings/regulator/regulator.txt). - -Example: - - hsusb1_phy { - compatible = "usb-nop-xceiv"; - clock-frequency = <19200000>; - clocks = <&osc 0>; - clock-names = "main_clk"; - vcc-supply = <&hsusb1_vcc_regulator>; - reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; - vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; - vbus-regulator = <&vbus_regulator>; - #phy-cells = <0>; - }; - -hsusb1_phy is a NOP USB PHY device that gets its clock from an oscillator -and expects that clock to be configured to 19.2MHz by the NOP PHY driver. -hsusb1_vcc_regulator provides power to the PHY and GPIO 7 controls RESET. -GPIO 13 detects VBus insertion, and accordingly notifies the vbus-regulator. diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml new file mode 100644 index 000000000000..2824c17285ee --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-nop-xceiv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB NOP PHY + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + compatible: + const: usb-nop-xceiv + + clocks: + maxItems: 1 + + clock-names: + const: main_clk + + clock-frequency: true + + '#phy-cells': + const: 0 + + vcc-supply: + description: phandle to the regulator that provides power to the PHY. + + reset-gpios: + maxItems: 1 + + vbus-detect-gpio: + description: Should specify the GPIO detecting a VBus insertion + maxItems: 1 + + vbus-regulator: + description: Should specifiy the regulator supplying current drawn from + the VBus line. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - '#phy-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + hsusb1_phy { + compatible = "usb-nop-xceiv"; + clock-frequency = <19200000>; + clocks = <&osc 0>; + clock-names = "main_clk"; + vcc-supply = <&hsusb1_vcc_regulator>; + reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; + vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; + vbus-regulator = <&vbus_regulator>; + #phy-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/usb/usb.yaml b/Documentation/devicetree/bindings/usb/usb.yaml index 78491e66ed24..939f217b8c7b 100644 --- a/Documentation/devicetree/bindings/usb/usb.yaml +++ b/Documentation/devicetree/bindings/usb/usb.yaml @@ -16,7 +16,6 @@ properties: pattern: "^usb(@.*)?" phys: - $ref: /schemas/types.yaml#/definitions/phandle-array description: List of all the USB PHYs on this HCD diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index a5631e68f5d1..30e9a0817e21 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -57,6 +57,8 @@ patternProperties: description: Advantech Corporation "^aeroflexgaisler,.*": description: Aeroflex Gaisler AB + "^aesop,.*": + description: AESOP Embedded Forum "^al,.*": description: Annapurna Labs "^alcatel,.*": @@ -103,6 +105,8 @@ patternProperties: description: Anvo-Systems Dresden GmbH "^apm,.*": description: Applied Micro Circuits Corporation (APM) + "^apple,.*": + description: Apple Inc. "^aptina,.*": description: Aptina Imaging "^arasan,.*": @@ -169,6 +173,8 @@ patternProperties: description: Beckhoff Automation GmbH & Co. KG "^bitmain,.*": description: Bitmain Technologies + "^blutek,.*": + description: BluTek Power "^boe,.*": description: BOE Technology Group Co., Ltd. "^bosch,.*": @@ -653,6 +659,8 @@ patternProperties: description: Liebherr-Werk Nenzing GmbH "^lxa,.*": description: Linux Automation GmbH + "^m5stack,.*": + description: M5Stack "^macnica,.*": description: Macnica Americas "^mantix,.*": @@ -766,6 +774,8 @@ patternProperties: description: Broadcom Corporation (formerly NetLogic Microsystems) "^netron-dy,.*": description: Netron DY + "^netronix,.*": + description: Netronix, Inc. "^netxeon,.*": description: Shenzhen Netxeon Technology CO., LTD "^neweast,.*": @@ -934,6 +944,8 @@ patternProperties: description: Unisoc Communications, Inc. "^realtek,.*": description: Realtek Semiconductor Corp. + "^remarkable,.*": + description: reMarkable AS "^renesas,.*": description: Renesas Electronics Corporation "^rex,.*": @@ -1024,8 +1036,12 @@ patternProperties: description: Silergy Corp. "^silex-insight,.*": description: Silex Insight + "^siliconfile,.*": + description: Siliconfile Technologies lnc. "^siliconmitus,.*": description: Silicon Mitus, Inc. + "^siemens,.*": + description: Siemens AG "^simtek,.*": description: Cypress Semiconductor Corporation (Simtek Corporation) "^sinlinx,.*": @@ -1089,6 +1105,8 @@ patternProperties: description: Shenzhen Sunchip Technology Co., Ltd "^SUNW,.*": description: Sun Microsystems, Inc + "^supermicro,.*": + description: Super Micro Computer, Inc. "^silvaco,.*": description: Silvaco, Inc. "^swir,.*": @@ -1105,6 +1123,8 @@ patternProperties: description: Trusted Computing Group "^tcl,.*": description: Toby Churchill Ltd. + "^tcs,.*": + description: Shenzhen City Tang Cheng Technology Co., Ltd. "^tdo,.*": description: Shangai Top Display Optoelectronics Co., Ltd "^technexion,.*": @@ -1272,6 +1292,8 @@ patternProperties: description: Yamaha Corporation "^yes-optoelectronics,.*": description: Yes Optoelectronics Co.,Ltd. + "^yic,.*": + description: YIC System Co., Ltd. "^ylm,.*": description: Shenzhen Yangliming Electronic Technology Co., Ltd. "^yna,.*": diff --git a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt index 6d593003c933..9059f54dc023 100644 --- a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt @@ -5,7 +5,8 @@ The watchdog supports a pre-timeout interrupt that fires 10ms before the expiry. Required properties: -- compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg). +- compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg), or + "nuvoton,wpcm450-wdt" for WPCM450 (Hermon). - reg : Offset and length of the register set for the device. - interrupts : Contain the timer interrupt with flags for falling edge. diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 16f21e182ff6..23d6579aea2c 100644 --- a/Documentation/devicetree/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -Writing DeviceTree Bindings in json-schema +Writing Devicetree Bindings in json-schema ========================================== Devicetree bindings are written using json-schema vocabulary. Schema files are @@ -8,6 +8,8 @@ written in a JSON compatible subset of YAML. YAML is used instead of JSON as it is considered more human readable and has some advantages such as allowing comments (Prefixed with '#'). +Also see :ref:`example-schema`. + Schema Contents --------------- @@ -46,12 +48,12 @@ select schema. By default without 'select', nodes are matched against their possible compatible string values or node name. Most bindings should not need select. - allOf +allOf Optional. A list of other schemas to include. This is used to include other schemas the binding conforms to. This may be schemas for a particular class of devices such as I2C or SPI controllers. - properties +properties A set of sub-schema defining all the DT properties for the binding. The exact schema syntax depends on whether properties are known, common properties (e.g. 'interrupts') or are binding/vendor specific properties. @@ -170,3 +172,12 @@ json-schema Resources `JSON-Schema Specifications <http://json-schema.org/>`_ `Using JSON Schema Book <http://usingjsonschema.com/>`_ + +.. _example-schema: + +Annotated Example Schema +------------------------ + +Also available as a separate file: :download:`example-schema.yaml` + +.. literalinclude:: example-schema.yaml diff --git a/Documentation/devicetree/changesets.rst b/Documentation/devicetree/changesets.rst index c7fd8cd6a270..2091468d4837 100644 --- a/Documentation/devicetree/changesets.rst +++ b/Documentation/devicetree/changesets.rst @@ -1,10 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 -============= -DT Changesets -============= +===================== +Devicetree Changesets +===================== -A DT changeset is a method which allows one to apply changes +A Devicetree changeset is a method which allows one to apply changes in the live tree in such a way that either the full set of changes will be applied, or none of them will be. If an error occurs partway through applying the changeset, then the tree will be rolled back to the diff --git a/Documentation/devicetree/dynamic-resolution-notes.rst b/Documentation/devicetree/dynamic-resolution-notes.rst index 570b7e1f39eb..f81ad8daa36f 100644 --- a/Documentation/devicetree/dynamic-resolution-notes.rst +++ b/Documentation/devicetree/dynamic-resolution-notes.rst @@ -1,11 +1,11 @@ .. SPDX-License-Identifier: GPL-2.0 -================================== -Device Tree Dynamic Resolver Notes -================================== +================================= +Devicetree Dynamic Resolver Notes +================================= This document describes the implementation of the in-kernel -Device Tree resolver, residing in drivers/of/resolver.c +DeviceTree resolver, residing in drivers/of/resolver.c How the resolver works ---------------------- diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 54026763916d..1a2fc8014996 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,17 +1,30 @@ .. SPDX-License-Identifier: GPL-2.0 ============================= -Open Firmware and Device Tree +Open Firmware and Devicetree ============================= +Kernel Devicetree Usage +======================= .. toctree:: :maxdepth: 1 usage-model - writing-schema + of_unittest + kernel-api + +Devicetree Overlays +=================== +.. toctree:: + :maxdepth: 1 + changesets dynamic-resolution-notes - of_unittest overlay-notes +Devicetree Bindings +=================== +.. toctree:: + :maxdepth: 1 + bindings/index diff --git a/Documentation/devicetree/kernel-api.rst b/Documentation/devicetree/kernel-api.rst new file mode 100644 index 000000000000..b7429e6ed6d5 --- /dev/null +++ b/Documentation/devicetree/kernel-api.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _devicetree: + +====================================== +DeviceTree Kernel API +====================================== + +Core functions +-------------- + +.. kernel-doc:: drivers/of/base.c + :export: + +.. kernel-doc:: include/linux/of.h + :internal: + +.. kernel-doc:: drivers/of/property.c + :export: + +.. kernel-doc:: include/linux/of_graph.h + :internal: + +.. kernel-doc:: drivers/of/address.c + :export: + +.. kernel-doc:: drivers/of/irq.c + :export: + +.. kernel-doc:: drivers/of/fdt.c + :export: + +Driver model functions +---------------------- + +.. kernel-doc:: include/linux/of_device.h + :internal: + +.. kernel-doc:: drivers/of/device.c + :export: + +.. kernel-doc:: include/linux/of_platform.h + :internal: + +.. kernel-doc:: drivers/of/platform.c + :export: + +Overlay and Dynamic DT functions +-------------------------------- + +.. kernel-doc:: drivers/of/resolver.c + :export: + +.. kernel-doc:: drivers/of/dynamic.c + :export: + +.. kernel-doc:: drivers/of/overlay.c + :export: diff --git a/Documentation/devicetree/of_unittest.rst b/Documentation/devicetree/of_unittest.rst index dea05214f3ad..2afe41a37148 100644 --- a/Documentation/devicetree/of_unittest.rst +++ b/Documentation/devicetree/of_unittest.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -================================== -Open Firmware Device Tree Unittest -================================== +================================= +Open Firmware Devicetree Unittest +================================= Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst index c67cc676bbd2..b2b8db765b8c 100644 --- a/Documentation/devicetree/overlay-notes.rst +++ b/Documentation/devicetree/overlay-notes.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -========================= -Device Tree Overlay Notes -========================= +======================== +Devicetree Overlay Notes +======================== This document describes the implementation of the in-kernel device tree overlay functionality residing in drivers/of/overlay.c and is a @@ -11,7 +11,7 @@ companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1] How overlays work ----------------- -A Device Tree's overlay purpose is to modify the kernel's live tree, and +A Devicetree's overlay purpose is to modify the kernel's live tree, and have the modification affecting the state of the kernel in a way that is reflecting the changes. Since the kernel mainly deals with devices, any new device node that result diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst index 1eb83496ca1e..b6a287955ee5 100644 --- a/Documentation/devicetree/usage-model.rst +++ b/Documentation/devicetree/usage-model.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -========================= -Linux and the Device Tree -========================= +======================== +Linux and the Devicetree +======================== The Linux usage model for device tree data @@ -14,7 +14,7 @@ at devicetree.org\ [1]_. .. [1] https://www.devicetree.org/specifications/ -The "Open Firmware Device Tree", or simply Device Tree (DT), is a data +The "Open Firmware Device Tree", or simply Devicetree (DT), is a data structure and language for describing hardware. More specifically, it is a description of hardware that is readable by an operating system so that the operating system doesn't need to hard code details of the diff --git a/Documentation/dontdiff b/Documentation/dontdiff index e361fc95ca29..910b30a2a7d9 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -178,6 +178,7 @@ mktables mktree mkutf8data modpost +modules-only.symvers modules.builtin modules.builtin.modinfo modules.nsdeps @@ -252,6 +253,7 @@ vmlinux-* vmlinux.aout vmlinux.bin.all vmlinux.lds +vmlinux.map vmlinux.symvers vmlinuz voffset.h diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 764963876d08..e9f04b1815d1 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -146,6 +146,362 @@ There are also equivalents to memcpy. The ins() and outs() functions copy bytes, words or longs to the given port. +__iomem pointer tokens +====================== + +The data type for an MMIO address is an ``__iomem`` qualified pointer, such as +``void __iomem *reg``. On most architectures it is a regular pointer that +points to a virtual memory address and can be offset or dereferenced, but in +portable code, it must only be passed from and to functions that explicitly +operated on an ``__iomem`` token, in particular the ioremap() and +readl()/writel() functions. The 'sparse' semantic code checker can be used to +verify that this is done correctly. + +While on most architectures, ioremap() creates a page table entry for an +uncached virtual address pointing to the physical MMIO address, some +architectures require special instructions for MMIO, and the ``__iomem`` pointer +just encodes the physical address or an offsettable cookie that is interpreted +by readl()/writel(). + +Differences between I/O access functions +======================================== + +readq(), readl(), readw(), readb(), writeq(), writel(), writew(), writeb() + + These are the most generic accessors, providing serialization against other + MMIO accesses and DMA accesses as well as fixed endianness for accessing + little-endian PCI devices and on-chip peripherals. Portable device drivers + should generally use these for any access to ``__iomem`` pointers. + + Note that posted writes are not strictly ordered against a spinlock, see + Documentation/driver-api/io_ordering.rst. + +readq_relaxed(), readl_relaxed(), readw_relaxed(), readb_relaxed(), +writeq_relaxed(), writel_relaxed(), writew_relaxed(), writeb_relaxed() + + On architectures that require an expensive barrier for serializing against + DMA, these "relaxed" versions of the MMIO accessors only serialize against + each other, but contain a less expensive barrier operation. A device driver + might use these in a particularly performance sensitive fast path, with a + comment that explains why the usage in a specific location is safe without + the extra barriers. + + See memory-barriers.txt for a more detailed discussion on the precise ordering + guarantees of the non-relaxed and relaxed versions. + +ioread64(), ioread32(), ioread16(), ioread8(), +iowrite64(), iowrite32(), iowrite16(), iowrite8() + + These are an alternative to the normal readl()/writel() functions, with almost + identical behavior, but they can also operate on ``__iomem`` tokens returned + for mapping PCI I/O space with pci_iomap() or ioport_map(). On architectures + that require special instructions for I/O port access, this adds a small + overhead for an indirect function call implemented in lib/iomap.c, while on + other architectures, these are simply aliases. + +ioread64be(), ioread32be(), ioread16be() +iowrite64be(), iowrite32be(), iowrite16be() + + These behave in the same way as the ioread32()/iowrite32() family, but with + reversed byte order, for accessing devices with big-endian MMIO registers. + Device drivers that can operate on either big-endian or little-endian + registers may have to implement a custom wrapper function that picks one or + the other depending on which device was found. + + Note: On some architectures, the normal readl()/writel() functions + traditionally assume that devices are the same endianness as the CPU, while + using a hardware byte-reverse on the PCI bus when running a big-endian kernel. + Drivers that use readl()/writel() this way are generally not portable, but + tend to be limited to a particular SoC. + +hi_lo_readq(), lo_hi_readq(), hi_lo_readq_relaxed(), lo_hi_readq_relaxed(), +ioread64_lo_hi(), ioread64_hi_lo(), ioread64be_lo_hi(), ioread64be_hi_lo(), +hi_lo_writeq(), lo_hi_writeq(), hi_lo_writeq_relaxed(), lo_hi_writeq_relaxed(), +iowrite64_lo_hi(), iowrite64_hi_lo(), iowrite64be_lo_hi(), iowrite64be_hi_lo() + + Some device drivers have 64-bit registers that cannot be accessed atomically + on 32-bit architectures but allow two consecutive 32-bit accesses instead. + Since it depends on the particular device which of the two halves has to be + accessed first, a helper is provided for each combination of 64-bit accessors + with either low/high or high/low word ordering. A device driver must include + either <linux/io-64-nonatomic-lo-hi.h> or <linux/io-64-nonatomic-hi-lo.h> to + get the function definitions along with helpers that redirect the normal + readq()/writeq() to them on architectures that do not provide 64-bit access + natively. + +__raw_readq(), __raw_readl(), __raw_readw(), __raw_readb(), +__raw_writeq(), __raw_writel(), __raw_writew(), __raw_writeb() + + These are low-level MMIO accessors without barriers or byteorder changes and + architecture specific behavior. Accesses are usually atomic in the sense that + a four-byte __raw_readl() does not get split into individual byte loads, but + multiple consecutive accesses can be combined on the bus. In portable code, it + is only safe to use these to access memory behind a device bus but not MMIO + registers, as there are no ordering guarantees with regard to other MMIO + accesses or even spinlocks. The byte order is generally the same as for normal + memory, so unlike the other functions, these can be used to copy data between + kernel memory and device memory. + +inl(), inw(), inb(), outl(), outw(), outb() + + PCI I/O port resources traditionally require separate helpers as they are + implemented using special instructions on the x86 architecture. On most other + architectures, these are mapped to readl()/writel() style accessors + internally, usually pointing to a fixed area in virtual memory. Instead of an + ``__iomem`` pointer, the address is a 32-bit integer token to identify a port + number. PCI requires I/O port access to be non-posted, meaning that an outb() + must complete before the following code executes, while a normal writeb() may + still be in progress. On architectures that correctly implement this, I/O port + access is therefore ordered against spinlocks. Many non-x86 PCI host bridge + implementations and CPU architectures however fail to implement non-posted I/O + space on PCI, so they can end up being posted on such hardware. + + In some architectures, the I/O port number space has a 1:1 mapping to + ``__iomem`` pointers, but this is not recommended and device drivers should + not rely on that for portability. Similarly, an I/O port number as described + in a PCI base address register may not correspond to the port number as seen + by a device driver. Portable drivers need to read the port number for the + resource provided by the kernel. + + There are no direct 64-bit I/O port accessors, but pci_iomap() in combination + with ioread64/iowrite64 can be used instead. + +inl_p(), inw_p(), inb_p(), outl_p(), outw_p(), outb_p() + + On ISA devices that require specific timing, the _p versions of the I/O + accessors add a small delay. On architectures that do not have ISA buses, + these are aliases to the normal inb/outb helpers. + +readsq, readsl, readsw, readsb +writesq, writesl, writesw, writesb +ioread64_rep, ioread32_rep, ioread16_rep, ioread8_rep +iowrite64_rep, iowrite32_rep, iowrite16_rep, iowrite8_rep +insl, insw, insb, outsl, outsw, outsb + + These are helpers that access the same address multiple times, usually to copy + data between kernel memory byte stream and a FIFO buffer. Unlike the normal + MMIO accessors, these do not perform a byteswap on big-endian kernels, so the + first byte in the FIFO register corresponds to the first byte in the memory + buffer regardless of the architecture. + +Device memory mapping modes +=========================== + +Some architectures support multiple modes for mapping device memory. +ioremap_*() variants provide a common abstraction around these +architecture-specific modes, with a shared set of semantics. + +ioremap() is the most common mapping type, and is applicable to typical device +memory (e.g. I/O registers). Other modes can offer weaker or stronger +guarantees, if supported by the architecture. From most to least common, they +are as follows: + +ioremap() +--------- + +The default mode, suitable for most memory-mapped devices, e.g. control +registers. Memory mapped using ioremap() has the following characteristics: + +* Uncached - CPU-side caches are bypassed, and all reads and writes are handled + directly by the device +* No speculative operations - the CPU may not issue a read or write to this + memory, unless the instruction that does so has been reached in committed + program flow. +* No reordering - The CPU may not reorder accesses to this memory mapping with + respect to each other. On some architectures, this relies on barriers in + readl_relaxed()/writel_relaxed(). +* No repetition - The CPU may not issue multiple reads or writes for a single + program instruction. +* No write-combining - Each I/O operation results in one discrete read or write + being issued to the device, and multiple writes are not combined into larger + writes. This may or may not be enforced when using __raw I/O accessors or + pointer dereferences. +* Non-executable - The CPU is not allowed to speculate instruction execution + from this memory (it probably goes without saying, but you're also not + allowed to jump into device memory). + +On many platforms and buses (e.g. PCI), writes issued through ioremap() +mappings are posted, which means that the CPU does not wait for the write to +actually reach the target device before retiring the write instruction. + +On many platforms, I/O accesses must be aligned with respect to the access +size; failure to do so will result in an exception or unpredictable results. + +ioremap_wc() +------------ + +Maps I/O memory as normal memory with write combining. Unlike ioremap(), + +* The CPU may speculatively issue reads from the device that the program + didn't actually execute, and may choose to basically read whatever it wants. +* The CPU may reorder operations as long as the result is consistent from the + program's point of view. +* The CPU may write to the same location multiple times, even when the program + issued a single write. +* The CPU may combine several writes into a single larger write. + +This mode is typically used for video framebuffers, where it can increase +performance of writes. It can also be used for other blocks of memory in +devices (e.g. buffers or shared memory), but care must be taken as accesses are +not guaranteed to be ordered with respect to normal ioremap() MMIO register +accesses without explicit barriers. + +On a PCI bus, it is usually safe to use ioremap_wc() on MMIO areas marked as +``IORESOURCE_PREFETCH``, but it may not be used on those without the flag. +For on-chip devices, there is no corresponding flag, but a driver can use +ioremap_wc() on a device that is known to be safe. + +ioremap_wt() +------------ + +Maps I/O memory as normal memory with write-through caching. Like ioremap_wc(), +but also, + +* The CPU may cache writes issued to and reads from the device, and serve reads + from that cache. + +This mode is sometimes used for video framebuffers, where drivers still expect +writes to reach the device in a timely manner (and not be stuck in the CPU +cache), but reads may be served from the cache for efficiency. However, it is +rarely useful these days, as framebuffer drivers usually perform writes only, +for which ioremap_wc() is more efficient (as it doesn't needlessly trash the +cache). Most drivers should not use this. + +ioremap_np() +------------ + +Like ioremap(), but explicitly requests non-posted write semantics. On some +architectures and buses, ioremap() mappings have posted write semantics, which +means that writes can appear to "complete" from the point of view of the +CPU before the written data actually arrives at the target device. Writes are +still ordered with respect to other writes and reads from the same device, but +due to the posted write semantics, this is not the case with respect to other +devices. ioremap_np() explicitly requests non-posted semantics, which means +that the write instruction will not appear to complete until the device has +received (and to some platform-specific extent acknowledged) the written data. + +This mapping mode primarily exists to cater for platforms with bus fabrics that +require this particular mapping mode to work correctly. These platforms set the +``IORESOURCE_MEM_NONPOSTED`` flag for a resource that requires ioremap_np() +semantics and portable drivers should use an abstraction that automatically +selects it where appropriate (see the `Higher-level ioremap abstractions`_ +section below). + +The bare ioremap_np() is only available on some architectures; on others, it +always returns NULL. Drivers should not normally use it, unless they are +platform-specific or they derive benefit from non-posted writes where +supported, and can fall back to ioremap() otherwise. The normal approach to +ensure posted write completion is to do a dummy read after a write as +explained in `Accessing the device`_, which works with ioremap() on all +platforms. + +ioremap_np() should never be used for PCI drivers. PCI memory space writes are +always posted, even on architectures that otherwise implement ioremap_np(). +Using ioremap_np() for PCI BARs will at best result in posted write semantics, +and at worst result in complete breakage. + +Note that non-posted write semantics are orthogonal to CPU-side ordering +guarantees. A CPU may still choose to issue other reads or writes before a +non-posted write instruction retires. See the previous section on MMIO access +functions for details on the CPU side of things. + +ioremap_uc() +------------ + +ioremap_uc() behaves like ioremap() except that on the x86 architecture without +'PAT' mode, it marks memory as uncached even when the MTRR has designated +it as cacheable, see Documentation/x86/pat.rst. + +Portable drivers should avoid the use of ioremap_uc(). + +ioremap_cache() +--------------- + +ioremap_cache() effectively maps I/O memory as normal RAM. CPU write-back +caches can be used, and the CPU is free to treat the device as if it were a +block of RAM. This should never be used for device memory which has side +effects of any kind, or which does not return the data previously written on +read. + +It should also not be used for actual RAM, as the returned pointer is an +``__iomem`` token. memremap() can be used for mapping normal RAM that is outside +of the linear kernel memory area to a regular pointer. + +Portable drivers should avoid the use of ioremap_cache(). + +Architecture example +-------------------- + +Here is how the above modes map to memory attribute settings on the ARM64 +architecture: + ++------------------------+--------------------------------------------+ +| API | Memory region type and cacheability | ++------------------------+--------------------------------------------+ +| ioremap_np() | Device-nGnRnE | ++------------------------+--------------------------------------------+ +| ioremap() | Device-nGnRE | ++------------------------+--------------------------------------------+ +| ioremap_uc() | (not implemented) | ++------------------------+--------------------------------------------+ +| ioremap_wc() | Normal-Non Cacheable | ++------------------------+--------------------------------------------+ +| ioremap_wt() | (not implemented; fallback to ioremap) | ++------------------------+--------------------------------------------+ +| ioremap_cache() | Normal-Write-Back Cacheable | ++------------------------+--------------------------------------------+ + +Higher-level ioremap abstractions +================================= + +Instead of using the above raw ioremap() modes, drivers are encouraged to use +higher-level APIs. These APIs may implement platform-specific logic to +automatically choose an appropriate ioremap mode on any given bus, allowing for +a platform-agnostic driver to work on those platforms without any special +cases. At the time of this writing, the following ioremap() wrappers have such +logic: + +devm_ioremap_resource() + + Can automatically select ioremap_np() over ioremap() according to platform + requirements, if the ``IORESOURCE_MEM_NONPOSTED`` flag is set on the struct + resource. Uses devres to automatically unmap the resource when the driver + probe() function fails or a device in unbound from its driver. + + Documented in Documentation/driver-api/driver-model/devres.rst. + +of_address_to_resource() + + Automatically sets the ``IORESOURCE_MEM_NONPOSTED`` flag for platforms that + require non-posted writes for certain buses (see the nonposted-mmio and + posted-mmio device tree properties). + +of_iomap() + + Maps the resource described in a ``reg`` property in the device tree, doing + all required translations. Automatically selects ioremap_np() according to + platform requirements, as above. + +pci_ioremap_bar(), pci_ioremap_wc_bar() + + Maps the resource described in a PCI base address without having to extract + the physical address first. + +pci_iomap(), pci_iomap_wc() + + Like pci_ioremap_bar()/pci_ioremap_bar(), but also works on I/O space when + used together with ioread32()/iowrite32() and similar accessors + +pcim_iomap() + + Like pci_iomap(), but uses devres to automatically unmap the resource when + the driver probe() function fails or a device in unbound from its driver + + Documented in Documentation/driver-api/driver-model/devres.rst. + +Not using these wrappers may make drivers unusable on certain platforms with +stricter rules for mapping I/O memory. + Public Functions Provided ========================= diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index a2133d69872c..7f37ec30d9fd 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -257,3 +257,79 @@ fences in the kernel. This means: userspace is allowed to use userspace fencing or long running compute workloads. This also means no implicit fencing for shared buffers in these cases. + +Recoverable Hardware Page Faults Implications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Modern hardware supports recoverable page faults, which has a lot of +implications for DMA fences. + +First, a pending page fault obviously holds up the work that's running on the +accelerator and a memory allocation is usually required to resolve the fault. +But memory allocations are not allowed to gate completion of DMA fences, which +means any workload using recoverable page faults cannot use DMA fences for +synchronization. Synchronization fences controlled by userspace must be used +instead. + +On GPUs this poses a problem, because current desktop compositor protocols on +Linux rely on DMA fences, which means without an entirely new userspace stack +built on top of userspace fences, they cannot benefit from recoverable page +faults. Specifically this means implicit synchronization will not be possible. +The exception is when page faults are only used as migration hints and never to +on-demand fill a memory request. For now this means recoverable page +faults on GPUs are limited to pure compute workloads. + +Furthermore GPUs usually have shared resources between the 3D rendering and +compute side, like compute units or command submission engines. If both a 3D +job with a DMA fence and a compute workload using recoverable page faults are +pending they could deadlock: + +- The 3D workload might need to wait for the compute job to finish and release + hardware resources first. + +- The compute workload might be stuck in a page fault, because the memory + allocation is waiting for the DMA fence of the 3D workload to complete. + +There are a few options to prevent this problem, one of which drivers need to +ensure: + +- Compute workloads can always be preempted, even when a page fault is pending + and not yet repaired. Not all hardware supports this. + +- DMA fence workloads and workloads which need page fault handling have + independent hardware resources to guarantee forward progress. This could be + achieved through e.g. through dedicated engines and minimal compute unit + reservations for DMA fence workloads. + +- The reservation approach could be further refined by only reserving the + hardware resources for DMA fence workloads when they are in-flight. This must + cover the time from when the DMA fence is visible to other threads up to + moment when fence is completed through dma_fence_signal(). + +- As a last resort, if the hardware provides no useful reservation mechanics, + all workloads must be flushed from the GPU when switching between jobs + requiring DMA fences or jobs requiring page fault handling: This means all DMA + fences must complete before a compute job with page fault handling can be + inserted into the scheduler queue. And vice versa, before a DMA fence can be + made visible anywhere in the system, all compute workloads must be preempted + to guarantee all pending GPU page faults are flushed. + +- Only a fairly theoretical option would be to untangle these dependencies when + allocating memory to repair hardware page faults, either through separate + memory blocks or runtime tracking of the full dependency graph of all DMA + fences. This results very wide impact on the kernel, since resolving the page + on the CPU side can itself involve a page fault. It is much more feasible and + robust to limit the impact of handling hardware page faults to the specific + driver. + +Note that workloads that run on independent hardware like copy engines or other +GPUs do not have any impact. This allows us to keep using DMA fences internally +in the kernel even for resolving hardware page faults, e.g. by using copy +engines to clear or copy memory needed to resolve the page fault. + +In some ways this page fault problem is a special case of the `Infinite DMA +Fences` discussions: Infinite fences from compute workloads are allowed to +depend on DMA fences, but not the other way around. And not even the page fault +problem is new, because some other CPU thread in userspace might +hit a page fault which holds up a userspace fence - supporting page faults on +GPUs doesn't anything fundamentally new. diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-api/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - -<Insert List of Device Classes Here> - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like:: - - - typedef int (*devclass_add)(struct device *); - typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like:: - - struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, - }; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using:: - - int devclass_register(struct device_class * cls); - void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories:: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory):: - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy:: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); - }; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this:: - - static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring:: - - static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using:: - - int devclass_create_file(struct device_class *, struct devclass_attribute *); - void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index b9b022371e85..0833be568b06 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -63,8 +63,14 @@ Attributes are declared using a macro called DEVICE_ATTR:: Example::: - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); + static DEVICE_ATTR(type, 0444, type_show, NULL); + static DEVICE_ATTR(power, 0644, power_show, power_store); + +Helper macros are available for common values of mode, so the above examples +can be simplified to::: + + static DEVICE_ATTR_RO(type); + static DEVICE_ATTR_RW(power); This declares two structures of type struct device_attribute with respective names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be @@ -76,19 +82,24 @@ organized as follows into a group:: NULL, }; - static struct attribute_group dev_attr_group = { + static struct attribute_group dev_group = { .attrs = dev_attrs, }; - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, + static const struct attribute_group *dev_groups[] = { + &dev_group, NULL, }; +A helper macro is available for the common case of a single group, so the +above two structures can be declared using::: + + ATTRIBUTE_GROUPS(dev); + This array of groups can then be associated with a device by setting the group pointer in struct device before device_register() is invoked:: - dev->groups = dev_attr_groups; + dev->groups = dev_groups; device_register(dev); The device_register() function will use the 'groups' pointer to create the diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index cd8b6e657b94..e0814d214048 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -285,7 +285,8 @@ I2C IIO devm_iio_device_alloc() devm_iio_device_register() - devm_iio_kfifo_allocate() + devm_iio_dmaengine_buffer_setup() + devm_iio_kfifo_buffer_setup() devm_iio_triggered_buffer_setup() devm_iio_trigger_alloc() devm_iio_trigger_register() @@ -309,6 +310,7 @@ IOMAP devm_ioremap() devm_ioremap_uc() devm_ioremap_wc() + devm_ioremap_np() devm_ioremap_resource() : checks resource, requests memory region, ioremaps devm_ioremap_resource_wc() devm_platform_ioremap_resource() : calls devm_ioremap_resource() for platform device diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst index 755016422269..4831bdd92e5c 100644 --- a/Documentation/driver-api/driver-model/index.rst +++ b/Documentation/driver-api/driver-model/index.rst @@ -7,7 +7,6 @@ Driver Model binding bus - class design-patterns device devres diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 22271c342d92..3366a991b4aa 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -12,7 +12,7 @@ Guidelines for GPIOs consumers Drivers that can't work without standard GPIO calls should have Kconfig entries that depend on GPIOLIB or select GPIOLIB. The functions that allow a driver to -obtain and use GPIOs are available by including the following file: +obtain and use GPIOs are available by including the following file:: #include <linux/gpio/consumer.h> diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index 41ec3cc72d32..af632d764ac6 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -96,6 +96,12 @@ hardware descriptions such as device tree or ACPI: way to pass the charging parameters from hardware descriptions such as the device tree. +- gpio-mux: drivers/mux/gpio.c is used for controlling a multiplexer using + n GPIO lines such that you can mux in 2^n different devices by activating + different GPIO lines. Often the GPIOs are on a SoC and the devices are + some SoC-external entities, such as different components on a PCB that + can be selectively enabled. + Apart from this there are special GPIO drivers in subsystems like MMC/SD to read card detect and write protect GPIO lines, and in the TTY serial subsystem to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index 94dd7185e76e..2e924fb5b3d5 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -27,7 +27,7 @@ What is a GPIO? =============== A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar +digital signal. They are provided from many kinds of chips, and are familiar to Linux developers working with embedded and custom hardware. Each GPIO represents a bit connected to a particular pin, or "ball" on Ball Grid Array (BGA) packages. Board schematics show which external hardware connects to diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst index 9bc34ba697d9..9b12eeb89170 100644 --- a/Documentation/driver-api/gpio/legacy.rst +++ b/Documentation/driver-api/gpio/legacy.rst @@ -461,7 +461,7 @@ pin controller? This is done by registering "ranges" of pins, which are essentially cross-reference tables. These are described in -Documentation/driver-api/pinctl.rst +Documentation/driver-api/pin-control.rst While the pin allocation is totally managed by the pinctrl subsystem, gpio (under gpiolib) is still maintained by gpio drivers. It may happen diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index 3ddebddc02ca..e83026aebe97 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -28,24 +28,26 @@ IIO buffer setup The meta information associated with a channel reading placed in a buffer is called a scan element. The important bits configuring scan elements are exposed to userspace applications via the -:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains +:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains attributes of the following form: * :file:`enable`, used for enabling a channel. If and only if its attribute is non *zero*, then a triggered capture will contain data samples for this channel. +* :file:`index`, the scan_index of the channel. * :file:`type`, description of the scan element data storage within the buffer and hence the form in which it is read from user space. - Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] . + * *be* or *le*, specifies big or little endian. * *s* or *u*, specifies if signed (2's complement) or unsigned. * *bits*, is the number of valid data bits. * *storagebits*, is the number of bits (after padding) that it occupies in the - buffer. - * *shift*, if specified, is the shift that needs to be applied prior to - masking out unused bits. + buffer. * *repeat*, specifies the number of bits/storagebits repetitions. When the - repeat element is 0 or 1, then the repeat value is omitted. + repeat element is 0 or 1, then the repeat value is omitted. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. For example, a driver for a 3-axis accelerometer with 12 bit resolution where data is stored in two 8-bits registers as follows:: @@ -122,4 +124,3 @@ More details .. kernel-doc:: include/linux/iio/buffer.h .. kernel-doc:: drivers/iio/industrialio-buffer.c :export: - diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b0ab367896ab..f5a3207aa7fa 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -62,7 +62,7 @@ available subsections can be seen below. 80211/index uio-howto firmware/index - pinctl + pin-control gpio/index md/index media/index diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 3fc378b3b269..7160336aa475 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -144,8 +144,7 @@ of the device. This is because the power state of the device is only changed after the power state transition has taken place. The ``s_ctrl`` callback can be used to obtain device's power state after the power state transition: -.. c:function:: - int pm_runtime_get_if_in_use(struct device *dev); +.. c:function:: int pm_runtime_get_if_in_use(struct device *dev); The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index c140692454b1..2ad71dfa8828 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -28,6 +28,8 @@ Please see: :maxdepth: 5 :numbered: + maintainer-entry-profile + v4l2-core dtv-core rc-core diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst new file mode 100644 index 000000000000..eb1cdfd280ba --- /dev/null +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -0,0 +1,206 @@ +Media Subsystem Profile +======================= + +Overview +-------- + +The media subsystem covers support for a variety of devices: stream +capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC +and media pipeline control. + +It covers, mainly, the contents of those directories: + + - drivers/media + - drivers/staging/media + - Documentation/admin-guide/media + - Documentation/driver-api/media + - Documentation/userspace-api/media + - Documentation/devicetree/bindings/media/\ [1]_ + - include/media + +.. [1] Device tree bindings are maintained by the + OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers + (see the MAINTAINERS file). So, changes there must be reviewed + by them before being merged via the media subsystem's development + tree. + +Both media userspace and Kernel APIs are documented and the documentation +must be kept in sync with the API changes. It means that all patches that +add new features to the subsystem must also bring changes to the +corresponding API files. + +Due to the size and wide scope of the media subsystem, media's +maintainership model is to have sub-maintainers that have a broad +knowledge of a specific aspect of the subsystem. It is the sub-maintainers' +task to review the patches, providing feedback to users if the patches are +following the subsystem rules and are properly using the media kernel and +userspace APIs. + +Patches for the media subsystem must be sent to the media mailing list +at linux-media@vger.kernel.org as plain text only e-mail. Emails with +HTML will be automatically rejected by the mail server. It could be wise +to also copy the sub-maintainer(s). + +Media's workflow is heavily based on Patchwork, meaning that, once a patch +is submitted, the e-mail will first be accepted by the mailing list +server, and, after a while, it should appear at: + + - https://patchwork.linuxtv.org/project/linux-media/list/ + +If it doesn't automatically appear there after a few minutes, then +probably something went wrong on your submission. Please check if the +email is in plain text\ [2]_ only and if your emailer is not mangling +whitespaces before complaining or submitting them again. + +You can check if the mailing list server accepted your patch, by looking at: + + - https://lore.kernel.org/linux-media/ + +.. [2] If your email contains HTML, the mailing list server will simply + drop it, without any further notice. + + +Media maintainers ++++++++++++++++++ + +At the media subsystem, we have a group of senior developers that +are responsible for doing the code reviews at the drivers (also known as +sub-maintainers), and another senior developer responsible for the +subsystem as a whole. For core changes, whenever possible, multiple +media maintainers do the review. + +The media maintainers that work on specific areas of the subsystem are: + +- Digital TV and remote controllers: + Sean Young <sean@mess.org> + +- HDMI CEC: + Hans Verkuil <hverkuil@xs4all.nl> + +- Media controller drivers: + Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: + Sakari Ailus <sakari.ailus@linux.intel.com> + +- V4L2 drivers and core V4L2 frameworks: + Hans Verkuil <hverkuil@xs4all.nl> + +The subsystem maintainer is: + Mauro Carvalho Chehab <mchehab@kernel.org> + +Media maintainers may delegate a patch to other media maintainers as needed. +On such case, checkpatch's ``delegate`` field indicates who's currently +responsible for reviewing a patch. + +Submit Checklist Addendum +------------------------- + +Patches that change the Open Firmware/Device Tree bindings must be +reviewed by the Device Tree maintainers. So, DT maintainers should be +Cc:ed when those are submitted via devicetree@vger.kernel.org mailing +list. + +There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/ +that should be used in order to check if the drivers are properly +implementing the media APIs: + +==================== ======================================================= +Type Tool +==================== ======================================================= +V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 virtual drivers ``contrib/test/test-media`` +CEC drivers ``cec-compliance`` +==================== ======================================================= + +.. [3] The ``v4l2-compliance`` also covers the media controller usage inside + V4L2 drivers. + +Other compilance tools are under development to check other parts of the +subsystem. + +Those tests need to pass before the patches go upstream. + +Also, please notice that we build the Kernel with:: + + make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script + +Where the check script is:: + + #!/bin/bash + /devel/smatch/smatch -p=kernel $@ >&2 + /devel/sparse/sparse $@ >&2 + +Be sure to not introduce new warnings on your patches without a +very good reason. + +Style Cleanup Patches ++++++++++++++++++++++ + +Style cleanups are welcome when they come together with other changes +at the files where the style changes will affect. + +We may accept pure standalone style cleanups, but they should ideally +be one patch for the whole subsystem (if the cleanup is low volume), +or at least be grouped per directory. So, for example, if you're doing a +big cleanup change set at drivers under drivers/media, please send a single +patch for all drivers under drivers/media/pci, another one for +drivers/media/usb and so on. + +Coding Style Addendum ++++++++++++++++++++++ + +Media development uses ``checkpatch.pl`` on strict mode to verify the code +style, e.g.:: + + $ ./scripts/checkpatch.pl --strict --max-line-length=80 + +In principle, patches should follow the coding style rules, but exceptions +are allowed if there are good reasons. On such case, maintainers and reviewers +may question about the rationale for not addressing the ``checkpatch.pl``. + +Please notice that the goal here is to improve code readability. On +a few cases, ``checkpatch.pl`` may actually point to something that would +look worse. So, you should use good sense. + +Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead +to having longer lines than 80 characters per line. While this is not +strictly prohibited, efforts should be made towards staying within 80 +characters per line. This could include using re-factoring code that leads +to less indentation, shorter variable or function names and last but not +least, simply wrapping the lines. + +In particular, we accept lines with more than 80 columns: + + - on strings, as they shouldn't be broken due to line length limits; + - when a function or variable name need to have a big identifier name, + which keeps hard to honor the 80 columns limit; + - on arithmetic expressions, when breaking lines makes them harder to + read; + - when they avoid a line to end with an open parenthesis or an open + bracket. + +Key Cycle Dates +--------------- + +New submissions can be sent at any time, but if they intend to hit the +next merge window they should be sent before -rc5, and ideally stabilized +in the linux-media branch by -rc6. + +Review Cadence +-------------- + +Provided that your patch is at https://patchwork.linuxtv.org, it should +be sooner or later handled, so you don't need to re-submit a patch. + +Except for bug fixes, we don't usually add new patches to the development +tree between -rc6 and the next -rc1. + +Please notice that the media subsystem is a high traffic one, so it +could take a while for us to be able to review your patches. Feel free +to ping if you don't get a feedback in a couple of weeks or to ask +other developers to publicly add Reviewed-by and, more importantly, +``Tested-by:`` tags. + +Please note that we expect a detailed description for ``Tested-by:``, +identifying what boards were used at the test and what it was tested. diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 8b53da2f9c74..7736da077fb8 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -208,7 +208,7 @@ the needs of the driver. :c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for registering their async sub-devices with the notifier. -:c:func:`v4l2_async_register_subdev_sensor_common` is a helper function for +:c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor drivers registering their own async sub-device, but it also registers a notifier and further registers async sub-devices for lens and flash devices found in firmware. The notifier for the sub-device is unregistered with the @@ -252,7 +252,7 @@ contain several subdevs that use an I2C bus, but also a subdev that is controlled through GPIO pins. This distinction is only relevant when setting up the device, but once the subdev is registered it is completely transparent. -Once te subdev has been registered you can call an ops function either +Once the subdev has been registered you can call an ops function either directly: .. code-block:: c diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index ef6d59e0978e..1d8302b89bd4 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -4,7 +4,7 @@ LIBNVDIMM: Non-Volatile Devices libnvdimm - kernel / libndctl - userspace helper library -linux-nvdimm@lists.01.org +nvdimm@lists.linux.dev Version 13 diff --git a/Documentation/driver-api/pinctl.rst b/Documentation/driver-api/pin-control.rst index 3d2deaf48841..e2474425fb0c 100644 --- a/Documentation/driver-api/pinctl.rst +++ b/Documentation/driver-api/pin-control.rst @@ -1235,7 +1235,7 @@ default state like this:: foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); if (IS_ERR(foo->s)) { /* FIXME: clean up "foo" here */ - return PTR_ERR(s); + return PTR_ERR(foo->s); } ret = pinctrl_select_state(foo->s); @@ -1428,3 +1428,40 @@ on the pins defined by group B:: The above has to be done from process context. The reservation of the pins will be done when the state is activated, so in effect one specific pin can be used by different functions at different times on a running system. + + +Debugfs files +============= +These files are created in ``/sys/kernel/debug/pinctrl``: + +- ``pinctrl-devices``: prints each pin controller device along with columns to + indicate support for pinmux and pinconf + +- ``pinctrl-handles``: prints each configured pin controller handle and the + corresponding pinmux maps + +- ``pinctrl-maps``: print all pinctrl maps + +A sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin +controller device containing these files: + +- ``pins``: prints a line for each pin registered on the pin controller. The + pinctrl driver may add additional information such as register contents. + +- ``gpio-ranges``: print ranges that map gpio lines to pins on the controller + +- ``pingroups``: print all pin groups registered on the pin controller + +- ``pinconf-pins``: print pin config settings for each pin + +- ``pinconf-groups``: print pin config settings per pin group + +- ``pinmux-functions``: print each pin function along with the pin groups that + map to the pin function + +- ``pinmux-pins``: iterate through all pins and print mux owner, gpio owner + and if the pin is a hog + +- ``pinmux-select``: write to this file to activate a pin function for a group:: + + echo "<group-name function-name>" > pinmux-select diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index ab62f1bb0366..a7ca4f58305a 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -55,7 +55,11 @@ several parameter at once. For example, if you see pwm_config() and pwm_{enable,disable}() calls in the same function, this probably means you should switch to pwm_apply_state(). -The PWM user API also allows one to query the PWM state with pwm_get_state(). +The PWM user API also allows one to query the PWM state that was passed to the +last invocation of pwm_apply_state() using pwm_get_state(). Note this is +different to what the driver has actually implemented if the request cannot be +satisfied exactly with the hardware in use. There is currently no way for +consumers to get the actually implemented settings. In addition to the PWM state, the PWM API also exposes PWM arguments, which are the reference PWM config one should use on this PWM. diff --git a/Documentation/driver-api/serial/cyclades_z.rst b/Documentation/driver-api/serial/cyclades_z.rst deleted file mode 100644 index 532ff67e2f1c..000000000000 --- a/Documentation/driver-api/serial/cyclades_z.rst +++ /dev/null @@ -1,11 +0,0 @@ -================ -Cyclades-Z notes -================ - -The Cyclades-Z must have firmware loaded onto the card before it will -operate. This operation should be performed during system startup, - -The firmware, loader program and the latest device driver code are -available from Cyclades at - - ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/ diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst index 33ad10d05b26..8f7d7af3b90b 100644 --- a/Documentation/driver-api/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -17,10 +17,8 @@ Serial drivers .. toctree:: :maxdepth: 1 - cyclades_z moxa-smartio n_gsm - rocket serial-iso7816 serial-rs485 diff --git a/Documentation/driver-api/serial/rocket.rst b/Documentation/driver-api/serial/rocket.rst deleted file mode 100644 index 23761eae4282..000000000000 --- a/Documentation/driver-api/serial/rocket.rst +++ /dev/null @@ -1,185 +0,0 @@ -================================================ -Comtrol(tm) RocketPort(R)/RocketModem(TM) Series -================================================ - -Device Driver for the Linux Operating System -============================================ - -Product overview ----------------- - -This driver provides a loadable kernel driver for the Comtrol RocketPort -and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32 -high-speed serial ports or modems. This driver supports up to a combination -of four RocketPort or RocketModems boards in one machine simultaneously. -This file assumes that you are using the RocketPort driver which is -integrated into the kernel sources. - -The driver can also be installed as an external module using the usual -"make;make install" routine. This external module driver, obtainable -from the Comtrol website listed below, is useful for updating the driver -or installing it into kernels which do not have the driver configured -into them. Installations instructions for the external module -are in the included README and HW_INSTALL files. - -RocketPort ISA and RocketModem II PCI boards currently are only supported by -this driver in module form. - -The RocketPort ISA board requires I/O ports to be configured by the DIP -switches on the board. See the section "ISA Rocketport Boards" below for -information on how to set the DIP switches. - -You pass the I/O port to the driver using the following module parameters: - -board1: - I/O port for the first ISA board -board2: - I/O port for the second ISA board -board3: - I/O port for the third ISA board -board4: - I/O port for the fourth ISA board - -There is a set of utilities and scripts provided with the external driver -(downloadable from http://www.comtrol.com) that ease the configuration and -setup of the ISA cards. - -The RocketModem II PCI boards require firmware to be loaded into the card -before it will function. The driver has only been tested as a module for this -board. - -Installation Procedures ------------------------ - -RocketPort/RocketModem PCI cards require no driver configuration, they are -automatically detected and configured. - -The RocketPort driver can be installed as a module (recommended) or built -into the kernel. This is selected, as for other drivers, through the `make config` -command from the root of the Linux source tree during the kernel build process. - -The RocketPort/RocketModem serial ports installed by this driver are assigned -device major number 46, and will be named /dev/ttyRx, where x is the port number -starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards -installed in the system, the mapping of port names to serial ports is displayed -in the system log at /var/log/messages. - -If installed as a module, the module must be loaded. This can be done -manually by entering "modprobe rocket". To have the module loaded automatically -upon system boot, edit a `/etc/modprobe.d/*.conf` file and add the line -"alias char-major-46 rocket". - -In order to use the ports, their device names (nodes) must be created with mknod. -This is only required once, the system will retain the names once created. To -create the RocketPort/RocketModem device names, use the command -"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. - -For example:: - - > mknod /dev/ttyR0 c 46 0 - > mknod /dev/ttyR1 c 46 1 - > mknod /dev/ttyR2 c 46 2 - -The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) -for you:: - - >/dev/MAKEDEV ttyR - -ISA Rocketport Boards ---------------------- - -You must assign and configure the I/O addresses used by the ISA Rocketport -card before installing and using it. This is done by setting a set of DIP -switches on the Rocketport board. - - -Setting the I/O address ------------------------ - -Before installing RocketPort(R) or RocketPort RA boards, you must find -a range of I/O addresses for it to use. The first RocketPort card -requires a 68-byte contiguous block of I/O addresses, starting at one -of the following: 0x100h, 0x140h, 0x180h, 0x200h, 0x240h, 0x280h, -0x300h, 0x340h, 0x380h. This I/O address must be reflected in the DIP -switches of *all* of the Rocketport cards. - -The second, third, and fourth RocketPort cards require a 64-byte -contiguous block of I/O addresses, starting at one of the following -I/O addresses: 0x100h, 0x140h, 0x180h, 0x1C0h, 0x200h, 0x240h, 0x280h, -0x2C0h, 0x300h, 0x340h, 0x380h, 0x3C0h. The I/O address used by the -second, third, and fourth Rocketport cards (if present) are set via -software control. The DIP switch settings for the I/O address must be -set to the value of the first Rocketport cards. - -In order to distinguish each of the card from the others, each card -must have a unique board ID set on the dip switches. The first -Rocketport board must be set with the DIP switches corresponding to -the first board, the second board must be set with the DIP switches -corresponding to the second board, etc. IMPORTANT: The board ID is -the only place where the DIP switch settings should differ between the -various Rocketport boards in a system. - -The I/O address range used by any of the RocketPort cards must not -conflict with any other cards in the system, including other -RocketPort cards. Below, you will find a list of commonly used I/O -address ranges which may be in use by other devices in your system. -On a Linux system, "cat /proc/ioports" will also be helpful in -identifying what I/O addresses are being used by devices on your -system. - -Remember, the FIRST RocketPort uses 68 I/O addresses. So, if you set it -for 0x100, it will occupy 0x100 to 0x143. This would mean that you -CAN NOT set the second, third or fourth board for address 0x140 since -the first 4 bytes of that range are used by the first board. You would -need to set the second, third, or fourth board to one of the next available -blocks such as 0x180. - -RocketPort and RocketPort RA SW1 Settings:: - - +-------------------------------+ - | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | - +-------+-------+---------------+ - | Unused| Card | I/O Port Block| - +-------------------------------+ - - DIP Switches DIP Switches - 7 8 6 5 - =================== =================== - On On UNUSED, MUST BE ON. On On First Card <==== Default - On Off Second Card - Off On Third Card - Off Off Fourth Card - - DIP Switches I/O Address Range - 4 3 2 1 Used by the First Card - ===================================== - On Off On Off 100-143 - On Off Off On 140-183 - On Off Off Off 180-1C3 <==== Default - Off On On Off 200-243 - Off On Off On 240-283 - Off On Off Off 280-2C3 - Off Off On Off 300-343 - Off Off Off On 340-383 - Off Off Off Off 380-3C3 - -Reporting Bugs --------------- - -For technical support, please provide the following -information: Driver version, kernel release, distribution of -kernel, and type of board you are using. Error messages and log -printouts port configuration details are especially helpful. - -USA: - :Phone: (612) 494-4100 - :FAX: (612) 494-4199 - :email: support@comtrol.com - -Comtrol Europe: - :Phone: +44 (0) 1 869 323-220 - :FAX: +44 (0) 1 869 323-211 - :email: support@comtrol.co.uk - -Web: http://www.comtrol.com -FTP: ftp.comtrol.com diff --git a/Documentation/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst index 26d13085a117..e519d374c378 100644 --- a/Documentation/driver-api/surface_aggregator/client.rst +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -248,7 +248,7 @@ This example defines a function .. code-block:: c - int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); + static int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); executing the specified request, with the controller passed in when calling said function. In this example, the argument is provided via the ``arg`` @@ -296,7 +296,7 @@ This invocation of the macro defines a function .. code-block:: c - int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); + static int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); executing the specified request, using the device IDs and controller given in the client device. The full list of such macros for client devices is: diff --git a/Documentation/driver-api/surface_aggregator/clients/dtx.rst b/Documentation/driver-api/surface_aggregator/clients/dtx.rst new file mode 100644 index 000000000000..e7e7c20007f0 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/dtx.rst @@ -0,0 +1,718 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |__u16| replace:: :c:type:`__u16 <__u16>` +.. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>` +.. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>` +.. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>` +.. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>` + +====================================================== +User-Space DTX (Clipboard Detachment System) Interface +====================================================== + +The ``surface_dtx`` driver is responsible for proper clipboard detachment +and re-attachment handling. To this end, it provides the ``/dev/surface/dtx`` +device file, through which it can interface with a user-space daemon. This +daemon is then ultimately responsible for determining and taking necessary +actions, such as unmounting devices attached to the base, +unloading/reloading the graphics-driver, user-notifications, etc. + +There are two basic communication principles used in this driver: Commands +(in other parts of the documentation also referred to as requests) and +events. Commands are sent to the EC and may have a different implications in +different contexts. Events are sent by the EC upon some internal state +change. Commands are always driver-initiated, whereas events are always +initiated by the EC. + +.. contents:: + +Nomenclature +============ + +* **Clipboard:** + The detachable upper part of the Surface Book, housing the screen and CPU. + +* **Base:** + The lower part of the Surface Book from which the clipboard can be + detached, optionally (model dependent) housing the discrete GPU (dGPU). + +* **Latch:** + The mechanism keeping the clipboard attached to the base in normal + operation and allowing it to be detached when requested. + +* **Silently ignored commands:** + The command is accepted by the EC as a valid command and acknowledged + (following the standard communication protocol), but the EC does not act + upon it, i.e. ignores it.e upper part of the + + +Detachment Process +================== + +Warning: This part of the documentation is based on reverse engineering and +testing and thus may contain errors or be incomplete. + +Latch States +------------ + +The latch mechanism has two major states: *open* and *closed*. In the +*closed* state (default), the clipboard is secured to the base, whereas in +the *open* state, the clipboard can be removed by a user. + +The latch can additionally be locked and, correspondingly, unlocked, which +can influence the detachment procedure. Specifically, this locking mechanism +is intended to prevent the dGPU, positioned in the base of the device, from +being hot-unplugged while in use. More details can be found in the +documentation for the detachment procedure below. By default, the latch is +unlocked. + +Detachment Procedure +-------------------- + +Note that the detachment process is governed fully by the EC. The +``surface_dtx`` driver only relays events from the EC to user-space and +commands from user-space to the EC, i.e. it does not influence this process. + +The detachment process is started with the user pressing the *detach* button +on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL. +Following that: + +1. The EC turns on the indicator led on the detach-button, sends a + *detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further + instructions/commands. In case the latch is unlocked, the led will flash + green. If the latch has been locked, the led will be solid red + +2. The event is, via the ``surface_dtx`` driver, relayed to user-space, where + an appropriate user-space daemon can handle it and send instructions back + to the EC via IOCTLs provided by this driver. + +3. The EC waits for instructions from user-space and acts according to them. + If the EC does not receive any instructions in a given period, it will + time out and continue as follows: + + - If the latch is unlocked, the EC will open the latch and the clipboard + can be detached from the base. This is the exact behavior as without + this driver or any user-space daemon. See the ``SDTX_IOCTL_LATCH_CONFIRM`` + description below for more details on the follow-up behavior of the EC. + + - If the latch is locked, the EC will *not* open the latch, meaning the + clipboard cannot be detached from the base. Furthermore, the EC sends + an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel + reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details). + +Valid responses by a user-space daemon to a detachment request event are: + +- Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the + detachment process. Furthermore, the EC will send a detach-request event, + similar to the user pressing the detach-button to cancel said process (see + below). + +- Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the + latch, after which the user can separate clipboard and base. + + As this changes the latch state, a *latch-status* event + (``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened + successfully. If the EC fails to open the latch, e.g. due to hardware + error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be + sent with the cancel reason indicating the specific failure. + + If the latch is currently locked, the latch will automatically be + unlocked before it is opened. + +- Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout. + No other actions will be performed, i.e. the detachment process will neither + be completed nor canceled, and the EC will still be waiting for further + responses. + +- Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process, + similar to ``SDTX_IOCTL_LATCH_REQUEST``, described above, or the button + press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``) + is send in response to this. In contrast to those, however, this command + does not trigger a new detachment process if none is currently in + progress. + +- Do nothing. The detachment process eventually times out as described in + point 3. + +See :ref:`ioctls` for more details on these responses. + +It is important to note that, if the user presses the detach button at any +point when a detachment operation is in progress (i.e. after the EC has sent +the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it +received the corresponding response concluding the process), the detachment +process is canceled on the EC-level and an identical event is being sent. +Thus a *detach-request* event, by itself, does not signal the start of the +detachment process. + +The detachment process may further be canceled by the EC due to hardware +failures or a low clipboard battery. This is done via a cancel event +(``SDTX_EVENT_CANCEL``) with the corresponding cancel reason. + + +User-Space Interface Documentation +================================== + +Error Codes and Status Values +----------------------------- + +Error and status codes are divided into different categories, which can be +used to determine if the status code is an error, and, if it is, the +severity and type of that error. The current categories are: + +.. flat-table:: Overview of Status/Error Categories. + :widths: 2 1 3 + :header-rows: 1 + + * - Name + - Value + - Short Description + + * - ``STATUS`` + - ``0x0000`` + - Non-error status codes. + + * - ``RUNTIME_ERROR`` + - ``0x1000`` + - Non-critical runtime errors. + + * - ``HARDWARE_ERROR`` + - ``0x2000`` + - Critical hardware failures. + + * - ``UNKNOWN`` + - ``0xF000`` + - Unknown error codes. + +Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro +can be used to determine the category of any status value. The +``SDTX_SUCCESS()`` macro can be used to check if the status value is a +success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure. + +Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN`` +category by the driver and may be implemented via their own code in the +future. + +Currently used error codes are: + +.. flat-table:: Overview of Error Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_DETACH_NOT_FEASIBLE`` + - ``RUNTIME`` + - ``0x1001`` + - Detachment not feasible due to low clipboard battery. + + * - ``SDTX_DETACH_TIMEDOUT`` + - ``RUNTIME`` + - ``0x1002`` + - Detachment process timed out while the latch was locked. + + * - ``SDTX_ERR_FAILED_TO_OPEN`` + - ``HARDWARE`` + - ``0x2001`` + - Failed to open latch. + + * - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN`` + - ``HARDWARE`` + - ``0x2002`` + - Failed to keep latch open. + + * - ``SDTX_ERR_FAILED_TO_CLOSE`` + - ``HARDWARE`` + - ``0x2003`` + - Failed to close latch. + +Other error codes are reserved for future use. Non-error status codes may +overlap and are generally only unique within their use-case: + +.. flat-table:: Latch Status Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_LATCH_CLOSED`` + - ``STATUS`` + - ``0x0000`` + - Latch is closed/has been closed. + + * - ``SDTX_LATCH_OPENED`` + - ``STATUS`` + - ``0x0001`` + - Latch is open/has been opened. + +.. flat-table:: Base State Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_BASE_DETACHED`` + - ``STATUS`` + - ``0x0000`` + - Base has been detached/is not present. + + * - ``SDTX_BASE_ATTACHED`` + - ``STATUS`` + - ``0x0001`` + - Base has been attached/is present. + +Again, other codes are reserved for future use. + +.. _events: + +Events +------ + +Events can be received by reading from the device file. They are disabled by +default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE`` +first. All events follow the layout prescribed by |sdtx_event|. Specific +event types can be identified by their event code, described in +|sdtx_event_code|. Note that other event codes are reserved for future use, +thus an event parser must be able to handle any unknown/unsupported event +types gracefully, by relying on the payload length given in the event header. + +Currently provided event types are: + +.. flat-table:: Overview of DTX events. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Code + - Payload + - Short Description + + * - ``SDTX_EVENT_REQUEST`` + - ``1`` + - ``0`` bytes + - Detachment process initiated/aborted. + + * - ``SDTX_EVENT_CANCEL`` + - ``2`` + - ``2`` bytes + - EC canceled detachment process. + + * - ``SDTX_EVENT_BASE_CONNECTION`` + - ``3`` + - ``4`` bytes + - Base connection state changed. + + * - ``SDTX_EVENT_LATCH_STATUS`` + - ``4`` + - ``2`` bytes + - Latch status changed. + + * - ``SDTX_EVENT_DEVICE_MODE`` + - ``5`` + - ``2`` bytes + - Device mode changed. + +Individual events in more detail: + +``SDTX_EVENT_REQUEST`` +^^^^^^^^^^^^^^^^^^^^^^ + +Sent when a detachment process is started or, if in progress, aborted by the +user, either via a detach button press or a detach request +(``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space. + +Does not have any payload. + +``SDTX_EVENT_CANCEL`` +^^^^^^^^^^^^^^^^^^^^^ + +Sent when a detachment process is canceled by the EC due to unfulfilled +preconditions (e.g. clipboard battery too low to detach) or hardware +failure. The reason for cancellation is given in the event payload detailed +below and can be one of + +* ``SDTX_DETACH_TIMEDOUT``: Detachment timed out while the latch was locked. + The latch has neither been opened nor unlocked. + +* ``SDTX_DETACH_NOT_FEASIBLE``: Detachment not feasible due to low clipboard + battery. + +* ``SDTX_ERR_FAILED_TO_OPEN``: Could not open the latch (hardware failure). + +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``: Could not keep the latch open (hardware + failure). + +* ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure). + +Other error codes in this context are reserved for future use. + +These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern +between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or +runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may +happen during normal operation if certain preconditions for detachment are +not given. + +.. flat-table:: Detachment Cancel Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``reason`` + - |__u16| + - Reason for cancellation. + +``SDTX_EVENT_BASE_CONNECTION`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the base connection state has changed, i.e. when the base has been +attached, detached, or detachment has become infeasible due to low clipboard +battery. The new state and, if a base is connected, ID of the base is +provided as payload of type |sdtx_base_info| with its layout presented +below: + +.. flat-table:: Base-Connection-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``state`` + - |__u16| + - Base connection state. + + * - ``base_id`` + - |__u16| + - Type of base connected (zero if none). + +Possible values for ``state`` are: + +* ``SDTX_BASE_DETACHED``, +* ``SDTX_BASE_ATTACHED``, and +* ``SDTX_DETACH_NOT_FEASIBLE``. + +Other values are reserved for future use. + +``SDTX_EVENT_LATCH_STATUS`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the latch status has changed, i.e. when the latch has been opened, +closed, or an error occurred. The current status is provided as payload: + +.. flat-table:: Latch-Status-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``status`` + - |__u16| + - Latch status. + +Possible values for ``status`` are: + +* ``SDTX_LATCH_CLOSED``, +* ``SDTX_LATCH_OPENED``, +* ``SDTX_ERR_FAILED_TO_OPEN``, +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and +* ``SDTX_ERR_FAILED_TO_CLOSE``. + +Other values are reserved for future use. + +``SDTX_EVENT_DEVICE_MODE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the device mode has changed. The new device mode is provided as +payload: + +.. flat-table:: Device-Mode-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``mode`` + - |__u16| + - Device operation mode. + +Possible values for ``mode`` are: + +* ``SDTX_DEVICE_MODE_TABLET``, +* ``SDTX_DEVICE_MODE_LAPTOP``, and +* ``SDTX_DEVICE_MODE_STUDIO``. + +Other values are reserved for future use. + +.. _ioctls: + +IOCTLs +------ + +The following IOCTLs are provided: + +.. flat-table:: Overview of DTX IOCTLs + :widths: 1 1 1 1 4 + :header-rows: 1 + + * - Type + - Number + - Direction + - Name + - Description + + * - ``0xA5`` + - ``0x21`` + - ``-`` + - ``EVENTS_ENABLE`` + - Enable events for the current file descriptor. + + * - ``0xA5`` + - ``0x22`` + - ``-`` + - ``EVENTS_DISABLE`` + - Disable events for the current file descriptor. + + * - ``0xA5`` + - ``0x23`` + - ``-`` + - ``LATCH_LOCK`` + - Lock the latch. + + * - ``0xA5`` + - ``0x24`` + - ``-`` + - ``LATCH_UNLOCK`` + - Unlock the latch. + + * - ``0xA5`` + - ``0x25`` + - ``-`` + - ``LATCH_REQUEST`` + - Request clipboard detachment. + + * - ``0xA5`` + - ``0x26`` + - ``-`` + - ``LATCH_CONFIRM`` + - Confirm clipboard detachment request. + + * - ``0xA5`` + - ``0x27`` + - ``-`` + - ``LATCH_HEARTBEAT`` + - Send heartbeat signal to EC. + + * - ``0xA5`` + - ``0x28`` + - ``-`` + - ``LATCH_CANCEL`` + - Cancel detachment process. + + * - ``0xA5`` + - ``0x29`` + - ``R`` + - ``GET_BASE_INFO`` + - Get current base/connection information. + + * - ``0xA5`` + - ``0x2A`` + - ``R`` + - ``GET_DEVICE_MODE`` + - Get current device operation mode. + + * - ``0xA5`` + - ``0x2B`` + - ``R`` + - ``GET_LATCH_STATUS`` + - Get current device latch status. + +``SDTX_IOCTL_EVENTS_ENABLE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x22)``. + +Enable events for the current file descriptor. Events can be obtained by +reading from the device, if enabled. Events are disabled by default. + +``SDTX_IOCTL_EVENTS_DISABLE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x22)``. + +Disable events for the current file descriptor. Events can be obtained by +reading from the device, if enabled. Events are disabled by default. + +``SDTX_IOCTL_LATCH_LOCK`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x23)``. + +Locks the latch, causing the detachment procedure to abort without opening +the latch on timeout. The latch is unlocked by default. This command will be +silently ignored if the latch is already locked. + +``SDTX_IOCTL_LATCH_UNLOCK`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x24)``. + +Unlocks the latch, causing the detachment procedure to open the latch on +timeout. The latch is unlocked by default. This command will not open the +latch when sent during an ongoing detachment process. It will be silently +ignored if the latch is already unlocked. + +``SDTX_IOCTL_LATCH_REQUEST`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x25)``. + +Generic latch request. Behavior depends on the context: If no +detachment-process is active, detachment is requested. Otherwise the +currently active detachment-process will be aborted. + +If a detachment process is canceled by this operation, a generic detachment +request event (``SDTX_EVENT_REQUEST``) will be sent. + +This essentially behaves the same as a detachment button press. + +``SDTX_IOCTL_LATCH_CONFIRM`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x26)``. + +Acknowledges and confirms a latch request. If sent during an ongoing +detachment process, this command causes the latch to be opened immediately. +The latch will also be opened if it has been locked. In this case, the latch +lock is reset to the unlocked state. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_LATCH_HEARTBEAT`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x27)``. + +Sends a heartbeat, essentially resetting the detachment timeout. This +command can be used to keep the detachment process alive while work required +for the detachment to succeed is still in progress. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_LATCH_CANCEL`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x28)``. + +Cancels detachment in progress (if any). If a detachment process is canceled +by this operation, a generic detachment request event +(``SDTX_EVENT_REQUEST``) will be sent. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_GET_BASE_INFO`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``. + +Get the current base connection state (i.e. attached/detached) and the type +of the base connected to the clipboard. This is command essentially provides +a way to query the information provided by the base connection change event +(``SDTX_EVENT_BASE_CONNECTION``). + +Possible values for ``struct sdtx_base_info.state`` are: + +* ``SDTX_BASE_DETACHED``, +* ``SDTX_BASE_ATTACHED``, and +* ``SDTX_DETACH_NOT_FEASIBLE``. + +Other values are reserved for future use. + +``SDTX_IOCTL_GET_DEVICE_MODE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x2A, __u16)``. + +Returns the device operation mode, indicating if and how the base is +attached to the clipboard. This is command essentially provides a way to +query the information provided by the device mode change event +(``SDTX_EVENT_DEVICE_MODE``). + +Returned values are: + +* ``SDTX_DEVICE_MODE_LAPTOP`` +* ``SDTX_DEVICE_MODE_TABLET`` +* ``SDTX_DEVICE_MODE_STUDIO`` + +See |sdtx_device_mode| for details. Other values are reserved for future +use. + + +``SDTX_IOCTL_GET_LATCH_STATUS`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x2B, __u16)``. + +Get the current latch status or (presumably) the last error encountered when +trying to open/close the latch. This is command essentially provides a way +to query the information provided by the latch status change event +(``SDTX_EVENT_LATCH_STATUS``). + +Returned values are: + +* ``SDTX_LATCH_CLOSED``, +* ``SDTX_LATCH_OPENED``, +* ``SDTX_ERR_FAILED_TO_OPEN``, +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and +* ``SDTX_ERR_FAILED_TO_CLOSE``. + +Other values are reserved for future use. + +A Note on Base IDs +------------------ + +Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or +``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower +byte of the combined |__u16| value, with the driver storing the EC type from +which this ID comes in the high byte (without this, base IDs over different +types of ECs may be overlapping). + +The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device +type. This can be one of + +* ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and + +* ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial + Hub. + +Note that currently only the ``SSH`` type EC is supported, however ``HID`` +type is reserved for future use. + +Structures and Enums +-------------------- + +.. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h + +API Users +========= + +A user-space daemon utilizing this API can be found at +https://github.com/linux-surface/surface-dtx-daemon. diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst index 3ccabce23271..98ea9946b8a2 100644 --- a/Documentation/driver-api/surface_aggregator/clients/index.rst +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst @@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to :maxdepth: 1 cdev + dtx san .. only:: subproject and html diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst index 29fdd817ddb0..4b638c14bc16 100644 --- a/Documentation/driver-api/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -730,17 +730,7 @@ This function returns the thermal_instance corresponding to a given {thermal_zone, cooling_device, trip_point} combination. Returns NULL if such an instance does not exist. -4.3. thermal_notify_framework ------------------------------ - -This function handles the trip events from sensor drivers. It starts -throttling the cooling devices according to the policy configured. -For CRITICAL and HOT trip points, this notifies the respective drivers, -and does actual throttling for other trip points i.e ACTIVE and PASSIVE. -The throttling policy is based on the configured platform data; if no -platform data is provided, this uses the step_wise throttling policy. - -4.4. thermal_cdev_update +4.3. thermal_cdev_update ------------------------ This function serves as an arbitrator to set the state of a cooling diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..2c94ff2f4385 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -109,13 +109,19 @@ well as to make sure they aren't relying on some HCD-specific behavior. USB-Standard Types ================== -In ``<linux/usb/ch9.h>`` you will find the USB data types defined in -chapter 9 of the USB specification. These data types are used throughout +In ``include/uapi/linux/usb/ch9.h`` you will find the USB data types defined +in chapter 9 of the USB specification. These data types are used throughout USB, and in APIs including this host side API, gadget APIs, usb character -devices and debugfs interfaces. +devices and debugfs interfaces. That file is itself included by +``include/linux/usb/ch9.h``, which also contains declarations of a few +utility routines for manipulating these data types; the implementations +are in ``drivers/usb/common/common.c``. -.. kernel-doc:: include/linux/usb/ch9.h - :internal: +.. kernel-doc:: drivers/usb/common/common.c + :export: + +In addition, some functions useful for creating debugging output are +defined in ``drivers/usb/common/debug.c``. .. _usb_header: diff --git a/Documentation/driver-api/vfio-mediated-device.rst b/Documentation/driver-api/vfio-mediated-device.rst index 25eb7d5b834b..1779b85f014e 100644 --- a/Documentation/driver-api/vfio-mediated-device.rst +++ b/Documentation/driver-api/vfio-mediated-device.rst @@ -98,15 +98,13 @@ structure to represent a mediated device's driver:: /* * struct mdev_driver [2] - Mediated device's driver - * @name: driver name * @probe: called when new device created * @remove: called when device removed * @driver: device driver structure */ struct mdev_driver { - const char *name; - int (*probe) (struct device *dev); - void (*remove) (struct device *dev); + int (*probe) (struct mdev_device *dev); + void (*remove) (struct mdev_device *dev); struct device_driver driver; }; @@ -115,8 +113,7 @@ to register and unregister itself with the core driver: * Register:: - extern int mdev_register_driver(struct mdev_driver *drv, - struct module *owner); + extern int mdev_register_driver(struct mdev_driver *drv); * Unregister:: diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst index f1a4d3c3ba0b..606eed8823ce 100644 --- a/Documentation/driver-api/vfio.rst +++ b/Documentation/driver-api/vfio.rst @@ -2,7 +2,7 @@ VFIO - "Virtual Function I/O" [1]_ ================================== -Many modern system now provide DMA and interrupt remapping facilities +Many modern systems now provide DMA and interrupt remapping facilities to help ensure I/O devices behave within the boundaries they've been allotted. This includes x86 hardware with AMD-Vi and Intel VT-d, POWER systems with Partitionable Endpoints (PEs) and embedded PowerPC @@ -249,35 +249,41 @@ VFIO bus driver API VFIO bus drivers, such as vfio-pci make use of only a few interfaces into VFIO core. When devices are bound and unbound to the driver, -the driver should call vfio_add_group_dev() and vfio_del_group_dev() -respectively:: - - extern int vfio_add_group_dev(struct device *dev, - const struct vfio_device_ops *ops, - void *device_data); - - extern void *vfio_del_group_dev(struct device *dev); - -vfio_add_group_dev() indicates to the core to begin tracking the -iommu_group of the specified dev and register the dev as owned by -a VFIO bus driver. The driver provides an ops structure for callbacks +the driver should call vfio_register_group_dev() and +vfio_unregister_group_dev() respectively:: + + void vfio_init_group_dev(struct vfio_device *device, + struct device *dev, + const struct vfio_device_ops *ops); + int vfio_register_group_dev(struct vfio_device *device); + void vfio_unregister_group_dev(struct vfio_device *device); + +The driver should embed the vfio_device in its own structure and call +vfio_init_group_dev() to pre-configure it before going to registration. +vfio_register_group_dev() indicates to the core to begin tracking the +iommu_group of the specified dev and register the dev as owned by a VFIO bus +driver. Once vfio_register_group_dev() returns it is possible for userspace to +start accessing the driver, thus the driver should ensure it is completely +ready before calling it. The driver provides an ops structure for callbacks similar to a file operations structure:: struct vfio_device_ops { - int (*open)(void *device_data); - void (*release)(void *device_data); - ssize_t (*read)(void *device_data, char __user *buf, + int (*open)(struct vfio_device *vdev); + void (*release)(struct vfio_device *vdev); + ssize_t (*read)(struct vfio_device *vdev, char __user *buf, size_t count, loff_t *ppos); - ssize_t (*write)(void *device_data, const char __user *buf, + ssize_t (*write)(struct vfio_device *vdev, + const char __user *buf, size_t size, loff_t *ppos); - long (*ioctl)(void *device_data, unsigned int cmd, + long (*ioctl)(struct vfio_device *vdev, unsigned int cmd, unsigned long arg); - int (*mmap)(void *device_data, struct vm_area_struct *vma); + int (*mmap)(struct vfio_device *vdev, + struct vm_area_struct *vma); }; -Each function is passed the device_data that was originally registered -in the vfio_add_group_dev() call above. This allows the bus driver -an easy place to store its opaque, private data. The open/release +Each function is passed the vdev that was originally registered +in the vfio_register_group_dev() call above. This allows the bus driver +to obtain its private data using container_of(). The open/release callbacks are issued when a new file descriptor is created for a device (via VFIO_GROUP_GET_DEVICE_FD). The ioctl interface provides a direct pass through for VFIO_DEVICE_* ioctls. The read/write/mmap diff --git a/Documentation/driver-api/xilinx/eemi.rst b/Documentation/driver-api/xilinx/eemi.rst index 9dcbc6f18d75..c1bc47b9000d 100644 --- a/Documentation/driver-api/xilinx/eemi.rst +++ b/Documentation/driver-api/xilinx/eemi.rst @@ -16,35 +16,8 @@ components running across different processing clusters on a chip or device to communicate with a power management controller (PMC) on a device to issue or respond to power management requests. -EEMI ops is a structure containing all eemi APIs supported by Zynq MPSoC. -The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops -structure. Any driver who want to communicate with PMC using EEMI APIs -can call zynqmp_pm_get_eemi_ops(). - -Example of EEMI ops:: - - /* zynqmp-firmware driver maintain all EEMI APIs */ - struct zynqmp_eemi_ops { - int (*get_api_version)(u32 *version); - int (*query_data)(struct zynqmp_pm_query_data qdata, u32 *out); - }; - - static const struct zynqmp_eemi_ops eemi_ops = { - .get_api_version = zynqmp_pm_get_api_version, - .query_data = zynqmp_pm_query_data, - }; - -Example of EEMI ops usage:: - - static const struct zynqmp_eemi_ops *eemi_ops; - u32 ret_payload[PAYLOAD_ARG_CNT]; - int ret; - - eemi_ops = zynqmp_pm_get_eemi_ops(); - if (IS_ERR(eemi_ops)) - return PTR_ERR(eemi_ops); - - ret = eemi_ops->query_data(qdata, ret_payload); +Any driver who wants to communicate with PMC using EEMI APIs use the +functions provided for each function. IOCTL ------ diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 57f66de2f7e1..212f7003cfba 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -207,9 +207,9 @@ Documentation/driver-api/console.rst. To summarize: Echo a value to the bind file that represents the framebuffer console driver. So assuming vtcon1 represents fbcon, then:: - echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to + echo 1 > /sys/class/vtconsole/vtcon1/bind - attach framebuffer console to console layer - echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from + echo 0 > /sys/class/vtconsole/vtcon1/bind - detach framebuffer console from console layer If fbcon is detached from the console layer, your boot console driver (which is diff --git a/Documentation/features/arch-support.txt b/Documentation/features/arch-support.txt index d22a1095e661..118ae031840b 100644 --- a/Documentation/features/arch-support.txt +++ b/Documentation/features/arch-support.txt @@ -8,4 +8,5 @@ The meaning of entries in the tables is: | ok | # feature supported by the architecture |TODO| # feature not yet supported by the architecture | .. | # feature cannot be supported by the hardware + | N/A| # feature doesn't apply to the architecture diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt index 7aff505af706..fa83403b4aec 100644 --- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt +++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt @@ -21,7 +21,7 @@ | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | - | powerpc: | TODO | + | powerpc: | ok | | riscv: | ok | | s390: | ok | | sh: | TODO | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 48a5ca548399..e1c3a4c4d107 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | N/A | | csky: | TODO | | h8300: | .. | | hexagon: | TODO | diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index a94f17d9b836..7e5c04c98619 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -101,6 +101,9 @@ Other Functions .. kernel-doc:: fs/xattr.c :export: +.. kernel-doc:: fs/namespace.c + :export: + The proc filesystem =================== @@ -122,6 +125,12 @@ Events based on file descriptors .. kernel-doc:: fs/eventfd.c :export: +eventpoll (epoll) interfaces +============================ + +.. kernel-doc:: fs/eventpoll.c + :internal: + The Filesystem for Exporting Kernel Objects =========================================== diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index bf145171c2bf..832839fcf4c3 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -50,8 +50,8 @@ Here is the main features of EROFS: - Support POSIX.1e ACLs by using xattrs; - - Support transparent file compression as an option: - LZ4 algorithm with 4 KB fixed-sized output compression for high performance. + - Support transparent data compression as an option: + LZ4 algorithm with the fixed-sized output compression for high performance. The following git tree provides the file system user-space tools under development (ex, formatting tool mkfs.erofs): @@ -113,31 +113,31 @@ may not. All metadatas can be now observed in two different spaces (views): :: - |-> aligned with 8B - |-> followed closely - + meta_blkaddr blocks |-> another slot - _____________________________________________________________________ - | ... | inode | xattrs | extents | data inline | ... | inode ... - |________|_______|(optional)|(optional)|__(optional)_|_____|__________ - |-> aligned with the inode slot size - . . - . . - . . - . . - . . - . . - .____________________________________________________|-> aligned with 4B - | xattr_ibody_header | shared xattrs | inline xattrs | - |____________________|_______________|_______________| - |-> 12 bytes <-|->x * 4 bytes<-| . - . . . - . . . - . . . - ._______________________________.______________________. - | id | id | id | id | ... | id | ent | ... | ent| ... | - |____|____|____|____|______|____|_____|_____|____|_____| - |-> aligned with 4B - |-> aligned with 4B + |-> aligned with 8B + |-> followed closely + + meta_blkaddr blocks |-> another slot + _____________________________________________________________________ + | ... | inode | xattrs | extents | data inline | ... | inode ... + |________|_______|(optional)|(optional)|__(optional)_|_____|__________ + |-> aligned with the inode slot size + . . + . . + . . + . . + . . + . . + .____________________________________________________|-> aligned with 4B + | xattr_ibody_header | shared xattrs | inline xattrs | + |____________________|_______________|_______________| + |-> 12 bytes <-|->x * 4 bytes<-| . + . . . + . . . + . . . + ._______________________________.______________________. + | id | id | id | id | ... | id | ent | ... | ent| ... | + |____|____|____|____|______|____|_____|_____|____|_____| + |-> aligned with 4B + |-> aligned with 4B Inode could be 32 or 64 bytes, which can be distinguished from a common field which all inode versions have -- i_format:: @@ -175,13 +175,13 @@ may not. All metadatas can be now observed in two different spaces (views): Each share xattr can also be directly found by the following formula: xattr offset = xattr_blkaddr * block_size + 4 * xattr_id - :: +:: - |-> aligned by 4 bytes - + xattr_blkaddr blocks |-> aligned with 4 bytes - _________________________________________________________________________ - | ... | xattr_entry | xattr data | ... | xattr_entry | xattr data ... - |________|_____________|_____________|_____|______________|_______________ + |-> aligned by 4 bytes + + xattr_blkaddr blocks |-> aligned with 4 bytes + _________________________________________________________________________ + | ... | xattr_entry | xattr data | ... | xattr_entry | xattr data ... + |________|_____________|_____________|_____|______________|_______________ Directories ----------- @@ -193,48 +193,77 @@ algorithm (could refer to the related source code). :: - ___________________________ - / | - / ______________|________________ - / / | nameoff1 | nameoffN-1 - ____________.______________._______________v________________v__________ - | dirent | dirent | ... | dirent | filename | filename | ... | filename | - |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____| - \ ^ - \ | * could have - \ | trailing '\0' - \________________________| nameoff0 - - Directory block + ___________________________ + / | + / ______________|________________ + / / | nameoff1 | nameoffN-1 + ____________.______________._______________v________________v__________ + | dirent | dirent | ... | dirent | filename | filename | ... | filename | + |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____| + \ ^ + \ | * could have + \ | trailing '\0' + \________________________| nameoff0 + Directory block Note that apart from the offset of the first filename, nameoff0 also indicates the total number of directory entries in this block since it is no need to introduce another on-disk field at all. -Compression ------------ -Currently, EROFS supports 4KB fixed-sized output transparent file compression, -as illustrated below:: - - |---- Variant-Length Extent ----|-------- VLE --------|----- VLE ----- - clusterofs clusterofs clusterofs - | | | logical data - _________v_______________________________v_____________________v_______________ - ... | . | | . | | . | ... - ____|____.________|_____________|________.____|_____________|__.__________|____ - |-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-| - size size size size size - . . . . - . . . . - . . . . - _______._____________._____________._____________._____________________ - ... | | | | ... physical data - _______|_____________|_____________|_____________|_____________________ - |-> cluster <-|-> cluster <-|-> cluster <-| - size size size - -Currently each on-disk physical cluster can contain 4KB (un)compressed data -at most. For each logical cluster, there is a corresponding on-disk index to -describe its cluster type, physical cluster address, etc. - -See "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details. +Data compression +---------------- +EROFS implements LZ4 fixed-sized output compression which generates fixed-sized +compressed data blocks from variable-sized input in contrast to other existing +fixed-sized input solutions. Relatively higher compression ratios can be gotten +by using fixed-sized output compression since nowadays popular data compression +algorithms are mostly LZ77-based and such fixed-sized output approach can be +benefited from the historical dictionary (aka. sliding window). + +In details, original (uncompressed) data is turned into several variable-sized +extents and in the meanwhile, compressed into physical clusters (pclusters). +In order to record each variable-sized extent, logical clusters (lclusters) are +introduced as the basic unit of compress indexes to indicate whether a new +extent is generated within the range (HEAD) or not (NONHEAD). Lclusters are now +fixed in block size, as illustrated below:: + + |<- variable-sized extent ->|<- VLE ->| + clusterofs clusterofs clusterofs + | | | + _________v_________________________________v_______________________v________ + ... | . | | . | | . ... + ____|____._________|______________|________.___ _|______________|__.________ + |-> lcluster <-|-> lcluster <-|-> lcluster <-|-> lcluster <-| + (HEAD) (NONHEAD) (HEAD) (NONHEAD) . + . CBLKCNT . . + . . . + . . . + _______._____________________________.______________._________________ + ... | | | | ... + _______|______________|______________|______________|_________________ + |-> big pcluster <-|-> pcluster <-| + +A physical cluster can be seen as a container of physical compressed blocks +which contains compressed data. Previously, only lcluster-sized (4KB) pclusters +were supported. After big pcluster feature is introduced (available since +Linux v5.13), pcluster can be a multiple of lcluster size. + +For each HEAD lcluster, clusterofs is recorded to indicate where a new extent +starts and blkaddr is used to seek the compressed data. For each NONHEAD +lcluster, delta0 and delta1 are available instead of blkaddr to indicate the +distance to its HEAD lcluster and the next HEAD lcluster. A PLAIN lcluster is +also a HEAD lcluster except that its data is uncompressed. See the comments +around "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details. + +If big pcluster is enabled, pcluster size in lclusters needs to be recorded as +well. Let the delta0 of the first NONHEAD lcluster store the compressed block +count with a special flag as a new called CBLKCNT NONHEAD lcluster. It's easy +to understand its delta0 is constantly 1, as illustrated below:: + + __________________________________________________________ + | HEAD | NONHEAD | NONHEAD | ... | NONHEAD | HEAD | HEAD | + |__:___|_(CBLKCNT)_|_________|_____|_________|__:___|____:_| + |<----- a big pcluster (with CBLKCNT) ------>|<-- -->| + a lcluster-sized pcluster (without CBLKCNT) ^ + +If another HEAD follows a HEAD lcluster, there is no room to record CBLKCNT, +but it's easy to know the size of such pcluster is 1 lcluster as well. diff --git a/Documentation/filesystems/ext4/directory.rst b/Documentation/filesystems/ext4/directory.rst index 073940cc64ed..55f618b37144 100644 --- a/Documentation/filesystems/ext4/directory.rst +++ b/Documentation/filesystems/ext4/directory.rst @@ -121,6 +121,31 @@ The directory file type is one of the following values: * - 0x7 - Symbolic link. +To support directories that are both encrypted and casefolded directories, we +must also include hash information in the directory entry. We append +``ext4_extended_dir_entry_2`` to ``ext4_dir_entry_2`` except for the entries +for dot and dotdot, which are kept the same. The structure follows immediately +after ``name`` and is included in the size listed by ``rec_len`` If a directory +entry uses this extension, it may be up to 271 bytes. + +.. list-table:: + :widths: 8 8 24 40 + :header-rows: 1 + + * - Offset + - Size + - Name + - Description + * - 0x0 + - \_\_le32 + - hash + - The hash of the directory name + * - 0x4 + - \_\_le32 + - minor\_hash + - The minor hash of the directory name + + In order to add checksums to these classic directory blocks, a phony ``struct ext4_dir_entry`` is placed at the end of each leaf block to hold the checksum. The directory entry is 12 bytes long. The inode @@ -322,6 +347,8 @@ The directory hash is one of the following values: - Half MD4, unsigned. * - 0x5 - Tea, unsigned. + * - 0x6 + - Siphash. Interior nodes of an htree are recorded as ``struct dx_node``, which is also the full length of a data block: diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 35ed01a5fbc9..992bf91eeec8 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -110,6 +110,12 @@ background_gc=%s Turn on/off cleaning operations, namely garbage on synchronous garbage collection running in background. Default value for this option is on. So garbage collection is on by default. +gc_merge When background_gc is on, this option can be enabled to + let background GC thread to handle foreground GC requests, + it can eliminate the sluggish issue caused by slow foreground + GC operation when GC is triggered from a process with limited + I/O and CPU resources. +nogc_merge Disable GC merge feature. disable_roll_forward Disable the roll-forward recovery routine norecovery Disable the roll-forward recovery routine, mounted read- only (i.e., -o ro,disable_roll_forward) @@ -813,6 +819,14 @@ Compression implementation * chattr +c file * chattr +c dir; touch dir/file * mount w/ -o compress_extension=ext; touch file.ext + * mount w/ -o compress_extension=*; touch any_file + +- At this point, compression feature doesn't expose compressed space to user + directly in order to guarantee potential data updates later to the space. + Instead, the main goal is to reduce data writes to flash disk as much as + possible, resulting in extending disk life time as well as relaxing IO + congestion. Alternatively, we've added ioctl interface to reclaim compressed + space and show it to user after putting the immutable bit. Compress metadata layout:: diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 1f76b1cb3348..d4853cb919d2 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -53,6 +53,7 @@ filesystem implementations. journalling fscrypt fsverity + netfs_library Filesystems =========== diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index b7dcc86c92a4..1e894480115b 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -80,13 +80,16 @@ prototypes:: struct file *, unsigned open_flag, umode_t create_mode); int (*tmpfile) (struct inode *, struct dentry *, umode_t); + int (*fileattr_set)(struct user_namespace *mnt_userns, + struct dentry *dentry, struct fileattr *fa); + int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); locking rules: all may block -============ ============================================= +============= ============================================= ops i_rwsem(inode) -============ ============================================= +============= ============================================= lookup: shared create: exclusive link: exclusive (both) @@ -107,7 +110,9 @@ fiemap: no update_time: no atomic_open: shared (exclusive if O_CREAT is set in open flags) tmpfile: no -============ ============================================= +fileattr_get: no or exclusive +fileattr_set: exclusive +============= ============================================= Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem @@ -469,7 +474,6 @@ prototypes:: int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); void (*unlock_native_capacity) (struct gendisk *); - int (*revalidate_disk) (struct gendisk *); int (*getgeo)(struct block_device *, struct hd_geometry *); void (*swap_slot_free_notify) (struct block_device *, unsigned long); @@ -484,7 +488,6 @@ ioctl: no compat_ioctl: no direct_access: no unlock_native_capacity: no -revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) ======================= =================== diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst new file mode 100644 index 000000000000..57a641847818 --- /dev/null +++ b/Documentation/filesystems/netfs_library.rst @@ -0,0 +1,526 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +NETWORK FILESYSTEM HELPER LIBRARY +================================= + +.. Contents: + + - Overview. + - Buffered read helpers. + - Read helper functions. + - Read helper structures. + - Read helper operations. + - Read helper procedure. + - Read helper cache API. + + +Overview +======== + +The network filesystem helper library is a set of functions designed to aid a +network filesystem in implementing VM/VFS operations. For the moment, that +just includes turning various VM buffered read operations into requests to read +from the server. The helper library, however, can also interpose other +services, such as local caching or local data encryption. + +Note that the library module doesn't link against local caching directly, so +access must be provided by the netfs. + + +Buffered Read Helpers +===================== + +The library provides a set of read helpers that handle the ->readpage(), +->readahead() and much of the ->write_begin() VM operations and translate them +into a common call framework. + +The following services are provided: + + * Handles transparent huge pages (THPs). + + * Insulates the netfs from VM interface changes. + + * Allows the netfs to arbitrarily split reads up into pieces, even ones that + don't match page sizes or page alignments and that may cross pages. + + * Allows the netfs to expand a readahead request in both directions to meet + its needs. + + * Allows the netfs to partially fulfil a read, which will then be resubmitted. + + * Handles local caching, allowing cached data and server-read data to be + interleaved for a single request. + + * Handles clearing of bufferage that aren't on the server. + + * Handle retrying of reads that failed, switching reads from the cache to the + server as necessary. + + * In the future, this is a place that other services can be performed, such as + local encryption of data to be stored remotely or in the cache. + +From the network filesystem, the helpers require a table of operations. This +includes a mandatory method to issue a read operation along with a number of +optional methods. + + +Read Helper Functions +--------------------- + +Three read helpers are provided:: + + * void netfs_readahead(struct readahead_control *ractl, + const struct netfs_read_request_ops *ops, + void *netfs_priv);`` + * int netfs_readpage(struct file *file, + struct page *page, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + * int netfs_write_begin(struct file *file, + struct address_space *mapping, + loff_t pos, + unsigned int len, + unsigned int flags, + struct page **_page, + void **_fsdata, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + +Each corresponds to a VM operation, with the addition of a couple of parameters +for the use of the read helpers: + + * ``ops`` + + A table of operations through which the helpers can talk to the filesystem. + + * ``netfs_priv`` + + Filesystem private data (can be NULL). + +Both of these values will be stored into the read request structure. + +For ->readahead() and ->readpage(), the network filesystem should just jump +into the corresponding read helper; whereas for ->write_begin(), it may be a +little more complicated as the network filesystem might want to flush +conflicting writes or track dirty data and needs to put the acquired page if an +error occurs after calling the helper. + +The helpers manage the read request, calling back into the network filesystem +through the suppplied table of operations. Waits will be performed as +necessary before returning for helpers that are meant to be synchronous. + +If an error occurs and netfs_priv is non-NULL, ops->cleanup() will be called to +deal with it. If some parts of the request are in progress when an error +occurs, the request will get partially completed if sufficient data is read. + +Additionally, there is:: + + * void netfs_subreq_terminated(struct netfs_read_subrequest *subreq, + ssize_t transferred_or_error, + bool was_async); + +which should be called to complete a read subrequest. This is given the number +of bytes transferred or a negative error code, plus a flag indicating whether +the operation was asynchronous (ie. whether the follow-on processing can be +done in the current context, given this may involve sleeping). + + +Read Helper Structures +---------------------- + +The read helpers make use of a couple of structures to maintain the state of +the read. The first is a structure that manages a read request as a whole:: + + struct netfs_read_request { + struct inode *inode; + struct address_space *mapping; + struct netfs_cache_resources cache_resources; + void *netfs_priv; + loff_t start; + size_t len; + loff_t i_size; + const struct netfs_read_request_ops *netfs_ops; + unsigned int debug_id; + ... + }; + +The above fields are the ones the netfs can use. They are: + + * ``inode`` + * ``mapping`` + + The inode and the address space of the file being read from. The mapping + may or may not point to inode->i_data. + + * ``cache_resources`` + + Resources for the local cache to use, if present. + + * ``netfs_priv`` + + The network filesystem's private data. The value for this can be passed in + to the helper functions or set during the request. The ->cleanup() op will + be called if this is non-NULL at the end. + + * ``start`` + * ``len`` + + The file position of the start of the read request and the length. These + may be altered by the ->expand_readahead() op. + + * ``i_size`` + + The size of the file at the start of the request. + + * ``netfs_ops`` + + A pointer to the operation table. The value for this is passed into the + helper functions. + + * ``debug_id`` + + A number allocated to this operation that can be displayed in trace lines + for reference. + + +The second structure is used to manage individual slices of the overall read +request:: + + struct netfs_read_subrequest { + struct netfs_read_request *rreq; + loff_t start; + size_t len; + size_t transferred; + unsigned long flags; + unsigned short debug_index; + ... + }; + +Each subrequest is expected to access a single source, though the helpers will +handle falling back from one source type to another. The members are: + + * ``rreq`` + + A pointer to the read request. + + * ``start`` + * ``len`` + + The file position of the start of this slice of the read request and the + length. + + * ``transferred`` + + The amount of data transferred so far of the length of this slice. The + network filesystem or cache should start the operation this far into the + slice. If a short read occurs, the helpers will call again, having updated + this to reflect the amount read so far. + + * ``flags`` + + Flags pertaining to the read. There are two of interest to the filesystem + or cache: + + * ``NETFS_SREQ_CLEAR_TAIL`` + + This can be set to indicate that the remainder of the slice, from + transferred to len, should be cleared. + + * ``NETFS_SREQ_SEEK_DATA_READ`` + + This is a hint to the cache that it might want to try skipping ahead to + the next data (ie. using SEEK_DATA). + + * ``debug_index`` + + A number allocated to this slice that can be displayed in trace lines for + reference. + + +Read Helper Operations +---------------------- + +The network filesystem must provide the read helpers with a table of operations +through which it can issue requests and negotiate:: + + struct netfs_read_request_ops { + void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); + bool (*is_cache_enabled)(struct inode *inode); + int (*begin_cache_operation)(struct netfs_read_request *rreq); + void (*expand_readahead)(struct netfs_read_request *rreq); + bool (*clamp_length)(struct netfs_read_subrequest *subreq); + void (*issue_op)(struct netfs_read_subrequest *subreq); + bool (*is_still_valid)(struct netfs_read_request *rreq); + int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, + struct page *page, void **_fsdata); + void (*done)(struct netfs_read_request *rreq); + void (*cleanup)(struct address_space *mapping, void *netfs_priv); + }; + +The operations are as follows: + + * ``init_rreq()`` + + [Optional] This is called to initialise the request structure. It is given + the file for reference and can modify the ->netfs_priv value. + + * ``is_cache_enabled()`` + + [Required] This is called by netfs_write_begin() to ask if the file is being + cached. It should return true if it is being cached and false otherwise. + + * ``begin_cache_operation()`` + + [Optional] This is called to ask the network filesystem to call into the + cache (if present) to initialise the caching state for this read. The netfs + library module cannot access the cache directly, so the cache should call + something like fscache_begin_read_operation() to do this. + + The cache gets to store its state in ->cache_resources and must set a table + of operations of its own there (though of a different type). + + This should return 0 on success and an error code otherwise. If an error is + reported, the operation may proceed anyway, just without local caching (only + out of memory and interruption errors cause failure here). + + * ``expand_readahead()`` + + [Optional] This is called to allow the filesystem to expand the size of a + readahead read request. The filesystem gets to expand the request in both + directions, though it's not permitted to reduce it as the numbers may + represent an allocation already made. If local caching is enabled, it gets + to expand the request first. + + Expansion is communicated by changing ->start and ->len in the request + structure. Note that if any change is made, ->len must be increased by at + least as much as ->start is reduced. + + * ``clamp_length()`` + + [Optional] This is called to allow the filesystem to reduce the size of a + subrequest. The filesystem can use this, for example, to chop up a request + that has to be split across multiple servers or to put multiple reads in + flight. + + This should return 0 on success and an error code on error. + + * ``issue_op()`` + + [Required] The helpers use this to dispatch a subrequest to the server for + reading. In the subrequest, ->start, ->len and ->transferred indicate what + data should be read from the server. + + There is no return value; the netfs_subreq_terminated() function should be + called to indicate whether or not the operation succeeded and how much data + it transferred. The filesystem also should not deal with setting pages + uptodate, unlocking them or dropping their refs - the helpers need to deal + with this as they have to coordinate with copying to the local cache. + + Note that the helpers have the pages locked, but not pinned. It is possible + to use the ITER_XARRAY iov iterator to refer to the range of the inode that + is being operated upon without the need to allocate large bvec tables. + + * ``is_still_valid()`` + + [Optional] This is called to find out if the data just read from the local + cache is still valid. It should return true if it is still valid and false + if not. If it's not still valid, it will be reread from the server. + + * ``check_write_begin()`` + + [Optional] This is called from the netfs_write_begin() helper once it has + allocated/grabbed the page to be modified to allow the filesystem to flush + conflicting state before allowing it to be modified. + + It should return 0 if everything is now fine, -EAGAIN if the page should be + regrabbed and any other error code to abort the operation. + + * ``done`` + + [Optional] This is called after the pages in the request have all been + unlocked (and marked uptodate if applicable). + + * ``cleanup`` + + [Optional] This is called as the request is being deallocated so that the + filesystem can clean up ->netfs_priv. + + + +Read Helper Procedure +--------------------- + +The read helpers work by the following general procedure: + + * Set up the request. + + * For readahead, allow the local cache and then the network filesystem to + propose expansions to the read request. This is then proposed to the VM. + If the VM cannot fully perform the expansion, a partially expanded read will + be performed, though this may not get written to the cache in its entirety. + + * Loop around slicing chunks off of the request to form subrequests: + + * If a local cache is present, it gets to do the slicing, otherwise the + helpers just try to generate maximal slices. + + * The network filesystem gets to clamp the size of each slice if it is to be + the source. This allows rsize and chunking to be implemented. + + * The helpers issue a read from the cache or a read from the server or just + clears the slice as appropriate. + + * The next slice begins at the end of the last one. + + * As slices finish being read, they terminate. + + * When all the subrequests have terminated, the subrequests are assessed and + any that are short or have failed are reissued: + + * Failed cache requests are issued against the server instead. + + * Failed server requests just fail. + + * Short reads against either source will be reissued against that source + provided they have transferred some more data: + + * The cache may need to skip holes that it can't do DIO from. + + * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the + end of the slice instead of reissuing. + + * Once the data is read, the pages that have been fully read/cleared: + + * Will be marked uptodate. + + * If a cache is present, will be marked with PG_fscache. + + * Unlocked + + * Any pages that need writing to the cache will then have DIO writes issued. + + * Synchronous operations will wait for reading to be complete. + + * Writes to the cache will proceed asynchronously and the pages will have the + PG_fscache mark removed when that completes. + + * The request structures will be cleaned up when everything has completed. + + +Read Helper Cache API +--------------------- + +When implementing a local cache to be used by the read helpers, two things are +required: some way for the network filesystem to initialise the caching for a +read request and a table of operations for the helpers to call. + +The network filesystem's ->begin_cache_operation() method is called to set up a +cache and this must call into the cache to do the work. If using fscache, for +example, the cache would call:: + + int fscache_begin_read_operation(struct netfs_read_request *rreq, + struct fscache_cookie *cookie); + +passing in the request pointer and the cookie corresponding to the file. + +The netfs_read_request object contains a place for the cache to hang its +state:: + + struct netfs_cache_resources { + const struct netfs_cache_ops *ops; + void *cache_priv; + void *cache_priv2; + }; + +This contains an operations table pointer and two private pointers. The +operation table looks like the following:: + + struct netfs_cache_ops { + void (*end_operation)(struct netfs_cache_resources *cres); + + void (*expand_readahead)(struct netfs_cache_resources *cres, + loff_t *_start, size_t *_len, loff_t i_size); + + enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, + loff_t i_size); + + int (*read)(struct netfs_cache_resources *cres, + loff_t start_pos, + struct iov_iter *iter, + bool seek_data, + netfs_io_terminated_t term_func, + void *term_func_priv); + + 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); + }; + +With a termination handler function pointer:: + + typedef void (*netfs_io_terminated_t)(void *priv, + ssize_t transferred_or_error, + bool was_async); + +The methods defined in the table are: + + * ``end_operation()`` + + [Required] Called to clean up the resources at the end of the read request. + + * ``expand_readahead()`` + + [Optional] Called at the beginning of a netfs_readahead() operation to allow + the cache to expand a request in either direction. This allows the cache to + size the request appropriately for the cache granularity. + + The function is passed poiners to the start and length in its parameters, + plus the size of the file for reference, and adjusts the start and length + appropriately. It should return one of: + + * ``NETFS_FILL_WITH_ZEROES`` + * ``NETFS_DOWNLOAD_FROM_SERVER`` + * ``NETFS_READ_FROM_CACHE`` + * ``NETFS_INVALID_READ`` + + to indicate whether the slice should just be cleared or whether it should be + downloaded from the server or read from the cache - or whether slicing + should be given up at the current point. + + * ``prepare_read()`` + + [Required] Called to configure the next slice of a request. ->start and + ->len in the subrequest indicate where and how big the next slice can be; + the cache gets to reduce the length to match its granularity requirements. + + * ``read()`` + + [Required] Called to read from the cache. The start file offset is given + along with an iterator to read to, which gives the length also. It can be + given a hint requesting that it seek forward from that start position for + data. + + Also provided is a pointer to a termination handler function and private + data to pass to that function. The termination function should be called + with the number of bytes transferred or an error code, plus a flag + indicating whether the termination is definitely happening in the caller's + context. + + * ``write()`` + + [Required] Called to write to the cache. The start file offset is given + along with an iterator to write from, which gives the length also. + + Also provided is a pointer to a termination handler function and private + data to pass to that function. The termination function should be called + with the number of bytes transferred or an error code, plus a flag + indicating whether the termination is definitely happening in the caller's + context. + +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 +cache. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 78240e29b0bb..455ca86eb4fc 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -40,17 +40,17 @@ On 64bit systems, even if all overlay layers are not on the same underlying filesystem, the same compliant behavior could be achieved with the "xino" feature. The "xino" feature composes a unique object identifier from the real object st_ino and an underlying fsid index. - -If all underlying filesystems support NFS file handles and export file -handles with 32bit inode number encoding (e.g. ext4), overlay filesystem -will use the high inode number bits for fsid. Even when the underlying -filesystem uses 64bit inode numbers, users can still enable the "xino" -feature with the "-o xino=on" overlay mount option. That is useful for the -case of underlying filesystems like xfs and tmpfs, which use 64bit inode -numbers, but are very unlikely to use the high inode number bits. In case +The "xino" feature uses the high inode number bits for fsid, because the +underlying filesystems rarely use the high inode number bits. In case the underlying inode number does overflow into the high xino bits, overlay filesystem will fall back to the non xino behavior for that inode. +The "xino" feature can be enabled with the "-o xino=on" overlay mount option. +If all underlying filesystems support NFS file handles, the value of st_ino +for overlay filesystem objects is not only unique, but also persistent over +the lifetime of the filesystem. The "-o xino=auto" overlay mount option +enables the "xino" feature only if the persistent st_ino requirement is met. + The following table summarizes what can be expected in different overlay configurations. @@ -66,14 +66,13 @@ Inode properties | All layers | Y | Y | Y | Y | Y | Y | Y | Y | | on same fs | | | | | | | | | +--------------+-----+------+-----+------+--------+--------+--------+-------+ -| Layers not | N | Y | Y | N | N | Y | N | Y | +| Layers not | N | N | Y | N | N | Y | N | Y | | on same fs, | | | | | | | | | | xino=off | | | | | | | | | +--------------+-----+------+-----+------+--------+--------+--------+-------+ | xino=on/auto | Y | Y | Y | Y | Y | Y | Y | Y | -| | | | | | | | | | +--------------+-----+------+-----+------+--------+--------+--------+-------+ -| xino=on/auto,| N | Y | Y | N | N | Y | N | Y | +| xino=on/auto,| N | N | Y | N | N | Y | N | Y | | ino overflow | | | | | | | | | +--------------+-----+------+-----+------+--------+--------+--------+-------+ @@ -81,7 +80,6 @@ Inode properties /proc files, such as /proc/locks and /proc/self/fdinfo/<fd> of an inotify file descriptor. - Upper and Lower --------------- @@ -461,7 +459,7 @@ enough free bits in the inode number, then overlayfs will not be able to guarantee that the values of st_ino and st_dev returned by stat(2) and the value of d_ino returned by readdir(3) will act like on a normal filesystem. E.g. the value of st_dev may be different for two objects in the same -overlay filesystem and the value of st_ino for directory objects may not be +overlay filesystem and the value of st_ino for filesystem objects may not be persistent and could change even while the overlay filesystem is mounted, as summarized in the `Inode properties`_ table above. @@ -476,7 +474,7 @@ a crash or deadlock. Offline changes, when the overlay is not mounted, are allowed to the upper tree. Offline changes to the lower tree are only allowed if the -"metadata only copy up", "inode index", and "redirect_dir" features +"metadata only copy up", "inode index", "xino" and "redirect_dir" features have not been used. If the lower tree is modified and any of these features has been used, the behavior of the overlay is undefined, though it will not result in a crash or deadlock. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 48fbfc336ebf..81bfe3c800cc 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -540,7 +540,9 @@ encoded manner. The codes are the following: ac area is accountable nr swap space is not reserved for the area ht area uses huge tlb pages + sf synchronous page fault ar architecture specific flag + wf wipe on fork dd do not include area into core dump sd soft dirty flag mm mixed map area @@ -549,6 +551,8 @@ encoded manner. The codes are the following: mg mergable advise flag bt arm64 BTI guarded page mt arm64 MTE allocation tags are enabled + um userfaultfd missing tracking + uw userfaultfd wr-protect tracking == ======================================= Note that there is no guarantee that every flag and associated mnemonic will diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst index e85d74e91295..760a4d83fdf9 100644 --- a/Documentation/filesystems/vfat.rst +++ b/Documentation/filesystems/vfat.rst @@ -189,7 +189,7 @@ VFAT MOUNT OPTIONS **discard** If set, issues discard/TRIM commands to the block device when blocks are freed. This is useful for SSD devices - and sparse/thinly-provisoned LUNs. + and sparse/thinly-provisioned LUNs. **nfs=stale_rw|nostale_ro** Enable this only if you want to export the FAT filesystem diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 2049bbf5e388..14c31eced416 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -441,6 +441,9 @@ As of kernel 2.6.22, the following members are defined: unsigned open_flag, umode_t create_mode); int (*tmpfile) (struct user_namespace *, struct inode *, struct dentry *, umode_t); int (*set_acl)(struct user_namespace *, struct inode *, struct posix_acl *, int); + int (*fileattr_set)(struct user_namespace *mnt_userns, + struct dentry *dentry, struct fileattr *fa); + int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); }; Again, all methods are called without any locks being held, unless @@ -588,6 +591,18 @@ otherwise noted. atomically creating, opening and unlinking a file in given directory. +``fileattr_get`` + called on ioctl(FS_IOC_GETFLAGS) and ioctl(FS_IOC_FSGETXATTR) to + retrieve miscellaneous file flags and attributes. Also called + before the relevant SET operation to check what is being changed + (in this case with i_rwsem locked exclusive). If unset, then + fall back to f_op->ioctl(). + +``fileattr_set`` + called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to + change miscellaneous file flags and attributes. Callers hold + i_rwsem exclusive. If unset, then fall back to f_op->ioctl(). + The Address Space Object ======================== diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 03cd4e25fc45..0639c9de07f9 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -1,18 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0 -================= -ACPI Debug Output -================= +==================== +ACPI CA Debug Output +==================== -The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug -output. This document describes how to use this facility. +The ACPI CA can generate debug output. This document describes how to use this +facility. Compile-time configuration ========================== -ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config -option is turned off, the debug messages are not even built into the -kernel. +The ACPI CA debug output is globally enabled by CONFIG_ACPI_DEBUG. If this +config option is not set, the debug messages are not even built into the kernel. Boot- and run-time configuration ================================ @@ -27,16 +26,16 @@ debug_layer (component) ======================= The "debug_layer" is a mask that selects components of interest, e.g., a -specific driver or part of the ACPI interpreter. To build the debug_layer -bitmask, look for the "#define _COMPONENT" in an ACPI source file. +specific part of the ACPI interpreter. To build the debug_layer bitmask, look +for the "#define _COMPONENT" in an ACPI source file. You can set the debug_layer mask at boot-time using the acpi.debug_layer command line argument, and you can change it after boot by writing values to /sys/module/acpi/parameters/debug_layer. -The possible components are defined in include/acpi/acoutput.h and -include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer -shows the supported mask values, currently these:: +The possible components are defined in include/acpi/acoutput.h. + +Reading /sys/module/acpi/parameters/debug_layer shows the supported mask values:: ACPI_UTILITIES 0x00000001 ACPI_HARDWARE 0x00000002 @@ -52,13 +51,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_SBS_COMPONENT 0x00100000 - ACPI_FAN_COMPONENT 0x00200000 - ACPI_PCI_COMPONENT 0x00400000 - ACPI_CONTAINER_COMPONENT 0x01000000 - ACPI_SYSTEM_COMPONENT 0x02000000 - ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 - ACPI_PROCESSOR_COMPONENT 0x20000000 debug_level =========== @@ -127,10 +119,6 @@ AML) during boot:: acpi.debug_layer=0xffffffff acpi.debug_level=0x2 -Enable PCI and PCI interrupt routing debug messages:: - - acpi.debug_layer=0x400000 acpi.debug_level=0x4 - Enable all ACPI hardware-related messages:: acpi.debug_layer=0x2 acpi.debug_level=0xffffffff diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index 4e264c16ddff..df4b711053ee 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -99,6 +99,12 @@ native:: } } +Note, that historically ACPI has no means of the GPIO polarity and thus +the SPISerialBus() resource defines it on the per-chip basis. In order +to avoid a chain of negations, the GPIO polarity is considered being +Active High. Even for the cases when _DSD() is involved (see the example +above) the GPIO CS polarity must be defined Active High to avoid ambiguity. + Other supported properties ========================== diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index c41ac76ffaae..f3a1223f2517 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -7,6 +7,7 @@ Authors: - Enno Luebbers <enno.luebbers@intel.com> - Xiao Guangrong <guangrong.xiao@linux.intel.com> - Wu Hao <hao.wu@intel.com> +- Xu Yilun <yilun.xu@intel.com> The Device Feature List (DFL) FPGA framework (and drivers according to this framework) hides the very details of low layer hardwares and provides @@ -530,6 +531,31 @@ Being able to specify more than one DFL per BAR has been considered, but it was determined the use case did not provide value. Specifying a single DFL per BAR simplifies the implementation and allows for extra error checking. + +Userspace driver support for DFL devices +======================================== +The purpose of an FPGA is to be reprogrammed with newly developed hardware +components. New hardware can instantiate a new private feature in the DFL, and +then present a DFL device in the system. In some cases users may need a +userspace driver for the DFL device: + +* Users may need to run some diagnostic test for their hardware. +* Users may prototype the kernel driver in user space. +* Some hardware is designed for specific purposes and does not fit into one of + the standard kernel subsystems. + +This requires direct access to MMIO space and interrupt handling from +userspace. The uio_dfl module exposes the UIO device interfaces for this +purpose. + +Currently the uio_dfl driver only supports the Ether Group sub feature, which +has no irq in hardware. So the interrupt handling is not added in this driver. + +UIO_DFL should be selected to enable the uio_dfl module driver. To support a +new DFL feature via UIO direct access, its feature id should be added to the +driver's id_table. + + Open discussion =============== FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index b89ddd06dabb..389892f36185 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -80,6 +80,18 @@ Atomic State Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export: +GEM Atomic Helper Reference +--------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_atomic_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c + :export: + Simple KMS Helper Reference =========================== diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index c9a51e3bfb5a..ec4bc72438e4 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -16,6 +16,7 @@ Linux GPU Driver Developer's Guide vga-switcheroo vgaarbiter todo + rfc/index .. only:: subproject and html diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst new file mode 100644 index 000000000000..a8621f7dab8b --- /dev/null +++ b/Documentation/gpu/rfc/index.rst @@ -0,0 +1,17 @@ +=============== +GPU RFC Section +=============== + +For complex work, especially new uapi, it is often good to nail the high level +design issues before getting lost in the code details. This section is meant to +host such documentation: + +* Each RFC should be a section in this file, explaining the goal and main design + considerations. Especially for uapi make sure you Cc: all relevant project + mailing lists and involved people outside of dri-devel. + +* For uapi structures add a file to this directory with and then pull the + kerneldoc in like with real uapi headers. + +* Once the code has landed move all the documentation to the right places in + the main core, helper or driver sections. diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 22ce801e3a8d..7ff9fac10d8b 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -459,52 +459,6 @@ Contact: Emil Velikov, respective driver maintainers Level: Intermediate -Plumb drm_atomic_state all over -------------------------------- - -Currently various atomic functions take just a single or a handful of -object states (eg. plane state). While that single object state can -suffice for some simple cases, we often have to dig out additional -object states for dealing with various dependencies between the individual -objects or the hardware they represent. The process of digging out the -additional states is rather non-intuitive and error prone. - -To fix that most functions should rather take the overall -drm_atomic_state as one of their parameters. The other parameters -would generally be the object(s) we mainly want to interact with. - -For example, instead of - -.. code-block:: c - - int (*atomic_check)(struct drm_plane *plane, struct drm_plane_state *state); - -we would have something like - -.. code-block:: c - - int (*atomic_check)(struct drm_plane *plane, struct drm_atomic_state *state); - -The implementation can then trivially gain access to any required object -state(s) via drm_atomic_get_plane_state(), drm_atomic_get_new_plane_state(), -drm_atomic_get_old_plane_state(), and their equivalents for -other object types. - -Additionally many drivers currently access the object->state pointer -directly in their commit functions. That is not going to work if we -eg. want to allow deeper commit pipelines as those pointers could -then point to the states corresponding to a future commit instead of -the current commit we're trying to process. Also non-blocking commits -execute locklessly so there are serious concerns with dereferencing -the object->state pointers without holding the locks that protect them. -Use of drm_atomic_get_new_plane_state(), drm_atomic_get_old_plane_state(), -etc. avoids these problems as well since they relate to a specific -commit via the passed in drm_atomic_state. - -Contact: Ville Syrjälä, Daniel Vetter - -Level: Intermediate - Use struct dma_buf_map throughout codebase ------------------------------------------ @@ -596,20 +550,24 @@ Contact: Daniel Vetter Level: Intermediate -KMS cleanups ------------- +Object lifetime fixes +--------------------- + +There's two related issues here + +- Cleanup up the various ->destroy callbacks, which often are all the same + simple code. -Some of these date from the very introduction of KMS in 2008 ... +- Lots of drivers erroneously allocate DRM modeset objects using devm_kzalloc, + which results in use-after free issues on driver unload. This can be serious + trouble even for drivers for hardware integrated on the SoC due to + EPROBE_DEFERRED backoff. -- Make ->funcs and ->helper_private vtables optional. There's a bunch of empty - function tables in drivers, but before we can remove them we need to make sure - that all the users in helpers and drivers do correctly check for a NULL - vtable. +Both these problems can be solved by switching over to drmm_kzalloc(), and the +various convenience wrappers provided, e.g. drmm_crtc_alloc_with_planes(), +drmm_universal_plane_alloc(), ... and so on. -- Cleanup up the various ->destroy callbacks. A lot of them just wrapt the - drm_*_cleanup implementations and can be removed. Some tack a kfree() at the - end, for which we could add drm_*_cleanup_kfree(). And then there's the (for - historical reasons) misnamed drm_primary_helper_destroy() function. +Contact: Daniel Vetter Level: Intermediate @@ -666,8 +624,6 @@ See the documentation of :ref:`VKMS <vkms>` for more details. This is an ideal internship task, since it only requires a virtual machine and can be sized to fit the available time. -Contact: Daniel Vetter - Level: See details Backlight Refactoring @@ -721,7 +677,7 @@ Outside DRM Convert fbdev drivers to DRM ---------------------------- -There are plenty of fbdev drivers for older hardware. Some hwardware has +There are plenty of fbdev drivers for older hardware. Some hardware has become obsolete, but some still provides good(-enough) framebuffers. The drivers that are still useful should be converted to DRM and afterwards removed from fbdev. diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index f6ce44ff611d..7a851252267a 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -345,7 +345,7 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. To debug ISH, event tracing mechanism is used. To enable debug logs:: echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable - cat sys/kernel/debug/tracing/trace + cat /sys/kernel/debug/tracing/trace 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 ----------------------------------------------------- diff --git a/Documentation/hwmon/amd_energy.rst b/Documentation/hwmon/amd_energy.rst deleted file mode 100644 index 9d58cd5ee3da..000000000000 --- a/Documentation/hwmon/amd_energy.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Kernel driver amd_energy -========================== - -Supported chips: - -* AMD Family 17h Processors: Model 30h - -* AMD Family 19h Processors: Model 01h - - Prefix: 'amd_energy' - - Addresses used: RAPL MSRs - - Datasheets: - - - Processor Programming Reference (PPR) for AMD Family 17h Model 01h, Revision B1 Processors - - https://developer.amd.com/wp-content/resources/55570-B1_PUB.zip - - - Preliminary Processor Programming Reference (PPR) for AMD Family 17h Model 31h, Revision B0 Processors - - https://developer.amd.com/wp-content/resources/56176_ppr_Family_17h_Model_71h_B0_pub_Rev_3.06.zip - -Author: Naveen Krishna Chatradhi <nchatrad@amd.com> - -Description ------------ - -The Energy driver exposes the energy counters that are -reported via the Running Average Power Limit (RAPL) -Model-specific Registers (MSRs) via the hardware monitor -(HWMON) sysfs interface. - -1. Power, Energy and Time Units - MSR_RAPL_POWER_UNIT/ C001_0299: - shared with all cores in the socket - -2. Energy consumed by each Core - MSR_CORE_ENERGY_STATUS/ C001_029A: - 32-bitRO, Accumulator, core-level power reporting - -3. Energy consumed by Socket - MSR_PACKAGE_ENERGY_STATUS/ C001_029B: - 32-bitRO, Accumulator, socket-level power reporting, - shared with all cores in socket - -These registers are updated every 1ms and cleared on -reset of the system. - -Note: If SMT is enabled, Linux enumerates all threads as cpus. -Since, the energy status registers are accessed at core level, -reading those registers from the sibling threads would result -in duplicate values. Hence, energy counter entries are not -populated for the siblings. - -Energy Caluclation ------------------- - -Energy information (in Joules) is based on the multiplier, -1/2^ESU; where ESU is an unsigned integer read from -MSR_RAPL_POWER_UNIT register. Default value is 10000b, -indicating energy status unit is 15.3 micro-Joules increment. - -Reported values are scaled as per the formula - -scaled value = ((1/2^ESU) * (Raw value) * 1000000UL) in uJoules - -Users calculate power for a given domain by calculating - dEnergy/dTime for that domain. - -Energy accumulation --------------------------- - -Current, Socket energy status register is 32bit, assuming a 240W -2P system, the register would wrap around in - - 2^32*15.3 e-6/240 * 2 = 547.60833024 secs to wrap(~9 mins) - -The Core energy register may wrap around after several days. - -To improve the wrap around time, a kernel thread is implemented -to accumulate the socket energy counters and one core energy counter -per run to a respective 64-bit counter. The kernel thread starts -running during probe, wakes up every 100secs and stops running -when driver is removed. - -Frequency of the accumulator thread is set during the probe -based on the chosen energy unit resolution. For example -A. fine grain (1.625 micro J) -B. course grain (0.125 milli J) - -A socket and core energy read would return the current register -value added to the respective energy accumulator. - -Sysfs attributes ----------------- - -=============== ======== ===================================== -Attribute Label Description -=============== ======== ===================================== - -* For index N between [1] and [nr_cpus] - -=============== ======== ====================================== -energy[N]_input EcoreX Core Energy X = [0] to [nr_cpus - 1] - Measured input core energy -=============== ======== ====================================== - -* For N between [nr_cpus] and [nr_cpus + nr_socks] - -=============== ======== ====================================== -energy[N]_input EsocketX Socket Energy X = [0] to [nr_socks -1] - Measured input socket energy -=============== ======== ====================================== - -Note: To address CVE-2020-12912, the visibility of the energy[N]_input -attributes is restricted to owner and groups only. diff --git a/Documentation/hwmon/bpa-rs600.rst b/Documentation/hwmon/bpa-rs600.rst new file mode 100644 index 000000000000..28313995d4ae --- /dev/null +++ b/Documentation/hwmon/bpa-rs600.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver bpa-rs600 +======================= + +Supported chips: + + * BPA-RS600-120 + + Datasheet: Publicly available at the BluTek website + http://blutekpower.com/wp-content/uploads/2019/01/BPA-RS600-120-07-19-2018.pdf + +Authors: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +Description +----------- + +The BPA-RS600 is a compact 600W removable power supply module. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Sysfs attributes +---------------- + +======================= ============================================ +curr1_label "iin" +curr1_input Measured input current +curr1_max Maximum input current +curr1_max_alarm Input current high alarm + +curr2_label "iout1" +curr2_input Measured output current +curr2_max Maximum output current +curr2_max_alarm Output current high alarm + +fan1_input Measured fan speed +fan1_alarm Fan warning +fan1_fault Fan fault + +in1_label "vin" +in1_input Measured input voltage +in1_max Maximum input voltage +in1_max_alarm Input voltage high alarm +in1_min Minimum input voltage +in1_min_alarm Input voltage low alarm + +in2_label "vout1" +in2_input Measured output voltage +in2_max Maximum output voltage +in2_max_alarm Output voltage high alarm +in2_min Maximum output voltage +in2_min_alarm Output voltage low alarm + +power1_label "pin" +power1_input Measured input power +power1_alarm Input power alarm +power1_max Maximum input power + +power2_label "pout1" +power2_input Measured output power +power2_max Maximum output power +power2_max_alarm Output power high alarm + +temp1_input Measured temperature around input connector +temp1_alarm Temperature alarm + +temp2_input Measured temperature around output connector +temp2_alarm Temperature alarm +======================= ============================================ diff --git a/Documentation/hwmon/corsair-psu.rst b/Documentation/hwmon/corsair-psu.rst index 396b95c9a76a..e8378e7a1d8c 100644 --- a/Documentation/hwmon/corsair-psu.rst +++ b/Documentation/hwmon/corsair-psu.rst @@ -47,19 +47,30 @@ Sysfs entries ======================= ======================================================== curr1_input Total current usage curr2_input Current on the 12v psu rail +curr2_crit Current max critical value on the 12v psu rail curr3_input Current on the 5v psu rail +curr3_crit Current max critical value on the 5v psu rail curr4_input Current on the 3.3v psu rail +curr4_crit Current max critical value on the 3.3v psu rail fan1_input RPM of psu fan in0_input Voltage of the psu ac input in1_input Voltage of the 12v psu rail +in1_crit Voltage max critical value on the 12v psu rail +in1_lcrit Voltage min critical value on the 12v psu rail in2_input Voltage of the 5v psu rail -in3_input Voltage of the 3.3 psu rail +in2_crit Voltage max critical value on the 5v psu rail +in2_lcrit Voltage min critical value on the 5v psu rail +in3_input Voltage of the 3.3v psu rail +in3_crit Voltage max critical value on the 3.3v psu rail +in3_lcrit Voltage min critical value on the 3.3v psu rail power1_input Total power usage power2_input Power usage of the 12v psu rail power3_input Power usage of the 5v psu rail power4_input Power usage of the 3.3v psu rail temp1_input Temperature of the psu vrm component +temp1_crit Temperature max cirtical value of the psu vrm component temp2_input Temperature of the psu case +temp2_crit Temperature max critical value of psu case ======================= ======================================================== Usage Notes diff --git a/Documentation/hwmon/fsp-3y.rst b/Documentation/hwmon/fsp-3y.rst new file mode 100644 index 000000000000..5693d83a2035 --- /dev/null +++ b/Documentation/hwmon/fsp-3y.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver fsp3y +====================== +Supported devices: + * 3Y POWER YH-5151E + * 3Y POWER YM-2151E + +Author: Václav Kubernát <kubernat@cesnet.cz> + +Description +----------- +This driver implements limited support for two 3Y POWER devices. + +Sysfs entries +------------- + * in1_input input voltage + * in2_input 12V output voltage + * in3_input 5V output voltage + * curr1_input input current + * curr2_input 12V output current + * curr3_input 5V output current + * fan1_input fan rpm + * temp1_input temperature 1 + * temp2_input temperature 2 + * temp3_input temperature 3 + * power1_input input power + * power2_input output power diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 8d5a2df1ecb6..9ed60fa84cbe 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -39,12 +39,12 @@ Hardware Monitoring Kernel Drivers adt7475 aht10 amc6821 - amd_energy asb100 asc7621 aspeed-pwm-tacho bcm54140 bel-pfe + bpa-rs600 bt1-pvt coretemp corsair-cpro @@ -62,6 +62,7 @@ Hardware Monitoring Kernel Drivers f71805f f71882fg fam15h_power + fsp-3y ftsteutates g760a g762 @@ -77,6 +78,7 @@ Hardware Monitoring Kernel Drivers intel-m10-bmc-hwmon ir35221 ir38064 + ir36021 isl68137 it87 jc42 @@ -112,6 +114,7 @@ Hardware Monitoring Kernel Drivers ltc4260 ltc4261 max127 + max15301 max16064 max16065 max1619 @@ -142,6 +145,7 @@ Hardware Monitoring Kernel Drivers npcm750-pwm-fan nsa320 ntc_thermistor + nzxt-kraken2 occ pc87360 pc87427 @@ -168,6 +172,7 @@ Hardware Monitoring Kernel Drivers smsc47m192 smsc47m1 sparx5-temp + stpddc60 tc654 tc74 thmc50 diff --git a/Documentation/hwmon/ir36021.rst b/Documentation/hwmon/ir36021.rst new file mode 100644 index 000000000000..ca3436b04e20 --- /dev/null +++ b/Documentation/hwmon/ir36021.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver ir36021 +===================== + +Supported chips: + + * Infineon IR36021 + + Prefix: ir36021 + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/ir36021.pdf?fileId=5546d462533600a4015355d0aa2d1775 + +Authors: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +Description +----------- + +The IR36021 is a dual‐loop digital multi‐phase buck controller designed for +point of load applications. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Sysfs attributes +---------------- + +======================= =========================== +curr1_label "iin" +curr1_input Measured input current +curr1_alarm Input fault alarm + +curr2_label "iout1" +curr2_input Measured output current +curr2_alarm Output over-current alarm + +in1_label "vin" +in1_input Measured input voltage +in1_alarm Input under-voltage alarm + +in2_label "vout1" +in2_input Measured output voltage +in2_alarm Output over-voltage alarm + +power1_label "pin" +power1_input Measured input power +power1_alarm Input under-voltage alarm + +power2_label "pout1" +power2_input Measured output power + +temp1_input Measured temperature +temp1_alarm Temperature alarm + +temp2_input Measured other loop temperature +temp2_alarm Temperature alarm +======================= =========================== diff --git a/Documentation/hwmon/max15301.rst b/Documentation/hwmon/max15301.rst new file mode 100644 index 000000000000..e3dc22fe1c6d --- /dev/null +++ b/Documentation/hwmon/max15301.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver max15301 +====================== + +Supported chips: + + * Maxim MAX15301 + + Prefix: 'max15301', 'bmr461' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX15301.pdf + +Author: Erik Rosen <erik.rosen@metormote.com> + + +Description +----------- + +This driver supports hardware monitoring for Maxim MAX15301 controller chip and +compatible modules. + +The driver is a client driver to the core PMBus driver. Please see +Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details +on PMBus client drivers. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for +details. + + +Platform data support +--------------------- + +The driver supports standard PMBus driver platform data. + + +Module parameters +----------------- + +delay +----- + +The controller requires a minimum interval between I2C bus accesses. +The default interval is set to 100 us. For manual override, the driver +provides a writeable module parameter, 'delay', which can be used to +set the interval to a value between 0 and 65,535 microseconds. + + +Sysfs entries +------------- + +The following attributes are supported. Limits are read-write; all other +attributes are read-only. + +======================= ======================================================== +in1_label "vin" +in1_input Measured input voltage. +in1_lcrit Critical minimum input voltage. +in1_crit Critical maximum input voltage. +in1_lcrit_alarm Input voltage critical low alarm. +in1_crit_alarm Input voltage critical high alarm. + +in2_label "vout1" +in2_input Measured output voltage. +in2_lcrit Critical minimum output Voltage. +in2_crit Critical maximum output voltage. +in2_lcrit_alarm Critical output voltage critical low alarm. +in2_crit_alarm Critical output voltage critical high alarm. + +curr1_label "iout1" +curr1_input Measured output current. +curr1_crit Critical maximum output current. +curr1_crit_alarm Output current critical high alarm. + +temp1_input Measured maximum temperature of all phases. +temp1_max Maximum temperature limit. +temp1_max_alarm High temperature alarm. +temp1_crit Critical maximum temperature limit. +temp1_crit_alarm Critical maximum temperature alarm. +======================= ======================================================== diff --git a/Documentation/hwmon/nzxt-kraken2.rst b/Documentation/hwmon/nzxt-kraken2.rst new file mode 100644 index 000000000000..94025de65a81 --- /dev/null +++ b/Documentation/hwmon/nzxt-kraken2.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-kraken2 +========================== + +Supported devices: + +* NZXT Kraken X42 +* NZXT Kraken X52 +* NZXT Kraken X62 +* NZXT Kraken X72 + +Author: Jonas Malaco + +Description +----------- + +This driver enables hardware monitoring support for NZXT Kraken X42/X52/X62/X72 +all-in-one CPU liquid coolers. Three sensors are available: fan speed, pump +speed and coolant temperature. + +Fan and pump control, while supported by the firmware, are not currently +exposed. The addressable RGB LEDs, present in the integrated CPU water block +and pump head, are not supported either. But both features can be found in +existing user-space tools (e.g. `liquidctl`_). + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Usage Notes +----------- + +As these are USB HIDs, the driver can be loaded automatically by the kernel and +supports hot swapping. + +Sysfs entries +------------- + +======================= ======================================================== +fan1_input Fan speed (in rpm) +fan2_input Pump speed (in rpm) +temp1_input Coolant temperature (in millidegrees Celsius) +======================= ======================================================== diff --git a/Documentation/hwmon/stpddc60.rst b/Documentation/hwmon/stpddc60.rst new file mode 100644 index 000000000000..7f7ce7f7871b --- /dev/null +++ b/Documentation/hwmon/stpddc60.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver stpddc60 +====================== + +Supported chips: + + * ST STPDDC60 + + Prefix: 'stpddc60', 'bmr481' + + Addresses scanned: - + + Datasheet: https://flexpowermodules.com/documents/fpm-techspec-bmr481 + +Author: Erik Rosen <erik.rosen@metormote.com> + + +Description +----------- + +This driver supports hardware monitoring for ST STPDDC60 controller chip and +compatible modules. + +The driver is a client driver to the core PMBus driver. Please see +Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details +on PMBus client drivers. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for +details. + +The vout under- and over-voltage limits are set in relation to the commanded +output voltage as a positive or negative offset in the interval 50mV to 400mV +in 50mV steps. This means that the absolute values of the limits will change +when the commanded output voltage changes. Also, care should be taken when +writing to those limits since in the worst case the commanded output voltage +could change at the same time as the limit is written to, wich will lead to +unpredictable results. + + +Platform data support +--------------------- + +The driver supports standard PMBus driver platform data. + + +Sysfs entries +------------- + +The following attributes are supported. Vin, iout, pout and temp limits +are read-write; all other attributes are read-only. + +======================= ======================================================== +in1_label "vin" +in1_input Measured input voltage. +in1_lcrit Critical minimum input voltage. +in1_crit Critical maximum input voltage. +in1_lcrit_alarm Input voltage critical low alarm. +in1_crit_alarm Input voltage critical high alarm. + +in2_label "vout1" +in2_input Measured output voltage. +in2_lcrit Critical minimum output voltage. +in2_crit Critical maximum output voltage. +in2_lcrit_alarm Critical output voltage critical low alarm. +in2_crit_alarm Critical output voltage critical high alarm. + +curr1_label "iout1" +curr1_input Measured output current. +curr1_max Maximum output current. +curr1_max_alarm Output current high alarm. +curr1_crit Critical maximum output current. +curr1_crit_alarm Output current critical high alarm. + +power1_label "pout1" +power1_input Measured output power. +power1_crit Critical maximum output power. +power1_crit_alarm Output power critical high alarm. + +temp1_input Measured maximum temperature of all phases. +temp1_max Maximum temperature limit. +temp1_max_alarm High temperature alarm. +temp1_crit Critical maximum temperature limit. +temp1_crit_alarm Critical maximum temperature alarm. +======================= ======================================================== diff --git a/Documentation/hwmon/sysfs-interface.rst b/Documentation/hwmon/sysfs-interface.rst index 678c9c60b5a3..13c5acb72d63 100644 --- a/Documentation/hwmon/sysfs-interface.rst +++ b/Documentation/hwmon/sysfs-interface.rst @@ -65,6 +65,14 @@ the desired value must be written, note that strings which are not a number are interpreted as 0! For more on how written strings are interpreted see the "sysfs attribute writes interpretation" section at the end of this file. +Attribute access +---------------- + +Hardware monitoring sysfs attributes are displayed by unrestricted userspace +applications. For this reason, all standard ABI attributes shall be world +readable. Writeable standard ABI attributes shall be writeable only for +privileged users. + ------------------------------------------------------------------------- ======= =========================================== diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst index e195a7d14309..b3ef81475cf8 100644 --- a/Documentation/hwmon/tmp103.rst +++ b/Documentation/hwmon/tmp103.rst @@ -21,10 +21,10 @@ Description The TMP103 is a digital output temperature sensor in a four-ball wafer chip-scale package (WCSP). The TMP103 is capable of reading temperatures to a resolution of 1°C. The TMP103 is specified for -operation over a temperature range of –40°C to +125°C. +operation over a temperature range of -40°C to +125°C. Resolution: 8 Bits -Accuracy: ±1°C Typ (–10°C to +100°C) +Accuracy: ±1°C Typ (-10°C to +100°C) The driver provides the common sysfs-interface for temperatures (see Documentation/hwmon/sysfs-interface.rst under Temperatures). diff --git a/Documentation/hwmon/tps53679.rst b/Documentation/hwmon/tps53679.rst index c7c589e49789..3b9561648c24 100644 --- a/Documentation/hwmon/tps53679.rst +++ b/Documentation/hwmon/tps53679.rst @@ -19,6 +19,14 @@ Supported chips: Datasheet: https://www.ti.com/lit/gpn/TPS53667 + * Texas Instruments TPS53676 + + Prefix: 'tps53676' + + Addresses scanned: - + + Datasheet: https://www.ti.com/lit/gpn/TPS53676 + * Texas Instruments TPS53679 Prefix: 'tps53679' @@ -136,7 +144,7 @@ power1_input Measured input power. power[N]_label "pout[1-2]". - TPS53647, TPS53667: N=2 - - TPS53679, TPS53681, TPS53588: N=2,3 + - TPS53676, TPS53679, TPS53681, TPS53588: N=2,3 power[N]_input Measured output power. @@ -156,10 +164,11 @@ curr[N]_label "iout[1-2]" or "iout1.[0-5]". The first digit is the output channel, the second digit is the phase within the channel. Per-phase - telemetry supported on TPS53681 only. + telemetry supported on TPS53676 and TPS53681 only. - TPS53647, TPS53667: N=2 - TPS53679, TPS53588: N=2,3 + - TPS53676: N=2-8 - TPS53681: N=2-9 curr[N]_input Measured output current. diff --git a/Documentation/iio/iio_configfs.rst b/Documentation/iio/iio_configfs.rst index 3a5d76f9e2b9..b276397af797 100644 --- a/Documentation/iio/iio_configfs.rst +++ b/Documentation/iio/iio_configfs.rst @@ -71,7 +71,7 @@ kernel module following the interface in include/linux/iio/sw_trigger.h:: .ops = &iio_trig_sample_ops, }; -module_iio_sw_trigger_driver(iio_trig_sample); + module_iio_sw_trigger_driver(iio_trig_sample); Each trigger type has its own directory under /config/iio/triggers. Loading iio-trig-sample module will create 'trig-sample' trigger type directory @@ -99,3 +99,4 @@ Each trigger can have one or more attributes specific to the trigger type. "hrtimer" trigger type doesn't have any configurable attribute from /config dir. It does introduce the sampling_frequency attribute to trigger directory. +That attribute sets the polling frequency in Hz, with mHz precision. diff --git a/Documentation/index.rst b/Documentation/index.rst index 31f2adc8542d..54ce34fd6fbd 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -149,27 +149,11 @@ Architecture-agnostic documentation Architecture-specific documentation ----------------------------------- -These books provide programming details about architecture-specific -implementation. - .. toctree:: :maxdepth: 2 - arm/index - arm64/index - ia64/index - m68k/index - mips/index - nios2/index - openrisc/index - parisc/index - powerpc/index - riscv/index - s390/index - sh/index - sparc/index - x86/index - xtensa/index + arch + Other documentation ------------------- diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index 3118fc1c1e26..b24ae7d292cc 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -246,9 +246,9 @@ A few EV_ABS codes have special meanings: A device should set the resolution of the axis to indicate whether the pressure is in measurable units. If the resolution is zero, the - pressure data is in arbitrary units. If the resolution is nonzero, the + pressure data is in arbitrary units. If the resolution is non-zero, the pressure data is in units/gram. For example, a value of 10 with a - resolution of 1 represents 10 gram, a value of 10 with a resolution on + resolution of 1 represents 10 gram, a value of 10 with a resolution of 1000 represents 10 microgram. EV_SW @@ -344,7 +344,7 @@ INPUT_PROP_BUTTONPAD For touchpads where the button is placed beneath the surface, such that pressing down on the pad causes a button click, this property should be -set. Common in clickpad notebooks and macbooks from 2009 and onwards. +set. Common in Clickpad notebooks and Macbooks from 2009 and onwards. Originally, the buttonpad property was coded into the bcm5974 driver version field under the name integrated button. For backwards @@ -356,7 +356,7 @@ INPUT_PROP_SEMI_MT Some touchpads, most common between 2008 and 2011, can detect the presence of multiple contacts without resolving the individual positions; only the number of contacts and a rectangular shape is known. For such -touchpads, the semi-mt property should be set. +touchpads, the SEMI_MT property should be set. Depending on the device, the rectangle may enclose all touches, like a bounding box, or just some of them, for instance the two most recent @@ -394,7 +394,7 @@ Guidelines ========== The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for +For multi-touch functionality, see the multi-touch-protocol.rst document for more information. Mice diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 0c02e87ee86d..5a1da42c33b3 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -16,8 +16,8 @@ goal is not to support these devices as if they were simple input-only devices (as it is already the case), but to really enable the rendering of force effects. This document only describes the force feedback part of the Linux input -interface. Please read joystick.txt and input.txt before reading further this -document. +interface. Please read joydev/joystick.rst and input.rst before reading further +this document. Instructions to the user ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -36,7 +36,7 @@ should keep a hand on your device, in order to avoid it to break down if something goes wrong. If you have a serial iforce device, you need to start inputattach. See -joystick.txt for details. +joydev/joystick.rst for details. Does it work ? -------------- diff --git a/Documentation/input/gameport-programming.rst b/Documentation/input/gameport-programming.rst index c96911df1c54..7d7063ad0f9f 100644 --- a/Documentation/input/gameport-programming.rst +++ b/Documentation/input/gameport-programming.rst @@ -21,7 +21,7 @@ choose which one to program the hardware to, starting from the more exotic addresses is preferred, because the likelihood of clashing with the standard 0x201 address is smaller. -Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then +E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then 0x218 would be the address of first choice. If your hardware supports a gameport address that is not mapped to ISA io @@ -78,7 +78,7 @@ the gameport. To register a cooked gameport:: for (i = 0; i < 4; i++) axes[i] = my_mmio[i]; - buttons[i] = my_mmio[4]; + buttons[0] = my_mmio[4]; } int my_open(struct gameport *gameport, int mode) @@ -117,25 +117,28 @@ Simple:: The gameport structure ~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This section is outdated. There are several fields here that don't - match what's there at include/linux/gameport.h. - :: struct gameport { - void *private; + void *port_data; A private pointer for free use in the gameport driver. (Not the joystick driver!) :: - int number; + char name[32]; + +Driver's name as set by driver calling gameport_set_name(). Informational +purpose only. + +:: + + char phys[32]; -Number assigned to the gameport when registered. Informational purpose only. +gameport's physical name/description as set by driver calling gameport_set_phys(). +Informational purpose only. :: @@ -210,8 +213,16 @@ gameport. :: - struct gameport_dev *dev; - struct gameport *next; + struct timer_list poll_timer; + unsigned int poll_interval; /* in msecs */ + spinlock_t timer_lock; + unsigned int poll_cnt; + void (*poll_handler)(struct gameport *); + struct gameport *parent, *child; + struct gameport_driver *drv; + struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */ + struct device dev; + struct list_head node; For internal use by the gameport layer. diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 5938145b0e35..2638dce69764 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -120,7 +120,7 @@ Then there is the:: call to tell those who receive the events that we've sent a complete report. This doesn't seem important in the one button case, but is quite important -for for example mouse movement, where you don't want the X and Y values +for example for mouse movement, where you don't want the X and Y values to be interpreted separately, because that'd result in a different movement. dev->open() and dev->close() @@ -128,7 +128,7 @@ dev->open() and dev->close() In case the driver has to repeatedly poll the device, because it doesn't have an interrupt coming from it and the polling is too expensive to be done -all the time, or if the device uses a valuable resource (eg. interrupt), it +all the time, or if the device uses a valuable resource (e.g. interrupt), it can use the open and close callback to know when it can stop polling or release the interrupt and when it must resume polling or grab the interrupt again. To do that, we would add this to our example driver:: @@ -161,7 +161,7 @@ makes sure that dev->open() is called only when the first user connects to the device and that dev->close() is called when the very last user disconnects. Calls to both callbacks are serialized. -The open() callback should return a 0 in case of success or any nonzero value +The open() callback should return a 0 in case of success or any non-zero value in case of failure. The close() callback (which is void) must always succeed. Inhibiting input devices @@ -182,8 +182,8 @@ providing events to the input core. Calling the device's close() method on inhibit (if there are users) allows the driver to save power. Either by directly powering down the device or by -releasing the runtime-pm reference it got in open() when the driver is using -runtime-pm. +releasing the runtime-PM reference it got in open() when the driver is using +runtime-PM. Inhibiting and uninhibiting are orthogonal to opening and closing the device by input handlers. Userspace might want to inhibit a device in anticipation before @@ -219,8 +219,8 @@ It's reported to the input system via:: input_report_key(struct input_dev *dev, int code, int value) See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to -KEY_MAX). Value is interpreted as a truth value, ie any nonzero value means key -pressed, zero value means key released. The input code generates events only +KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero value means +key pressed, zero value means key released. The input code generates events only in case the value is different from before. In addition to EV_KEY, there are two more basic event types: EV_REL and @@ -231,12 +231,12 @@ because it doesn't have any absolute coordinate system to work in. Absolute events are namely for joysticks and digitizers - devices that do work in an absolute coordinate systems. -Having the device report EV_REL buttons is as simple as with EV_KEY, simply +Having the device report EV_REL buttons is as simple as with EV_KEY; simply set the corresponding bits and call the:: input_report_rel(struct input_dev *dev, int code, int value) -function. Events are generated only for nonzero value. +function. Events are generated only for non-zero values. However EV_ABS requires a little special care. Before calling input_register_device, you have to fill additional fields in the input_dev @@ -280,7 +280,7 @@ device driver. It's a string like 'Generic button device' containing a user friendly name of the device. The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID -of the device. The bus IDs are defined in input.h. The vendor and device ids +of the device. The bus IDs are defined in input.h. The vendor and device IDs are defined in pci_ids.h, usb_ids.h and similar include files. These fields should be set by the input device driver before registering it. diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst index 0eb61e67a7b7..2c67fa904adc 100644 --- a/Documentation/input/input.rst +++ b/Documentation/input/input.rst @@ -9,7 +9,7 @@ Introduction Architecture ============ -Input subsystem a collection of drivers that is designed to support +Input subsystem is a collection of drivers that is designed to support all input devices under Linux. Most of the drivers reside in drivers/input, although quite a few live in drivers/hid and drivers/platform. @@ -50,7 +50,7 @@ will be available as a character device on major 13, minor 63:: crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice -This device usually created automatically by the system. The commands +This device is usually created automatically by the system. The commands to create it by hand are:: cd /dev @@ -180,7 +180,7 @@ whole suite. It handles all HID devices, and because there is a very wide variety of them, and because the USB HID specification isn't simple, it needs to be this big. -Currently, it handles USB mice, joysticks, gamepads, steering wheels +Currently, it handles USB mice, joysticks, gamepads, steering wheels, keyboards, trackballs and digitizers. However, USB uses HID also for monitor controls, speaker controls, UPSs, @@ -268,7 +268,7 @@ events on a read. Their layout is:: }; ``time`` is the timestamp, it returns the time at which the event happened. -Type is for example EV_REL for relative moment, EV_KEY for a keypress or +Type is for example EV_REL for relative movement, EV_KEY for a keypress or release. More types are defined in include/uapi/linux/input-event-codes.h. ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete diff --git a/Documentation/input/joydev/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst index 95803e2e8cd0..af5934c10c1c 100644 --- a/Documentation/input/joydev/joystick-api.rst +++ b/Documentation/input/joydev/joystick-api.rst @@ -71,7 +71,7 @@ The possible values of ``type`` are:: #define JS_EVENT_INIT 0x80 /* initial state of device */ As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed -events on open. That is, if it's issuing a INIT BUTTON event, the +events on open. That is, if it's issuing an INIT BUTTON event, the current type value will be:: int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */ @@ -100,8 +100,8 @@ is, you have both an axis 0 and a button 0). Generally, =============== ======= Hats vary from one joystick type to another. Some can be moved in 8 -directions, some only in 4, The driver, however, always reports a hat as two -independent axis, even if the hardware doesn't allow independent movement. +directions, some only in 4. The driver, however, always reports a hat as two +independent axes, even if the hardware doesn't allow independent movement. js_event.value @@ -188,10 +188,10 @@ One reason for emptying the queue is that if it gets full you'll start missing events since the queue is finite, and older events will get overwritten. -The other reason is that you want to know all what happened, and not +The other reason is that you want to know all that happened, and not delay the processing till later. -Why can get the queue full? Because you don't empty the queue as +Why can the queue get full? Because you don't empty the queue as mentioned, or because too much time elapses from one read to another and too many events to store in the queue get generated. Note that high system load may contribute to space those reads even more. @@ -277,7 +277,7 @@ to be in the stable part of the API, and therefore may change without warning in following releases of the driver. Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold -information for all axis. That is, struct js_corr corr[MAX_AXIS]; +information for all axes. That is, struct js_corr corr[MAX_AXIS]; struct js_corr is defined as:: @@ -328,7 +328,7 @@ To test the state of the buttons, second_button_state = js.buttons & 2; The axis values do not have a defined range in the original 0.x driver, -except for that the values are non-negative. The 1.2.8+ drivers use a +except that the values are non-negative. The 1.2.8+ drivers use a fixed range for reporting the values, 1 being the minimum, 128 the center, and 255 maximum value. diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst index 9746fd76cc58..f615906a0821 100644 --- a/Documentation/input/joydev/joystick.rst +++ b/Documentation/input/joydev/joystick.rst @@ -133,15 +133,15 @@ And add a line to your rc script executing that file:: This way, after the next reboot your joystick will remain calibrated. You can also add the ``jscal -p`` line to your shutdown script. -HW specific driver information -============================== +Hardware-specific driver information +==================================== In this section each of the separate hardware specific drivers is described. Analog joysticks ---------------- -The analog.c uses the standard analog inputs of the gameport, and thus +The analog.c driver uses the standard analog inputs of the gameport, and thus supports all standard joysticks and gamepads. It uses a very advanced routine for this, allowing for data precision that can't be found on any other system. @@ -266,7 +266,7 @@ to: * Logitech WingMan Extreme Digital 3D ADI devices are autodetected, and the driver supports up to two (any -combination of) devices on a single gameport, using an Y-cable or chained +combination of) devices on a single gameport, using a Y-cable or chained together. Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan @@ -288,7 +288,7 @@ supports: * Gravis Xterminator DualControl All these devices are autodetected, and you can even use any combination -of up to two of these pads either chained together or using an Y-cable on a +of up to two of these pads either chained together or using a Y-cable on a single gameport. GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is @@ -311,7 +311,7 @@ allow connecting analog joysticks to them, you'll need to load the analog driver as well to handle the attached joysticks. The trackball should work with USB mousedev module as a normal mouse. See -the USB documentation for how to setup an USB mouse. +the USB documentation for how to setup a USB mouse. ThrustMaster DirectConnect (BSP) -------------------------------- @@ -332,7 +332,7 @@ If you have one of these, contact me. TMDC devices are autodetected, and thus no parameters to the module are needed. Up to two TMDC devices can be connected to one gameport, using -an Y-cable. +a Y-cable. Creative Labs Blaster --------------------- @@ -342,7 +342,7 @@ the: * Creative Blaster GamePad Cobra -Up to two of these can be used on a single gameport, using an Y-cable. +Up to two of these can be used on a single gameport, using a Y-cable. Genius Digital joysticks ------------------------ @@ -381,7 +381,7 @@ card, 16 in case you have two in your system. Trident 4DWave / Aureal Vortex ------------------------------ -Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets +Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset provide an "Enhanced Game Port" mode where the soundcard handles polling the joystick. This mode is supported by the pcigame.c module. Once loaded the analog driver can use the enhanced features of these gameports.. @@ -454,7 +454,7 @@ Devices currently supported by spaceball.c are: * SpaceTec SpaceBall 4000 FLX In addition to having the spaceorb/spaceball and serport modules in the -kernel, you also need to attach a serial port to it. to do that, run the +kernel, you also need to attach a serial port to it. To do that, run the inputattach program:: inputattach --spaceorb /dev/tts/x & @@ -466,7 +466,7 @@ or:: where /dev/tts/x is the serial port which the device is connected to. After doing this, the device will be reported and will start working. -There is one caveat with the SpaceOrb. The button #6, the on the bottom +There is one caveat with the SpaceOrb. The button #6, the one on the bottom side of the orb, although reported as an ordinary button, causes internal recentering of the spaceorb, moving the zero point to the position in which the ball is at the moment of pressing the button. So, think first before @@ -500,7 +500,7 @@ joy-magellan module. It currently supports only the: * Magellan 3D * Space Mouse -models, the additional buttons on the 'Plus' versions are not supported yet. +models; the additional buttons on the 'Plus' versions are not supported yet. To use it, you need to attach the serial port to the driver using the:: @@ -575,7 +575,7 @@ FAQ :A: The device files don't exist. Create them (see section 2.2). :Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick - or pad that uses a 9-pin D-type cannon connector to the serial port of my + or pad that uses a 9-pin D-type Cannon connector to the serial port of my PC? :A: Yes, it is possible, but it'll burn your serial port or the pad. It won't work, of course. diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 21c1e6a22888..1085cbee4ee7 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -261,7 +261,7 @@ ABS_MT_PRESSURE signal intensity distribution. If the resolution is zero, the pressure data is in arbitrary units. - If the resolution is nonzero, the pressure data is in units/gram. See + If the resolution is non-zero, the pressure data is in units/gram. See :ref:`input-event-codes` for details. ABS_MT_DISTANCE @@ -279,14 +279,14 @@ ABS_MT_ORIENTATION max should be returned; when aligned with the X axis in the negative direction, the range -max should be returned. - Touch ellipsis are symmetrical by default. For devices capable of true 360 + Touch ellipses are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to indicate more than a quarter of a revolution. For an upside-down finger, range max * 2 should be returned. Orientation can be omitted if the touch area is circular, or if the information is not available in the kernel driver. Partial orientation - support is possible if the device can distinguish between the two axis, but + support is possible if the device can distinguish between the two axes, but not (uniquely) any values in between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] [#f4]_. @@ -356,7 +356,7 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that the device can distinguish between a finger along the Y axis (0) and a finger along the X axis (1). -For win8 devices with both T and C coordinates, the position mapping is:: +For Win8 devices with both T and C coordinates, the position mapping is:: ABS_MT_POSITION_X := T_X ABS_MT_POSITION_Y := T_Y diff --git a/Documentation/input/notifier.rst b/Documentation/input/notifier.rst index 161350cb865e..824379399e61 100644 --- a/Documentation/input/notifier.rst +++ b/Documentation/input/notifier.rst @@ -4,11 +4,12 @@ Keyboard notifier One can use register_keyboard_notifier to get called back on keyboard events (see kbd_keycode() function for details). The passed structure is -keyboard_notifier_param: +keyboard_notifier_param (see <linux/keyboard.h>): - 'vc' always provide the VC for which the keyboard event applies; - 'down' is 1 for a key press event, 0 for a key release; - 'shift' is the current modifier state, mask bit indexes are KG_*; +- 'ledstate' is the current LED state; - 'value' depends on the type of event. - KBD_KEYCODE events are always sent before other events, value is the keycode. diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst index 10c62e62a0a6..30fe80e325a5 100644 --- a/Documentation/input/uinput.rst +++ b/Documentation/input/uinput.rst @@ -179,7 +179,7 @@ uinput old interface -------------------- Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual -device. Programs supportinf older versions of uinput interface need to fill +device. Programs supporting older versions of uinput interface need to fill a uinput_user_dev structure and write it to the uinput file descriptor to configure the new uinput device. New code should not use the old interface but interact with uinput via ioctl calls, or use libevdev. diff --git a/Documentation/kbuild/Kconfig.recursion-issue-02 b/Documentation/kbuild/Kconfig.recursion-issue-02 index df245fd7670d..0034eb494d11 100644 --- a/Documentation/kbuild/Kconfig.recursion-issue-02 +++ b/Documentation/kbuild/Kconfig.recursion-issue-02 @@ -6,7 +6,7 @@ # make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig # # The recursive limitations with Kconfig has some non intuitive implications on -# kconfig sematics which are documented here. One known practical implication +# kconfig semantics which are documented here. One known practical implication # of the recursive limitation is that drivers cannot negate features from other # drivers if they share a common core requirement and use disjoint semantics to # annotate those requirements, ie, some drivers use "depends on" while others diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 226ae072da7d..98c24183d8c3 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -223,25 +223,10 @@ applicable everywhere (see syntax). the indentation level, this means it ends at the first line which has a smaller indentation than the first line of the help text. -- misc options: "option" <symbol>[=<value>] - - Various less common options can be defined via this option syntax, - which can modify the behaviour of the menu entry and its config - symbol. These options are currently possible: - - - "defconfig_list" - This declares a list of default entries which can be used when - looking for the default configuration (which is used when the main - .config doesn't exists yet.) - - - "modules" - This declares the symbol to be used as the MODULES symbol, which - enables the third modular state for all config symbols. - At most one symbol may have the "modules" option set. - - - "allnoconfig_y" - This declares the symbol as one that should have the value y when - using "allnoconfig". Used for symbols that hide other symbols. +- module attribute: "modules" + This declares the symbol to be used as the MODULES symbol, which + enables the third modular state for all config symbols. + At most one symbol may have the "modules" option set. Menu dependencies ----------------- diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index dce6801d66c9..5967c79c3baa 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -41,6 +41,14 @@ KCONFIG_CONFIG This environment variable can be used to specify a default kernel config file name to override the default name of ".config". +KCONFIG_DEFCONFIG_LIST +---------------------- + +This environment variable specifies a list of config files which can be used +as a base configuration in case the .config does not exist yet. Entries in +the list are separated with whitespaces to each other, and the first one +that exists is used. + KCONFIG_OVERWRITECONFIG ----------------------- If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not diff --git a/Documentation/leds/leds-lm3556.rst b/Documentation/leds/leds-lm3556.rst index 1ef17d7d800e..32e3983473ba 100644 --- a/Documentation/leds/leds-lm3556.rst +++ b/Documentation/leds/leds-lm3556.rst @@ -23,7 +23,7 @@ from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A), or by pulling the STROBE pin HIGH. -LM3556 Flash can be controlled through sys/class/leds/flash/brightness file +LM3556 Flash can be controlled through /sys/class/leds/flash/brightness file * if STROBE pin is enabled, below example control brightness only, and ON / OFF will be controlled by STROBE pin. @@ -32,17 +32,17 @@ Flash Example: OFF:: - #echo 0 > sys/class/leds/flash/brightness + #echo 0 > /sys/class/leds/flash/brightness 93.75 mA:: - #echo 1 > sys/class/leds/flash/brightness + #echo 1 > /sys/class/leds/flash/brightness ... 1500 mA:: - #echo 16 > sys/class/leds/flash/brightness + #echo 16 > /sys/class/leds/flash/brightness Torch Mode ^^^^^^^^^^ @@ -51,7 +51,7 @@ In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the hardware TORCH input. -LM3556 torch can be controlled through sys/class/leds/torch/brightness file. +LM3556 torch can be controlled through /sys/class/leds/torch/brightness file. * if TORCH pin is enabled, below example control brightness only, and ON / OFF will be controlled by TORCH pin. @@ -59,22 +59,22 @@ Torch Example: OFF:: - #echo 0 > sys/class/leds/torch/brightness + #echo 0 > /sys/class/leds/torch/brightness 46.88 mA:: - #echo 1 > sys/class/leds/torch/brightness + #echo 1 > /sys/class/leds/torch/brightness ... 375 mA:: - #echo 8 > sys/class/leds/torch/brightness + #echo 8 > /sys/class/leds/torch/brightness Indicator Mode ^^^^^^^^^^^^^^ -Indicator pattern can be set through sys/class/leds/indicator/pattern file, +Indicator pattern can be set through /sys/class/leds/indicator/pattern file, and 4 patterns are pre-defined in indicator_pattern array. According to N-lank, Pulse time and N Period values, different pattern wiill @@ -87,13 +87,13 @@ Indicator pattern example: pattern 0:: - #echo 0 > sys/class/leds/indicator/pattern + #echo 0 > /sys/class/leds/indicator/pattern ... pattern 3:: - #echo 3 > sys/class/leds/indicator/pattern + #echo 3 > /sys/class/leds/indicator/pattern Indicator brightness can be controlled through sys/class/leds/indicator/brightness file. @@ -102,17 +102,17 @@ Example: OFF:: - #echo 0 > sys/class/leds/indicator/brightness + #echo 0 > /sys/class/leds/indicator/brightness 5.86 mA:: - #echo 1 > sys/class/leds/indicator/brightness + #echo 1 > /sys/class/leds/indicator/brightness ... 46.875mA:: - #echo 8 > sys/class/leds/indicator/brightness + #echo 8 > /sys/class/leds/indicator/brightness Notes ----- diff --git a/Documentation/livepatch/shadow-vars.rst b/Documentation/livepatch/shadow-vars.rst index c05715aeafa4..6a7d43a8787d 100644 --- a/Documentation/livepatch/shadow-vars.rst +++ b/Documentation/livepatch/shadow-vars.rst @@ -165,8 +165,8 @@ In-flight parent objects Sometimes it may not be convenient or possible to allocate shadow variables alongside their parent objects. Or a livepatch fix may -require shadow varibles to only a subset of parent object instances. In -these cases, the klp_shadow_get_or_alloc() call can be used to attach +require shadow variables for only a subset of parent object instances. +In these cases, the klp_shadow_get_or_alloc() call can be used to attach shadow variables to parents already in-flight. For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index b7a627d6c97d..5d5cc3acdf85 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -102,3 +102,4 @@ to do something different in the near future. ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile ../riscv/patch-acceptance + ../driver-api/media/maintainer-entry-profile diff --git a/Documentation/misc-devices/dw-xdata-pcie.rst b/Documentation/misc-devices/dw-xdata-pcie.rst new file mode 100644 index 000000000000..781c6794a506 --- /dev/null +++ b/Documentation/misc-devices/dw-xdata-pcie.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================================================== +Driver for Synopsys DesignWare PCIe traffic generator (also known as xData) +=========================================================================== + +Supported chips: +Synopsys DesignWare PCIe prototype solution + +Datasheet: +Not freely available + +Author: +Gustavo Pimentel <gustavo.pimentel@synopsys.com> + +Description +----------- + +This driver should be used as a host-side (Root Complex) driver and Synopsys +DesignWare prototype that includes this IP. + +The dw-xdata-pcie driver can be used to enable/disable PCIe traffic +generator in either direction (mutual exclusion) besides allowing the +PCIe link performance analysis. + +The interaction with this driver is done through the module parameter and +can be changed in runtime. The driver outputs the requested command state +information to ``/var/log/kern.log`` or dmesg. + +Example +------- + +Write TLPs traffic generation - Root Complex to Endpoint direction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate traffic:: + + # echo 1 > /sys/class/misc/dw-xdata-pcie.0/write + +Get link throughput in MB/s:: + + # cat /sys/class/misc/dw-xdata-pcie.0/write + 204 + +Stop traffic in any direction:: + + # echo 0 > /sys/class/misc/dw-xdata-pcie.0/write + +Read TLPs traffic generation - Endpoint to Root Complex direction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate traffic:: + + # echo 1 > /sys/class/misc/dw-xdata-pcie.0/read + +Get link throughput in MB/s:: + + # cat /sys/class/misc/dw-xdata-pcie.0/read + 199 + +Stop traffic in any direction:: + + # echo 0 > /sys/class/misc/dw-xdata-pcie.0/read + diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 64420b3314fe..30ac58f81901 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -19,6 +19,7 @@ fit into other categories. bh1770glc eeprom c2port + dw-xdata-pcie ibmvmc ics932s401 isl29003 diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index f8dae662e454..f34cb0e4460e 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -608,6 +608,8 @@ demand: setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, &recv_own_msgs, sizeof(recv_own_msgs)); +Note that reception of a socket's own CAN frames are subject to the same +filtering as other CAN frames (see :ref:`socketcan-rawfilter`). .. _socketcan-rawfd: diff --git a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst index 8a9b18573688..2d3f6bd969a2 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst @@ -173,7 +173,7 @@ Director rule is added from ethtool (Sideband filter), ATR is turned off by the driver. To re-enable ATR, the sideband can be disabled with the ethtool -K option. For example:: - ethtool –K [adapter] ntuple [off|on] + ethtool -K [adapter] ntuple [off|on] If sideband is re-enabled after ATR is re-enabled, ATR remains enabled until a TCP-IP flow is added. When all TCP-IP sideband rules are deleted, ATR is @@ -688,7 +688,7 @@ shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates. Totals must be equal or less than port speed. For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples] +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]` 2. Enable HW TC offload on interface:: diff --git a/Documentation/networking/device_drivers/ethernet/intel/iavf.rst b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst index 52e037b11c97..25330b7b5168 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/iavf.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst @@ -179,7 +179,7 @@ shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates. Totals must be equal or less than port speed. For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples] +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]`` NOTE: Setting up channels via ethtool (ethtool -L) is not supported when the diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst index 1b7e32d8a61b..936a10f1942c 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst @@ -183,6 +183,40 @@ User command examples: values: cmode driverinit value true +esw_port_metadata: Eswitch port metadata state +---------------------------------------------- +When applicable, disabling Eswitch metadata can increase packet rate +up to 20% depending on the use case and packet sizes. + +Eswitch port metadata state controls whether to internally tag packets with +metadata. Metadata tagging must be enabled for multi-port RoCE, failover +between representors and stacked devices. +By default metadata is enabled on the supported devices in E-switch. +Metadata is applicable only for E-switch in switchdev mode and +users may disable it when NONE of the below use cases will be in use: +1. HCA is in Dual/multi-port RoCE mode. +2. VF/SF representor bonding (Usually used for Live migration) +3. Stacked devices + +When metadata is disabled, the above use cases will fail to initialize if +users try to enable them. + +- Show eswitch port metadata:: + + $ devlink dev param show pci/0000:06:00.0 name esw_port_metadata + pci/0000:06:00.0: + name esw_port_metadata type driver-specific + values: + cmode runtime value true + +- Disable eswitch port metadata:: + + $ devlink dev param set pci/0000:06:00.0 name esw_port_metadata value false cmode runtime + +- Change eswitch mode to switchdev mode where after choosing the metadata value:: + + $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev + mlx5 subfunction ================ mlx5 supports subfunction management using devlink port (see :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`) interface. diff --git a/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst b/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst index c3f51c672a68..fc5acd427a5d 100644 --- a/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst +++ b/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst @@ -87,11 +87,15 @@ Receive Buffer contain one or more packets. The number of receive sections may be changed via ethtool Rx ring parameters. - There is a similar send buffer which is used to aggregate packets for sending. - The send area is broken into chunks of 6144 bytes, each of section may - contain one or more packets. The send buffer is an optimization, the driver - will use slower method to handle very large packets or if the send buffer - area is exhausted. + There is a similar send buffer which is used to aggregate packets + for sending. The send area is broken into chunks, typically of 6144 + bytes, each of section may contain one or more packets. Small + packets are usually transmitted via copy to the send buffer. However, + if the buffer is temporarily exhausted, or the packet to be transmitted is + an LSO packet, the driver will provide the host with pointers to the data + from the SKB. This attempts to achieve a balance between the overhead of + data copy and the impact of remapping VM memory to be accessible by the + host. XDP support ----------- diff --git a/Documentation/networking/device_drivers/fddi/defza.rst b/Documentation/networking/device_drivers/fddi/defza.rst index 73c2f793ea26..7393f33ea705 100644 --- a/Documentation/networking/device_drivers/fddi/defza.rst +++ b/Documentation/networking/device_drivers/fddi/defza.rst @@ -60,4 +60,4 @@ To do: Both success and failure reports are welcome. -Maciej W. Rozycki <macro@linux-mips.org> +Maciej W. Rozycki <macro@orcam.me.uk> diff --git a/Documentation/networking/devlink/devlink-health.rst b/Documentation/networking/devlink/devlink-health.rst index 0c99b11f05f9..e37f77734b5b 100644 --- a/Documentation/networking/devlink/devlink-health.rst +++ b/Documentation/networking/devlink/devlink-health.rst @@ -24,7 +24,7 @@ attributes of the health reporting and recovery procedures. The ``devlink`` health reporter: Device driver creates a "health reporter" per each error/health type. -Error/Health type can be a known/generic (eg pci error, fw error, rx/tx error) +Error/Health type can be a known/generic (e.g. PCI error, fw error, rx/tx error) or unknown (driver specific). For each registered health reporter a driver can issue error/health reports asynchronously. All health reports handling is done by ``devlink``. @@ -48,6 +48,7 @@ Once an error is reported, devlink health will perform the following actions: * Object dump is being taken and saved at the reporter instance (as long as there is no other dump which is already stored) * Auto recovery attempt is being done. Depends on: + - Auto-recovery configuration - Grace period vs. time passed since last recover @@ -72,14 +73,18 @@ via ``devlink``, e.g per error type (per health reporter): * - ``DEVLINK_CMD_HEALTH_REPORTER_SET`` - Allows reporter-related configuration setting. * - ``DEVLINK_CMD_HEALTH_REPORTER_RECOVER`` - - Triggers a reporter's recovery procedure. + - Triggers reporter's recovery procedure. + * - ``DEVLINK_CMD_HEALTH_REPORTER_TEST`` + - Triggers a fake health event on the reporter. The effects of the test + event in terms of recovery flow should follow closely that of a real + event. * - ``DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE`` - - Retrieves diagnostics data from a reporter on a device. + - Retrieves current device state related to the reporter. * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_GET`` - Retrieves the last stored dump. Devlink health - saves a single dump. If an dump is not already stored by the devlink + saves a single dump. If an dump is not already stored by devlink for this reporter, devlink generates a new dump. - dump output is defined by the reporter. + Dump output is defined by the reporter. * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_CLEAR`` - Clears the last saved dump file for the specified reporter. @@ -93,7 +98,7 @@ The following diagram provides a general overview of ``devlink-health``:: +--------------------------+ |request for ops |(diagnose, - mlx5_core devlink |recover, + driver devlink |recover, |dump) +--------+ +--------------------------+ | | | reporter| | diff --git a/Documentation/networking/dsa/configuration.rst b/Documentation/networking/dsa/configuration.rst index 11bd5e6108c0..774f0e76c746 100644 --- a/Documentation/networking/dsa/configuration.rst +++ b/Documentation/networking/dsa/configuration.rst @@ -34,8 +34,15 @@ interface. The CPU port is the switch port connected to an Ethernet MAC chip. The corresponding linux Ethernet interface is called the master interface. All other corresponding linux interfaces are called slave interfaces. -The slave interfaces depend on the master interface. They can only brought up, -when the master interface is up. +The slave interfaces depend on the master interface being up in order for them +to send or receive traffic. Prior to kernel v5.12, the state of the master +interface had to be managed explicitly by the user. Starting with kernel v5.12, +the behavior is as follows: + +- when a DSA slave interface is brought up, the master interface is + automatically brought up. +- when the master interface is brought down, all DSA slave interfaces are + automatically brought down. In this documentation the following Ethernet interfaces are used: @@ -78,79 +85,76 @@ The tagging based configuration is desired and supported by the majority of DSA switches. These switches are capable to tag incoming and outgoing traffic without using a VLAN based configuration. -single port -~~~~~~~~~~~ - -.. code-block:: sh - - # configure each interface - ip addr add 192.0.2.1/30 dev lan1 - ip addr add 192.0.2.5/30 dev lan2 - ip addr add 192.0.2.9/30 dev lan3 - - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up +*single port* + .. code-block:: sh - # bring up the slave interfaces - ip link set lan1 up - ip link set lan2 up - ip link set lan3 up + # configure each interface + ip addr add 192.0.2.1/30 dev lan1 + ip addr add 192.0.2.5/30 dev lan2 + ip addr add 192.0.2.9/30 dev lan3 -bridge -~~~~~~ + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up -.. code-block:: sh + # bring up the slave interfaces + ip link set lan1 up + ip link set lan2 up + ip link set lan3 up - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up +*bridge* + .. code-block:: sh - # bring up the slave interfaces - ip link set lan1 up - ip link set lan2 up - ip link set lan3 up + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up - # create bridge - ip link add name br0 type bridge + # bring up the slave interfaces + ip link set lan1 up + ip link set lan2 up + ip link set lan3 up - # add ports to bridge - ip link set dev lan1 master br0 - ip link set dev lan2 master br0 - ip link set dev lan3 master br0 + # create bridge + ip link add name br0 type bridge - # configure the bridge - ip addr add 192.0.2.129/25 dev br0 + # add ports to bridge + ip link set dev lan1 master br0 + ip link set dev lan2 master br0 + ip link set dev lan3 master br0 - # bring up the bridge - ip link set dev br0 up + # configure the bridge + ip addr add 192.0.2.129/25 dev br0 -gateway -~~~~~~~ + # bring up the bridge + ip link set dev br0 up -.. code-block:: sh +*gateway* + .. code-block:: sh - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up - # bring up the slave interfaces - ip link set wan up - ip link set lan1 up - ip link set lan2 up + # bring up the slave interfaces + ip link set wan up + ip link set lan1 up + ip link set lan2 up - # configure the upstream port - ip addr add 192.0.2.1/30 dev wan + # configure the upstream port + ip addr add 192.0.2.1/30 dev wan - # create bridge - ip link add name br0 type bridge + # create bridge + ip link add name br0 type bridge - # add ports to bridge - ip link set dev lan1 master br0 - ip link set dev lan2 master br0 + # add ports to bridge + ip link set dev lan1 master br0 + ip link set dev lan2 master br0 - # configure the bridge - ip addr add 192.0.2.129/25 dev br0 + # configure the bridge + ip addr add 192.0.2.129/25 dev br0 - # bring up the bridge - ip link set dev br0 up + # bring up the bridge + ip link set dev br0 up .. _dsa-vlan-configuration: @@ -161,132 +165,130 @@ A minority of switches are not capable to use a taging protocol (DSA_TAG_PROTO_NONE). These switches can be configured by a VLAN based configuration. -single port -~~~~~~~~~~~ -The configuration can only be set up via VLAN tagging and bridge setup. - -.. code-block:: sh - - # tag traffic on CPU port - ip link add link eth0 name eth0.1 type vlan id 1 - ip link add link eth0 name eth0.2 type vlan id 2 - ip link add link eth0 name eth0.3 type vlan id 3 - - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up - ip link set eth0.1 up - ip link set eth0.2 up - ip link set eth0.3 up - - # bring up the slave interfaces - ip link set lan1 up - ip link set lan2 up - ip link set lan3 up - - # create bridge - ip link add name br0 type bridge - - # activate VLAN filtering - ip link set dev br0 type bridge vlan_filtering 1 - - # add ports to bridges - ip link set dev lan1 master br0 - ip link set dev lan2 master br0 - ip link set dev lan3 master br0 - - # tag traffic on ports - bridge vlan add dev lan1 vid 1 pvid untagged - bridge vlan add dev lan2 vid 2 pvid untagged - bridge vlan add dev lan3 vid 3 pvid untagged - - # configure the VLANs - ip addr add 192.0.2.1/30 dev eth0.1 - ip addr add 192.0.2.5/30 dev eth0.2 - ip addr add 192.0.2.9/30 dev eth0.3 - - # bring up the bridge devices - ip link set br0 up - +*single port* + The configuration can only be set up via VLAN tagging and bridge setup. -bridge -~~~~~~ + .. code-block:: sh -.. code-block:: sh + # tag traffic on CPU port + ip link add link eth0 name eth0.1 type vlan id 1 + ip link add link eth0 name eth0.2 type vlan id 2 + ip link add link eth0 name eth0.3 type vlan id 3 - # tag traffic on CPU port - ip link add link eth0 name eth0.1 type vlan id 1 + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up + ip link set eth0.1 up + ip link set eth0.2 up + ip link set eth0.3 up - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up - ip link set eth0.1 up + # bring up the slave interfaces + ip link set lan1 up + ip link set lan2 up + ip link set lan3 up - # bring up the slave interfaces - ip link set lan1 up - ip link set lan2 up - ip link set lan3 up + # create bridge + ip link add name br0 type bridge - # create bridge - ip link add name br0 type bridge + # activate VLAN filtering + ip link set dev br0 type bridge vlan_filtering 1 - # activate VLAN filtering - ip link set dev br0 type bridge vlan_filtering 1 + # add ports to bridges + ip link set dev lan1 master br0 + ip link set dev lan2 master br0 + ip link set dev lan3 master br0 - # add ports to bridge - ip link set dev lan1 master br0 - ip link set dev lan2 master br0 - ip link set dev lan3 master br0 - ip link set eth0.1 master br0 + # tag traffic on ports + bridge vlan add dev lan1 vid 1 pvid untagged + bridge vlan add dev lan2 vid 2 pvid untagged + bridge vlan add dev lan3 vid 3 pvid untagged - # tag traffic on ports - bridge vlan add dev lan1 vid 1 pvid untagged - bridge vlan add dev lan2 vid 1 pvid untagged - bridge vlan add dev lan3 vid 1 pvid untagged + # configure the VLANs + ip addr add 192.0.2.1/30 dev eth0.1 + ip addr add 192.0.2.5/30 dev eth0.2 + ip addr add 192.0.2.9/30 dev eth0.3 - # configure the bridge - ip addr add 192.0.2.129/25 dev br0 + # bring up the bridge devices + ip link set br0 up - # bring up the bridge - ip link set dev br0 up -gateway -~~~~~~~ +*bridge* + .. code-block:: sh -.. code-block:: sh + # tag traffic on CPU port + ip link add link eth0 name eth0.1 type vlan id 1 - # tag traffic on CPU port - ip link add link eth0 name eth0.1 type vlan id 1 - ip link add link eth0 name eth0.2 type vlan id 2 + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up + ip link set eth0.1 up - # The master interface needs to be brought up before the slave ports. - ip link set eth0 up - ip link set eth0.1 up - ip link set eth0.2 up + # bring up the slave interfaces + ip link set lan1 up + ip link set lan2 up + ip link set lan3 up - # bring up the slave interfaces - ip link set wan up - ip link set lan1 up - ip link set lan2 up + # create bridge + ip link add name br0 type bridge - # create bridge - ip link add name br0 type bridge + # activate VLAN filtering + ip link set dev br0 type bridge vlan_filtering 1 - # activate VLAN filtering - ip link set dev br0 type bridge vlan_filtering 1 + # add ports to bridge + ip link set dev lan1 master br0 + ip link set dev lan2 master br0 + ip link set dev lan3 master br0 + ip link set eth0.1 master br0 - # add ports to bridges - ip link set dev wan master br0 - ip link set eth0.1 master br0 - ip link set dev lan1 master br0 - ip link set dev lan2 master br0 + # tag traffic on ports + bridge vlan add dev lan1 vid 1 pvid untagged + bridge vlan add dev lan2 vid 1 pvid untagged + bridge vlan add dev lan3 vid 1 pvid untagged - # tag traffic on ports - bridge vlan add dev lan1 vid 1 pvid untagged - bridge vlan add dev lan2 vid 1 pvid untagged - bridge vlan add dev wan vid 2 pvid untagged + # configure the bridge + ip addr add 192.0.2.129/25 dev br0 - # configure the VLANs - ip addr add 192.0.2.1/30 dev eth0.2 - ip addr add 192.0.2.129/25 dev br0 + # bring up the bridge + ip link set dev br0 up - # bring up the bridge devices - ip link set br0 up +*gateway* + .. code-block:: sh + + # tag traffic on CPU port + ip link add link eth0 name eth0.1 type vlan id 1 + ip link add link eth0 name eth0.2 type vlan id 2 + + # For kernels earlier than v5.12, the master interface needs to be + # brought up manually before the slave ports. + ip link set eth0 up + ip link set eth0.1 up + ip link set eth0.2 up + + # bring up the slave interfaces + ip link set wan up + ip link set lan1 up + ip link set lan2 up + + # create bridge + ip link add name br0 type bridge + + # activate VLAN filtering + ip link set dev br0 type bridge vlan_filtering 1 + + # add ports to bridges + ip link set dev wan master br0 + ip link set eth0.1 master br0 + ip link set dev lan1 master br0 + ip link set dev lan2 master br0 + + # tag traffic on ports + bridge vlan add dev lan1 vid 1 pvid untagged + bridge vlan add dev lan2 vid 1 pvid untagged + bridge vlan add dev wan vid 2 pvid untagged + + # configure the VLANs + ip addr add 192.0.2.1/30 dev eth0.2 + ip addr add 192.0.2.129/25 dev br0 + + # bring up the bridge devices + ip link set br0 up diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index e9517af5fe02..8688009514cc 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -65,14 +65,8 @@ Note that DSA does not currently create network interfaces for the "cpu" and Switch tagging protocols ------------------------ -DSA currently supports 5 different tagging protocols, and a tag-less mode as -well. The different protocols are implemented in: - -- ``net/dsa/tag_trailer.c``: Marvell's 4 trailer tag mode (legacy) -- ``net/dsa/tag_dsa.c``: Marvell's original DSA tag -- ``net/dsa/tag_edsa.c``: Marvell's enhanced DSA tag -- ``net/dsa/tag_brcm.c``: Broadcom's 4 bytes tag -- ``net/dsa/tag_qca.c``: Qualcomm's 2 bytes tag +DSA supports many vendor-specific tagging protocols, one software-defined +tagging protocol, and a tag-less mode as well (``DSA_TAG_PROTO_NONE``). The exact format of the tag protocol is vendor specific, but in general, they all contain something which: @@ -80,6 +74,144 @@ all contain something which: - identifies which port the Ethernet frame came from/should be sent to - provides a reason why this frame was forwarded to the management interface +All tagging protocols are in ``net/dsa/tag_*.c`` files and implement the +methods of the ``struct dsa_device_ops`` structure, which are detailed below. + +Tagging protocols generally fall in one of three categories: + +1. The switch-specific frame header is located before the Ethernet header, + shifting to the right (from the perspective of the DSA master's frame + parser) the MAC DA, MAC SA, EtherType and the entire L2 payload. +2. The switch-specific frame header is located before the EtherType, keeping + the MAC DA and MAC SA in place from the DSA master's perspective, but + shifting the 'real' EtherType and L2 payload to the right. +3. The switch-specific frame header is located at the tail of the packet, + keeping all frame headers in place and not altering the view of the packet + that the DSA master's frame parser has. + +A tagging protocol may tag all packets with switch tags of the same length, or +the tag length might vary (for example packets with PTP timestamps might +require an extended switch tag, or there might be one tag length on TX and a +different one on RX). Either way, the tagging protocol driver must populate the +``struct dsa_device_ops::overhead`` with the length in octets of the longest +switch frame header. The DSA framework will automatically adjust the MTU of the +master interface to accomodate for this extra size in order for DSA user ports +to support the standard MTU (L2 payload length) of 1500 octets. The ``overhead`` +is also used to request from the network stack, on a best-effort basis, the +allocation of packets with a ``needed_headroom`` or ``needed_tailroom`` +sufficient such that the act of pushing the switch tag on transmission of a +packet does not cause it to reallocate due to lack of memory. + +Even though applications are not expected to parse DSA-specific frame headers, +the format on the wire of the tagging protocol represents an Application Binary +Interface exposed by the kernel towards user space, for decoders such as +``libpcap``. The tagging protocol driver must populate the ``proto`` member of +``struct dsa_device_ops`` with a value that uniquely describes the +characteristics of the interaction required between the switch hardware and the +data path driver: the offset of each bit field within the frame header and any +stateful processing required to deal with the frames (as may be required for +PTP timestamping). + +From the perspective of the network stack, all switches within the same DSA +switch tree use the same tagging protocol. In case of a packet transiting a +fabric with more than one switch, the switch-specific frame header is inserted +by the first switch in the fabric that the packet was received on. This header +typically contains information regarding its type (whether it is a control +frame that must be trapped to the CPU, or a data frame to be forwarded). +Control frames should be decapsulated only by the software data path, whereas +data frames might also be autonomously forwarded towards other user ports of +other switches from the same fabric, and in this case, the outermost switch +ports must decapsulate the packet. + +Note that in certain cases, it might be the case that the tagging format used +by a leaf switch (not connected directly to the CPU) to not be the same as what +the network stack sees. This can be seen with Marvell switch trees, where the +CPU port can be configured to use either the DSA or the Ethertype DSA (EDSA) +format, but the DSA links are configured to use the shorter (without Ethertype) +DSA frame header, in order to reduce the autonomous packet forwarding overhead. +It still remains the case that, if the DSA switch tree is configured for the +EDSA tagging protocol, the operating system sees EDSA-tagged packets from the +leaf switches that tagged them with the shorter DSA header. This can be done +because the Marvell switch connected directly to the CPU is configured to +perform tag translation between DSA and EDSA (which is simply the operation of +adding or removing the ``ETH_P_EDSA`` EtherType and some padding octets). + +It is possible to construct cascaded setups of DSA switches even if their +tagging protocols are not compatible with one another. In this case, there are +no DSA links in this fabric, and each switch constitutes a disjoint DSA switch +tree. The DSA links are viewed as simply a pair of a DSA master (the out-facing +port of the upstream DSA switch) and a CPU port (the in-facing port of the +downstream DSA switch). + +The tagging protocol of the attached DSA switch tree can be viewed through the +``dsa/tagging`` sysfs attribute of the DSA master:: + + cat /sys/class/net/eth0/dsa/tagging + +If the hardware and driver are capable, the tagging protocol of the DSA switch +tree can be changed at runtime. This is done by writing the new tagging +protocol name to the same sysfs device attribute as above (the DSA master and +all attached switch ports must be down while doing this). + +It is desirable that all tagging protocols are testable with the ``dsa_loop`` +mockup driver, which can be attached to any network interface. The goal is that +any network interface should be capable of transmitting the same packet in the +same way, and the tagger should decode the same received packet in the same way +regardless of the driver used for the switch control path, and the driver used +for the DSA master. + +The transmission of a packet goes through the tagger's ``xmit`` function. +The passed ``struct sk_buff *skb`` has ``skb->data`` pointing at +``skb_mac_header(skb)``, i.e. at the destination MAC address, and the passed +``struct net_device *dev`` represents the virtual DSA user network interface +whose hardware counterpart the packet must be steered to (i.e. ``swp0``). +The job of this method is to prepare the skb in a way that the switch will +understand what egress port the packet is for (and not deliver it towards other +ports). Typically this is fulfilled by pushing a frame header. Checking for +insufficient size in the skb headroom or tailroom is unnecessary provided that +the ``overhead`` and ``tail_tag`` properties were filled out properly, because +DSA ensures there is enough space before calling this method. + +The reception of a packet goes through the tagger's ``rcv`` function. The +passed ``struct sk_buff *skb`` has ``skb->data`` pointing at +``skb_mac_header(skb) + ETH_ALEN`` octets, i.e. to where the first octet after +the EtherType would have been, were this frame not tagged. The role of this +method is to consume the frame header, adjust ``skb->data`` to really point at +the first octet after the EtherType, and to change ``skb->dev`` to point to the +virtual DSA user network interface corresponding to the physical front-facing +switch port that the packet was received on. + +Since tagging protocols in category 1 and 2 break software (and most often also +hardware) packet dissection on the DSA master, features such as RPS (Receive +Packet Steering) on the DSA master would be broken. The DSA framework deals +with this by hooking into the flow dissector and shifting the offset at which +the IP header is to be found in the tagged frame as seen by the DSA master. +This behavior is automatic based on the ``overhead`` value of the tagging +protocol. If not all packets are of equal size, the tagger can implement the +``flow_dissect`` method of the ``struct dsa_device_ops`` and override this +default behavior by specifying the correct offset incurred by each individual +RX packet. Tail taggers do not cause issues to the flow dissector. + +Due to various reasons (most common being category 1 taggers being associated +with DSA-unaware masters, mangling what the master perceives as MAC DA), the +tagging protocol may require the DSA master to operate in promiscuous mode, to +receive all frames regardless of the value of the MAC DA. This can be done by +setting the ``promisc_on_master`` property of the ``struct dsa_device_ops``. +Note that this assumes a DSA-unaware master driver, which is the norm. + +Hardware manufacturers are strongly discouraged to do this, but some tagging +protocols might not provide source port information on RX for all packets, but +e.g. only for control traffic (link-local PDUs). In this case, by implementing +the ``filter`` method of ``struct dsa_device_ops``, the tagger might select +which packets are to be redirected on RX towards the virtual DSA user network +interfaces, and which are to be left in the DSA master's RX data path. + +It might also happen (although silicon vendors are strongly discouraged to +produce hardware like this) that a tagging protocol splits the switch-specific +information into a header portion and a tail portion, therefore not falling +cleanly into any of the above 3 categories. DSA does not support this +configuration. + Master network devices ---------------------- @@ -172,23 +304,34 @@ Graphical representation Summarized, this is basically how DSA looks like from a network device perspective:: - - |--------------------------- - | CPU network device (eth0)| - ---------------------------- - | <tag added by switch | - | | - | | - | tag added by CPU> | - |--------------------------------------------| - | Switch driver | - |--------------------------------------------| - || || || - |-------| |-------| |-------| - | sw0p0 | | sw0p1 | | sw0p2 | - |-------| |-------| |-------| - - + Unaware application + opens and binds socket + | ^ + | | + +-----------v--|--------------------+ + |+------+ +------+ +------+ +------+| + || swp0 | | swp1 | | swp2 | | swp3 || + |+------+-+------+-+------+-+------+| + | DSA switch driver | + +-----------------------------------+ + | ^ + Tag added by | | Tag consumed by + switch driver | | switch driver + v | + +-----------------------------------+ + | Unmodified host interface driver | Software + --------+-----------------------------------+------------ + | Host interface (eth0) | Hardware + +-----------------------------------+ + | ^ + Tag consumed by | | Tag added by + switch hardware | | switch hardware + v | + +-----------------------------------+ + | Switch | + |+------+ +------+ +------+ +------+| + || swp0 | | swp1 | | swp2 | | swp3 || + ++------+-+------+-+------+-+------++ Slave MDIO bus -------------- @@ -239,14 +382,6 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as Design limitations ================== -Limits on the number of devices and ports ------------------------------------------ - -DSA currently limits the number of maximum switches within a tree to 4 -(``DSA_MAX_SWITCHES``), and the number of ports per switch to 12 (``DSA_MAX_PORTS``). -These limits could be extended to support larger configurations would this need -arise. - Lack of CPU/DSA network devices ------------------------------- @@ -281,6 +416,7 @@ DSA currently leverages the following subsystems: - MDIO/PHY library: ``drivers/net/phy/phy.c``, ``mdio_bus.c`` - Switchdev:``net/switchdev/*`` - Device Tree for various of_* functions +- Devlink: ``net/core/devlink.c`` MDIO/PHY library ---------------- @@ -317,14 +453,39 @@ SWITCHDEV DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and more specifically with its VLAN filtering portion when configuring VLANs on top -of per-port slave network devices. Since DSA primarily deals with -MDIO-connected switches, although not exclusively, SWITCHDEV's -prepare/abort/commit phases are often simplified into a prepare phase which -checks whether the operation is supported by the DSA switch driver, and a commit -phase which applies the changes. - -As of today, the only SWITCHDEV objects supported by DSA are the FDB and VLAN -objects. +of per-port slave network devices. As of today, the only SWITCHDEV objects +supported by DSA are the FDB and VLAN objects. + +Devlink +------- + +DSA registers one devlink device per physical switch in the fabric. +For each devlink device, every physical port (i.e. user ports, CPU ports, DSA +links or unused ports) is exposed as a devlink port. + +DSA drivers can make use of the following devlink features: + +- Regions: debugging feature which allows user space to dump driver-defined + areas of hardware information in a low-level, binary format. Both global + regions as well as per-port regions are supported. It is possible to export + devlink regions even for pieces of data that are already exposed in some way + to the standard iproute2 user space programs (ip-link, bridge), like address + tables and VLAN tables. For example, this might be useful if the tables + contain additional hardware-specific details which are not visible through + the iproute2 abstraction, or it might be useful to inspect these tables on + the non-user ports too, which are invisible to iproute2 because no network + interface is registered for them. +- Params: a feature which enables user to configure certain low-level tunable + knobs pertaining to the device. Drivers may implement applicable generic + devlink params, or may add new device-specific devlink params. +- Resources: a monitoring feature which enables users to see the degree of + utilization of certain hardware tables in the device, such as FDB, VLAN, etc. +- Shared buffers: a QoS feature for adjusting and partitioning memory and frame + reservations per port and per traffic class, in the ingress and egress + directions, such that low-priority bulk traffic does not impede the + processing of high-priority critical traffic. + +For more details, consult ``Documentation/networking/devlink/``. Device Tree ----------- @@ -490,6 +651,17 @@ Bridge layer computing a STP state change based on current and asked parameters and perform the relevant ageing based on the intersection results +- ``port_bridge_flags``: bridge layer function invoked when a port must + configure its settings for e.g. flooding of unknown traffic or source address + learning. The switch driver is responsible for initial setup of the + standalone ports with address learning disabled and egress flooding of all + types of traffic, then the DSA core notifies of any change to the bridge port + flags when the port joins and leaves a bridge. DSA does not currently manage + the bridge port flags for the CPU port. The assumption is that address + learning should be statically enabled (if supported by the hardware) on the + CPU port, and flooding towards the CPU port should also be enabled, due to a + lack of an explicit address filtering mechanism in the DSA core. + Bridge VLAN filtering --------------------- @@ -503,14 +675,10 @@ Bridge VLAN filtering accept any 802.1Q frames irrespective of their VLAN ID, and untagged frames are allowed. -- ``port_vlan_prepare``: bridge layer function invoked when the bridge prepares the - configuration of a VLAN on the given port. If the operation is not supported - by the hardware, this function should return ``-EOPNOTSUPP`` to inform the bridge - code to fallback to a software implementation. No hardware setup must be done - in this function. See port_vlan_add for this and details. - - ``port_vlan_add``: bridge layer function invoked when a VLAN is configured - (tagged or untagged) for the given switch port + (tagged or untagged) for the given switch port. If the operation is not + supported by the hardware, this function should return ``-EOPNOTSUPP`` to + inform the bridge code to fallback to a software implementation. - ``port_vlan_del``: bridge layer function invoked when a VLAN is removed from the given switch port @@ -538,14 +706,10 @@ Bridge VLAN filtering function that the driver has to call for each MAC address known to be behind the given port. A switchdev object is used to carry the VID and FDB info. -- ``port_mdb_prepare``: bridge layer function invoked when the bridge prepares the - installation of a multicast database entry. If the operation is not supported, - this function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback - to a software implementation. No hardware setup must be done in this function. - See ``port_fdb_add`` for this and details. - - ``port_mdb_add``: bridge layer function invoked when the bridge wants to install - a multicast database entry, the switch hardware should be programmed with the + a multicast database entry. If the operation is not supported, this function + should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to a + software implementation. The switch hardware should be programmed with the specified address in the specified VLAN ID in the forwarding database associated with this VLAN ID. @@ -561,6 +725,101 @@ Bridge VLAN filtering function that the driver has to call for each MAC address known to be behind the given port. A switchdev object is used to carry the VID and MDB info. +Link aggregation +---------------- + +Link aggregation is implemented in the Linux networking stack by the bonding +and team drivers, which are modeled as virtual, stackable network interfaces. +DSA is capable of offloading a link aggregation group (LAG) to hardware that +supports the feature, and supports bridging between physical ports and LAGs, +as well as between LAGs. A bonding/team interface which holds multiple physical +ports constitutes a logical port, although DSA has no explicit concept of a +logical port at the moment. Due to this, events where a LAG joins/leaves a +bridge are treated as if all individual physical ports that are members of that +LAG join/leave the bridge. Switchdev port attributes (VLAN filtering, STP +state, etc) and objects (VLANs, MDB entries) offloaded to a LAG as bridge port +are treated similarly: DSA offloads the same switchdev object / port attribute +on all members of the LAG. Static bridge FDB entries on a LAG are not yet +supported, since the DSA driver API does not have the concept of a logical port +ID. + +- ``port_lag_join``: function invoked when a given switch port is added to a + LAG. The driver may return ``-EOPNOTSUPP``, and in this case, DSA will fall + back to a software implementation where all traffic from this port is sent to + the CPU. +- ``port_lag_leave``: function invoked when a given switch port leaves a LAG + and returns to operation as a standalone port. +- ``port_lag_change``: function invoked when the link state of any member of + the LAG changes, and the hashing function needs rebalancing to only make use + of the subset of physical LAG member ports that are up. + +Drivers that benefit from having an ID associated with each offloaded LAG +can optionally populate ``ds->num_lag_ids`` from the ``dsa_switch_ops::setup`` +method. The LAG ID associated with a bonding/team interface can then be +retrieved by a DSA switch driver using the ``dsa_lag_id`` function. + +IEC 62439-2 (MRP) +----------------- + +The Media Redundancy Protocol is a topology management protocol optimized for +fast fault recovery time for ring networks, which has some components +implemented as a function of the bridge driver. MRP uses management PDUs +(Test, Topology, LinkDown/Up, Option) sent at a multicast destination MAC +address range of 01:15:4e:00:00:0x and with an EtherType of 0x88e3. +Depending on the node's role in the ring (MRM: Media Redundancy Manager, +MRC: Media Redundancy Client, MRA: Media Redundancy Automanager), certain MRP +PDUs might need to be terminated locally and others might need to be forwarded. +An MRM might also benefit from offloading to hardware the creation and +transmission of certain MRP PDUs (Test). + +Normally an MRP instance can be created on top of any network interface, +however in the case of a device with an offloaded data path such as DSA, it is +necessary for the hardware, even if it is not MRP-aware, to be able to extract +the MRP PDUs from the fabric before the driver can proceed with the software +implementation. DSA today has no driver which is MRP-aware, therefore it only +listens for the bare minimum switchdev objects required for the software assist +to work properly. The operations are detailed below. + +- ``port_mrp_add`` and ``port_mrp_del``: notifies driver when an MRP instance + with a certain ring ID, priority, primary port and secondary port is + created/deleted. +- ``port_mrp_add_ring_role`` and ``port_mrp_del_ring_role``: function invoked + when an MRP instance changes ring roles between MRM or MRC. This affects + which MRP PDUs should be trapped to software and which should be autonomously + forwarded. + +IEC 62439-3 (HSR/PRP) +--------------------- + +The Parallel Redundancy Protocol (PRP) is a network redundancy protocol which +works by duplicating and sequence numbering packets through two independent L2 +networks (which are unaware of the PRP tail tags carried in the packets), and +eliminating the duplicates at the receiver. The High-availability Seamless +Redundancy (HSR) protocol is similar in concept, except all nodes that carry +the redundant traffic are aware of the fact that it is HSR-tagged (because HSR +uses a header with an EtherType of 0x892f) and are physically connected in a +ring topology. Both HSR and PRP use supervision frames for monitoring the +health of the network and for discovery of other nodes. + +In Linux, both HSR and PRP are implemented in the hsr driver, which +instantiates a virtual, stackable network interface with two member ports. +The driver only implements the basic roles of DANH (Doubly Attached Node +implementing HSR) and DANP (Doubly Attached Node implementing PRP); the roles +of RedBox and QuadBox are not implemented (therefore, bridging a hsr network +interface with a physical switch port does not produce the expected result). + +A driver which is able of offloading certain functions of a DANP or DANH should +declare the corresponding netdev features as indicated by the documentation at +``Documentation/networking/netdev-features.rst``. Additionally, the following +methods must be implemented: + +- ``port_hsr_join``: function invoked when a given switch port is added to a + DANP/DANH. The driver may return ``-EOPNOTSUPP`` and in this case, DSA will + fall back to a software implementation where all traffic from this port is + sent to the CPU. +- ``port_hsr_leave``: function invoked when a given switch port leaves a + DANP/DANH and returns to normal operation as a standalone port. + TODO ==== @@ -576,8 +835,5 @@ two subsystems and get the best of both worlds. Other hanging fruits -------------------- -- making the number of ports fully dynamic and not dependent on ``DSA_MAX_PORTS`` - allowing more than one CPU/management interface: http://comments.gmane.org/gmane.linux.network/365657 -- porting more drivers from other vendors: - http://comments.gmane.org/gmane.linux.network/365510 diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index dc03ff884541..25131df3c2bd 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -208,41 +208,49 @@ Userspace to kernel: ``ETHTOOL_MSG_CABLE_TEST_ACT`` action start cable test ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` action start raw TDR cable test ``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info + ``ETHTOOL_MSG_FEC_GET`` get FEC settings + ``ETHTOOL_MSG_FEC_SET`` set FEC settings + ``ETHTOOL_MSG_MODULE_EEPROM_GET`` read SFP module EEPROM + ``ETHTOOL_MSG_STATS_GET`` get standard statistics ===================================== ================================ Kernel to userspace: - ===================================== ================================= - ``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents - ``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings - ``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification - ``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info - ``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification - ``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info - ``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings - ``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification - ``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings - ``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification - ``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features - ``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET - ``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification - ``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags - ``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags - ``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes - ``ETHTOOL_MSG_RINGS_NTF`` ring sizes - ``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts - ``ETHTOOL_MSG_CHANNELS_NTF`` channel counts - ``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters - ``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters - ``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters - ``ETHTOOL_MSG_PAUSE_NTF`` pause parameters - ``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings - ``ETHTOOL_MSG_EEE_NTF`` EEE settings - ``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info - ``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results - ``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results - ``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info - ===================================== ================================= + ======================================== ================================= + ``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents + ``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings + ``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification + ``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info + ``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification + ``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info + ``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings + ``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification + ``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings + ``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification + ``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features + ``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET + ``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification + ``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags + ``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags + ``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes + ``ETHTOOL_MSG_RINGS_NTF`` ring sizes + ``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts + ``ETHTOOL_MSG_CHANNELS_NTF`` channel counts + ``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters + ``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters + ``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters + ``ETHTOOL_MSG_PAUSE_NTF`` pause parameters + ``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings + ``ETHTOOL_MSG_EEE_NTF`` EEE settings + ``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info + ``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results + ``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results + ``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info + ``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings + ``ETHTOOL_MSG_FEC_NTF`` FEC settings + ``ETHTOOL_MSG_MODULE_EEPROM_GET_REPLY`` read SFP module EEPROM + ``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics + ======================================== ================================= ``GET`` requests are sent by userspace applications to retrieve device information. They usually do not contain any message specific attributes. @@ -1280,6 +1288,193 @@ Kernel response contents: For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that the table contains static entries, hard-coded by the NIC. +FEC_GET +======= + +Gets FEC configuration and state like ``ETHTOOL_GFECPARAM`` ioctl request. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_FEC_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_FEC_HEADER`` nested request header + ``ETHTOOL_A_FEC_MODES`` bitset configured modes + ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection + ``ETHTOOL_A_FEC_ACTIVE`` u32 index of active FEC mode + ``ETHTOOL_A_FEC_STATS`` nested FEC statistics + ===================================== ====== ========================== + +``ETHTOOL_A_FEC_ACTIVE`` is the bit index of the FEC link mode currently +active on the interface. This attribute may not be present if device does +not support FEC. + +``ETHTOOL_A_FEC_MODES`` and ``ETHTOOL_A_FEC_AUTO`` are only meaningful when +autonegotiation is disabled. If ``ETHTOOL_A_FEC_AUTO`` is non-zero driver will +select the FEC mode automatically based on the parameters of the SFP module. +This is equivalent to the ``ETHTOOL_FEC_AUTO`` bit of the ioctl interface. +``ETHTOOL_A_FEC_MODES`` carry the current FEC configuration using link mode +bits (rather than old ``ETHTOOL_FEC_*`` bits). + +``ETHTOOL_A_FEC_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in +``ETHTOOL_A_HEADER_FLAGS``. +Each attribute carries an array of 64bit statistics. First entry in the array +contains the total number of events on the port, while the following entries +are counters corresponding to lanes/PCS instances. The number of entries in +the array will be: + ++--------------+---------------------------------------------+ +| `0` | device does not support FEC statistics | ++--------------+---------------------------------------------+ +| `1` | device does not support per-lane break down | ++--------------+---------------------------------------------+ +| `1 + #lanes` | device has full support for FEC stats | ++--------------+---------------------------------------------+ + +Drivers fill in the statistics in the following structure: + +.. kernel-doc:: include/linux/ethtool.h + :identifiers: ethtool_fec_stats + +FEC_SET +======= + +Sets FEC parameters like ``ETHTOOL_SFECPARAM`` ioctl request. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_FEC_HEADER`` nested request header + ``ETHTOOL_A_FEC_MODES`` bitset configured modes + ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection + ===================================== ====== ========================== + +``FEC_SET`` is only meaningful when autonegotiation is disabled. Otherwise +FEC mode is selected as part of autonegotiation. + +``ETHTOOL_A_FEC_MODES`` selects which FEC mode should be used. It's recommended +to set only one bit, if multiple bits are set driver may choose between them +in an implementation specific way. + +``ETHTOOL_A_FEC_AUTO`` requests the driver to choose FEC mode based on SFP +module parameters. This does not mean autonegotiation. + +MODULE_EEPROM +============= + +Fetch module EEPROM data dump. +This interface is designed to allow dumps of at most 1/2 page at once. This +means only dumps of 128 (or less) bytes are allowed, without crossing half page +boundary located at offset 128. For pages other than 0 only high 128 bytes are +accessible. + +Request contents: + + ======================================= ====== ========================== + ``ETHTOOL_A_MODULE_EEPROM_HEADER`` nested request header + ``ETHTOOL_A_MODULE_EEPROM_OFFSET`` u32 offset within a page + ``ETHTOOL_A_MODULE_EEPROM_LENGTH`` u32 amount of bytes to read + ``ETHTOOL_A_MODULE_EEPROM_PAGE`` u8 page number + ``ETHTOOL_A_MODULE_EEPROM_BANK`` u8 bank number + ``ETHTOOL_A_MODULE_EEPROM_I2C_ADDRESS`` u8 page I2C address + ======================================= ====== ========================== + +Kernel response contents: + + +---------------------------------------------+--------+---------------------+ + | ``ETHTOOL_A_MODULE_EEPROM_HEADER`` | nested | reply header | + +---------------------------------------------+--------+---------------------+ + | ``ETHTOOL_A_MODULE_EEPROM_DATA`` | nested | array of bytes from | + | | | module EEPROM | + +---------------------------------------------+--------+---------------------+ + +``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of +bytes driver actually read. + +STATS_GET +========= + +Get standard statistics for the interface. Note that this is not +a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined +stats. + +Request contents: + + ======================================= ====== ========================== + ``ETHTOOL_A_STATS_HEADER`` nested request header + ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats + ======================================= ====== ========================== + +Kernel response contents: + + +-----------------------------------+--------+--------------------------------+ + | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header | + +-----------------------------------+--------+--------------------------------+ + | ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats | + +-+---------------------------------+--------+--------------------------------+ + | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` | + +-+---------------------------------+--------+--------------------------------+ + | | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names | + +-+---------------------------------+--------+--------------------------------+ + | | ``ETHTOOL_A_STATS_GRP_STAT`` | nested | nest containing a statistic | + +-+---------------------------------+--------+--------------------------------+ + | | ``ETHTOOL_A_STATS_GRP_HIST_RX`` | nested | histogram statistic (Rx) | + +-+---------------------------------+--------+--------------------------------+ + | | ``ETHTOOL_A_STATS_GRP_HIST_TX`` | nested | histogram statistic (Tx) | + +-+---------------------------------+--------+--------------------------------+ + +Users specify which groups of statistics they are requesting via +the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are: + + ====================== ======== =============================================== + ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*) + ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*) + ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*) + ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics + ====================== ======== =============================================== + +Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply. +``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains. +``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of +the statistics in the group, if available. + +Statistics are added to the ``ETHTOOL_A_STATS_GRP`` nest under +``ETHTOOL_A_STATS_GRP_STAT``. ``ETHTOOL_A_STATS_GRP_STAT`` should contain +single 8 byte (u64) attribute inside - the type of that attribute is +the statistic ID and the value is the value of the statistic. +Each group has its own interpretation of statistic IDs. +Attribute IDs correspond to strings from the string set identified +by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics (such as RMON histogram +entries) are also listed inside ``ETHTOOL_A_STATS_GRP`` and do not have +a string defined in the string set. + +RMON "histogram" counters count number of packets within given size range. +Because RFC does not specify the ranges beyond the standard 1518 MTU devices +differ in definition of buckets. For this reason the definition of packet ranges +is left to each driver. + +``ETHTOOL_A_STATS_GRP_HIST_RX`` and ``ETHTOOL_A_STATS_GRP_HIST_TX`` nests +contain the following attributes: + + ================================= ====== =================================== + ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket + ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket + ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter + ================================= ====== =================================== + +Low and high bounds are inclusive, for example: + + ============================= ==== ==== + RFC statistic low high + ============================= ==== ==== + etherStatsPkts64Octets 0 64 + etherStatsPkts512to1023Octets 512 1023 + ============================= ==== ==== + Request translation =================== @@ -1357,8 +1552,8 @@ are netlink only. ``ETHTOOL_GET_DUMP_FLAG`` n/a ``ETHTOOL_GET_DUMP_DATA`` n/a ``ETHTOOL_GET_TS_INFO`` ``ETHTOOL_MSG_TSINFO_GET`` - ``ETHTOOL_GMODULEINFO`` n/a - ``ETHTOOL_GMODULEEEPROM`` n/a + ``ETHTOOL_GMODULEINFO`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` + ``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` ``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET`` ``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET`` ``ETHTOOL_GRSSH`` n/a @@ -1373,9 +1568,9 @@ are netlink only. ``ETHTOOL_MSG_LINKMODES_SET`` ``ETHTOOL_PHY_GTUNABLE`` n/a ``ETHTOOL_PHY_STUNABLE`` n/a - ``ETHTOOL_GFECPARAM`` n/a - ``ETHTOOL_SFECPARAM`` n/a - n/a ''ETHTOOL_MSG_CABLE_TEST_ACT'' - n/a ''ETHTOOL_MSG_CABLE_TEST_TDR_ACT'' + ``ETHTOOL_GFECPARAM`` ``ETHTOOL_MSG_FEC_GET`` + ``ETHTOOL_SFECPARAM`` ``ETHTOOL_MSG_FEC_SET`` + n/a ``ETHTOOL_MSG_CABLE_TEST_ACT`` + n/a ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` n/a ``ETHTOOL_MSG_TUNNEL_INFO_GET`` =================================== ===================================== diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index 251c6bd73d15..3e2221f4abe4 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -327,7 +327,7 @@ Examples for low-level BPF: ret #-1 drop: ret #0 -**icmp random packet sampling, 1 in 4**: +**icmp random packet sampling, 1 in 4**:: ldh [12] jne #0x800, drop diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index b8a29997d433..e9ce55992aa9 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -76,6 +76,7 @@ Contents: netdevices netfilter-sysctl netif-msg + nexthop-group-resilient nf_conntrack-sysctl nf_flowtable openvswitch diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 3feb5e565b1a..c2ecc9894fd0 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1073,7 +1073,9 @@ ip_local_reserved_ports - list of comma separated ranges although this is redundant. However such a setting is useful if later the port range is changed to a value that will - include the reserved ports. + include the reserved ports. Also keep in mind, that overlapping + of these ranges may affect probability of selecting ephemeral + ports which are right after block of reserved ports. Default: Empty @@ -1143,6 +1145,12 @@ icmp_echo_ignore_all - BOOLEAN Default: 0 +icmp_echo_enable_probe - BOOLEAN + If set to one, then the kernel will respond to RFC 8335 PROBE + requests sent to it. + + Default: 0 + icmp_echo_ignore_broadcasts - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO and TIMESTAMP requests sent to it via broadcast/multicast. diff --git a/Documentation/networking/nexthop-group-resilient.rst b/Documentation/networking/nexthop-group-resilient.rst new file mode 100644 index 000000000000..fabecee24d85 --- /dev/null +++ b/Documentation/networking/nexthop-group-resilient.rst @@ -0,0 +1,293 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Resilient Next-hop Groups +========================= + +Resilient groups are a type of next-hop group that is aimed at minimizing +disruption in flow routing across changes to the group composition and +weights of constituent next hops. + +The idea behind resilient hashing groups is best explained in contrast to +the legacy multipath next-hop group, which uses the hash-threshold +algorithm, described in RFC 2992. + +To select a next hop, hash-threshold algorithm first assigns a range of +hashes to each next hop in the group, and then selects the next hop by +comparing the SKB hash with the individual ranges. When a next hop is +removed from the group, the ranges are recomputed, which leads to +reassignment of parts of hash space from one next hop to another. RFC 2992 +illustrates it thus:: + + +-------+-------+-------+-------+-------+ + | 1 | 2 | 3 | 4 | 5 | + +-------+-+-----+---+---+-----+-+-------+ + | 1 | 2 | 4 | 5 | + +---------+---------+---------+---------+ + + Before and after deletion of next hop 3 + under the hash-threshold algorithm. + +Note how next hop 2 gave up part of the hash space in favor of next hop 1, +and 4 in favor of 5. While there will usually be some overlap between the +previous and the new distribution, some traffic flows change the next hop +that they resolve to. + +If a multipath group is used for load-balancing between multiple servers, +this hash space reassignment causes an issue that packets from a single +flow suddenly end up arriving at a server that does not expect them. This +can result in TCP connections being reset. + +If a multipath group is used for load-balancing among available paths to +the same server, the issue is that different latencies and reordering along +the way causes the packets to arrive in the wrong order, resulting in +degraded application performance. + +To mitigate the above-mentioned flow redirection, resilient next-hop groups +insert another layer of indirection between the hash space and its +constituent next hops: a hash table. The selection algorithm uses SKB hash +to choose a hash table bucket, then reads the next hop that this bucket +contains, and forwards traffic there. + +This indirection brings an important feature. In the hash-threshold +algorithm, the range of hashes associated with a next hop must be +continuous. With a hash table, mapping between the hash table buckets and +the individual next hops is arbitrary. Therefore when a next hop is deleted +the buckets that held it are simply reassigned to other next hops:: + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |1|1|1|1|2|2|2|2|3|3|3|3|4|4|4|4|5|5|5|5| + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + v v v v + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |1|1|1|1|2|2|2|2|1|2|4|5|4|4|4|4|5|5|5|5| + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Before and after deletion of next hop 3 + under the resilient hashing algorithm. + +When weights of next hops in a group are altered, it may be possible to +choose a subset of buckets that are currently not used for forwarding +traffic, and use those to satisfy the new next-hop distribution demands, +keeping the "busy" buckets intact. This way, established flows are ideally +kept being forwarded to the same endpoints through the same paths as before +the next-hop group change. + +Algorithm +--------- + +In a nutshell, the algorithm works as follows. Each next hop deserves a +certain number of buckets, according to its weight and the number of +buckets in the hash table. In accordance with the source code, we will call +this number a "wants count" of a next hop. In case of an event that might +cause bucket allocation change, the wants counts for individual next hops +are updated. + +Next hops that have fewer buckets than their wants count, are called +"underweight". Those that have more are "overweight". If there are no +overweight (and therefore no underweight) next hops in the group, it is +said to be "balanced". + +Each bucket maintains a last-used timer. Every time a packet is forwarded +through a bucket, this timer is updated to current jiffies value. One +attribute of a resilient group is then the "idle timer", which is the +amount of time that a bucket must not be hit by traffic in order for it to +be considered "idle". Buckets that are not idle are busy. + +After assigning wants counts to next hops, an "upkeep" algorithm runs. For +buckets: + +1) that have no assigned next hop, or +2) whose next hop has been removed, or +3) that are idle and their next hop is overweight, + +upkeep changes the next hop that the bucket references to one of the +underweight next hops. If, after considering all buckets in this manner, +there are still underweight next hops, another upkeep run is scheduled to a +future time. + +There may not be enough "idle" buckets to satisfy the updated wants counts +of all next hops. Another attribute of a resilient group is the "unbalanced +timer". This timer can be set to 0, in which case the table will stay out +of balance until idle buckets do appear, possibly never. If set to a +non-zero value, the value represents the period of time that the table is +permitted to stay out of balance. + +With this in mind, we update the above list of conditions with one more +item. Thus buckets: + +4) whose next hop is overweight, and the amount of time that the table has + been out of balance exceeds the unbalanced timer, if that is non-zero, + +\... are migrated as well. + +Offloading & Driver Feedback +---------------------------- + +When offloading resilient groups, the algorithm that distributes buckets +among next hops is still the one in SW. Drivers are notified of updates to +next hop groups in the following three ways: + +- Full group notification with the type + ``NH_NOTIFIER_INFO_TYPE_RES_TABLE``. This is used just after the group is + created and buckets populated for the first time. + +- Single-bucket notifications of the type + ``NH_NOTIFIER_INFO_TYPE_RES_BUCKET``, which is used for notifications of + individual migrations within an already-established group. + +- Pre-replace notification, ``NEXTHOP_EVENT_RES_TABLE_PRE_REPLACE``. This + is sent before the group is replaced, and is a way for the driver to veto + the group before committing anything to the HW. + +Some single-bucket notifications are forced, as indicated by the "force" +flag in the notification. Those are used for the cases where e.g. the next +hop associated with the bucket was removed, and the bucket really must be +migrated. + +Non-forced notifications can be overridden by the driver by returning an +error code. The use case for this is that the driver notifies the HW that a +bucket should be migrated, but the HW discovers that the bucket has in fact +been hit by traffic. + +A second way for the HW to report that a bucket is busy is through the +``nexthop_res_grp_activity_update()`` API. The buckets identified this way +as busy are treated as if traffic hit them. + +Offloaded buckets should be flagged as either "offload" or "trap". This is +done through the ``nexthop_bucket_set_hw_flags()`` API. + +Netlink UAPI +------------ + +Resilient Group Replacement +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Resilient groups are configured using the ``RTM_NEWNEXTHOP`` message in the +same manner as other multipath groups. The following changes apply to the +attributes passed in the netlink message: + + =================== ========================================================= + ``NHA_GROUP_TYPE`` Should be ``NEXTHOP_GRP_TYPE_RES`` for resilient group. + ``NHA_RES_GROUP`` A nest that contains attributes specific to resilient + groups. + =================== ========================================================= + +``NHA_RES_GROUP`` payload: + + =================================== ========================================= + ``NHA_RES_GROUP_BUCKETS`` Number of buckets in the hash table. + ``NHA_RES_GROUP_IDLE_TIMER`` Idle timer in units of clock_t. + ``NHA_RES_GROUP_UNBALANCED_TIMER`` Unbalanced timer in units of clock_t. + =================================== ========================================= + +Next Hop Get +^^^^^^^^^^^^ + +Requests to get resilient next-hop groups use the ``RTM_GETNEXTHOP`` +message in exactly the same way as other next hop get requests. The +response attributes match the replacement attributes cited above, except +``NHA_RES_GROUP`` payload will include the following attribute: + + =================================== ========================================= + ``NHA_RES_GROUP_UNBALANCED_TIME`` How long has the resilient group been out + of balance, in units of clock_t. + =================================== ========================================= + +Bucket Get +^^^^^^^^^^ + +The message ``RTM_GETNEXTHOPBUCKET`` without the ``NLM_F_DUMP`` flag is +used to request a single bucket. The attributes recognized at get requests +are: + + =================== ========================================================= + ``NHA_ID`` ID of the next-hop group that the bucket belongs to. + ``NHA_RES_BUCKET`` A nest that contains attributes specific to bucket. + =================== ========================================================= + +``NHA_RES_BUCKET`` payload: + + ======================== ==================================================== + ``NHA_RES_BUCKET_INDEX`` Index of bucket in the resilient table. + ======================== ==================================================== + +Bucket Dumps +^^^^^^^^^^^^ + +The message ``RTM_GETNEXTHOPBUCKET`` with the ``NLM_F_DUMP`` flag is used +to request a dump of matching buckets. The attributes recognized at dump +requests are: + + =================== ========================================================= + ``NHA_ID`` If specified, limits the dump to just the next-hop group + with this ID. + ``NHA_OIF`` If specified, limits the dump to buckets that contain + next hops that use the device with this ifindex. + ``NHA_MASTER`` If specified, limits the dump to buckets that contain + next hops that use a device in the VRF with this ifindex. + ``NHA_RES_BUCKET`` A nest that contains attributes specific to bucket. + =================== ========================================================= + +``NHA_RES_BUCKET`` payload: + + ======================== ==================================================== + ``NHA_RES_BUCKET_NH_ID`` If specified, limits the dump to just the buckets + that contain the next hop with this ID. + ======================== ==================================================== + +Usage +----- + +To illustrate the usage, consider the following commands:: + + # ip nexthop add id 1 via 192.0.2.2 dev eth0 + # ip nexthop add id 2 via 192.0.2.3 dev eth0 + # ip nexthop add id 10 group 1/2 type resilient \ + buckets 8 idle_timer 60 unbalanced_timer 300 + +The last command creates a resilient next-hop group. It will have 8 buckets +(which is unusually low number, and used here for demonstration purposes +only), each bucket will be considered idle when no traffic hits it for at +least 60 seconds, and if the table remains out of balance for 300 seconds, +it will be forcefully brought into balance. + +Changing next-hop weights leads to change in bucket allocation:: + + # ip nexthop replace id 10 group 1,3/2 type resilient + +This can be confirmed by looking at individual buckets:: + + # ip nexthop bucket show id 10 + id 10 index 0 idle_time 5.59 nhid 1 + id 10 index 1 idle_time 5.59 nhid 1 + id 10 index 2 idle_time 8.74 nhid 2 + id 10 index 3 idle_time 8.74 nhid 2 + id 10 index 4 idle_time 8.74 nhid 1 + id 10 index 5 idle_time 8.74 nhid 1 + id 10 index 6 idle_time 8.74 nhid 1 + id 10 index 7 idle_time 8.74 nhid 1 + +Note the two buckets that have a shorter idle time. Those are the ones that +were migrated after the next-hop replace command to satisfy the new demand +that next hop 1 be given 6 buckets instead of 4. + +Netdevsim +--------- + +The netdevsim driver implements a mock offload of resilient groups, and +exposes debugfs interface that allows marking individual buckets as busy. +For example, the following will mark bucket 23 in next-hop group 10 as +active:: + + # echo 10 23 > /sys/kernel/debug/netdevsim/netdevsim10/fib/nexthop_bucket_activity + +In addition, another debugfs interface can be used to configure that the +next attempt to migrate a bucket should fail:: + + # echo 1 > /sys/kernel/debug/netdevsim/netdevsim10/fib/fail_nexthop_bucket_replace + +Besides serving as an example, the interfaces that netdevsim exposes are +useful in automated testing, and +``tools/testing/selftests/drivers/net/netdevsim/nexthop.sh`` makes use of +them to test the algorithm. diff --git a/Documentation/networking/nf_flowtable.rst b/Documentation/networking/nf_flowtable.rst index 6cdf9a1724b6..d757c21c10f2 100644 --- a/Documentation/networking/nf_flowtable.rst +++ b/Documentation/networking/nf_flowtable.rst @@ -4,35 +4,38 @@ Netfilter's flowtable infrastructure ==================================== -This documentation describes the software flowtable infrastructure available in -Netfilter since Linux kernel 4.16. +This documentation describes the Netfilter flowtable infrastructure which allows +you to define a fastpath through the flowtable datapath. This infrastructure +also provides hardware offload support. The flowtable supports for the layer 3 +IPv4 and IPv6 and the layer 4 TCP and UDP protocols. Overview -------- -Initial packets follow the classic forwarding path, once the flow enters the -established state according to the conntrack semantics (ie. we have seen traffic -in both directions), then you can decide to offload the flow to the flowtable -from the forward chain via the 'flow offload' action available in nftables. +Once the first packet of the flow successfully goes through the IP forwarding +path, from the second packet on, you might decide to offload the flow to the +flowtable through your ruleset. The flowtable infrastructure provides a rule +action that allows you to specify when to add a flow to the flowtable. -Packets that find an entry in the flowtable (ie. flowtable hit) are sent to the -output netdevice via neigh_xmit(), hence, they bypass the classic forwarding -path (the visible effect is that you do not see these packets from any of the -netfilter hooks coming after the ingress). In case of flowtable miss, the packet -follows the classic forward path. +A packet that finds a matching entry in the flowtable (ie. flowtable hit) is +transmitted to the output netdevice via neigh_xmit(), hence, packets bypass the +classic IP forwarding path (the visible effect is that you do not see these +packets from any of the Netfilter hooks coming after ingress). In case that +there is no matching entry in the flowtable (ie. flowtable miss), the packet +follows the classic IP forwarding path. -The flowtable uses a resizable hashtable, lookups are based on the following -7-tuple selectors: source, destination, layer 3 and layer 4 protocols, source -and destination ports and the input interface (useful in case there are several -conntrack zones in place). +The flowtable uses a resizable hashtable. Lookups are based on the following +n-tuple selectors: layer 2 protocol encapsulation (VLAN and PPPoE), layer 3 +source and destination, layer 4 source and destination ports and the input +interface (useful in case there are several conntrack zones in place). -Flowtables are populated via the 'flow offload' nftables action, so the user can -selectively specify what flows are placed into the flow table. Hence, packets -follow the classic forwarding path unless the user explicitly instruct packets -to use this new alternative forwarding path via nftables policy. +The 'flow add' action allows you to populate the flowtable, the user selectively +specifies what flows are placed into the flowtable. Hence, packets follow the +classic IP forwarding path unless the user explicitly instruct flows to use this +new alternative forwarding path via policy. -This is represented in Fig.1, which describes the classic forwarding path -including the Netfilter hooks and the flowtable fastpath bypass. +The flowtable datapath is represented in Fig.1, which describes the classic IP +forwarding path including the Netfilter hooks and the flowtable fastpath bypass. :: @@ -67,11 +70,13 @@ including the Netfilter hooks and the flowtable fastpath bypass. Fig.1 Netfilter hooks and flowtable interactions The flowtable entry also stores the NAT configuration, so all packets are -mangled according to the NAT policy that matches the initial packets that went -through the classic forwarding path. The TTL is decremented before calling -neigh_xmit(). Fragmented traffic is passed up to follow the classic forwarding -path given that the transport selectors are missing, therefore flowtable lookup -is not possible. +mangled according to the NAT policy that is specified from the classic IP +forwarding path. The TTL is decremented before calling neigh_xmit(). Fragmented +traffic is passed up to follow the classic IP forwarding path given that the +transport header is missing, in this case, flowtable lookups are not possible. +TCP RST and FIN packets are also passed up to the classic IP forwarding path to +release the flow gracefully. Packets that exceed the MTU are also passed up to +the classic forwarding path to report packet-too-big ICMP errors to the sender. Example configuration --------------------- @@ -85,7 +90,7 @@ flowtable and add one rule to your forward chain:: } chain y { type filter hook forward priority 0; policy accept; - ip protocol tcp flow offload @f + ip protocol tcp flow add @f counter packets 0 bytes 0 } } @@ -103,6 +108,119 @@ flow is offloaded, you will observe that the counter rule in the example above does not get updated for the packets that are being forwarded through the forwarding bypass. +You can identify offloaded flows through the [OFFLOAD] tag when listing your +connection tracking table. + +:: + + # conntrack -L + tcp 6 src=10.141.10.2 dst=192.168.10.2 sport=52728 dport=5201 src=192.168.10.2 dst=192.168.10.1 sport=5201 dport=52728 [OFFLOAD] mark=0 use=2 + + +Layer 2 encapsulation +--------------------- + +Since Linux kernel 5.13, the flowtable infrastructure discovers the real +netdevice behind VLAN and PPPoE netdevices. The flowtable software datapath +parses the VLAN and PPPoE layer 2 headers to extract the ethertype and the +VLAN ID / PPPoE session ID which are used for the flowtable lookups. The +flowtable datapath also deals with layer 2 decapsulation. + +You do not need to add the PPPoE and the VLAN devices to your flowtable, +instead the real device is sufficient for the flowtable to track your flows. + +Bridge and IP forwarding +------------------------ + +Since Linux kernel 5.13, you can add bridge ports to the flowtable. The +flowtable infrastructure discovers the topology behind the bridge device. This +allows the flowtable to define a fastpath bypass between the bridge ports +(represented as eth1 and eth2 in the example figure below) and the gateway +device (represented as eth0) in your switch/router. + +:: + + fastpath bypass + .-------------------------. + / \ + | IP forwarding | + | / \ \/ + | br0 eth0 ..... eth0 + . / \ *host B* + -> eth1 eth2 + . *switch/router* + . + . + eth0 + *host A* + +The flowtable infrastructure also supports for bridge VLAN filtering actions +such as PVID and untagged. You can also stack a classic VLAN device on top of +your bridge port. + +If you would like that your flowtable defines a fastpath between your bridge +ports and your IP forwarding path, you have to add your bridge ports (as +represented by the real netdevice) to your flowtable definition. + +Counters +-------- + +The flowtable can synchronize packet and byte counters with the existing +connection tracking entry by specifying the counter statement in your flowtable +definition, e.g. + +:: + + table inet x { + flowtable f { + hook ingress priority 0; devices = { eth0, eth1 }; + counter + } + } + +Counter support is available since Linux kernel 5.7. + +Hardware offload +---------------- + +If your network device provides hardware offload support, you can turn it on by +means of the 'offload' flag in your flowtable definition, e.g. + +:: + + table inet x { + flowtable f { + hook ingress priority 0; devices = { eth0, eth1 }; + flags offload; + } + } + +There is a workqueue that adds the flows to the hardware. Note that a few +packets might still run over the flowtable software path until the workqueue has +a chance to offload the flow to the network device. + +You can identify hardware offloaded flows through the [HW_OFFLOAD] tag when +listing your connection tracking table. Please, note that the [OFFLOAD] tag +refers to the software offload mode, so there is a distinction between [OFFLOAD] +which refers to the software flowtable fastpath and [HW_OFFLOAD] which refers +to the hardware offload datapath being used by the flow. + +The flowtable hardware offload infrastructure also supports for the DSA +(Distributed Switch Architecture). + +Limitations +----------- + +The flowtable behaves like a cache. The flowtable entries might get stale if +either the destination MAC address or the egress netdevice that is used for +transmission changes. + +This might be a problem if: + +- You run the flowtable in software mode and you combine bridge and IP + forwarding in your setup. +- Hardware offload is enabled. + More reading ------------ diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index 06adfc2afcf0..3f05d50ecd6e 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -80,8 +80,8 @@ values of phy_interface_t must be understood from the perspective of the PHY device itself, leading to the following: * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any - internal delay by itself, it assumes that either the Ethernet MAC (if capable - or the PCB traces) insert the correct 1.5-2ns delay + internal delay by itself, it assumes that either the Ethernet MAC (if capable) + or the PCB traces insert the correct 1.5-2ns delay * PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay for the transmit data lines (TXD[3:0]) processed by the PHY device diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst index 234abedc29b2..c9aeb70dafa2 100644 --- a/Documentation/networking/statistics.rst +++ b/Documentation/networking/statistics.rst @@ -44,8 +44,27 @@ If `-s` is specified once the detailed errors won't be shown. Protocol-specific statistics ---------------------------- -Some of the interfaces used for configuring devices are also able -to report related statistics. For example ethtool interface used +Protocol-specific statistics are exposed via relevant interfaces, +the same interfaces as are used to configure them. + +ethtool +~~~~~~~ + +Ethtool exposes common low-level statistics. +All the standard statistics are expected to be maintained +by the device, not the driver (as opposed to driver-defined stats +described in the next section which mix software and hardware stats). +For devices which contain unmanaged +switches (e.g. legacy SR-IOV or multi-host NICs) the events counted +may not pertain exclusively to the packets destined to +the local host interface. In other words the events may +be counted at the network port (MAC/PHY blocks) without separation +for different host side (PCIe) devices. Such ambiguity must not +be present when internal switch is managed by Linux (so called +switchdev mode for NICs). + +Standard ethtool statistics can be accessed via the interfaces used +for configuration. For example ethtool interface used to configure pause frames can report corresponding hardware counters:: $ ethtool --include-statistics -a eth0 @@ -57,6 +76,27 @@ to configure pause frames can report corresponding hardware counters:: tx_pause_frames: 1 rx_pause_frames: 1 +General Ethernet statistics not associated with any particular +functionality are exposed via ``ethtool -S $ifc`` by specifying +the ``--groups`` parameter:: + + $ ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon + Stats for eth0: + eth-phy-SymbolErrorDuringCarrier: 0 + eth-mac-FramesTransmittedOK: 1 + eth-mac-FrameTooLongErrors: 1 + eth-ctrl-MACControlFramesTransmitted: 1 + eth-ctrl-MACControlFramesReceived: 0 + eth-ctrl-UnsupportedOpcodesReceived: 1 + rmon-etherStatsUndersizePkts: 1 + rmon-etherStatsJabbers: 0 + rmon-rx-etherStatsPkts64Octets: 1 + rmon-rx-etherStatsPkts65to127Octets: 0 + rmon-rx-etherStatsPkts128to255Octets: 0 + rmon-tx-etherStatsPkts64Octets: 2 + rmon-tx-etherStatsPkts65to127Octets: 3 + rmon-tx-etherStatsPkts128to255Octets: 0 + Driver-defined statistics ------------------------- @@ -130,6 +170,7 @@ the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently statistics are supported in the following commands: - `ETHTOOL_MSG_PAUSE_GET` + - `ETHTOOL_MSG_FEC_GET` debugfs ------- @@ -176,3 +217,4 @@ translated to netlink attributes when dumped. Drivers must not overwrite the statistics they don't report with 0. - ethtool_pause_stats() +- ethtool_fec_stats() diff --git a/Documentation/networking/switchdev.rst b/Documentation/networking/switchdev.rst index ddc3f35775dc..f1f4e6a85a29 100644 --- a/Documentation/networking/switchdev.rst +++ b/Documentation/networking/switchdev.rst @@ -181,18 +181,41 @@ To offloading L2 bridging, the switchdev driver/device should support: Static FDB Entries ^^^^^^^^^^^^^^^^^^ -The switchdev driver should implement ndo_fdb_add, ndo_fdb_del and ndo_fdb_dump -to support static FDB entries installed to the device. Static bridge FDB -entries are installed, for example, using iproute2 bridge cmd:: - - bridge fdb add ADDR dev DEV [vlan VID] [self] - -The driver should use the helper switchdev_port_fdb_xxx ops for ndo_fdb_xxx -ops, and handle add/delete/dump of SWITCHDEV_OBJ_ID_PORT_FDB object using -switchdev_port_obj_xxx ops. - -XXX: what should be done if offloading this rule to hardware fails (for -example, due to full capacity in hardware tables) ? +A driver which implements the ``ndo_fdb_add``, ``ndo_fdb_del`` and +``ndo_fdb_dump`` operations is able to support the command below, which adds a +static bridge FDB entry:: + + bridge fdb add dev DEV ADDRESS [vlan VID] [self] static + +(the "static" keyword is non-optional: if not specified, the entry defaults to +being "local", which means that it should not be forwarded) + +The "self" keyword (optional because it is implicit) has the role of +instructing the kernel to fulfill the operation through the ``ndo_fdb_add`` +implementation of the ``DEV`` device itself. If ``DEV`` is a bridge port, this +will bypass the bridge and therefore leave the software database out of sync +with the hardware one. + +To avoid this, the "master" keyword can be used:: + + bridge fdb add dev DEV ADDRESS [vlan VID] master static + +The above command instructs the kernel to search for a master interface of +``DEV`` and fulfill the operation through the ``ndo_fdb_add`` method of that. +This time, the bridge generates a ``SWITCHDEV_FDB_ADD_TO_DEVICE`` notification +which the port driver can handle and use it to program its hardware table. This +way, the software and the hardware database will both contain this static FDB +entry. + +Note: for new switchdev drivers that offload the Linux bridge, implementing the +``ndo_fdb_add`` and ``ndo_fdb_del`` bridge bypass methods is strongly +discouraged: all static FDB entries should be added on a bridge port using the +"master" flag. The ``ndo_fdb_dump`` is an exception and can be implemented to +visualize the hardware tables, if the device does not have an interrupt for +notifying the operating system of newly learned/forgotten dynamic FDB +addresses. In that case, the hardware FDB might end up having entries that the +software FDB does not, and implementing ``ndo_fdb_dump`` is the only way to see +them. Note: by default, the bridge does not filter on VLAN and only bridges untagged traffic. To enable VLAN support, turn on VLAN filtering:: @@ -385,3 +408,156 @@ The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port. + +Device driver expected behavior +------------------------------- + +Below is a set of defined behavior that switchdev enabled network devices must +adhere to. + +Configuration-less state +^^^^^^^^^^^^^^^^^^^^^^^^ + +Upon driver bring up, the network devices must be fully operational, and the +backing driver must configure the network device such that it is possible to +send and receive traffic to this network device and it is properly separated +from other network devices/ports (e.g.: as is frequent with a switch ASIC). How +this is achieved is heavily hardware dependent, but a simple solution can be to +use per-port VLAN identifiers unless a better mechanism is available +(proprietary metadata for each network port for instance). + +The network device must be capable of running a full IP protocol stack +including multicast, DHCP, IPv4/6, etc. If necessary, it should program the +appropriate filters for VLAN, multicast, unicast etc. The underlying device +driver must effectively be configured in a similar fashion to what it would do +when IGMP snooping is enabled for IP multicast over these switchdev network +devices and unsolicited multicast must be filtered as early as possible in +the hardware. + +When configuring VLANs on top of the network device, all VLANs must be working, +irrespective of the state of other network devices (e.g.: other ports being part +of a VLAN-aware bridge doing ingress VID checking). See below for details. + +If the device implements e.g.: VLAN filtering, putting the interface in +promiscuous mode should allow the reception of all VLAN tags (including those +not present in the filter(s)). + +Bridged switch ports +^^^^^^^^^^^^^^^^^^^^ + +When a switchdev enabled network device is added as a bridge member, it should +not disrupt any functionality of non-bridged network devices and they +should continue to behave as normal network devices. Depending on the bridge +configuration knobs below, the expected behavior is documented. + +Bridge VLAN filtering +^^^^^^^^^^^^^^^^^^^^^ + +The Linux bridge allows the configuration of a VLAN filtering mode (statically, +at device creation time, and dynamically, during run time) which must be +observed by the underlying switchdev network device/hardware: + +- with VLAN filtering turned off: the bridge is strictly VLAN unaware and its + data path will process all Ethernet frames as if they are VLAN-untagged. + The bridge VLAN database can still be modified, but the modifications should + have no effect while VLAN filtering is turned off. Frames ingressing the + device with a VID that is not programmed into the bridge/switch's VLAN table + must be forwarded and may be processed using a VLAN device (see below). + +- with VLAN filtering turned on: the bridge is VLAN-aware and frames ingressing + the device with a VID that is not programmed into the bridges/switch's VLAN + table must be dropped (strict VID checking). + +When there is a VLAN device (e.g: sw0p1.100) configured on top of a switchdev +network device which is a bridge port member, the behavior of the software +network stack must be preserved, or the configuration must be refused if that +is not possible. + +- with VLAN filtering turned off, the bridge will process all ingress traffic + for the port, except for the traffic tagged with a VLAN ID destined for a + VLAN upper. The VLAN upper interface (which consumes the VLAN tag) can even + be added to a second bridge, which includes other switch ports or software + interfaces. Some approaches to ensure that the forwarding domain for traffic + belonging to the VLAN upper interfaces are managed properly: + + * If forwarding destinations can be managed per VLAN, the hardware could be + configured to map all traffic, except the packets tagged with a VID + belonging to a VLAN upper interface, to an internal VID corresponding to + untagged packets. This internal VID spans all ports of the VLAN-unaware + bridge. The VID corresponding to the VLAN upper interface spans the + physical port of that VLAN interface, as well as the other ports that + might be bridged with it. + * Treat bridge ports with VLAN upper interfaces as standalone, and let + forwarding be handled in the software data path. + +- with VLAN filtering turned on, these VLAN devices can be created as long as + the bridge does not have an existing VLAN entry with the same VID on any + bridge port. These VLAN devices cannot be enslaved into the bridge since they + duplicate functionality/use case with the bridge's VLAN data path processing. + +Non-bridged network ports of the same switch fabric must not be disturbed in any +way by the enabling of VLAN filtering on the bridge device(s). If the VLAN +filtering setting is global to the entire chip, then the standalone ports +should indicate to the network stack that VLAN filtering is required by setting +'rx-vlan-filter: on [fixed]' in the ethtool features. + +Because VLAN filtering can be turned on/off at runtime, the switchdev driver +must be able to reconfigure the underlying hardware on the fly to honor the +toggling of that option and behave appropriately. If that is not possible, the +switchdev driver can also refuse to support dynamic toggling of the VLAN +filtering knob at runtime and require a destruction of the bridge device(s) and +creation of new bridge device(s) with a different VLAN filtering value to +ensure VLAN awareness is pushed down to the hardware. + +Even when VLAN filtering in the bridge is turned off, the underlying switch +hardware and driver may still configure itself in a VLAN-aware mode provided +that the behavior described above is observed. + +The VLAN protocol of the bridge plays a role in deciding whether a packet is +treated as tagged or not: a bridge using the 802.1ad protocol must treat both +VLAN-untagged packets, as well as packets tagged with 802.1Q headers, as +untagged. + +The 802.1p (VID 0) tagged packets must be treated in the same way by the device +as untagged packets, since the bridge device does not allow the manipulation of +VID 0 in its database. + +When the bridge has VLAN filtering enabled and a PVID is not configured on the +ingress port, untagged and 802.1p tagged packets must be dropped. When the bridge +has VLAN filtering enabled and a PVID exists on the ingress port, untagged and +priority-tagged packets must be accepted and forwarded according to the +bridge's port membership of the PVID VLAN. When the bridge has VLAN filtering +disabled, the presence/lack of a PVID should not influence the packet +forwarding decision. + +Bridge IGMP snooping +^^^^^^^^^^^^^^^^^^^^ + +The Linux bridge allows the configuration of IGMP snooping (statically, at +interface creation time, or dynamically, during runtime) which must be observed +by the underlying switchdev network device/hardware in the following way: + +- when IGMP snooping is turned off, multicast traffic must be flooded to all + ports within the same bridge that have mcast_flood=true. The CPU/management + port should ideally not be flooded (unless the ingress interface has + IFF_ALLMULTI or IFF_PROMISC) and continue to learn multicast traffic through + the network stack notifications. If the hardware is not capable of doing that + then the CPU/management port must also be flooded and multicast filtering + happens in software. + +- when IGMP snooping is turned on, multicast traffic must selectively flow + to the appropriate network ports (including CPU/management port). Flooding of + unknown multicast should be only towards the ports connected to a multicast + router (the local device may also act as a multicast router). + +The switch must adhere to RFC 4541 and flood multicast traffic accordingly +since that is what the Linux bridge implementation does. + +Because IGMP snooping can be turned on/off at runtime, the switchdev driver +must be able to reconfigure the underlying hardware on the fly to honor the +toggling of that option and behave appropriately. + +A switchdev driver can also refuse to support dynamic toggling of the multicast +snooping knob at runtime and require the destruction of the bridge device(s) +and creation of a new bridge device(s) with a different multicast snooping +value. diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index f682e88fa87e..7db3985359bc 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -630,30 +630,45 @@ hardware timestamping on it. This is because the SO_TIMESTAMPING API does not allow the delivery of multiple hardware timestamps for the same packet, so anybody else except for the DSA switch port must be prevented from doing so. -In code, DSA provides for most of the infrastructure for timestamping already, -in generic code: a BPF classifier (``ptp_classify_raw``) is used to identify -PTP event messages (any other packets, including PTP general messages, are not -timestamped), and provides two hooks to drivers: - -- ``.port_txtstamp()``: The driver is passed a clone of the timestampable skb - to be transmitted, before actually transmitting it. Typically, a switch will - have a PTP TX timestamp register (or sometimes a FIFO) where the timestamp - becomes available. There may be an IRQ that is raised upon this timestamp's - availability, or the driver might have to poll after invoking - ``dev_queue_xmit()`` towards the host interface. Either way, in the - ``.port_txtstamp()`` method, the driver only needs to save the clone for - later use (when the timestamp becomes available). Each skb is annotated with - a pointer to its clone, in ``DSA_SKB_CB(skb)->clone``, to ease the driver's - job of keeping track of which clone belongs to which skb. - -- ``.port_rxtstamp()``: The original (and only) timestampable skb is provided - to the driver, for it to annotate it with a timestamp, if that is immediately - available, or defer to later. On reception, timestamps might either be - available in-band (through metadata in the DSA header, or attached in other - ways to the packet), or out-of-band (through another RX timestamping FIFO). - Deferral on RX is typically necessary when retrieving the timestamp needs a - sleepable context. In that case, it is the responsibility of the DSA driver - to call ``netif_rx_ni()`` on the freshly timestamped skb. +In the generic layer, DSA provides the following infrastructure for PTP +timestamping: + +- ``.port_txtstamp()``: a hook called prior to the transmission of + packets with a hardware TX timestamping request from user space. + This is required for two-step timestamping, since the hardware + timestamp becomes available after the actual MAC transmission, so the + driver must be prepared to correlate the timestamp with the original + packet so that it can re-enqueue the packet back into the socket's + error queue. To save the packet for when the timestamp becomes + available, the driver can call ``skb_clone_sk`` , save the clone pointer + in skb->cb and enqueue a tx skb queue. Typically, a switch will have a + PTP TX timestamp register (or sometimes a FIFO) where the timestamp + becomes available. In case of a FIFO, the hardware might store + key-value pairs of PTP sequence ID/message type/domain number and the + actual timestamp. To perform the correlation correctly between the + packets in a queue waiting for timestamping and the actual timestamps, + drivers can use a BPF classifier (``ptp_classify_raw``) to identify + the PTP transport type, and ``ptp_parse_header`` to interpret the PTP + header fields. There may be an IRQ that is raised upon this + timestamp's availability, or the driver might have to poll after + invoking ``dev_queue_xmit()`` towards the host interface. + One-step TX timestamping do not require packet cloning, since there is + no follow-up message required by the PTP protocol (because the + TX timestamp is embedded into the packet by the MAC), and therefore + user space does not expect the packet annotated with the TX timestamp + to be re-enqueued into its socket's error queue. + +- ``.port_rxtstamp()``: On RX, the BPF classifier is run by DSA to + identify PTP event messages (any other packets, including PTP general + messages, are not timestamped). The original (and only) timestampable + skb is provided to the driver, for it to annotate it with a timestamp, + if that is immediately available, or defer to later. On reception, + timestamps might either be available in-band (through metadata in the + DSA header, or attached in other ways to the packet), or out-of-band + (through another RX timestamping FIFO). Deferral on RX is typically + necessary when retrieving the timestamp needs a sleepable context. In + that case, it is the responsibility of the DSA driver to call + ``netif_rx_ni()`` on the freshly timestamped skb. 3.2.2 Ethernet PHYs ^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/networking/x25-iface.rst b/Documentation/networking/x25-iface.rst index df401891dce6..f34e9ec64937 100644 --- a/Documentation/networking/x25-iface.rst +++ b/Documentation/networking/x25-iface.rst @@ -70,60 +70,13 @@ First Byte = 0x03 (X25_IFACE_PARAMS) LAPB parameters. To be defined. +Requirements for the device driver +---------------------------------- -Possible Problems -================= - -(Henner Eisen, 2000-10-28) - -The X.25 packet layer protocol depends on a reliable datalink service. -The LAPB protocol provides such reliable service. But this reliability -is not preserved by the Linux network device driver interface: - -- With Linux 2.4.x (and above) SMP kernels, packet ordering is not - preserved. Even if a device driver calls netif_rx(skb1) and later - netif_rx(skb2), skb2 might be delivered to the network layer - earlier that skb1. -- Data passed upstream by means of netif_rx() might be dropped by the - kernel if the backlog queue is congested. - -The X.25 packet layer protocol will detect this and reset the virtual -call in question. But many upper layer protocols are not designed to -handle such N-Reset events gracefully. And frequent N-Reset events -will always degrade performance. - -Thus, driver authors should make netif_rx() as reliable as possible: - -SMP re-ordering will not occur if the driver's interrupt handler is -always executed on the same CPU. Thus, - -- Driver authors should use irq affinity for the interrupt handler. - -The probability of packet loss due to backlog congestion can be -reduced by the following measures or a combination thereof: - -(1) Drivers for kernel versions 2.4.x and above should always check the - return value of netif_rx(). If it returns NET_RX_DROP, the - driver's LAPB protocol must not confirm reception of the frame - to the peer. - This will reliably suppress packet loss. The LAPB protocol will - automatically cause the peer to re-transmit the dropped packet - later. - The lapb module interface was modified to support this. Its - data_indication() method should now transparently pass the - netif_rx() return value to the (lapb module) caller. -(2) Drivers for kernel versions 2.2.x should always check the global - variable netdev_dropping when a new frame is received. The driver - should only call netif_rx() if netdev_dropping is zero. Otherwise - the driver should not confirm delivery of the frame and drop it. - Alternatively, the driver can queue the frame internally and call - netif_rx() later when netif_dropping is 0 again. In that case, delivery - confirmation should also be deferred such that the internal queue - cannot grow to much. - This will not reliably avoid packet loss, but the probability - of packet loss in netif_rx() path will be significantly reduced. -(3) Additionally, driver authors might consider to support - CONFIG_NET_HW_FLOWCONTROL. This allows the driver to be woken up - when a previously congested backlog queue becomes empty again. - The driver could uses this for flow-controlling the peer by means - of the LAPB protocol's flow-control service. +Packets should not be reordered or dropped when delivering between the +Packet Layer and the device driver. + +To avoid packets from being reordered or dropped when delivering from +the device driver to the Packet Layer, the device driver should not +call "netif_rx" to deliver the received packets. Instead, it should +call "netif_receive_skb_core" from softirq context to deliver them. diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst index 7b8c42f8b1de..c04fabee0a58 100644 --- a/Documentation/power/power_supply_class.rst +++ b/Documentation/power/power_supply_class.rst @@ -233,7 +233,7 @@ Devicetree battery characteristics ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Drivers should call power_supply_get_battery_info() to obtain battery characteristics from a devicetree battery node, defined in -Documentation/devicetree/bindings/power/supply/battery.txt. This is +Documentation/devicetree/bindings/power/supply/battery.yaml. This is implemented in drivers/power/supply/bq27xxx_battery.c. Properties in struct power_supply_battery_info and their counterparts in the diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index d9c777b18f7a..18ae21bf7f92 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -339,6 +339,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: checked additionally, and -EACCES means that 'power.disable_depth' is different from 0 + `int pm_runtime_resume_and_get(struct device *dev);` + - run pm_runtime_resume(dev) and if successful, increment the device's + usage counter; return the result of pm_runtime_resume + `int pm_request_idle(struct device *dev);` - submit a request to execute the subsystem-level idle callback for the device (the request is represented by a work item in pm_wq); returns 0 on diff --git a/Documentation/powerpc/booting.rst b/Documentation/powerpc/booting.rst index 2d0ec2ff2b57..11aa440f98cc 100644 --- a/Documentation/powerpc/booting.rst +++ b/Documentation/powerpc/booting.rst @@ -94,7 +94,7 @@ should: a) add your platform support as a _boolean_ option in arch/powerpc/Kconfig, following the example of PPC_PSERIES, - PPC_PMAC and PPC_MAPLE. The later is probably a good + PPC_PMAC and PPC_MAPLE. The latter is probably a good example of a board support to start from. b) create your main platform file as diff --git a/Documentation/powerpc/dawr-power9.rst b/Documentation/powerpc/dawr-power9.rst index c96ab6befd9c..e55ac6a24b97 100644 --- a/Documentation/powerpc/dawr-power9.rst +++ b/Documentation/powerpc/dawr-power9.rst @@ -4,7 +4,7 @@ DAWR issues on POWER9 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop if it points to cache inhibited (CI) memory. Currently Linux has no way to -disinguish CI memory when configuring the DAWR, so (for now) the DAWR is +distinguish CI memory when configuring the DAWR, so (for now) the DAWR is disabled by this commit:: commit 9654153158d3e0684a1bdb76dbababdb7111d5a0 diff --git a/Documentation/powerpc/eeh-pci-error-recovery.rst b/Documentation/powerpc/eeh-pci-error-recovery.rst index 438a87ebc095..d6643a91bdf8 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/powerpc/eeh-pci-error-recovery.rst @@ -73,7 +73,7 @@ return all-ff's (0xff, 0xffff, 0xffffffff for 8/16/32-bit reads). This value was chosen because it is the same value you would get if the device was physically unplugged from the slot. This includes access to PCI memory, I/O space, and PCI config -space. Interrupts; however, will continued to be delivered. +space. Interrupts; however, will continue to be delivered. Detection and recovery are performed with the aid of ppc64 firmware. The programming interfaces in the Linux kernel diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/powerpc/elfnote.rst index 06602248621c..3ec8d61e9a33 100644 --- a/Documentation/powerpc/elfnote.rst +++ b/Documentation/powerpc/elfnote.rst @@ -8,7 +8,7 @@ capabilities and information which can be used by a bootloader or userland. Types and Descriptors --------------------- -The types to be used with the "PowerPC" namesapce are defined in [#f1]_. +The types to be used with the "PowerPC" namespace are defined in [#f1]_. 1) PPC_ELFNOTE_CAPABILITIES diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst index 20ea8cdee0aa..e363fc48529a 100644 --- a/Documentation/powerpc/firmware-assisted-dump.rst +++ b/Documentation/powerpc/firmware-assisted-dump.rst @@ -171,7 +171,7 @@ that were present in CMA region:: (meta area) | | | - Metadata: This area holds a metadata struture whose + Metadata: This area holds a metadata structure whose address is registered with f/w and retrieved in the second kernel after crash, on platforms that support tags (OPAL). Having such structure with info needed @@ -207,7 +207,7 @@ Currently the dump will be copied from /proc/vmcore to a new file upon user intervention. The dump data available through /proc/vmcore will be in ELF format. Hence the existing kdump infrastructure (kdump scripts) to save the dump works fine with minor modifications. KDump scripts on -major Distro releases have already been modified to work seemlessly (no +major Distro releases have already been modified to work seamlessly (no user intervention in saving the dump) when FADump is used, instead of KDump, as dump mechanism. diff --git a/Documentation/powerpc/kaslr-booke32.rst b/Documentation/powerpc/kaslr-booke32.rst index 8b259fdfdf03..5681c1d1b65b 100644 --- a/Documentation/powerpc/kaslr-booke32.rst +++ b/Documentation/powerpc/kaslr-booke32.rst @@ -38,5 +38,5 @@ bit of the entropy to decide the index of the 64M zone. Then we chose a kernstart_virt_addr -To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enable and you +To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enabled and you want to disable it at runtime, add "nokaslr" to the kernel cmdline. diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/powerpc/mpc52xx.rst index 30260707c3fe..5243b1763fad 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/powerpc/mpc52xx.rst @@ -34,7 +34,7 @@ To compile/use : Some remarks: - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100 - is not supported, and I'm not sure anyone is interesting in working on it + is not supported, and I'm not sure anyone is interested in working on it so. I didn't took 5xxx because there's apparently a lot of 5xxx that have nothing to do with the MPC5200. I also included the 'MPC' for the same reason. diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst index 48fcf1255a33..fce8bc793660 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/powerpc/papr_hcalls.rst @@ -40,7 +40,7 @@ and any in-arguments for the hcall are provided in registers *r4-r12*. If values have to be passed through a memory buffer, the data stored in that buffer should be in Big-endian byte order. -Once control is returns back to the guest after hypervisor has serviced the +Once control returns back to the guest after hypervisor has serviced the 'HVCS' instruction the return value of the hcall is available in *r3* and any out values are returned in registers *r4-r12*. Again like in case of in-arguments, any out values stored in a memory buffer will be in Big-endian byte order. @@ -147,7 +147,7 @@ corresponding opcode values please look into the arch specific header [4]_: | Out: *numBytesRead* | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_Hardware* -Given a DRC Index of an NVDIMM, read N-bytes from the the metadata area +Given a DRC Index of an NVDIMM, read N-bytes from the metadata area associated with it, at a specified offset and copy it to provided buffer. The metadata area stores configuration information such as label information, bad-blocks etc. The metadata area is located out-of-band of NVDIMM storage @@ -275,6 +275,20 @@ Health Bitmap Flags: Given a DRC Index collect the performance statistics for NVDIMM and copy them to the resultBuffer. +**H_SCM_FLUSH** + +| Input: *drcIndex, continue-token* +| Out: *continue-token* +| Return Value: *H_SUCCESS, H_Parameter, H_P2, H_BUSY* + +Given a DRC Index Flush the data to backend NVDIMM device. + +The hcall returns H_BUSY when the flush takes longer time and the hcall needs +to be issued multiple times in order to be completely serviced. The +*continue-token* from the output to be passed in the argument list of +subsequent hcalls to the hypervisor until the hcall is completely serviced +at which point H_SUCCESS or other error is returned by the hypervisor. + References ========== .. [1] "Power Architecture Platform Reference" diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/powerpc/syscall64-abi.rst index dabee3729e5a..56490c4c0c07 100644 --- a/Documentation/powerpc/syscall64-abi.rst +++ b/Documentation/powerpc/syscall64-abi.rst @@ -109,6 +109,16 @@ auxiliary vector. scv 0 syscalls will always behave as PPC_FEATURE2_HTM_NOSC. +ptrace +------ +When ptracing system calls (PTRACE_SYSCALL), the pt_regs.trap value contains +the system call type that can be used to distinguish between sc and scv 0 +system calls, and the different register conventions can be accounted for. + +If the value of (pt_regs.trap & 0xfff0) is 0xc00 then the system call was +performed with the sc instruction, if it is 0x3000 then the system call was +performed with the scv 0 instruction. + vsyscall ======== diff --git a/Documentation/powerpc/transactional_memory.rst b/Documentation/powerpc/transactional_memory.rst index b5b09bf00966..040a20675fd1 100644 --- a/Documentation/powerpc/transactional_memory.rst +++ b/Documentation/powerpc/transactional_memory.rst @@ -189,7 +189,7 @@ kernel aborted a transaction: ====================== ================================ These can be checked by the user program's abort handler as TEXASR[0:7]. If -bit 7 is set, it indicates that the error is consider persistent. For example +bit 7 is set, it indicates that the error is considered persistent. For example a TM_CAUSE_ALIGNMENT will be persistent while a TM_CAUSE_RESCHED will not. GDB @@ -271,4 +271,4 @@ with these lines: hrfid and mtmsrd have the same quirk. -The Linux kernel uses this quirk in it's early exception handling. +The Linux kernel uses this quirk in its early exception handling. diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst index 90c50ed839f3..bdb50fed903e 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/powerpc/vas-api.rst @@ -254,7 +254,7 @@ using this window. the signal will be issued to the thread group leader signals. NX-GZIP User's Manual: -https://github.com/libnxz/power-gzip/blob/master/power_nx_gzip_um.pdf +https://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf Simple example ============== @@ -301,5 +301,5 @@ Simple example close(fd) or window can be closed upon process exit } - Refer https://github.com/abalib/power-gzip for tests or more + Refer https://github.com/libnxz/power-gzip for tests or more use cases. diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index dac17711dc11..d3a8557b66a1 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -48,7 +48,6 @@ quota-tools 3.09 quota -V PPP 2.4.0 pppd --version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version -oprofile 0.9 oprofiled --version udev 081 udevd --version grub 0.93 grub --version || grub-install --version mcelog 0.6 mcelog --version diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index e5a1be476047..dc2d813b2e79 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -1,4 +1,4 @@ -.. _process_statement_kernel: +.. _process_statement_kernel: Linux Kernel Enforcement Statement ---------------------------------- diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index fa5a62f4150c..f5ba36e96461 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -73,12 +73,10 @@ CMAGIC 0x0111 user ``include/linux/ MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` PTY_MAGIC 0x5001 ``drivers/char/pty.c`` PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -90,14 +88,12 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 91de63b201c1..c66a19201deb 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -341,6 +341,16 @@ that you have sent your patches to the right place. Wait for a minimum of one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows. +It's also ok to resend the patch or the patch series after a couple of +weeks with the word "RESEND" added to the subject line:: + + [PATCH Vx RESEND] sub/sys: Condensed patch summary + +Don't add "RESEND" when you are submitting a modified version of your +patch or patch series - "RESEND" only applies to resubmission of a +patch or patch series which have not been modified in any way from the +previous submission. + Include PATCH in the subject ----------------------------- @@ -625,16 +635,19 @@ not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if the multiple versions of the patch have been sent out in response to comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. +comments. -A couple of example Subjects:: +If there are four patches in a patch series the individual patches may +be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers +understand the order in which the patches should be applied and that +they have reviewed or applied all of the patches in the patch series. + +Here are some good example Subjects:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary The ``from`` line must be the very first line in the message body, and has the form: @@ -647,34 +660,54 @@ then the ``From:`` line from the email header will be used to determine the patch author in the changelog. The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the ``summary phrase``, it is important to be both succinct as -well as descriptive. - -The ``---`` marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the ``---`` marker is for -a ``diffstat``, to show what files have changed, and the number of -inserted and deleted lines per file. A ``diffstat`` is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be ``patch changelogs`` -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a ``diffstat`` after the ``---`` marker, please -use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (``git`` -generates appropriate diffstats by default.) +changelog, so should make sense to a competent reader who has long since +forgotten the immediate details of the discussion that might have led to +this patch. Including symptoms of the failure which the patch addresses +(kernel log messages, oops messages, etc.) are especially useful for +people who might be searching the commit logs looking for the applicable +patch. The text should be written in such detail so that when read +weeks, months or even years later, it can give the reader the needed +details to grasp the reasoning for **why** the patch was created. + +If a patch fixes a compile failure, it may not be necessary to include +_all_ of the compile failures; just enough that it is likely that +someone searching for the patch can find it. As in the ``summary +phrase``, it is important to be both succinct as well as descriptive. + +The ``---`` marker line serves the essential purpose of marking for +patch handling tools where the changelog message ends. + +One good use for the additional comments after the ``---`` marker is +for a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful +on bigger patches. If you are going to include a ``diffstat`` after the +``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that +filenames are listed from the top of the kernel source tree and don't +use too much horizontal space (easily fit in 80 columns, maybe with some +indentation). (``git`` generates appropriate diffstats by default.) + +Other comments relevant only to the moment or the maintainer, not +suitable for the permanent changelog, should also go here. A good +example of such comments might be ``patch changelogs`` which describe +what has changed between the v1 and v2 version of the patch. + +Please put this information **after** the ``---`` line which separates +the changelog from the rest of the patch. The version information is +not part of the changelog which gets committed to the git tree. It is +additional information for the reviewers. If it's placed above the +commit tags, it needs manual interaction to remove it. If it is below +the separator line, it gets automatically stripped off when applying the +patch:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... See more details on the proper patch format in the following references. diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst index 6e6e39482502..ea915c196048 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/riscv/index.rst @@ -6,6 +6,7 @@ RISC-V architecture :maxdepth: 1 boot-image-header + vm-layout pmu patch-acceptance diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/riscv/vm-layout.rst new file mode 100644 index 000000000000..b7f98930d38d --- /dev/null +++ b/Documentation/riscv/vm-layout.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Virtual Memory Layout on RISC-V Linux +===================================== + +:Author: Alexandre Ghiti <alex@ghiti.fr> +:Date: 12 February 2021 + +This document describes the virtual memory layout used by the RISC-V Linux +Kernel. + +RISC-V Linux Kernel 32bit +========================= + +RISC-V Linux Kernel SV32 +------------------------ + +TODO + +RISC-V Linux Kernel 64bit +========================= + +The RISC-V privileged architecture document states that the 64bit addresses +"must have bits 63–48 all equal to bit 47, or else a page-fault exception will +occur.": that splits the virtual address space into 2 halves separated by a very +big hole, the lower half is where the userspace resides, the upper half is where +the RISC-V Linux Kernel resides. + +RISC-V Linux Kernel SV39 +------------------------ + +:: + + ======================================================================================================================== + Start addr | Offset | End addr | Size | VM area description + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 0000003fffffffff | 256 GB | user-space virtual memory, different per mm + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical + | | | | virtual memory addresses up to the -256 GB + | | | | starting offset of kernel mappings. + __________________|____________|__________________|_________|___________________________________________________________ + | + | 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 + __________________|____________|__________________|_________|____________________________________________________________ + | + | + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst index 492850bff316..8157f0cddbc2 100644 --- a/Documentation/s390/pci.rst +++ b/Documentation/s390/pci.rst @@ -50,7 +50,8 @@ Entries specific to zPCI functions and entries that hold zPCI information. * /sys/bus/pci/slots/XXXXXXXX The slot entries are set up using the function identifier (FID) of the - PCI function. + PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits + with 0 padding and lower case hexadecimal digitis. - /sys/bus/pci/slots/XXXXXXXX/power @@ -88,8 +89,15 @@ Entries specific to zPCI functions and entries that hold zPCI information. is attached to. - uid - The unique identifier (UID) is defined when configuring an LPAR and is - unique in the LPAR. + The user identifier (UID) may be defined as part of the machine + configuration or the z/VM or KVM guest configuration. If the accompanying + uid_is_unique attribute is 1 the platform guarantees that the UID is unique + within that instance and no devices with the same UID can be attached + during the lifetime of the system. + + - uid_is_unique + Indicates whether the user identifier (UID) is guaranteed to be and remain + unique within this Linux instance. - pfip/segmentX The segments determine the isolation of a function. diff --git a/Documentation/scheduler/sched-domains.rst b/Documentation/scheduler/sched-domains.rst index 8582fa5e9170..84dcdcd2911c 100644 --- a/Documentation/scheduler/sched-domains.rst +++ b/Documentation/scheduler/sched-domains.rst @@ -74,8 +74,8 @@ for a given topology level by creating a sched_domain_topology_level array and calling set_sched_topology() with this array as the parameter. The sched-domains debugging infrastructure can be enabled by enabling -CONFIG_SCHED_DEBUG and adding 'sched_debug' to your cmdline. If you forgot to -tweak your cmdline, you can also flip the /sys/kernel/debug/sched_debug -knob. This enables an error checking parse of the sched domains which should -catch most possible errors (described above). It also prints out the domain -structure in a visual format. +CONFIG_SCHED_DEBUG and adding 'sched_verbose' to your cmdline. If you +forgot to tweak your cmdline, you can also flip the +/sys/kernel/debug/sched/verbose knob. This enables an error checking parse of +the sched domains which should catch most possible errors (described above). It +also prints out the domain structure in a visual format. diff --git a/Documentation/scsi/BusLogic.rst b/Documentation/scsi/BusLogic.rst index b60169812358..d7d4d56981ca 100644 --- a/Documentation/scsi/BusLogic.rst +++ b/Documentation/scsi/BusLogic.rst @@ -251,8 +251,6 @@ BT-445C VLB Fast SCSI-2 BT-747C EISA Fast SCSI-2 BT-757C EISA Wide Fast SCSI-2 BT-757CD EISA Wide Differential Fast SCSI-2 -BT-545C ISA Fast SCSI-2 -BT-540CF ISA Fast SCSI-2 ======== ==== ============================== MultiMaster "S" Series Host Adapters: @@ -263,17 +261,13 @@ BT-747S EISA Fast SCSI-2 BT-747D EISA Differential Fast SCSI-2 BT-757S EISA Wide Fast SCSI-2 BT-757D EISA Wide Differential Fast SCSI-2 -BT-545S ISA Fast SCSI-2 -BT-542D ISA Differential Fast SCSI-2 BT-742A EISA SCSI-2 (742A revision H) -BT-542B ISA SCSI-2 (542B revision H) ======= ==== ============================== MultiMaster "A" Series Host Adapters: ======= ==== ============================== BT-742A EISA SCSI-2 (742A revisions A - G) -BT-542B ISA SCSI-2 (542B revisions A - G) ======= ==== ============================== AMI FastDisk Host Adapters that are true BusLogic MultiMaster clones are also @@ -400,26 +394,11 @@ selected host adapter. The BusLogic Driver Probing Options comprise the following: -IO:<integer> - - The "IO:" option specifies an ISA I/O Address to be probed for a non-PCI - MultiMaster Host Adapter. If neither "IO:" nor "NoProbeISA" options are - specified, then the standard list of BusLogic MultiMaster ISA I/O Addresses - will be probed (0x330, 0x334, 0x230, 0x234, 0x130, and 0x134). Multiple - "IO:" options may be specified to precisely determine the I/O Addresses to - be probed, but the probe order will always follow the standard list. - NoProbe The "NoProbe" option disables all probing and therefore no BusLogic Host Adapters will be detected. -NoProbeISA - - The "NoProbeISA" option disables probing of the standard BusLogic ISA I/O - Addresses and therefore only PCI MultiMaster and FlashPoint Host Adapters - will be detected. - NoProbePCI The "NoProbePCI" options disables the interrogation of PCI Configuration @@ -464,10 +443,7 @@ QueueDepth:<integer> Depth for devices that do not support Tagged Queuing. If no Queue Depth option is provided, the Queue Depth will be determined automatically based on the Host Adapter's Total Queue Depth and the number, type, speed, and - capabilities of the detected Target Devices. For Host Adapters that - require ISA Bounce Buffers, the Queue Depth is automatically set by default - to BusLogic_TaggedQueueDepthBB or BusLogic_UntaggedQueueDepthBB to avoid - excessive preallocation of DMA Bounce Buffer memory. Target Devices that + capabilities of the detected Target Devices. Target Devices that do not support Tagged Queuing always have their Queue Depth set to BusLogic_UntaggedQueueDepth or BusLogic_UntaggedQueueDepthBB, unless a lower Queue Depth option is provided. A Queue Depth of 1 automatically diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index d2052fdbedd2..cbb329956897 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -220,7 +220,7 @@ Older Version : 2.20.4.5 (scsi module), 2.20.2.5 (cmm module) 4. Use the pre defined DMA mask constants from dma-mapping.h Use the DMA_{64,32}BIT_MASK constants from dma-mapping.h when calling - pci_set_dma_mask() or pci_set_consistend_dma_mask(). See + pci_set_dma_mask() or pci_set_consistent_dma_mask(). See http://marc.theaimsgroup.com/?t=108001993000001&r=1&w=2 for more details. Signed-off-by: Tobias Klauser <tklauser@nuerscht.ch> diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 5bc17d012b25..096ffe9cae0e 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -1095,10 +1095,6 @@ of interest: - maximum number of commands that can be queued on devices controlled by the host. Overridden by LLD calls to scsi_change_queue_depth(). - unchecked_isa_dma - - 1=>only use bottom 16 MB of ram (ISA DMA addressing - restriction), 0=>can use full 32 bit (or better) DMA - address space no_async_abort - 1=>Asynchronous aborts are not supported - 0=>Timed-out commands will be aborted asynchronously diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 8129405eb2cc..16335de04e8c 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -16,3 +16,4 @@ Security Documentation siphash tpm/index digsig + landlock diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 1da879a68640..80d5a5af62a1 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -6,30 +6,127 @@ Trusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, and in both cases all keys are created in the kernel, and user space sees, stores, and loads only encrypted blobs. Trusted Keys require the availability -of a Trusted Platform Module (TPM) chip for greater security, while Encrypted -Keys can be used on any system. All user level blobs, are displayed and loaded -in hex ascii for convenience, and are integrity verified. +of a Trust Source for greater security, while Encrypted Keys can be used on any +system. All user level blobs, are displayed and loaded in hex ASCII for +convenience, and are integrity verified. -Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed -under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR -(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob -integrity verifications match. A loaded Trusted Key can be updated with new -(future) PCR values, so keys are easily migrated to new pcr values, such as -when the kernel and initramfs are updated. The same key can have many saved -blobs under different PCR values, so multiple boots are easily supported. -TPM 1.2 -------- +Trust Source +============ -By default, trusted keys are sealed under the SRK, which has the default -authorization value (20 zeros). This can be set at takeownership time with the -trouser's utility: "tpm_takeownership -u -z". +A trust source provides the source of security for Trusted Keys. This +section lists currently supported trust sources, along with their security +considerations. Whether or not a trust source is sufficiently safe depends +on the strength and correctness of its implementation, as well as the threat +environment for a specific use case. Since the kernel doesn't know what the +environment is, and there is no metric of trust, it is dependent on the +consumer of the Trusted Keys to determine if the trust source is sufficiently +safe. -TPM 2.0 -------- + * Root of trust for storage -The user must first create a storage key and make it persistent, so the key is -available after reboot. This can be done using the following commands. + (1) TPM (Trusted Platform Module: hardware device) + + Rooted to Storage Root Key (SRK) which never leaves the TPM that + provides crypto operation to establish root of trust for storage. + + (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) + + Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip + fuses and is accessible to TEE only. + + * Execution isolation + + (1) TPM + + Fixed set of operations running in isolated execution environment. + + (2) TEE + + Customizable set of operations running in isolated execution + environment verified via Secure/Trusted boot process. + + * Optional binding to platform integrity state + + (1) TPM + + Keys can be optionally sealed to specified PCR (integrity measurement) + values, and only unsealed by the TPM, if PCRs and blob integrity + verifications match. A loaded Trusted Key can be updated with new + (future) PCR values, so keys are easily migrated to new PCR values, + such as when the kernel and initramfs are updated. The same key can + have many saved blobs under different PCR values, so multiple boots are + easily supported. + + (2) TEE + + Relies on Secure/Trusted boot process for platform integrity. It can + be extended with TEE based measured boot process. + + * Interfaces and APIs + + (1) TPM + + TPMs have well-documented, standardized interfaces and APIs. + + (2) TEE + + TEEs have well-documented, standardized client interface and APIs. For + more details refer to ``Documentation/staging/tee.rst``. + + + * Threat model + + The strength and appropriateness of a particular TPM or TEE for a given + purpose must be assessed when using them to protect security-relevant data. + + +Key Generation +============== + +Trusted Keys +------------ + +New keys are created from random numbers generated in the trust source. They +are encrypted/decrypted using a child key in the storage key hierarchy. +Encryption and decryption of the child key must be protected by a strong +access control policy within the trust source. + + * TPM (hardware device) based RNG + + Strength of random numbers may vary from one device manufacturer to + another. + + * TEE (OP-TEE based on Arm TrustZone) based RNG + + RNG is customizable as per platform needs. It can either be direct output + from platform specific hardware RNG or a software based Fortuna CSPRNG + which can be seeded via multiple entropy sources. + +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. + + +Usage +===== + +Trusted Keys usage: TPM +----------------------- + +TPM 1.2: By default, trusted keys are sealed under the SRK, which has the +default authorization value (20 bytes of 0s). This can be set at takeownership +time with the TrouSerS utility: "tpm_takeownership -u -z". + +TPM 2.0: The user must first create a storage key and make it persistent, so the +key is available after reboot. This can be done using the following commands. With the IBM TSS 2 stack:: @@ -78,14 +175,21 @@ TPM_STORED_DATA format. The key length for new keys are always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. -Encrypted keys do not depend on a TPM, 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. +Trusted Keys usage: TEE +----------------------- + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +specific to TEE device implementation. The key length for new keys is always +in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + +Encrypted Keys usage +-------------------- The decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is @@ -103,8 +207,8 @@ Where:: format:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user' - -Examples of trusted and encrypted key usage: +Examples of trusted and encrypted key usage +------------------------------------------- Create and save a trusted key named "kmk" of length 32 bytes. @@ -150,7 +254,7 @@ Load a trusted key from the saved blob:: f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba -Reseal a trusted key under new pcr values:: +Reseal (TPM specific) a trusted key under new PCR values:: $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 @@ -164,11 +268,12 @@ Reseal a trusted key under new pcr values:: 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 + The initial consumer of trusted keys is EVM, which at boot time needs a high -quality symmetric key for HMAC protection of file metadata. The use of a +quality symmetric key for HMAC protection of file metadata. The use of a trusted key provides strong guarantees that the EVM key has not been -compromised by a user level problem, and when sealed to specific boot PCR -values, protects against boot and offline attacks. Create and save an +compromised by a user level problem, and when sealed to a platform integrity +state, protects against boot and offline attacks. Create and save an encrypted key "evm" using the above trusted key "kmk": option 1: omitting 'format':: @@ -207,3 +312,61 @@ about the usage can be found in the file Another new format 'enc32' has been defined in order to support encrypted keys with payload size of 32 bytes. This will initially be used for nvdimm security but may expand to other usages that require 32 bytes payload. + + +TPM 2.0 ASN.1 Key Format +------------------------ + +The TPM 2.0 ASN.1 key format is designed to be easily recognisable, +even in binary form (fixing a problem we had with the TPM 1.2 ASN.1 +format) and to be extensible for additions like importable keys and +policy:: + + TPMKey ::= SEQUENCE { + type OBJECT IDENTIFIER + emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL + parent INTEGER + pubkey OCTET STRING + privkey OCTET STRING + } + +type is what distinguishes the key even in binary form since the OID +is provided by the TCG to be unique and thus forms a recognizable +binary pattern at offset 3 in the key. The OIDs currently made +available are:: + + 2.23.133.10.1.3 TPM Loadable key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Load() operation. + + 2.23.133.10.1.4 TPM Importable Key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Import() operation. + + 2.23.133.10.1.5 TPM Sealed Data. This is a set of data (up to 128 + bytes) which is sealed by the TPM. It usually + represents a symmetric key and must be unsealed before + use. + +The trusted key code only uses the TPM Sealed Data OID. + +emptyAuth is true if the key has well known authorization "". If it +is false or not present, the key requires an explicit authorization +phrase. This is used by most user space consumers to decide whether +to prompt for a password. + +parent represents the parent key handle, either in the 0x81 MSO space, +like 0x81000001 for the RSA primary storage key. Userspace programmes +also support specifying the primary handle in the 0x40 MSO space. If +this happens the Elliptic Curve variant of the primary key using the +TCG defined template will be generated on the fly into a volatile +object and used as the parent. The current kernel code only supports +the 0x81 MSO form. + +pubkey is the binary representation of TPM2B_PRIVATE excluding the +initial TPM2B header, which can be reconstructed from the ASN.1 octet +string length. + +privkey is the binary representation of TPM2B_PUBLIC excluding the +initial TPM2B header which can be reconstructed from the ASN.1 octed +string length. diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst new file mode 100644 index 000000000000..2e84925ae971 --- /dev/null +++ b/Documentation/security/landlock.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> +.. Copyright © 2019-2020 ANSSI + +================================== +Landlock LSM: kernel documentation +================================== + +:Author: Mickaël Salaün +:Date: March 2021 + +Landlock's goal is to create scoped access-control (i.e. sandboxing). To +harden a whole system, this feature should be available to any process, +including unprivileged ones. Because such process may be compromised or +backdoored (i.e. untrusted), Landlock's features must be safe to use from the +kernel and other processes point of view. Landlock's interface must therefore +expose a minimal attack surface. + +Landlock is designed to be usable by unprivileged processes while following the +system security policy enforced by other access control mechanisms (e.g. DAC, +LSM). Indeed, a Landlock rule shall not interfere with other access-controls +enforced on the system, only add more restrictions. + +Any user can enforce Landlock rulesets on their processes. They are merged and +evaluated according to the inherited ones in a way that ensures that only more +constraints can be added. + +User space documentation can be found here: :doc:`/userspace-api/landlock`. + +Guiding principles for safe access controls +=========================================== + +* A Landlock rule shall be focused on access control on kernel objects instead + of syscall filtering (i.e. syscall arguments), which is the purpose of + seccomp-bpf. +* To avoid multiple kinds of side-channel attacks (e.g. leak of security + policies, CPU-based attacks), Landlock rules shall not be able to + programmatically communicate with user space. +* Kernel access check shall not slow down access request from unsandboxed + processes. +* Computation related to Landlock operations (e.g. enforcing a ruleset) shall + only impact the processes requesting them. + +Tests +===== + +Userspace tests for backward compatibility, ptrace restrictions and filesystem +support can be found here: `tools/testing/selftests/landlock/`_. + +Kernel structures +================= + +Object +------ + +.. kernel-doc:: security/landlock/object.h + :identifiers: + +Filesystem +---------- + +.. kernel-doc:: security/landlock/fs.h + :identifiers: + +Ruleset and domain +------------------ + +A domain is a read-only ruleset tied to a set of subjects (i.e. tasks' +credentials). Each time a ruleset is enforced on a task, the current domain is +duplicated and the ruleset is imported as a new layer of rules in the new +domain. Indeed, once in a domain, each rule is tied to a layer level. To +grant access to an object, at least one rule of each layer must allow the +requested action on the object. A task can then only transit to a new domain +that is the intersection of the constraints from the current domain and those +of a ruleset provided by the task. + +The definition of a subject is implicit for a task sandboxing itself, which +makes the reasoning much easier and helps avoid pitfalls. + +.. kernel-doc:: security/landlock/ruleset.h + :identifiers: + +.. Links +.. _tools/testing/selftests/landlock/: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/ diff --git a/Documentation/security/tpm/xen-tpmfront.rst b/Documentation/security/tpm/xen-tpmfront.rst index 00d5b1db227d..31c67522f2ad 100644 --- a/Documentation/security/tpm/xen-tpmfront.rst +++ b/Documentation/security/tpm/xen-tpmfront.rst @@ -1,4 +1,4 @@ -============================= +============================= Virtual TPM interface for Xen ============================= diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py index a3eea0bbe6ba..16bea0632555 100755 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -22,7 +22,7 @@ u""" * *auto span* rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior - can changed from *auto span* to *auto fill*, which automaticly inserts + can be changed from *auto span* to *auto fill*, which automatically inserts (empty) cells instead of spanning the last cell. Options: @@ -161,7 +161,7 @@ class ListTableBuilder(object): for colwidth in colwidths: colspec = nodes.colspec(colwidth=colwidth) # FIXME: It seems, that the stub method only works well in the - # absence of rowspan (observed by the html buidler, the docutils-xml + # absence of rowspan (observed by the html builder, the docutils-xml # build seems OK). This is not extraordinary, because there exists # no table directive (except *this* flat-table) which allows to # define coexistent of rowspan and stubs (there was no use-case diff --git a/Documentation/spi/butterfly.rst b/Documentation/spi/butterfly.rst index e614a589547c..56088fb090c7 100644 --- a/Documentation/spi/butterfly.rst +++ b/Documentation/spi/butterfly.rst @@ -11,7 +11,7 @@ develop firmware for this, and flash it using this adapter cable. You can make this adapter from an old printer cable and solder things directly to the Butterfly. Or (if you have the parts and skills) you -can come up with something fancier, providing ciruit protection to the +can come up with something fancier, providing circuit protection to the Butterfly and the printer port, or with a better power supply than two signal pins from the printer port. Or for that matter, you can use similar cables to talk to many AVR boards, even a breadboard. diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst index f1daffe10d78..d4239025461d 100644 --- a/Documentation/spi/spi-summary.rst +++ b/Documentation/spi/spi-summary.rst @@ -411,8 +411,11 @@ any more such messages. duplex (one pointer is NULL) transfers; + optionally defining short delays after transfers ... using - the spi_transfer.delay_usecs setting (this delay can be the - only protocol effect, if the buffer length is zero); + the spi_transfer.delay.value setting (this delay can be the + only protocol effect, if the buffer length is zero) ... + when specifying this delay the default spi_transfer.delay.unit + is microseconds, however this can be adjusted to clock cycles + or nanoseconds if needed; + whether the chipselect becomes inactive after a transfer and any delay ... by using the spi_transfer.cs_change flag; diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index c4c70e1aada3..6cadad7c3aad 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -1,4 +1,4 @@ -====================================== +====================================== NO_HZ: Reducing Scheduling-Clock Ticks ====================================== diff --git a/Documentation/trace/coresight/coresight-trbe.rst b/Documentation/trace/coresight/coresight-trbe.rst new file mode 100644 index 000000000000..b9928ef148da --- /dev/null +++ b/Documentation/trace/coresight/coresight-trbe.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Trace Buffer Extension (TRBE). +============================== + + :Author: Anshuman Khandual <anshuman.khandual@arm.com> + :Date: November 2020 + +Hardware Description +-------------------- + +Trace Buffer Extension (TRBE) is a percpu hardware which captures in system +memory, CPU traces generated from a corresponding percpu tracing unit. This +gets plugged in as a coresight sink device because the corresponding trace +generators (ETE), are plugged in as source device. + +The TRBE is not compliant to CoreSight architecture specifications, but is +driven via the CoreSight driver framework to support the ETE (which is +CoreSight compliant) integration. + +Sysfs files and directories +--------------------------- + +The TRBE devices appear on the existing coresight bus alongside the other +coresight devices:: + + >$ ls /sys/bus/coresight/devices + trbe0 trbe1 trbe2 trbe3 + +The ``trbe<N>`` named TRBEs are associated with a CPU.:: + + >$ ls /sys/bus/coresight/devices/trbe0/ + align flag + +*Key file items are:-* + * ``align``: TRBE write pointer alignment + * ``flag``: TRBE updates memory with access and dirty flags diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 090d2949d345..0046d75d9a70 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -330,17 +330,17 @@ la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti* - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Che verrà rappresentata nel seguente modo: @@ -352,37 +352,46 @@ Che verrà rappresentata nel seguente modo: - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Riferimenti incrociati ---------------------- -Per fare dei riferimenti incrociati da una pagina ad un'altra -specificando il percorso a partire dalla cartella *Documentation*. -Per esempio, se volete aggiungere un riferimento a questa pagina -(l'estensione .rst è opzionale):: +Aggiungere un riferimento incrociato da una pagina della +documentazione ad un'altra può essere fatto scrivendo il percorso al +file corrispondende, non serve alcuna sintassi speciale. Si possono +usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con +"documentation/". Per esempio, potete fare riferimento a questo +documento in uno dei seguenti modi (da notare che l'estensione +``.rst`` è necessaria):: - See Documentation/translations/it_IT/doc-guide/sphinx.rst. + Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre + Guardate pshinx.rst, che si trova nella stessa cartella. + Leggete ../sphinx.rst, che si trova nella cartella precedente. -Se preferite usare un percorso relative allora vi serve la direttiva -Sphinx ``doc``. Per esempio, se volete aggiungere un riferimento a -questa pagina dalla stessa cartella:: +Se volete che il collegamento abbia un testo diverso rispetto al +titolo del documento, allora dovrete usare la direttiva Sphinx +``doc``. Per esempio:: - See :doc:`sphinx`. + Vedere :doc:`il mio testo per il collegamento <sphinx>`. -Per maggiori informazioni su come aggiungere riferimenti incrociati a -commenti kernel-doc di funzioni o tipi, leggete -Documentation/translations/it_IT/doc-guide/sphinx.rst. +Nella maggioranza dei casi si consiglia il primo metodo perché è più +pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:`` +che non da alcun valore, sentitevi liberi di convertirlo in un +percorso al documento. + +Per informazioni riguardo ai riferimenti incrociati ai commenti +kernel-doc per funzioni o tipi, consultate .. _it_sphinx_kfigure: @@ -391,7 +400,7 @@ Figure ed immagini Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in -formato SVG:: +formato SVG (:ref:`it_svg_image_example`):: .. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: una semplice immagine SVG diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 3d30b69f1ec1..f6beb385b4ac 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -369,7 +369,7 @@ all'inizio dell'avvio del sistema è attraverso la procedura Prima di inventare la vostra cache per gli oggetti più usati, considerate l'uso di una cache slab disponibile in ``include/linux/slab.h``. -:c:func:`current()` +:c:macro:`current` ------------------- Definita in ``include/asm/current.h`` diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index bf1acd6204ef..1e7c84def369 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -127,11 +127,11 @@ il vostro processo si auto-sospenderà; verrà riattivato quando il mutex verrà rilasciato. Questo significa che il processore potrà occuparsi d'altro mentre il vostro processo è in attesa. Esistono molti casi in cui non potete permettervi di sospendere un processo (vedere -:ref:`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? <it_sleeping-things>`) +`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni?`_) e quindi dovrete utilizzare gli spinlock. Nessuno di questi *lock* è ricorsivo: vedere -:ref:`Stallo: semplice ed avanzato <it_deadlock>` +`Stallo: semplice ed avanzato`_ I *lock* e i kernel per sistemi monoprocessore ---------------------------------------------- @@ -190,7 +190,7 @@ perfetto questa funzione si chiamerebbe 'spin_lock_softirq()'). Da notare che in questo caso potete utilizzare anche spin_lock_irq() o spin_lock_irqsave(), queste fermano anche le interruzioni hardware: -vedere :ref:`Contesto di interruzione hardware <it_hardirq-context>`. +vedere `Contesto di interruzione hardware`_. Questo funziona alla perfezione anche sui sistemi monoprocessore: gli spinlock svaniscono e questa macro diventa semplicemente local_bh_disable() @@ -241,7 +241,7 @@ Lo stesso softirq Lo stesso softirq può essere eseguito su un diverso processore: allo scopo di migliorare le prestazioni potete utilizzare dati riservati ad ogni -processore (vedere :ref:`Dati per processore <it_per-cpu>`). Se siete arrivati +processore (vedere `Dati per processore`_). Se siete arrivati fino a questo punto nell'uso dei softirq, probabilmente tenete alla scalabilità delle prestazioni abbastanza da giustificarne la complessità aggiuntiva. @@ -896,8 +896,6 @@ leggendo solamente il codice. E come dice Alan Cox: “Lock data, not code”. Problemi comuni =============== -.. _`it_deadlock`: - Stallo: semplice ed avanzato ---------------------------- @@ -1282,7 +1280,6 @@ Il beneficio qui sta nel fatto che il contatore di riferimenti no viene scritto: l'oggetto non viene alterato in alcun modo e quindi diventa molto più veloce su sistemi molti-processore grazie alla loro memoria cache. -.. _`it_per-cpu`: Dati per processore ------------------- @@ -1333,7 +1330,6 @@ Naturalmente, questo è più lento della semplice chiamata spin_lock_irq(), quindi ha senso solo se questo genere di accesso è estremamente raro. -.. _`it_sleeping-things`: Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? ========================================================================= diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst index 8012fe9497ae..54fd255b77d0 100644 --- a/Documentation/translations/it_IT/process/4.Coding.rst +++ b/Documentation/translations/it_IT/process/4.Coding.rst @@ -264,11 +264,10 @@ La maggior parte di queste opzioni possono essere attivate per qualsiasi kernel utilizzato per lo sviluppo o a scopo di test. In particolare dovreste attivare: - - ENABLE_MUST_CHECK e FRAME_WARN per ottenere degli - avvertimenti dedicati a problemi come l'uso di interfacce deprecate o - l'ignorare un importante valore di ritorno di una funzione. Il risultato - generato da questi avvertimenti può risultare verboso, ma non bisogna - preoccuparsi per gli avvertimenti provenienti da altre parti del kernel. + - FRAME_WARN per ottenere degli avvertimenti su stack frame più + grandi di un dato valore. Il risultato generato da questi + avvertimenti può risultare verboso, ma non bisogna preoccuparsi per + gli avvertimenti provenienti da altre parti del kernel. - DEBUG_OBJECTS aggiungerà un codice per tracciare il ciclo di vita di diversi oggetti creati dal kernel e avvisa quando qualcosa viene eseguito diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst index c478b6e8c292..df8c652d004b 100644 --- a/Documentation/translations/it_IT/process/adding-syscalls.rst +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst @@ -562,7 +562,7 @@ kernel. Se la nuova funzionalità è utile all'interno del kernel, per esempio dev'essere condivisa fra una vecchia e una nuova chiamata di sistema o dev'essere utilizzata da una chiamata di sistema e la sua variante compatibile, allora dev'essere implementata come una funzione di supporto -(*helper function*) (per esempio ``kern_xyzzy()``). Questa funzione potrà +(*helper function*) (per esempio ``ksys_xyzzy()``). Questa funzione potrà essere chiamata dallo *stub* (``sys_xyzzy()``), dalla variante compatibile (``compat_sys_xyzzy()``), e/o da altri parti del kernel. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index cc883f8d96c4..87d081889bfc 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -51,7 +51,6 @@ quota-tools 3.09 quota -V PPP 2.4.0 pppd --version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version -oprofile 0.9 oprofiled --version udev 081 udevd --version grub 0.93 grub --version || grub-install --version mcelog 0.6 mcelog --version diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index c86c4543f249..95f2e7c985e2 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -75,9 +75,26 @@ stessa riga: if (condition) do_this; do_something_everytime; -né mettete più assegnamenti sulla stessa riga. Lo stile del kernel +Non usate le virgole per evitare le parentesi: + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +Invece, usate sempre le parentesi per racchiudere più istruzioni. + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +Non mettete nemmeno più assegnamenti sulla stessa riga. Lo stile del kernel è ultrasemplice. Evitate espressioni intricate. + Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è volutamente errato. @@ -320,8 +337,7 @@ qualcosa di simile, **non** dovreste chiamarla ``cntusr()``. Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione ungherese) è stupido - il compilatore conosce comunque il tipo e -può verificarli, e inoltre confonde i programmatori. Non c'è da -sorprendersi che MicroSoft faccia programmi bacati. +può verificarli, e inoltre confonde i programmatori. Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``. diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 1db5a1082389..9554368a2ae2 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -357,17 +357,10 @@ benvenuti. Riportare Bug ------------- -https://bugzilla.kernel.org è dove gli sviluppatori del kernel Linux tracciano -i bachi del kernel. Gli utenti sono incoraggiati nel riportare tutti i bachi -che trovano utilizzando questo strumento. -Per maggiori dettagli su come usare il bugzilla del kernel, guardare: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -Il file admin-guide/reporting-bugs.rst nella cartella principale del kernel -fornisce un buon modello sul come segnalare un baco nel kernel, e spiega quali -informazioni sono necessarie agli sviluppatori per poter aiutare il -rintracciamento del problema. +Il file 'Documentation/admin-guide/reporting-issues.rst' nella +cartella principale del kernel spiega come segnalare un baco nel +kernel, e fornisce dettagli su quali informazioni sono necessarie agli +sviluppatori del kernel per poter studiare il problema. Gestire i rapporti sui bug -------------------------- @@ -380,8 +373,14 @@ al corrente della vostra presenza. Riparare bachi è una delle migliori vie per acquisire meriti tra gli altri sviluppatori, perchè non a molte persone piace perdere tempo a sistemare i bachi di altri. -Per lavorare sui rapporti di bachi già riportati, andate su -https://bugzilla.kernel.org. +Per lavorare sui bachi già segnalati, per prima cosa cercate il +sottosistema che vi interessa. Poi, verificate nel file MAINTAINERS +dove vengono collezionati solitamente i bachi per quel sottosistema; +spesso sarà una lista di discussione, raramente un bugtracker. Cercate +bachi nell'archivio e aiutate dove credete di poterlo fare. Potete +anche consultare https://bugzilla.kernel.org; però, solo una manciata di +sottosistemi lo usano attivamente, ciò nonostante i bachi che +coinvolgono l'intero kernel sono sempre riportati lì. Liste di discussione -------------------- diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index 1af30f4228f2..f452fafb1e84 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -79,12 +79,10 @@ CMAGIC 0x0111 user ``include/linux/ MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` PTY_MAGIC 0x5001 ``drivers/char/pty.c`` PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -96,16 +94,13 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` @@ -148,7 +143,6 @@ PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/me NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index 614fc17d9086..2fc09cc1f0be 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -28,6 +28,10 @@ sottomissione delle patch, in particolare c) quando si usa ``O=builddir`` + d) Qualsiasi modifica in Documentation/ deve compilare con successo senza + avvisi o errori. Usare ``make htmldocs`` o ``make pdfdocs`` per verificare + e correggere i problemi + 3) Compilare per diverse architetture di processore usando strumenti per la cross-compilazione o altri. @@ -54,8 +58,7 @@ sottomissione delle patch, in particolare 9) Verificare con sparse. -10) Usare ``make checkstack`` e ``make namespacecheck`` e correggere tutti i - problemi rilevati. +10) Usare ``make checkstack`` e correggere tutti i problemi rilevati. .. note:: @@ -95,31 +98,29 @@ sottomissione delle patch, in particolare informazioni. Le patch che modificano le interfacce utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -20) Verifica che il kernel passi con successo ``make headers_check`` - -21) La patch è stata verificata con l'iniezione di fallimenti in slab e +20) La patch è stata verificata con l'iniezione di fallimenti in slab e nell'allocazione di pagine. Vedere ``Documentation/fault-injection/``. Se il nuovo codice è corposo, potrebbe essere opportuno aggiungere l'iniezione di fallimenti specifici per il sottosistema. -22) Il nuovo codice è stato compilato con ``gcc -W`` (usate +21) Il nuovo codice è stato compilato con ``gcc -W`` (usate ``make KCFLAGS=-W``). Questo genererà molti avvisi, ma è ottimo per scovare bachi come "warning: comparison between signed and unsigned". -23) La patch è stata verificata dopo essere stata inclusa nella serie di patch +22) La patch è stata verificata dopo essere stata inclusa nella serie di patch -mm; questo al fine di assicurarsi che continui a funzionare assieme a tutte le altre patch in coda e i vari cambiamenti nei sottosistemi VM, VFS e altri. -24) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, +23) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, ``rmb()``, ``wmb()``} devono essere accompagnate da un commento nei sorgenti che ne spieghi la logica: cosa fanno e perché. -25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate +24) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate ``Documentation/userspace-api/ioctl/ioctl-number.rst``. -26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o +25) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o funzionalità del kernel che è associata a uno dei seguenti simboli ``Kconfig``, allora verificate che il kernel compili con diverse configurazioni dove i simboli sono disabilitati e/o ``=m`` (se c'è la diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index ae00352346ed..ded95048b9a8 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -433,6 +433,14 @@ Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno ignorate, ma potete farlo per meglio identificare procedure aziendali interne o per aggiungere dettagli circa la firma. +In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da +parte di tutte quelle persone che si sono occupate della gestione e +del trasporto della patch. Queste però non sono state coinvolte nello +sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso +**reale** che una patch a intrapreso dallo sviluppatore, fino al +manutentore, per poi giungere a Linus. + + Quando utilizzare Acked-by:, Cc:, e Co-developed-by: ---------------------------------------------------- @@ -574,6 +582,10 @@ kernel stabili al fine di capire quale kernel deve ricevere la correzione. Questo è il modo suggerito per indicare che un baco è stato corretto nella patch. Per maggiori dettagli leggete :ref:`it_describe_changes` +Da notare che aggiungere un tag "Fixes:" non esime dalle regole +previste per i kernel stabili, e nemmeno dalla necessità di aggiungere +in copia conoscenza stable@vger.kernel.org su tutte le patch per +suddetti kernel. Il formato canonico delle patch ------------------------------- @@ -642,16 +654,20 @@ Le etichette non verranno considerate come parte della frase riassuntiva, ma indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni ci sono quelle di versione che vengono usate quando una patch è stata inviata più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si -attendono dei commenti (*Request For Comments*). Se ci sono quattro patch -nella serie, queste dovrebbero essere enumerate così: 1/4, 2/4, 3/4, 4/4. -Questo assicura che gli sviluppatori capiranno l'ordine in cui le patch -dovrebbero essere applicate, e per tracciare quelle che hanno revisionate o -che hanno applicato. +attendono dei commenti (*Request For Comments*). + +Se ci sono quattro patch nella serie, queste dovrebbero essere +enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli +sviluppatori capiranno l'ordine in cui le patch dovrebbero essere +applicate, e per tracciare quelle che hanno revisionate o che hanno +applicato. Un paio di esempi di oggetti:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel formato: @@ -668,30 +684,76 @@ deve aver senso per un lettore esperto che è ha dimenticato i dettagli della discussione che hanno portato alla patch. L'inclusione di informazioni sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops, eccetera) è particolarmente utile per le persone che potrebbero cercare fra -i messaggi di log per la patch che li tratta. Se la patch corregge un errore -di compilazione, non sarà necessario includere proprio _tutto_ quello che -è uscito dal compilatore; aggiungete solo quello che è necessario per far si -che la vostra patch venga trovata. Come nella ``summary phrase``, è importante -essere sia brevi che descrittivi. +i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto +con abbastanza dettagli da far capire al lettore **perché** quella +patch fu creata, e questo a distanza di settimane, mesi, o addirittura +anni. + +Se la patch corregge un errore di compilazione, non sarà necessario +includere proprio _tutto_ quello che è uscito dal compilatore; +aggiungete solo quello che è necessario per far si che la vostra patch +venga trovata. Come nella ``summary phrase``, è importante essere sia +brevi che descrittivi. La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce il messaggio di changelog. Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi. -Un ``diffstat`` è particolarmente utile per le patch grandi. Altri commenti -che sono importanti solo per i manutentori, quindi inadatti al changelog -permanente, dovrebbero essere messi qui. Un buon esempio per questo tipo -di commenti potrebbe essere quello di descrivere le differenze fra le versioni +Un ``diffstat`` è particolarmente utile per le patch grandi. Se +includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` +cosicché i nomi dei file elencati non occupino troppo spazio +(facilmente rientreranno negli 80 caratteri, magari con qualche +indentazione). (``git`` genera di base dei diffstat adatti). + +I commenti che sono importanti solo per i manutentori, quindi +inadatti al changelog permanente, dovrebbero essere messi qui. Un +buon esempio per questo tipo di commenti potrebbe essere il cosiddetto +``patch changelogs`` che descrivere le differenze fra le versioni della patch. -Se includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` -cosicché i nomi dei file elencati non occupino troppo spazio (facilmente -rientreranno negli 80 caratteri, magari con qualche indentazione). -(``git`` genera di base dei diffstat adatti). +Queste informazioni devono andare **dopo** la linea ``---`` che separa +il *changelog* dal resto della patch. Le informazioni riguardanti la +versione di una patch non sono parte del *chagelog* che viene incluso +in git. Queste sono informazioni utili solo ai revisori. Se venissero +messe sopra la riga, qualcuno dovrà fare del lavoro manuale per +rimuoverle; cosa che invece viene fatta automaticamente quando vengono +messe correttamente oltre la riga.:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +Aggiungere i *backtrace* nei messaggi di commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +I *backtrace* aiutano a documentare la sequenza di chiamate a funzione +che portano ad un problema. Tuttavia, non tutti i *backtrace* sono +davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche +e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante +informazioni che distraggono dal vero problema (per esempio, i +marcatori temporali, la lista dei moduli, la lista dei registri, lo +stato dello stack). + +Quindi, per rendere utile un *backtrace* dovreste eliminare le +informazioni inutili, cosicché ci si possa focalizzare sul +problema. Ecco un esempio di un *backtrace* essenziale:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + .. _it_explicit_in_reply_to: Usare esplicitamente In-Reply-To nell'intestazione diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist index b42220d3d46c..4429447b0965 100644 --- a/Documentation/translations/ja_JP/SubmitChecklist +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -88,20 +88,18 @@ Linux カーネルパッチ投稿者向けチェックリスト 18: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に Documentation/ABI/README を参考にして必ずドキュメントを追加してください。 -19: 'make headers_check'を実行して全く問題がないことを確認してください。 - -20: 少なくともslabアロケーションとpageアロケーションに失敗した場合の +19: 少なくともslabアロケーションとpageアロケーションに失敗した場合の 挙動について、fault-injectionを利用して確認してください。 Documentation/fault-injection/ を参照してください。 追加したコードがかなりの量であったならば、サブシステム特有の fault-injectionを追加したほうが良いかもしれません。 -21: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 +20: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 このオプションは大量の不要なメッセージを出力しますが、 "warning: comparison between signed and unsigned" のようなメッセージは、 バグを見つけるのに役に立ちます。 -22: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや +21: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存 できることを確認するテストを行ってください。 diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 787f1e85f8a0..a2bdd564c907 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -339,14 +339,8 @@ Andrew Morton의 글이 있다. 버그 보고 --------- -https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버그를 추적하는 -곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 -권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. - - https://bugzilla.kernel.org/page.cgi?id=faq.html - 메인 커널 소스 디렉토리에 있는 'Documentation/admin-guide/reporting-issues.rst' -파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 +파일은 커널 버그라고 생각되는 것을 어떻게 보고하면 되는지, 그리고 문제를 추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. @@ -362,8 +356,14 @@ https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. -이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org -를 참조하라. +이미 보고된 버그 리포트들을 가지고 작업하기 위해서는 여러분이 관심있는 +서브시스템을 찾아라. 해당 서브시스템의 버그들이 어디로 리포트 되는지 +MAINTAINERS 파일을 체크하라; 그건 대부분 메일링 리스트이고, 가끔은 버그 추적 +시스템이다. 그 장소에 있는 최근 버그 리포트 기록들을 검색하고 여러분이 보기에 +적합하다 싶은 것을 도와라. 여러분은 버그 리포트를 위해 +https://bugzilla.kernel.org 를 체크하고자 할 수도 있다; 소수의 커널 +서브시스템들만이 버그 신고와 추적을 위해 해당 시스템을 실제로 사용하고 있지만, +전체 커널의 버그들이 그곳에 정리된다. 메일링 리스트들 diff --git a/Documentation/translations/zh_CN/SecurityBugs b/Documentation/translations/zh_CN/SecurityBugs deleted file mode 100644 index 2d0fffd122ce..000000000000 --- a/Documentation/translations/zh_CN/SecurityBugs +++ /dev/null @@ -1,50 +0,0 @@ -Chinese translated version of Documentation/admin-guide/security-bugs.rst - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Chinese maintainer: Harry Wei <harryxiyou@gmail.com> ---------------------------------------------------------------------- -Documentation/admin-guide/security-bugs.rst 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 - -中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> -中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> -中文版校译者： 贾威威 Harry Wei <harryxiyou@gmail.com> - - -以下为正文 ---------------------------------------------------------------------- -Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于 -安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全 -漏洞报告给Linux内核安全团队。 - -1) 联系 - -linux内核安全团队可以通过email<security@kernel.org>来联系。这是 -一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 -全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 -当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 -是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任 -何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 -被公布于众。 - -2) 公开 - -Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直 -到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理 -解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们 -期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开 -日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很 -短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我 -们所期望通知公众的日期是7天的安排。 - -3) 保密协议 - -Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst new file mode 100644 index 000000000000..669a022f6817 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -0,0 +1,347 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/README.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Linux内核5.x版本 <http://kernel.org/> +========================================= + +以下是Linux版本5的发行注记。仔细阅读它们， +它们会告诉你这些都是什么，解释如何安装内核，以及遇到问题时该如何做。 + +什么是Linux？ +--------------- + + Linux是Unix操作系统的克隆版本，由Linus Torvalds在一个松散的网络黑客 + （Hacker，无贬义）团队的帮助下从头开始编写。它旨在实现兼容POSIX和 + 单一UNIX规范。 + + 它具有在现代成熟的Unix中应当具有的所有功能，包括真正的多任务处理、虚拟内存、 + 共享库、按需加载、共享的写时拷贝（COW）可执行文件、恰当的内存管理以及包括 + IPv4和IPv6在内的复合网络栈。 + + Linux在GNU通用公共许可证，版本2（GNU GPLv2）下分发，详见随附的COPYING文件。 + +它能在什么样的硬件上运行？ +----------------------------- + + 虽然Linux最初是为32位的x86 PC机（386或更高版本）开发的，但今天它也能运行在 + （至少）Compaq Alpha AXP、Sun SPARC与UltraSPARC、Motorola 68000、PowerPC、 + PowerPC64、ARM、Hitachi SuperH、Cell、IBM S/390、MIPS、HP PA-RISC、Intel + IA-64、DEC VAX、AMD x86-64 Xtensa和ARC架构上。 + + Linux很容易移植到大多数通用的32位或64位体系架构，只要它们有一个分页内存管理 + 单元（PMMU）和一个移植的GNU C编译器（gcc；GNU Compiler Collection，GCC的一 + 部分）。Linux也被移植到许多没有PMMU的体系架构中，尽管功能显然受到了一定的 + 限制。 + Linux也被移植到了其自己上。现在可以将内核作为用户空间应用程序运行——这被 + 称为用户模式Linux（UML）。 + +文档 +----- +因特网上和书籍上都有大量的电子文档，既有Linux专属文档，也有与一般UNIX问题相关 +的文档。我建议在任何Linux FTP站点上查找LDP（Linux文档项目）书籍的文档子目录。 +本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 因特网上和书籍上都有大量的（电子）文档，既有Linux专属文档，也有与普通 + UNIX问题相关的文档。我建议在任何有LDP（Linux文档项目）书籍的Linux FTP + 站点上查找文档子目录。本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 文档/子目录中有各种自述文件：例如，这些文件通常包含一些特定驱动程序的 + 内核安装说明。请阅读 + :ref:`Documentation/process/changes.rst <changes>` 文件，它包含了升级内核 + 可能会导致的问题的相关信息。 + +安装内核源代码 +--------------- + + - 如果您要安装完整的源代码，请把内核tar档案包放在您有权限的目录中（例如您 + 的主目录）并将其解包:: + + xz -cd linux-5.x.tar.xz | tar xvf - + + 将“X”替换成最新内核的版本号。 + + 【不要】使用 /usr/src/linux 目录！这里有一组库头文件使用的内核头文件 + （通常是不完整的）。它们应该与库匹配，而不是被内核的变化搞得一团糟。 + + - 您还可以通过打补丁在5.x版本之间升级。补丁以xz格式分发。要通过打补丁进行 + 安装，请获取所有较新的补丁文件，进入内核源代码（linux-5.x）的目录并 + 执行:: + + xz -cd ../patch-5.x.xz | patch -p1 + + 请【按顺序】替换所有大于当前源代码树版本的“x”，这样就可以了。您可能想要 + 删除备份文件（文件名类似xxx~ 或 xxx.orig)，并确保没有失败的补丁（文件名 + 类似xxx# 或 xxx.rej）。如果有，不是你就是我犯了错误。 + + 与5.x内核的补丁不同，5.x.y内核（也称为稳定版内核）的补丁不是增量的，而是 + 直接应用于基本的5.x内核。例如，如果您的基本内核是5.0，并且希望应用5.0.3 + 补丁，则不应先应用5.0.1和5.0.2的补丁。类似地，如果您运行的是5.0.2内核， + 并且希望跳转到5.0.3，那么在应用5.0.3补丁之前，必须首先撤销5.0.2补丁 + （即patch -R）。更多关于这方面的内容，请阅读 + :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 + + 或者，脚本 patch-kernel 可以用来自动化这个过程。它能确定当前内核版本并 + 应用找到的所有补丁:: + + linux/scripts/patch-kernel linux + + 上面命令中的第一个参数是内核源代码的位置。补丁是在当前目录应用的，但是 + 可以将另一个目录指定为第二个参数。 + + - 确保没有过时的 .o 文件和依赖项:: + + cd linux + make mrproper + + 现在您应该已经正确安装了源代码。 + +软件要求 +--------- + + 编译和运行5.x内核需要各种软件包的最新版本。请参考 + :ref:`Documentation/process/changes.rst <changes>` + 来了解最低版本要求以及如何升级软件包。请注意，使用过旧版本的这些包可能会 + 导致很难追踪的间接错误，因此不要以为在生成或操作过程中出现明显问题时可以 + 只更新包。 + +为内核建立目录 +--------------- + + 编译内核时，默认情况下所有输出文件都将与内核源代码放在一起。使用 + ``make O=output/dir`` 选项可以为输出文件（包括 .config）指定备用位置。 + 例如:: + + kernel source code: /usr/src/linux-5.x + build directory: /home/name/build/kernel + + 要配置和构建内核，请使用:: + + cd /usr/src/linux-5.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + 请注意：如果使用了 ``O=output/dir`` 选项，那么它必须用于make的所有调用。 + +配置内核 +--------- + + 即使只升级一个小版本，也不要跳过此步骤。每个版本中都会添加新的配置选项， + 如果配置文件没有按预定设置，就会出现奇怪的问题。如果您想以最少的工作量 + 将现有配置升级到新版本，请使用 ``makeoldconfig`` ，它只会询问您新配置 + 选项的答案。 + + - 其他配置命令包括:: + + "make config" 纯文本界面。 + + "make menuconfig" 基于文本的彩色菜单、选项列表和对话框。 + + "make nconfig" 增强的基于文本的彩色菜单。 + + "make xconfig" 基于Qt的配置工具。 + + "make gconfig" 基于GTK+的配置工具。 + + "make oldconfig" 基于现有的 ./.config 文件选择所有选项，并询问 + 新配置选项。 + + "make olddefconfig" + 类似上一个，但不询问直接将新选项设置为默认值。 + + "make defconfig" 根据体系架构，使用arch/$arch/defconfig或 + arch/$arch/configs/${PLATFORM}_defconfig中的 + 默认选项值创建./.config文件。 + + "make ${PLATFORM}_defconfig" + 使用arch/$arch/configs/${PLATFORM}_defconfig中 + 的默认选项值创建一个./.config文件。 + 用“makehelp”来获取您体系架构中所有可用平台的列表。 + + "make allyesconfig" + 通过尽可能将选项值设置为“y”，创建一个 + ./.config文件。 + + "make allmodconfig" + 通过尽可能将选项值设置为“m”，创建一个 + ./.config文件。 + + "make allnoconfig" 通过尽可能将选项值设置为“n”，创建一个 + ./.config文件。 + + "make randconfig" 通过随机设置选项值来创建./.config文件。 + + "make localmodconfig" 基于当前配置和加载的模块（lsmod）创建配置。禁用 + 已加载的模块不需要的任何模块选项。 + + 要为另一台计算机创建localmodconfig，请将该计算机 + 的lsmod存储到一个文件中，并将其作为lsmod参数传入。 + + 此外，通过在参数LMC_KEEP中指定模块的路径，可以将 + 模块保留在某些文件夹或kconfig文件中。 + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + 上述方法在交叉编译时也适用。 + + "make localyesconfig" 与localmodconfig类似，只是它会将所有模块选项转换 + 为内置（=y）。你可以同时通过LMC_KEEP保留模块。 + + "make kvmconfig" 为kvm客体内核支持启用其他选项。 + + "make xenconfig" 为xen dom0客体内核支持启用其他选项。 + + "make tinyconfig" 配置尽可能小的内核。 + + 更多关于使用Linux内核配置工具的信息，见文档 + Documentation/kbuild/kconfig.rst。 + + - ``make config`` 注意事项: + + - 包含不必要的驱动程序会使内核变大，并且在某些情况下会导致问题： + 探测不存在的控制器卡可能会混淆其他控制器。 + + - 如果存在协处理器，则编译了数学仿真的内核仍将使用协处理器：在 + 这种情况下，数学仿真永远不会被使用。内核会稍微大一点，但不管 + 是否有数学协处理器，都可以在不同的机器上工作。 + + - “kernel hacking”配置细节通常会导致更大或更慢的内核（或两者 + 兼而有之），甚至可以通过配置一些例程来主动尝试破坏坏代码以发现 + 内核问题，从而降低内核的稳定性（kmalloc()）。因此，您可能应该 + 用于研究“开发”、“实验”或“调试”特性相关问题。 + +编译内核 +--------- + + - 确保您至少有gcc 4.9可用。 + 有关更多信息，请参阅 :ref:`Documentation/process/changes.rst <changes>` 。 + + 请注意，您仍然可以使用此内核运行a.out用户程序。 + + - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， + 那么也可以进行 ``makeinstall`` ，但是您可能需要先检查特定的lilo设置。 + + 实际安装必须以root身份执行，但任何正常构建都不需要。 + 无须徒然使用root身份。 + + - 如果您将内核的任何部分配置为模块，那么还必须执行 ``make modules_install`` 。 + + - 详细的内核编译/生成输出： + + 通常，内核构建系统在相当安静的模式下运行（但不是完全安静）。但是有时您或 + 其他内核开发人员需要看到编译、链接或其他命令的执行过程。为此，可使用 + “verbose（详细）”构建模式。 + 向 ``make`` 命令传递 ``V=1`` 来实现，例如:: + + make V=1 all + + 如需构建系统也给出内个目标重建的愿意，请使用 ``V=2`` 。默认为 ``V=0`` 。 + + - 准备一个备份内核以防出错。对于开发版本尤其如此，因为每个新版本都包含 + 尚未调试的新代码。也要确保保留与该内核对应的模块的备份。如果要安装 + 与工作内核版本号相同的新内核，请在进行 ``make modules_install`` 安装 + 之前备份modules目录。 + + 或者，在编译之前，使用内核配置选项“LOCALVERSION”向常规内核版本附加 + 一个唯一的后缀。LOCALVERSION可以在“General Setup”菜单中设置。 + + - 为了引导新内核，您需要将内核映像（例如编译后的 + .../linux/arch/x86/boot/bzImage）复制到常规可引导内核的位置。 + + - 不再支持在没有LILO等启动装载程序帮助的情况下直接从软盘引导内核。 + + 如果从硬盘引导Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 + 指定的内核映像文件。内核映像文件通常是/vmlinuz、/boot/vmlinuz、 + /bzImage或/boot/bzImage。使用新内核前，请保存旧映像的副本，并复制 + 新映像覆盖旧映像。然后您【必须重新运行LILO】来更新加载映射！否则， + 将无法启动新的内核映像。 + + 重新安装LILO通常需要运行/sbin/LILO。您可能希望编辑/etc/lilo.conf + 文件为旧内核映像指定一个条目（例如/vmlinux.old)防止新的不能正常 + 工作。有关更多信息，请参阅LILO文档。 + + 重新安装LILO之后，您应该就已经准备好了。关闭系统，重新启动，尽情 + 享受吧！ + + 如果需要更改内核映像中的默认根设备、视频模式等，请在适当的地方使用 + 启动装载程序的引导选项。无需重新编译内核即可更改这些参数。 + + - 使用新内核重新启动并享受它吧。 + +若遇到问题 +----------- + + - 如果您发现了一些可能由于内核缺陷所导致的问题，请检查MAINTAINERS（维护者） + 文件看看是否有人与令您遇到麻烦的内核部分相关。如果无人在此列出，那么第二 + 个最好的方案就是把它们发给我（torvalds@linux-foundation.org），也可能发送 + 到任何其他相关的邮件列表或新闻组。 + + - 在所有的缺陷报告中，【请】告诉我们您在说什么内核，如何复现问题，以及您的 + 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， + 请尝试告诉我您什么时候首次注意到它。 + + - 如果缺陷导致如下消息:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + 或者类似的内核调试信息显示在屏幕上或在系统日志里，请【如实】复制它。 + 可能对你来说转储（dump）看起来不可理解，但它确实包含可能有助于调试问题的 + 信息。转储上方的文本也很重要：它说明了内核转储代码的原因（在上面的示例中， + 是由于内核指针错误）。更多关于如何理解转储的信息，请参见 + Documentation/admin-guide/bug-hunting.rst。 + + - 如果使用 CONFIG_KALLSYMS 编译内核，则可以按原样发送转储，否则必须使用 + ``ksymoops`` 程序来理解转储（但通常首选使用CONFIG_KALLSYMS编译）。 + 此实用程序可从 + https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 + 或者，您可以手动执行转储查找： + + - 在调试像上面这样的转储时，如果您可以查找EIP值的含义，这将非常有帮助。 + 十六进制值本身对我或其他任何人都没有太大帮助：它会取决于特定的内核设置。 + 您应该做的是从EIP行获取十六进制值（忽略 ``0010:`` ），然后在内核名字列表 + 中查找它，以查看哪个内核函数包含有问题的地址。 + + 要找到内核函数名，您需要找到与显示症状的内核相关联的系统二进制文件。就是 + 文件“linux/vmlinux”。要提取名字列表并将其与内核崩溃中的EIP进行匹配， + 请执行:: + + nm vmlinux | sort | less + + 这将为您提供一个按升序排序的内核地址列表，从中很容易找到包含有问题的地址 + 的函数。请注意，内核调试消息提供的地址不一定与函数地址完全匹配（事实上， + 这是不可能的），因此您不能只“grep”列表：不过列表将为您提供每个内核函数 + 的起点，因此通过查找起始地址低于你正在搜索的地址，但后一个函数的高于的 + 函数，你会找到您想要的。实际上，在您的问题报告中加入一些“上下文”可能是 + 一个好主意，给出相关的上下几行。 + + 如果您由于某些原因无法完成上述操作（如您使用预编译的内核映像或类似的映像）， + 请尽可能多地告诉我您的相关设置信息，这会有所帮助。有关详细信息请阅读 + ‘Documentation/admin-guide/reporting-issues.rst’。 + + - 或者，您可以在正在运行的内核上使用gdb（只读的；即不能更改值或设置断点）。 + 为此，请首先使用-g编译内核；适当地编辑arch/x86/Makefile，然后执行 ``make + clean`` 。您还需要启用CONFIG_PROC_FS（通过 ``make config`` ）。 + + 使用新内核重新启动后，执行 ``gdb vmlinux /proc/kcore`` 。现在可以使用所有 + 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替换为EIP + 值）。 + + 用gdb无法调试一个当前未运行的内核是由于gdb（错误地）忽略了编译内核的起始 + 偏移量。 diff --git a/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..662eb5b46e84 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +二分（bisect）缺陷 ++++++++++++++++++++ + +（英文版）最后更新：2016年10月28日 + +引言 +===== + +始终尝试由来自kernel.org的源代码构建的最新内核。如果您没有信心这样做，请将 +错误报告给您的发行版供应商，而不是内核开发人员。 + +找到缺陷（bug）并不总是那么容易，不过仍然得去找。如果你找不到它，不要放弃。 +尽可能多的向相关维护人员报告您发现的信息。请参阅MAINTAINERS文件以了解您所 +关注的子系统的维护人员。 + +在提交错误报告之前，请阅读“Documentation/admin-guide/reporting-issues.rst”。 + +设备未出现（Devices not appearing） +==================================== + +这通常是由udev/systemd引起的。在将其归咎于内核之前先检查一下。 + +查找导致缺陷的补丁 +=================== + +使用 ``git`` 提供的工具可以很容易地找到缺陷，只要缺陷是可复现的。 + +操作步骤： + +- 从git源代码构建内核 +- 以此开始二分 [#f1]_:: + + $ git bisect start + +- 标记损坏的变更集:: + + $ git bisect bad [commit] + +- 标记正常工作的变更集:: + + $ git bisect good [commit] + +- 重新构建内核并测试 +- 使用以下任一与git bisect进行交互:: + + $ git bisect good + + 或:: + + $ git bisect bad + + 这取决于您测试的变更集上是否有缺陷 +- 在一些交互之后，git bisect将给出可能导致缺陷的变更集。 + +- 例如，如果您知道当前版本有问题，而4.8版本是正常的，则可以执行以下操作:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] 您可以（可选地）在开始git bisect的时候提供good或bad参数 + ``git bisect start [BAD] [GOOD]`` + +如需进一步参考，请阅读： + +- ``git-bisect`` 的手册页 +- `Fighting regressions with git bisect（用git bisect解决回归） + <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + 来全自动二分） <https://lwn.net/Articles/317154>`_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分来找出何时引入了错误） <http://webchick.net/node/99>`_ diff --git a/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..decb9b26d2f1 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst @@ -0,0 +1,340 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +追踪缺陷 +========= + +内核错误报告通常附带如下堆栈转储:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [<c12ba080>] ? dump_stack+0x44/0x64 + [<c103ed6a>] ? __warn+0xfa/0x120 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c103ee33>] ? warn_slowpath_null+0x23/0x30 + [<c109e8a7>] ? module_put+0x57/0x70 + [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [<c109f617>] ? symbol_put_addr+0x27/0x50 + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0 + [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [<c13d2882>] ? usb_unbind_interface+0x62/0x250 + [<c136b514>] ? __pm_runtime_idle+0x44/0x70 + [<c13620d8>] ? __device_release_driver+0x78/0x120 + [<c1362907>] ? driver_detach+0x87/0x90 + [<c1361c48>] ? bus_remove_driver+0x38/0x90 + [<c13d1c18>] ? usb_deregister+0x58/0xb0 + [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0 + [<c1055654>] ? task_work_run+0x64/0x80 + [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90 + [<c10013f0>] ? do_fast_syscall_32+0x80/0x130 + [<c1549f43>] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +这样的堆栈跟踪提供了足够的信息来识别内核源代码中发生错误的那一行。根据问题的 +严重性，它还可能包含 **“Oops”** 一词，比如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [<c06969d4>] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +尽管有 **Oops** 或其他类型的堆栈跟踪，但通常需要找到出问题的行来识别和处理缺 +陷。在本章中，我们将参考“Oops”来了解需要分析的各种堆栈跟踪。 + +如果内核是用 ``CONFIG_DEBUG_INFO`` 编译的，那么可以使用文件： +`scripts/decode_stacktrace.sh` 。 + +链接的模块 +----------- + +受到污染或正在加载/卸载的模块用“（…）”标记，污染标志在 +`Documentation/admin-guide/tainted-kernels.rst` 文件中进行了描述，“正在被加 +载”用“+”标注，“正在被卸载”用“-”标注。 + + +Oops消息在哪？ +--------------- + +通常，Oops文本由klogd从内核缓冲区读取，然后交给 ``syslogd`` ，后者将其写入 +syslog文件，通常是 ``/var/log/messages`` （取决于 ``/etc/syslog.conf`` ）。 +在使用systemd的系统上，它也可以由 ``journald`` 守护进程存储，并通过运行 +``journalctl`` 命令进行访问。 + +有时 ``klogd`` 会挂掉，这种情况下您可以运行 ``dmesg > file`` 从内核缓冲区 +读取数据并保存它。或者您可以 ``cat /proc/kmsg > file`` ，但是您必须适时 +中断以停止传输，因为 ``kmsg`` 是一个“永无止境的文件”。 + +如果机器严重崩溃，无法输入命令或磁盘不可用，那还有三个选项： + +(1) 手动复制屏幕上的文本，并在机器重新启动后输入。很难受，但这是突然崩溃下 + 唯一的选择。或者你可以用数码相机拍下屏幕——虽然不那么好，但总比什么都没 + 有好。如果消息滚动超出控制台顶部，使用更高分辨率（例如 ``vga=791`` ） + 引导启动将允许您阅读更多文本。（警告：这需要 ``vesafb`` ，因此对“早期” + 的Oppses没有帮助） + +(2) 从串口终端启动（参见 + :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， + 在另一台机器上运行调制解调器然后用你喜欢的通信程序捕获输出。 + Minicom运行良好。 + +(3) 使用Kdump（参阅 Documentation/admin-guide/kdump/kdump.rst ），使用 + Documentation/admin-guide/kdump/gdbmacros.txt 中的dmesg gdbmacro从旧内存 + 中提取内核环形缓冲区。 + +找到缺陷位置 +------------- + +如果你能指出缺陷在内核源代码中的位置，则报告缺陷的效果会非常好。这有两种方法。 +通常来说使用 ``gdb`` 会比较容易，不过内核需要用调试信息来预编译。 + +gdb +^^^^ + +GNU 调试器（GNU debugger， ``gdb`` ）是从 ``vmlinux`` 文件中找出OOPS的确切 +文件和行号的最佳方法。 + +在使用 ``CONFIG_DEBUG_INFO`` 编译的内核上使用gdb效果最好。可通过运行以下命令 +进行设置:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +在用 ``CONFIG_DEBUG_INFO`` 编译的内核上，你可以直接从OOPS复制EIP值:: + + EIP: 0060:[<c021e50e>] Not tainted VLI + +并使用GDB来将其翻译成可读形式:: + + $ gdb vmlinux + (gdb) l *0xc021e50e + +如果没有启用 ``CONFIG_DEBUG_INFO`` ，则使用OOPS的函数偏移:: + + EIP is at vt_ioctl+0xda8/0x1482 + +并在启用 ``CONFIG_DEBUG_INFO`` 的情况下重新编译内核:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +或者若您想要更详细的显示:: + + (gdb) p vt_ioctl + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl> + (gdb) l *0xae0+0xda8 + +您也可以使用对象文件作为替代:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +如果你有调用跟踪，类似:: + + Call Trace: + [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 + [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e + [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee + ... + +这表明问题可能在 :jbd: 模块中。您可以在gdb中加载该模块并列出相关代码:: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您还可以对堆栈跟踪处的任何函数调用执行相同的操作，例如:: + + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + 上述调用发生的位置可以通过以下方式看到:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^^ + +要调试内核，请使用objdump并从崩溃输出中查找十六进制偏移，以找到有效的代码/汇 +编行。如果没有调试符号，您将看到所示例程的汇编程序代码，但是如果内核有调试 +符号，C代码也将可见（调试符号可以在内核配置菜单的hacking项中启用）。例如:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + 您需要处于内核树的顶层以便此获得您的C文件。 + +如果您无法访问源代码，仍然可以使用以下方法调试一些崩溃转储（如Dave Miller的 +示例崩溃转储输出所示）:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +`scripts/decodecode` 文件可以用来自动完成大部分工作，这取决于正在调试的CPU +体系结构。 + +报告缺陷 +--------- + +一旦你通过定位缺陷找到了其发生的地方，你可以尝试自己修复它或者向上游报告它。 + +为了向上游报告，您应该找出用于开发受影响代码的邮件列表。这可以使用 ``get_maintainer.pl`` 。 + + +例如，您在gspca的sonixj.c文件中发现一个缺陷，则可以通过以下方法找到它的维护者:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%) + Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +请注意它将指出： + +- 最后接触源代码的开发人员（如果这是在git树中完成的）。在上面的例子中是Tejun + 和Bhaktipriya（在这个特定的案例中，没有人真正参与这个文件的开发）； +- 驱动维护人员（Hans Verkuil）； +- 子系统维护人员（Mauro Carvalho Chehab）； +- 驱动程序和/或子系统邮件列表（linux-media@vger.kernel.org）； +- Linux内核邮件列表（linux-kernel@vger.kernel.org）。 + +通常，修复缺陷的最快方法是将它报告给用于开发相关代码的邮件列表（linux-media +ML），抄送驱动程序维护者（Hans）。 + +如果你完全不知道该把报告寄给谁，且 ``get_maintainer.pl`` 也没有提供任何有用 +的信息，请发送到linux-kernel@vger.kernel.org。 + +感谢您的帮助，这使Linux尽可能稳定:-) + +修复缺陷 +--------- + +如果你懂得编程，你不仅可以通过报告错误来帮助我们，还可以提供一个解决方案。 +毕竟，开源就是分享你的工作，你不想因为你的天才而被认可吗？ + +如果你决定这样做，请在制定解决方案后将其提交到上游。 + +请务必阅读 +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ， +以帮助您的代码被接受。 + + +--------------------------------------------------------------------------- + +用 ``klogd`` 进行Oops跟踪的注意事项 +------------------------------------ + +为了帮助Linus和其他内核开发人员， ``klogd`` 对保护故障的处理提供了大量支持。 +为了完整支持地址解析，至少应该使用 ``sysklogd`` 包的1.3-pl3版本。 + +当发生保护故障时， ``klogd`` 守护进程会自动将内核日志消息中的重要地址转换为 +它们的等效符号。然后通过 ``klogd`` 使用的任何报告机制来转发这个已翻译的内核 +消息。保护错误消息可以直接从消息文件中剪切出来并转发给内核开发人员。 + +``klogd`` 执行两种类型的地址解析，静态翻译和动态翻译。静态翻译使用System.map +文件。为了进行静态转换， ``klogd`` 守护进程必须能够在守护进程初始化时找到系 +统映射文件。有关 ``klogd`` 如何搜索映射文件的信息，请参见klogd手册页。 + +当使用内核可加载模块时，动态地址转换非常重要。由于内核模块的内存是从内核的 +动态内存池中分配的，因此无论是模块的开头还是模块中的函数和符号都没有固定的 +位置。 + +内核支持系统调用，允许程序确定加载哪些模块及其在内存中的位置。klogd守护进程 +使用这些系统调用构建了一个符号表，可用于调试可加载内核模块中发生的保护错误。 + +klogd至少会提供产生保护故障的模块的名称。如果可加载模块的开发人员选择从模块 +导出符号信息，则可能会有其他可用的符号信息。 + +由于内核模块环境可以是动态的，因此当模块环境发生变化时，必须有一种通知 +``klogd`` 守护进程的机制。有一些可用的命令行选项允许klogd向当前正在执行的守 +护进程发出信号示意应该刷新符号信息。有关更多信息，请参阅 ``klogd`` 手册页。 + +sysklogd发行版附带了一个补丁，它修改了 ``modules-2.0.0`` 包，以便在加载或 +卸载模块时自动向klogd发送信号。应用此补丁基本上可无缝支持调试内核可加载模块 +发生的保护故障。 + +以下是 ``klogd`` 处理的可加载模块中的保护故障示例:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 48bbd3ebad48..be835ec8e632 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -13,9 +13,13 @@ Linux 内核用户和管理员指南 这个初始部分包含总体信息，包括描述内核的README， 关于内核参数的文档等。 -Todolist: +.. toctree:: + :maxdepth: 1 README + +Todolist: + kernel-parameters devices sysctl/index @@ -28,16 +32,21 @@ Todolist: 下面的一组文档，针对的是试图跟踪问题和bug的用户。 -Todolist: +.. toctree:: + :maxdepth: 1 - reporting-bugs + reporting-issues security-bugs bug-hunting bug-bisect tainted-kernels + init + +Todolist: + + reporting-bugs ramoops dynamic-debug-howto - init kdump/index perf/index @@ -56,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + unicode Todolist: @@ -111,7 +121,6 @@ Todolist: sysrq thunderbolt ufs - unicode vga-softcursor video-output xfs diff --git a/Documentation/translations/zh_CN/admin-guide/init.rst b/Documentation/translations/zh_CN/admin-guide/init.rst new file mode 100644 index 000000000000..fbaf6d97f86c --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/init.rst @@ -0,0 +1,54 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/init` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +解释“No working init found.”启动挂起消息 +========================================= + +:作者: + + Andreas Mohr <andi at lisas period de> + + Cristian Souza <cristianmsbr at gmail period com> + +本文档提供了加载初始化二进制（init binary）失败的一些高层级原因（大致按执行 +顺序列出）。 + +1) **无法挂载根文件系统Unable to mount root FS** ：请设置“debug”内核参数（在 + 引导加载程序bootloader配置文件或CONFIG_CMDLINE）以获取更详细的内核消息。 + +2) **初始化二进制不存在于根文件系统上init binary doesn't exist on rootfs** ： + 确保您的根文件系统类型正确（并且 ``root=`` 内核参数指向正确的分区）；拥有 + 所需的驱动程序，例如SCSI或USB等存储硬件；文件系统（ext3、jffs2等）是内建的 + （或者作为模块由initrd预加载）。 + +3) **控制台设备损坏Broken console device** ： ``console= setup`` 中可能存在 + 冲突 --> 初始控制台不可用（initial console unavailable）。例如，由于串行 + IRQ问题（如缺少基于中断的配置）导致的某些串行控制台不可靠。尝试使用不同的 + ``console= device`` 或像 ``netconsole=`` 。 + +4) **二进制存在但依赖项不可用Binary exists but dependencies not available** ： + 例如初始化二进制的必需库依赖项，像 ``/lib/ld-linux.so.2`` 丢失或损坏。使用 + ``readelf -d <INIT>|grep NEEDED`` 找出需要哪些库。 + +5) **无法加载二进制Binary cannot be loaded** ：请确保二进制的体系结构与您的 + 硬件匹配。例如i386不匹配x86_64，或者尝试在ARM硬件上加载x86。如果您尝试在 + 此处加载非二进制文件（shell脚本？），您应该确保脚本在其工作头（shebang + header）行 ``#!/...`` 中指定能正常工作的解释器（包括其库依赖项）。在处理 + 脚本之前，最好先测试一个简单的非脚本二进制文件，比如 ``/bin/sh`` ，并确认 + 它能成功执行。要了解更多信息，请将代码添加到 ``init/main.c`` 以显示 + kernel_execve()的返回值。 + +当您发现新的失败原因时，请扩展本解释（毕竟加载初始化二进制是一个 **关键** 且 +艰难的过渡步骤，需要尽可能无痛地进行），然后向LKML提交一个补丁。 + +待办事项： + +- 通过一个可以存储 ``kernel_execve()`` 结果值的结构体数组实现各种 + ``run_init_process()`` 调用，并在失败时通过迭代 **所有** 结果来记录一切 + （非常重要的可用性修复）。 +- 试着使实现本身在一般情况下更有帮助，例如在受影响的地方提供额外的错误消息。 diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst new file mode 100644 index 000000000000..6b4988da2c5a --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -0,0 +1,1335 @@ +.. 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. + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + + +报告问题 ++++++++++ + + +简明指南（亦即 太长不看） +========================== + +您面临的是否为同系列稳定版或长期支持内核的普通内核的回归？是否仍然受支持？ +请搜索 `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ 和 +`Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹配的报告并 +加入讨论。如果找不到匹配的报告，请安装该系列的最新版本。如果它仍然出现问题， +报告给稳定版邮件列表（stable@vger.kernel.org）。 + +在所有其他情况下，请尽可能猜测是哪个内核部分导致了问题。查看MAINTAINERS文件， +了解开发人员希望如何得知问题，大多数情况下，报告问题都是通过电子邮件和抄送 +相关邮件列表进行的。检查报告目的地的存档中是否已有匹配的报告；也请搜索 +`LKML <https://lore.kernel.org/lkml/>`_ 和网络。如果找不到可加入的讨论，请 +安装 `最新的主线内核 <https://kernel.org/>`_ 。如果仍存在问题，请发送报告。 + +问题已经解决了，但是您希望看到它在一个仍然支持的稳定版或长期支持系列中得到 +解决？请安装其最新版本。如果它出现了问题，那么在主线中搜索修复它的更改，并 +检查是否正在回传（backporting）或者已放弃；如果两者都没有，那么可询问处理 +更改的人员。 + +**通用提醒** ：当安装和测试上述内核时，请确保它是普通的（即：没有补丁，也没 +有使用附加模块）。还要确保它是在一个正常的环境中构建和运行，并且在问题发生 +之前没有被污染（tainted）。 + +在编写报告时，要涵盖与问题相关的所有信息，如使用的内核和发行版。在碰见回归时， +尝试给出引入它的更改的提交ID，二分可以找到它。如果您同时面临Linux内核的多个 +问题，请分别报告每个问题。 + +一旦报告发出，请回答任何出现的问题，并尽可能地提供帮助。这包括通过不时重新 +测试新版本并发送状态更新来推动进展。 + + +如何向内核维护人员报告问题的逐步指南 +===================================== + +上面的简明指南概述了如何向Linux内核开发人员报告问题。对于已经熟悉向自由和开 +源软件（FLOSS）项目报告问题的人来说，这可能是他们所需要的全部内容。对于其他 +人，本部分更为详细，并一步一步地描述。为了便于阅读，它仍然尽量简洁，并省略 +了许多细节；这些在逐步指南后的参考章节中进行了描述，该章节更详细地解释了每 +个步骤。 + +注意：本节涉及的方面比简明指南多，顺序也稍有不同。这符合你的利益，以确保您 +尽早意识到看起来像Linux内核毛病的问题可能实际上是由其他原因引起的。这些步骤 +可以确保你最终不会觉得在这一过程中投入的时间是浪费： + + * 您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅读 + 本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。寻找 + 和解决问题往往需要后者。 + + * 使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查 + `Linux内核邮件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存档。如果 + 找到匹配的报告，请加入讨论而不是发送新报告。 + + * 看看你正在处理的问题是否为回归问题、安全问题或非常严重的问题：这些都是需 + 要在接下来的一些步骤中特别处理的“高优先级问题”。 + + * 确保不是内核环境导致了您面临的问题。 + + * 创建一个新的备份，并将系统修复和恢复工具放在手边。 + + * 确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解决 + 方案可能在您不知情的情况下就在本地进行了这样的工作。 + + * 当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可能 + 会导致您面临的问题。 + + * 粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写注 + 释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需要分 + 别报告给内核开发人员，除非它们严重纠缠在一起。 + + * 如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。 + + * 定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式和 + 位置。注意：大多数情况下不会是 bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。 + + * 在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果你发现了一些相关讨论，请加入讨论而不是发送新的报告。 + +在完成这些准备之后，你将进入主要部分： + + * 除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在某些 + 情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案；在 + 合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。无论 + 你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告被拒绝 + 或忽略的风险。 + + * 确保您刚刚安装的内核在运行时不会“污染”自己。 + + * 在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。 + + * 优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所有 + 重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到了一 + 些东西，请考虑再次搜索关于该问题的现有报告。 + + * 如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找触 + 发错误的代码行。 + + * 如果您的问题是回归问题，请尽可能缩小引入问题时的范围。 + + * 通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新内 + 核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内核 + 构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。包 + 含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` 的输出 + 。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概述问题和 + 影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。现在给出一 + 个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的那样发送或 + 提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面“高优先级问 + 题的特殊处理”所述特别关照。 + + * 等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请公 + 开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个新主 + 线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地提醒一 + 下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。 + + +报告稳定版和长期支持内核线的回归 +---------------------------------- + +如果您发现了稳定版或长期支持内核版本线中的回归问题并按上述流程跳到这里，那么 +请阅读本小节。即例如您在从5.10.4更新到5.10.5时出现了问题（从5.9.15到5.10.5则 +不是）。开发人员希望尽快修复此类回归，因此有一个简化流程来报告它们： + + * 检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 `kernel.org 的首页 + <https://kernel.org/>`_ ，确保此特定版本线的最新版没有“[EOL]”标记。 + + * 检查 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 中的现有报告。 + + * 从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍然 + 存在问题，因为问题可能已经在那里被修复了。如果您第一次发现供应商内核的问题， + 请检查已知最新版本的普通构建是否可以正常运行。 + + * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。大致 + 描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。 + 然后等待进一步的指示。 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +报告只发生在较旧内核版本线的问题 +---------------------------------- + +若您尝试了上述的最新主线内核，但未能在那里复现问题，那么本小节适用于您；以下 +流程有助于使问题在仍然支持的稳定版或长期支持版本线，或者定期基于最新稳定版或 +长期支持内核的供应商内核中得到修复。如果是这种情况，请执行以下步骤： + + * 请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或太 + 冒险，无法移植到那里。 + + * 执行前节“报告稳定版和长期支持内核线的回归”中的前三个步骤。 + + * 在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能会 + 告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表，寻找 + 讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适合支持。 + 如果支持根本不被考虑，加入最新的讨论，询问是否有可能。 + + * 前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题的 + 子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +参考章节：向内核维护者报告问题 +=============================== + +上面的详细指南简要地列出了所有主要步骤，这对大多数人来说应该足够了。但有时， +即使是有经验的用户也可能想知道如何实际执行这些步骤之一。这就是本节的目的， +因为它将提供关于上述每个步骤的更多细节。请将此作为参考文档：可以从头到尾 +阅读它。但它主要是为了浏览和查找如何实际执行这些步骤的详细信息。 + +在深入挖掘细节之前，我想先给你一些一般性建议： + + * Linux内核开发人员很清楚这个过程很复杂，比其他的FLOSS项目要求更多。我们很 + 希望让它更简单。但这需要在不同的地方以及一些基础设施上付诸努力，这些基础 + 设施需要持续的维护；尚未有人站出来做这些工作，所以目前情况就是这样。 + + * 与某些供应商签订的保证或支持合同并不能使您有权要求上游Linux内核社区的开 + 发人员进行修复：这样的合同完全在Linux内核、其开发社区和本文档的范围之外。 + 这就是为什么在这种情况下，你不能要求任何契约保证，即使开发人员处理的问 + 题对供应商有效。如果您想主张您的权利，使用供应商的支持渠道代替。当这样做 + 的时候，你可能想提出你希望看到这个问题在上游Linux内核中修复；可以这是确 + 保最终修复将被纳入所有Linux发行版的唯一方法来鼓励他们。 + + * 如果您从未向FLOSS项目报告过任何问题，那么您应该考虑阅读 `如何有效地报告 + 缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何 + 以明智的方式提问 <http://www.catb.org/esr/faqs/smart-questions.html>`_ ， + 和 `如何提出好问题 <https://jvns.ca/blog/good-questions/>`_ 。 + +解决这些问题之后，可以在下面找到如何正确地向Linux内核报告问题的详细信息。 + + +确保您使用的是上游Linux内核 +---------------------------- + + *您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅 + 读本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。 + 寻找和解决问题往往需要后者。* + +与大多数程序员一样，Linux内核开发人员不喜欢花时间处理他们维护的源代码中根本 +不会发生的问题的报告。这只会浪费每个人的时间，尤其是你的时间。不幸的是，当 +涉及到内核时，这样的情况很容易发生，并且常常导致双方气馁。这是因为几乎所有预 +装在设备（台式机、笔记本电脑、智能手机、路由器等）上的Linux内核，以及大多数 +由Linux发行商提供的内核，都与由kernel.org发行的官方Linux内核相距甚远：从Linux +开发的角度来看，这些供应商提供的内核通常是古老的或者经过了大量修改，通常两点 +兼具。 + +大多数供应商内核都不适合用来向Linux内核开发人员报告问题：您在其中遇到的问题 +可能已经由Linux内核开发人员在数月或数年前修复；此外，供应商的修改和增强可能 +会导致您面临的问题，即使它们看起来很小或者完全不相关。这就是为什么您应该向 +供应商报告这些内核的问题。它的开发者应该查看报告，如果它是一个上游问题，直接 +于上游修复或将报告转发到那里。在实践中，这有时行不通。因此，您可能需要考虑 +通过自己安装最新的Linux内核内核来绕过供应商。如果如果您选择此方法，那么本指 +南后面的步骤将解释如何在排除了其他可能导致您的问题的原因后执行此操作。 + +注意前段使用的词语是“大多数”，因为有时候开发人员实际上愿意处理供应商内核出现 +的问题报告。他们是否这么做很大程度上取决于开发人员和相关问题。如果发行版只 +根据最近的Linux版本对内核进行了较小修改，那么机会就比较大；例如对于Debian +GNU/Linux Sid或Fedora Rawhide所提供的主线内核。一些开发人员还将接受基于最新 +稳定内核的发行版内核问题报告，只要它改动不大；例如Arch Linux、常规Fedora版本 +和openSUSE Turboweed。但是请记住，您最好使用主线Linux，并避免在此流程中使用 +稳定版内核，如“安装一个新的内核进行测试”一节中所详述。 + +当然，您可以忽略所有这些建议，并向上游Linux开发人员报告旧的或经过大量修改的 +供应商内核的问题。但是注意，这样的报告经常被拒绝或忽视，所以自行小心考虑一下。 +不过这还是比根本不报告问题要好：有时候这样的报告会直接或间接地帮助解决之后的 +问题。 + + +搜索现有报告（第一部分） +------------------------- + + *使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查Linux内核 + 邮件列表（LKML）的存档。如果找到匹配的报告，请加入讨论而不是发送新报告。* + +报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告人的你。 +所以彻底检查是否有人已经报告了这个问题，这对你自己是有利的。在流程中的这一步， +可以只执行一个粗略的搜索：一旦您知道您的问题需要报告到哪里，稍后的步骤将告诉 +您如何详细搜索。尽管如此，不要仓促完成这一步，它可以节省您的时间和减少麻烦。 + +只需先用你最喜欢的搜索引擎在互联网上搜索。然后再搜索Linux内核邮件列表（LKML） +存档。 + +如果搜索结果实在太多，可以考虑让你的搜索引擎将搜索时间范围限制在过去的一个 +月或一年。而且无论你在哪里搜索，一定要用恰当的搜索关键词；也要变化几次关键 +词。同时，试着从别人的角度看问题：这将帮助你想出其他的关键词。另外，一定不 +要同时使用过多的关键词。记住搜索时要同时尝试包含和不包含内核驱动程序的名称 +或受影响的硬件组件的名称等信息。但其确切的品牌名称（比如说“华硕红魔 Radeon +RX 5700 XT Gaming OC”）往往帮助不大，因为它太具体了。相反，尝试搜索术语，如 +型号（Radeon 5700 或 Radeon 5000）和核心代号（“Navi”或“Navi10”），以及包含 +和不包含其制造商（“AMD”）。 + +如果你发现了关于你的问题的现有报告，请加入讨论，因为你可能会提供有价值的额 +外信息。这一点很重要，即使是在修复程序已经准备好或处于最后阶段，因为开发人 +员可能会寻找能够提供额外信息或测试建议修复程序的人。跳到“发布报告后的责任” +一节，了解有关如何正确参与的细节。 + +注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 网站可能 +也是一个好主意，因为这可能会提供有价值的见解或找到匹配的报告。如果您发现后者， +请记住：大多数子系统都希望在不同的位置报告，如下面“你需要将问题报告到何处” +一节中所述。因此本应处理这个问题的开发人员甚至可能不知道bugzilla的工单。所以 +请检查工单中的问题是否已经按照本文档所述得到报告，如果没有，请考虑这样做。 + +高优先级的问题？ +----------------- + + *看看你正在处理的问题是否是回归问题、安全问题或非常严重的问题：这些都是 + 需要在接下来的一些步骤中特别处理的“高优先级问题”。* + +Linus Torvalds和主要的Linux内核开发人员希望看到一些问题尽快得到解决，因此在 +报告过程中有一些“高优先级问题”的处理略有不同。有三种情况符合条件:回归、安全 +问题和非常严重的问题。 + +如果在旧版本的Linux内核中工作的东西不能在新版本的Linux内核中工作，或者某种 +程度上在新版本的Linux内核中工作得更差，那么你就需要处理“回归”。因此，当一个 +在Linux 5.7中表现良好的WiFi驱动程序在5.8中表现不佳或根本不能工作时，这是一 +种回归。如果应用程序在新的内核中出现不稳定的现象，这也是一种回归，这可能是 +由于内核和用户空间之间的接口（如procfs和sysfs）发生不兼容的更改造成的。显著 +的性能降低或功耗增加也可以称为回归。但是请记住:新内核需要使用与旧内核相似的 +配置来构建（参见下面如何实现这一点）。这是因为内核开发人员在实现新特性时有 +时无法避免不兼容性；但是为了避免回归，这些特性必须在构建配置期间显式地启用。 + +什么是安全问题留给您自己判断。在继续之前，请考虑阅读 +“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”， +因为它提供了如何最恰当地处理安全问题的额外细节。 + +当发生了完全无法接受的糟糕事情时，此问题就是一个“非常严重的问题”。例如， +Linux内核破坏了它处理的数据或损坏了它运行的硬件。当内核突然显示错误消息 +（“kernel panic”）并停止工作，或者根本没有任何停止信息时，您也在处理一个严重 +的问题。注意：不要混淆“panic”（内核停止自身的致命错误）和“Oops”（可恢复错误）， +因为显示后者之后内核仍然在运行。 + + +确保环境健康 +-------------- + + *确保不是内核所处环境导致了你所面临的问题。* + +看起来很像内核问题的问题有时是由构建或运行时环境引起的。很难完全排除这种问 +题，但你应该尽量减少这种问题： + + * 构建内核时，请使用经过验证的工具，因为编译器或二进制文件中的错误可能会导 + 致内核出现错误行为。 + + * 确保您的计算机组件在其设计规范内运行；这对处理器、内存和主板尤为重要。因 + 此，当面临潜在的内核问题时，停止低电压或超频。 + + * 尽量确保不是硬件故障导致了你的问题。例如，内存损坏会导致大量的问题，这些 + 问题会表现为看起来像内核问题。 + + * 如果你正在处理一个文件系统问题，你可能需要用 ``fsck`` 检查一下文件系统， + 因为它可能会以某种方式被损坏，从而导致无法预期的内核行为。 + + * 在处理回归问题时，要确保没有在更新内核的同时发生了其他变化。例如，这个问 + 题可能是由同时更新的其他软件引起的。也有可能是在你第一次重启进入新内核时， + 某个硬件巧合地坏了。更新系统 BIOS 或改变 BIOS 设置中的某些内容也会导致 + 一些看起来很像内核回归的问题。 + + +为紧急情况做好准备 +------------------- + + *创建一个全新的备份，并将系统修复和还原工具放在手边* + +我得提醒您，您正在和计算机打交道，计算机有时会出现意想不到的事情，尤其是当 +您折腾其操作系统的内核等关键部件时。而这就是你在这个过程中要做的事情。因此， +一定要创建一个全新的备份；还要确保你手头有修复或重装操作系统的所有工具， +以及恢复备份所需的一切。 + + +确保你的内核不会被增强 +------------------------ + + *确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解 + 决方案可能在您不知情的情况下就在本地进行了这样的工作。* + +如果内核以任何方式得到增强，那么问题报告被忽略或拒绝的风险就会急剧增加。这就 +是为什么您应该删除或禁用像akmods和DKMS这样的机制：这些机制会自动构建额外内核 +模块，例如当您安装新的Linux内核或第一次引导它时。也要记得同时删除他们可能安装 +的任何模块。然后重新启动再继续。 + +注意，你可能不知道你的系统正在使用这些解决方案之一：当你安装 Nvidia 专有图 +形驱动程序、VirtualBox 或其他需要 Linux 内核以外的模块支持的软件时，它们通 +常会静默设置。这就是为什么你可能需要卸载这些软件的软件包，以摆脱任何第三方 +内核模块。 + + +检查“污染”标志 +---------------- + + *当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可 + 能会导致您面临的问题。* + +当某些可能会导致看起来完全不相关的后续错误的事情发生时，内核会用“污染 +（taint）”标志标记自己。如果您的内核受到污染，那么您面临的可能是这样的错误。 +因此在投入更多时间到这个过程中之前，尽早排除此情况可能对你有好处。这是这个 +步骤出现在这里的唯一原因，因为这个过程稍后会告诉您安装最新的主线内核；然后 +您将需要再次检查污染标志，因为当它出问题的时候内核报告会关注它。 + +在正在运行的系统上检查内核是否污染非常容易：如果 ``cat /proc/sys/kernel/tainted`` +返回“0”，那么内核没有被污染，一切正常。在某些情况下无法检查该文件；这就是 +为什么当内核报告内部问题（“kernel bug”）、可恢复错误（“kernel Oops”）或停止 +操作前不可恢复的错误（“kernel panic”）时，它也会提到污染状态。当其中一个错 +误发生时，查看打印的错误消息的顶部，搜索以“CPU:”开头的行。如果发现问题时内 +核未被污染，那么它应该以“Not infected”结束；如果你看到“Tainted:”且后跟一些 +空格和字母，那就被污染了。 + +如果你的内核被污染了，请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst” +以找出原因。设法消除污染因素。通常是由以下三种因素之一引起的： + + 1. 发生了一个可恢复的错误（“kernel Oops”），内核污染了自己，因为内核知道在 + 此之后它可能会出现奇怪的行为错乱。在这种情况下，检查您的内核或系统日志， + 并寻找以下列文字开头的部分:: + + Oops: 0000 [#1] SMP + + 如方括号中的“#1”所示，这是自启动以来的第一次Oops。每个Oops和此后发生的 + 任何其他问题都可能是首个Oops的后续问题，即使这两个问题看起来完全不相关。 + 通过消除首个Oops的原因并在之后复现该问题，可以排除这种情况。有时仅仅 + 重新启动就足够了，有时更改配置后重新启动可以消除Oops。但是在这个流程中 + 不要花费太多时间在这一点上，因为引起Oops的原因可能已经在您稍后将按流程 + 安装的新Linux内核版本中修复了。 + + 2. 您的系统使用的软件安装了自己的内核模块，例如Nvidia的专有图形驱动程序或 + VirtualBox。当内核从外部源（即使它们是开源的）加载此类模块时，它会污染 + 自己：它们有时会在不相关的内核区域导致错误，从而可能导致您面临的问题。 + 因此，当您想要向Linux内核开发人员报告问题时，您必须阻止这些模块加载。 + 大多数情况下最简单的方法是：临时卸载这些软件，包括它们可能已经安装的任 + 何模块。之后重新启动。 + + 3. 当内核加载驻留在Linux内核源代码staging树中的模块时，它也会污染自身。这 + 是一个特殊的区域，代码（主要是驱动程序）还没有达到正常Linux内核的质量 + 标准。当您报告此种模块的问题时，内核受到污染显然是没有问题的；只需确保 + 问题模块是造成污染的唯一原因。如果问题发生在一个不相关的区域，重新启动 + 并通过指定 ``foo.blacklist=1`` 作为内核参数临时阻止该模块被加载（用有 + 问题的模块名替换“foo”）。 + + +记录如何重现问题 +------------------ + + *粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写 + 注释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需 + 要分别报告给内核开发人员，除非它们严重纠缠在一起。* + +如果你同时处理多个问题，必须分别报告每个问题，因为它们可能由不同的开发人员 +处理。在一份报告中描述多种问题，也会让其他人难以将其分开。因此只有在问题严 +重纠缠的情况下，才能将问题合并在一份报告中。 + +此外，在报告过程中，你必须测试该问题是否发生在其他内核版本上。因此，如果您 +知道如何在一个新启动的系统上快速重现问题，将使您的工作更加轻松。 + +注意：报告只发生过一次的问题往往是没有结果的，因为它们可能是由于宇宙辐射导 +致的位翻转。所以你应该尝试通过重现问题来排除这种情况，然后再继续。如果你有 +足够的经验来区分由于硬件故障引起的一次性错误和难以重现的罕见内核问题，可以 +忽略这个建议。 + + +稳定版或长期支持内核的回归？ +----------------------------- + + *如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。* + +稳定版和长期支持内核版本线中的回归是Linux开发人员非常希望解决的问题，这样的 +问题甚至比主线开发分支中的回归更不应出现，因为它们会很快影响到很多人。开发人员 +希望尽快了解此类问题，因此有一个简化流程来报告这些问题。注意，使用更新内核版 +本线的回归（比如从5.9.15切换到5.10.5时出现故障）不符合条件。 + + +你需要将问题报告到何处 +------------------------ + + *定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式 + 和位置。注意：大多数情况下不会是bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。* + +将报告发送给合适的人是至关重要的，因为Linux内核是一个大项目，大多数开发人员 +只熟悉其中的一小部分。例如，相当多的程序员只关心一个驱动程序，比如一个WiFi +芯片驱动程序；它的开发人员可能对疏远的或不相关的“子系统”（如TCP堆栈、 +PCIe/PCI子系统、内存管理或文件系统）的内部知识了解很少或完全不了解。 + +问题在于：Linux内核缺少一个，可以简单地将问题归档并让需要了解它的开发人员了 +解它的，中心化缺陷跟踪器。这就是为什么你必须找到正确的途径来自己报告问题。 +您可以在脚本的帮助下做到这一点（见下文），但它主要针对的是内核开发人员和专 +家。对于其他人来说，MAINTAINERS（维护人员）文件是更好的选择。 + +如何阅读MAINTAINERS维护者文件 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +为了说明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，让我们假设您的笔记 +本电脑中的WiFi在更新内核后突然出现了错误行为。这种情况下可能是WiFi驱动的问 +题。显然，它也可能由于驱动基于的某些代码，但除非你怀疑有这样的东西会附着在 +驱动程序上。如果真的是其他的问题，驱动程序的开发人员会让合适的人参与进来。 + +遗憾的是，没有通用且简单的办法来检查哪个代码驱动了特定硬件组件。 + +在WiFi驱动出现问题的情况下，你可能想查看 ``lspci -k`` 的输出，因为它列出了 +PCI/PCIe总线上的设备和驱动它的内核模块:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +但如果你的WiFi芯片通过USB或其他内部总线连接，这种方法就行不通了。在这种情况 +下，您可能需要检查您的WiFi管理器或 ``ip link`` 的输出。寻找有问题的网络接口 +的名称，它可能类似于“wlp58s0”。此名称可以用来找到驱动它的模块:: + + [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module + ath10k_pci + +如果这些技巧不能进一步帮助您，请尝试在网上搜索如何缩小相关驱动程序或子系统 +的范围。如果你不确定是哪一个：试着猜一下，即使你猜得不好，也会有人会帮助你 +的。 + +一旦您知道了相应的驱动程序或子系统，您就希望在MAINTAINERS文件中搜索它。如果 +是“ath10k_pci”，您不会找到任何东西，因为名称太具体了。有时你需要在网上寻找 +帮助；但在此之前，请尝试使用一个稍短或修改过的名称来搜索MAINTAINERS文件，因 +为这样你可能会发现类似这样的东西:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human <shuman@example.com> + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + Files: drivers/net/wireless/ath/ath10k/ + +注意：如果您阅读在Linux源代码树的根目录中找到的原始维护者文件，则行描述将是 +缩写。例如，“Mail:（邮件）”将是“M:”，“Mailing list:（邮件列表）”将是“L”， +“Status:（状态）”将是“S:”。此文件顶部有一段解释了这些和其他缩写。 + +首先查看“Status”状态行。理想情况下，它应该得到“Supported（支持）”或 +“Maintained（维护）”。如果状态为“Obsolete（过时的）”，那么你在使用一些过时的 +方法，需要转换到新的解决方案上。有时候，只有在感到有动力时，才会有人为代码 +提供“Odd Fixes”。如果碰见“Orphan”，你就完全不走运了，因为再也没有人关心代码 +了，只剩下这些选项:准备好与问题共存，自己修复它，或者找一个愿意修复它的程序员。 + +检查状态后，寻找以“bug:”开头的一行：它将告诉你在哪里可以找到子系统特定的缺 +陷跟踪器来提交你的问题。上面的例子没有此行。大多数部分都是这样，因为 Linux +内核的开发完全是由邮件驱动的。很少有子系统使用缺陷跟踪器，且其中只有一部分 +依赖于 bugzilla.kernel.org。 + +在这种以及其他很多情况下，你必须寻找以“Mail:”开头的行。这些行提到了特定代码 +的维护者的名字和电子邮件地址。也可以查找以“Mailing list:”开头的行，它告诉你 +开发代码的公共邮件列表。你的报告之后需要通过邮件发到这些地址。另外，对于所有 +通过电子邮件发送的问题报告，一定要抄送 Linux Kernel Mailing List（LKML） +<linux-kernel@vger.kernel.org>。在以后通过邮件发送问题报告时，不要遗漏任何 +一个邮件列表!维护者都是大忙人，可能会把一些工作留给子系统特定列表上的其他开 +发者；而 LKML 很重要，因为需要一个可以找到所有问题报告的地方。 + + +借助脚本找到维护者 +~~~~~~~~~~~~~~~~~~~~ + +对于手头有Linux源码的人来说，有第二个可以找到合适的报告地点的选择：脚本 +“scripts/get_maintainer.pl”，它尝试找到所有要联系的人。它会查询MAINTAINERS +文件，并需要用相关源代码的路径来调用。对于编译成模块的驱动程序，经常可以用 +这样的命令找到:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko + +将其中的部分内容传递给脚本:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +不要把你的报告发给所有的人。发送给维护者，脚本称之为“supporter:”；另外抄送 +代码最相关的邮件列表，以及 Linux 内核邮件列表（LKML）。在此例中，你需要将报 +告发送给 “Some Human <shuman@example.com>” ，并抄送 +“ath10k@lists.infradead.org”和“linux-kernel@vger.kernel.org”。 + +注意：如果你用 git 克隆了 Linux 源代码，你可能需要用--git 再次调用 +get_maintainer.pl。脚本会查看提交历史，以找到最近哪些人参与了相关代码的编写， +因为他们可能会提供帮助。但要小心使用这些结果，因为它很容易让你误入歧途。 +例如，这种情况常常会发生在很少被修改的地方（比如老旧的或未维护的驱动程序）： +有时这样的代码会在树级清理期间被根本不关心此驱动程序的开发者修改。 + + +搜索现有报告（第二部分） +-------------------------- + + *在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果找到匹配的报告，请加入讨论而不是发送新报告。* + +如前所述：报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告 +人的你。这就是为什么你应该再次搜索现有的报告。现在你已经知道问题需要报告到哪里。 +如果是邮件列表，那么一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以 +找到相应存档。 + +但有些列表运行在其他地方。例如前面步骤中当例子的ath10k WiFi驱动程序就是这种 +情况。但是你通常可以在网上很容易地找到这些列表的档案。例如搜索“archive +ath10k@lists.infradead.org”，将引导您到ath10k邮件列表的信息页，该页面顶部链接 +到其 `列表存档 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遗憾的是， +这个列表和其他一些列表缺乏搜索其存档的功能。在这种情况下可以使用常规的互联网 +搜索引擎，并添加类似“site:lists.infadead.org/pipermail/ath10k/”这 +样的搜索条件，这会把结果限制在该链接中的档案。 + +也请进一步搜索网络、LKML和bugzilla.kernel.org网站。 + +有关如何搜索以及在找到匹配报告时如何操作的详细信息，请参阅上面的“搜索现有报告 +（第一部分）”。 + +不要急着完成报告过程的这一步：花30到60分钟甚至更多的时间可以为你和其他人节省 / +减少相当多的时间和麻烦。 + + +安装一个新的内核进行测试 +-------------------------- + + *除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在 + 某些情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案； + 在合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。 + 无论你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告 + 被拒绝或忽略的风险。* + +正如第一步的详细解释中所提到的：与大多数程序员一样，与大多数程序员一样，Linux +内核开发人员不喜欢花时间处理他们维护的源代码中根本不会发生的问题的报告。这只 +会浪费每个人的时间，尤其是你的时间。这就是为什么在报告问题之前，您必须先确认 +问题仍然存在于最新的上游代码中，这符合每个人的利益。您可以忽略此建议，但如前 +所述：这样做会极大地增加问题报告被拒绝或被忽略的风险。 + +内核“最新上游”的范围通常指： + + * 安装一个主线内核；最新的稳定版内核也可以是一个选择，但大多数时候都最好避免。 + 长期支持内核（有时称为“LTS内核”）不适合此流程。下一小节将更详细地解释所有 + 这些。 + + * 下一小节描述获取和安装这样一个内核的方法。它还指出了使用预编译内核是可以的， + 但普通的内核更好，这意味着：它是直接使用从 `kernel.org <https://kernel.org/>`_ + 获得的Linux源代码构建并且没有任何方式修改或增强。 + + +选择适合测试的版本 +~~~~~~~~~~~~~~~~~~~~ + +前往 `kernel.org <https://kernel.org/>`_ 来决定使用哪个版本。忽略那个写着 +“Latest release最新版本”的巨大黄色按钮，往下看有一个表格。在表格的顶部，你会 +看到一行以“mainline”开头的字样，大多数情况下它会指向一个版本号类似“5.8-rc2” +的预发布版本。如果是这样的话，你将需要使用这个主线内核进行测试。不要让“rc” +吓到你，这些“开发版内核”实际上非常可靠——而且你已经按照上面的指示做了备份， +不是吗？ + +大概每九到十周，“mainline”可能会给你指出一个版本号类似“5.7”的正式版本。如果 +碰见这种情况，请考虑暂停报告过程，直到下一个版本的第一个预发布（5.8-rc1）出 +现在 `kernel.org <https://kernel.org/>`_ 上。这是因为 Linux 的开发周期正在 +两周的“合并窗口”内。大部分的改动和所有干扰性的改动都会在这段时间内被合并到 +下一个版本中。在此期间使用主线是比较危险的。内核开发者通常也很忙，可能没有 +多余的时间来处理问题报告。这也是很有可能在合并窗口中应用了许多修改来修复你 +所面临的问题；这就是为什么你很快就得用一个新的内核版本重新测试，就像下面“发 +布报告后的责任”一节中所述的那样。 + +这就是为什么要等到合并窗口结束后才去做。但是如果你处理的是一些不应该等待的 +东西，则无需这样做。在这种情况下，可以考虑通过 git 获取最新的主线内核（见下 +文），或者使用 kernel.org 上提供的最新稳定版本。如果 mainline 因为某些原因 +不无法正常工作，那么使用它也是可以接受的。总的来说：用它来重现问题也比完全 +不报告问题要好。 + +最好避免在合并窗口外使用最新的稳定版内核，因为所有修复都必须首先应用于主线。 +这就是为什么检查最新的主线内核是如此重要：你希望看到在旧版本线修复的任何问题 +需要先在主线修复，然后才能得到回传，这可能需要几天或几周。另一个原因是：您 +希望的修复对于回传来说可能太难或太冒险；因此再次报告问题不太可能改变任何事情。 + +这些方面也部分表明了为什么长期支持内核（有时称为“LTS内核”）不适合报告流程： +它们与当前代码的距离太远。因此，先去测试主线，然后再按流程走：如果主线没有 +出现问题，流程将指导您如何在旧版本线中修复它。 + +如何获得新的 Linux 内核 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +你可以使用预编译或自编译的内核进行测试；如果你选择后者，可以使用 git 获取源 +代码，或者下载其 tar 存档包。 + +**使用预编译的内核** ：这往往是最快速、最简单、最安全的方法——尤其是在你不熟 +悉 Linux 内核的情况下。问题是：发行商或附加存储库提供的大多数版本都是从修改 +过的Linux源代码构建的。因此它们不是普通的，通常不适合于测试和问题报告：这些 +更改可能会导致您面临的问题或以某种方式影响问题。 + +但是如果您使用的是流行的Linux发行版，那么您就很幸运了：对于大部分的发行版， +您可以在网上找到包含最新主线或稳定版本Linux内核包的存储库。使用这些是完全可 +以的，只要从存储库的描述中确认它们是普通的或者至少接近普通。此外，请确保软件 +包包含kernel.org上提供的最新版本内核。如果这些软件包的时间超过一周，那么它们 +可能就不合适了，因为新的主线和稳定版内核通常至少每周发布一次。 + +请注意，您以后可能需要手动构建自己的内核：有时这是调试或测试修复程序所必需的， +如后文所述。还要注意，预编译的内核可能缺少在出现panic、Oops、warning或BUG时 +解码内核打印的消息所需的调试符号；如果您计划解码这些消息，最好自己编译内核 +（有关详细信息，请参阅本小节结尾和“解码失败信息”小节）。 + +**使用git** ：熟悉 git 的开发者和有经验的 Linux 用户通常最好直接从 +`kernel.org 上的官方开发仓库 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ +中获取最新的 Linux 内核源代码。这些很可能比最新的主线预发布版本更新一些。不 +用担心：它们和正式的预发布版本一样可靠，除非内核的开发周期目前正处于合并窗 +口中。不过即便如此，它们也是相当可靠的。 + +**常规方法** ：不熟悉 git 的人通常最好从 `kernel.org <https://kernel.org/>`_ +下载源码的tar 存档包。 + +如何实际构建一个内核并不在这里描述，因为许多网站已经解释了必要的步骤。如果 +你是新手，可以考虑按照那些建议使用 ``make localmodconfig`` 来做，它将尝试获 +取你当前内核的配置，然后根据你的系统进行一些调整。这样做并不能使编译出来的 +内核更好，但可以更快地编译。 + +注意：如果您正在处理来自内核的pannc、Oops、warning或BUG，请在配置内核时尝试 +启用 CONFIG_KALLSYMS 选项。此外，还可以启用 CONFIG_DEBUG_KERNEL 和 +CONFIG_DEBUG_INFO；后者是相关选项，但只有启用前者才能开启。请注意， +CONFIG_DEBUG_INFO 会需要更多储存空间来构建内核。但这是值得的，因为这些选项将 +允许您稍后精确定位触发问题的确切代码行。下面的“解码失败信息”一节对此进行了更 +详细的解释。 + +但请记住：始终记录遇到的问题，以防难以重现。发送未解码的报告总比不报告要好。 + + +检查“污染”标志 +---------------- + + *确保您刚刚安装的内核在运行时不会“污染”自己。* + +正如上面已经详细介绍过的：当发生一些可能会导致一些看起来完全不相关的后续错 +误的事情时，内核会设置一个“污染”标志。这就是为什么你需要检查你刚刚安装的内 +核是否有设置此标志。如果有的话，几乎在任何情况下你都需要在报告问题之前先消 +除它。详细的操作方法请看上面的章节。 + + +用新内核重现问题 +------------------ + + *在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。* + +检查这个问题是否发生在你刚刚安装的新 Linux 内核版本上。如果新内核已经修复了， +可以考虑使用此版本线，放弃报告问题。但是请记住，只要它没有在 `kernel.org +<https://kernel.org/>`_ 的稳定版和长期版（以及由这些版本衍生出来的厂商内核） +中得到修复，其他用户可能仍然会受到它的困扰。如果你喜欢使用其中的一个，或 +者只是想帮助它们的用户，请前往下面的“报告只发生在较旧内核版本线的问题”一节。 + + +优化复现问题的描述 +-------------------- + + *优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所 + 有重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到 + 了一些东西，请考虑再次搜索关于该问题的现有报告。* + +过于复杂的报告会让别人很难理解。因此请尽量找到一个可以直接描述、易于以书面 +形式理解的再现方法。包含所有重要的细节，但同时也要尽量保持简短。 + +在这在前面的步骤中，你很可能已经了解了一些关于你所面临的问题的点。利用这些 +知识，再次搜索可以转而加入的现有报告。 + + +解码失败信息 +------------- + + *如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找 + 触发错误的代码行。* + +当内核检测到内部问题时，它会记录一些有关已执行代码的信息。这使得在源代码中精 +确定位触发问题的行并显示如何调用它成为可能。但只有在配置内核时启用了 +CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS选项时，这种方法才起效。如果已启用此选项， +请考虑解码内核日志中的信息。这将使我们更容易理解是什么导致了“panic”、“Oops”、 +“warning”或“BUG”，从而增加了有人提供修复的几率。 + +解码可以通过Linux源代码树中的脚本来完成。如果您运行的内核是之前自己编译的， +这样这样调用它:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +如果您运行的是打包好的普通内核，则可能需要安装带有调试符号的相应包。然后按以下 +方式调用脚本（如果发行版未打包，则可能需要从Linux源代码获取）:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +脚本将解码如下的日志行，这些日志行显示内核在发生错误时正在执行的代码的地址:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +解码之后，这些行将变成这样:: + + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module + +在本例中，执行的代码是从文件“~/linux-5.10.5/test-module/test-module.c”构建的， +错误出现在第16行的指令中。 + +该脚本也会如此解码以“Call trace”开头的部分中提到的地址，该部分显示出现问题的 +函数的路径。此外，脚本还会显示内核正在执行的代码部分的汇编输出。 + +注意，如果你没法做到这一点，只需跳过这一步，并在报告中说明原因。如果你幸运的 +话，可能无需解码。如果需要的话，也许有人会帮你做这件事情。还要注意，这只是解 +码内核堆栈跟踪的几种方法之一。有时需要采取不同的步骤来检索相关的详细信息。 +别担心，如果您碰到的情况需要这样做，开发人员会告诉您该怎么做。 + + +对回归的特别关照 +----------------- + + *如果您的问题是回归问题，请尽可能缩小引入问题时的范围。* + +Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这就是为什么他 +认为回归是不可接受的，并希望看到它们被迅速修复。这就是为什么引入了回归的改 +动导致的问题若无法通过其他方式快速解决，通常会被迅速撤销。因此，报告回归有 +点像“王炸”，会迅速得到修复。但要做到这一点，需要知道导致回归的变化。通常情 +况下，要由报告者来追查罪魁祸首，因为维护者往往没有时间或手头设置不便来自行 +重现它。 + +有一个叫做“二分”的过程可以来寻找变化，这在 +“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”文档中进行了详细 +的描述，这个过程通常需要你构建十到二十个内核镜像，每次都尝试在构建下一个镜像 +之前重现问题。是的，这需要花费一些时间，但不用担心，它比大多数人想象的要快得多。 +多亏了“binary search二进制搜索”，这将引导你在源代码管理系统中找到导致回归的提交。 +一旦你找到它，就在网上搜索其主题、提交ID和缩短的提交ID（提交ID的前12个字符）。 +如果有的话，这将引导您找到关于它的现有报告。 + +需要注意的是，二分法需要一点窍门，不是每个人都懂得诀窍，也需要相当多的努力， +不是每个人都愿意投入。尽管如此，还是强烈建议自己进行一次二分。如果你真的 +不能或者不想走这条路，至少要找出是哪个主线内核引入的回归。比如说从 5.5.15 +切换到 5.8.4 的时候出现了一些问题，那么至少可以尝试一下相近的所有的主线版本 +（5.6、5.7 和 5.8）来检查它是什么时候出现的。除非你想在一个稳定版或长期支持 +内核中找到一个回归，否则要避免测试那些编号有三段的版本（5.6.12、5.7.8），因 +为那会使结果难以解释，可能会让你的测试变得无用。一旦你找到了引入回归的主要 +版本，就可以放心地继续报告了。但请记住：在不知道罪魁祸首的情况下，开发人员 +是否能够提供帮助取决于手头的问题。有时他们可能会从报告中确认是什么出现了问 +题，并能修复它；有时他们可能无法提供帮助，除非你进行二分。 + +当处理回归问题时，请确保你所面临的问题真的是由内核引起的，而不是由其他东西 +引起的，如上文所述。 + +在整个过程中，请记住：只有当旧内核和新内核的配置相似时，问题才算回归。最好 +的方法是：把配置文件（``.config``）从旧的工作内核直接复制到你尝试的每个新内 +核版本。之后运行 ``make oldnoconfig`` 来调整它以适应新版本的需要，而不启用 +任何新的功能，因为那些功能也可能导致回归。 + + +撰写并发送报告 +--------------- + + *通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新 + 内核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内 + 核构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。 + 包含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` + 的输出。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概 + 述问题和影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。 + 现在给出一个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的 + 那样发送或提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面 + “高优先级问题的特殊处理”所述特别关照。* + +现在你已经准备好了一切，是时候写你的报告了。上文前言中链接的三篇文档对如何 +写报告做了部分解释。这就是为什么本文将只提到一些基本的内容以及 Linux 内核特 +有的东西。 + +有一点是符合这两类的：你的报告中最关键的部分是标题/主题、第一句话和第一段。 +开发者经常会收到许多邮件。因此，他们往往只是花几秒钟的时间浏览一下邮件，然 +后再决定继续下一封或仔细查看。因此，你报告的开头越好，有人研究并帮助你的机 +会就越大。这就是为什么你应该暂时忽略他们，先写出详细的报告。;-) + +每份报告都应提及的事项 +~~~~~~~~~~~~~~~~~~~~~~~~ + +详细描述你的问题是如何发生在你安装的新纯净内核上的。试着包含你之前写的和优 +化过的分步说明，概述你和其他人如何重现这个问题；在极少数无法重现的情况下， +尽量描述你做了什么来触发它。 + +还应包括其他人为了解该问题及其环境而可能需要的所有相关信息。实际需要的东西 +在很大程度上取决于具体问题，但有些事项你总是应该包括在内： + + * ``cat /proc/version`` 的输出，其中包含 Linux 内核版本号和构建时的编译器。 + + * 机器正在运行的 Linux 发行版（ ``hostnamectl | grep “Operating System“`` ） + + * CPU 和操作系统的架构（ ``uname -mi`` ） + + * 如果您正在处理回归，并进行了二分，请提及导致回归的变更的主题和提交ID。 + +许多情况下，让读你报告的人多了解两件事也是明智之举： + + * 用于构建 Linux 内核的配置（“.config”文件） + + * 内核的信息，你从 ``dmesg`` 得到的信息写到一个文件里。确保它以像“Linux + version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020”这样的行开始，如果没有，那么第 + 一次启动阶段的重要信息已经被丢弃了。在这种情况下，可以考虑使用 + ``journalctl -b 0 -k`` ；或者你也可以重启，重现这个问题，然后调用 + ``dmesg`` 。 + +这两个文件很大，所以直接把它们放到你的报告中是个坏主意。如果你是在缺陷跟踪 +器中提交问题，那么将它们附加到工单中。如果你通过邮件报告问题，不要用附件附 +上它们，因为那会使邮件变得太大，可以按下列之一做： + + * 将文件上传到某个公开的地方（你的网站，公共文件粘贴服务，在 + `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上创建的工单……）， + 并在你的报告中放上链接。理想情况下请使用允许这些文件保存很多年的地方，因 + 为它们可能在很多年后对别人有用；例如 5 年或 10 年后，一个开发者正在修改 + 一些代码，而这些代码正是为了修复你的问题。 + + * 把文件放在一边，然后说明你会在他人回复时再单独发送。只要记得报告发出去后， + 真正做到这一点就可以了。;-) + +提供这些东西可能是明智的 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +根据问题的不同，你可能需要提供更多的背景数据。这里有一些关于提供什么比较好 +的建议： + + * 如果你处理的是内核的“warning”、“OOPS”或“panic”，请包含它。如果你不能复制 + 粘贴它，试着用netconsole网络终端远程跟踪或者至少拍一张屏幕的照片。 + + * 如果问题可能与你的电脑硬件有关，请说明你使用的是什么系统。例如，如果你的 + 显卡有问题，请提及它的制造商，显卡的型号，以及使用的芯片。如果是笔记本电 + 脑，请提及它的型号名称，但尽量确保意义明确。例如“戴尔 XPS 13”就不很明确， + 因为它可能是 2012 年的那款，那款除了看起来和现在销售的没有什么不同之外， + 两者没有任何共同之处。因此，在这种情况下，要加上准确的型号，例如 2019 + 年内推出的 XPS 13 型号为“9380”或“7390”。像“联想 Thinkpad T590”这样的名字 + 也有些含糊不清：这款笔记本有带独立显卡和不带的子型号，所以要尽量找到准确 + 的型号名称或注明主要部件。 + + * 说明正在使用的相关软件。如果你在加载模块时遇到了问题，你要说明正在使用的 + kmod、systemd 和 udev 的版本。如果其中一个 DRM 驱动出现问题，你要说明 + libdrm 和 Mesa 的版本；还要说明你的 Wayland 合成器或 X-Server 及其驱动。 + 如果你有文件系统问题，请注明相应的文件系统实用程序的版本（e2fsprogs, + btrfs-progs, xfsprogs……）。 + + * 从内核中收集可能有用的额外信息。例如， ``lspci -nn`` 的输出可以帮助别人 + 识别你使用的硬件。如果你的硬件有问题，你甚至可以给出 ``sudo lspci -vvv`` + 的结果，因为它提供了组件是如何配置的信息。对于一些问题，可能最好包含 + ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， + ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的内容。一些子系统还提 + 供了收集相关信息的工具。 ``alsa-info.sh`` `就是这样一个工具，它是音频/声 + 音子系统开发者提供的 <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。 + +这些例子应该会给你一些知识点，让你知道附上什么数据可能是明智的，但你自己也 +要想一想，哪些数据对别人会有帮助。不要太担心忘记一些东西，因为开发人员会要 +求提供他们需要的额外细节。但从一开始就把所有重要的东西都提供出来，会增加别 +人仔细查看的机会。 + + +重要部分：报告的开头 +~~~~~~~~~~~~~~~~~~~~~~ + +现在你已经准备好了报告的详细部分，让我们进入最重要的部分：开头几句。现在到 +报告的最前面，在你刚才写的部分之前加上类似“The detailed description:”（详细 +描述）这样的内容，并在最前面插入两个新行。现在写一个正常长度的段落，大致概 +述这个问题。去掉所有枯燥的细节，把重点放在读者需要知道的关键部分，以让人了 +解这是怎么回事；如果你认为这个缺陷影响了很多用户，就提一下这点来吸引大家关 +注。 + +做好这一点后，在顶部再插入两行，写一句话的摘要，快速解释报告的内容。之后你 +要更加抽象，为报告写一个更短的主题/标题。 + +现在你已经写好了这部分，请花点时间来优化它，因为它是你的报告中最重要的部分： +很多人会先读这部分，然后才会决定是否值得花时间阅读其他部分。 + +现在就像 :ref:`MAINTAINERS <maintainers>` 维护者文件告诉你的那样发送或提交 +报告，除非它是前面概述的那些“高优先级问题”之一：在这种情况下，请先阅读下一 +小节，然后再发送报告。 + +高优先级问题的特殊处理 +~~~~~~~~~~~~~~~~~~~~~~~~ + +高优先级问题的报告需要特殊处理。 + +**非常严重的缺陷** ：确保在主题或工单标题以及第一段中明显标出 severeness +（非常严重的）。 + +**回归** ：如果问题是一个回归，请在邮件的主题或缺陷跟踪器的标题中添加 +[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） +和出现问题的最新版本（比如 5.8）。如果您成功地进行了二分，请注明导致回归 +的提交ID和主题。也请添加该变更的作者到你的报告中；如果您需要将您的缺陷提交 +到缺陷跟踪器中，请将报告以私人邮件的形式转发给他，并注明报告提交地点。 + +**安全问题** ：对于这种问题，你将必须评估：如果细节被公开披露，是否会对其他 +用户产生短期风险。如果不会，只需按照所述继续报告问题。如果有此风险，你需要 +稍微调整一下报告流程。 + + * 如果 MAINTAINERS 文件指示您通过邮件报告问题，请不要抄送任何公共邮件列表。 + + * 如果你应该在缺陷跟踪器中提交问题，请确保将工单标记为“私有”或“安全问题”。 + 如果缺陷跟踪器没有提供保持报告私密性的方法，那就别想了，把你的报告以私人 + 邮件的形式发送给维护者吧。 + +在这两种情况下，都一定要将报告发到 MAINTAINERS 文件中“安全联络”部分列出的 +地址。理想的情况是在发送报告的时候直接抄送他们。如果您在缺陷跟踪器中提交了 +报告，请将报告的文本转发到这些地址；但请在报告的顶部加上注释，表明您提交了 +报告，并附上工单链接。 + +更多信息请参见“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”。 + + +发布报告后的责任 +------------------ + + *等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请 + 公开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个 + 新主线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地 + 提醒一下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。* + +如果你的报告非常优秀，而且你真的很幸运，那么某个开发者可能会立即发现导致问 +题的原因；然后他们可能会写一个补丁来修复、测试它，并直接发送给主线集成，同 +时标记它以便以后回溯到需要它的稳定版和长期支持内核。那么你需要做的就是回复 +一句“Thank you very much”（非常感谢），然后在发布后换上修复好的版本。 + +但这种理想状况很少发生。这就是为什么你把报告拿出来之后工作才开始。你要做的 +事情要视情况而定，但通常会是下面列出的事情。但在深入研究细节之前，这里有几 +件重要的事情，你需要记住这部分的过程。 + + +关于进一步互动的一般建议 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**总是公开回复** ：当你在缺陷跟踪器中提交问题时，一定要在那里回复，不要私下 +联系任何开发者。对于邮件报告，在回复您收到的任何邮件时，总是使用“全部回复” +功能。这包括带有任何你可能想要添加到你的报告中的额外数据的邮件：进入邮件应 +用程序“已发送”文件夹，并在邮件上使用“全部回复”来回复报告。这种方法可以确保 +公共邮件列表和其他所有参与者都能及时了解情况；它还能保持邮件线程的完整性， +这对于邮件列表将所有相关邮件归为一类是非常重要的。 + +只有两种情况不适合在缺陷跟踪器或“全部回复”中发表评论： + + * 有人让你私下发东西。 + + * 你被告知要发送一些东西，但注意到其中包含需要保密的敏感信息。在这种情况下， + 可以私下发送给要求发送的开发者。但要在工单或邮件中注明你是这么做的，这 + 样其他人就知道你尊重了这个要求。 + +**在请求解释或帮助之前先研究一下** ：在这部分过程中，有人可能会告诉你用尚未 +掌握的技能做一些事情。例如你可能会被要求使用一些你从未听说过的测试工具；或 +者你可能会被要求在 Linux 内核源代码上应用一个补丁来测试它是否有帮助。在某些 +情况下，发个回复询问如何做就可以了。但在走这条路之前，尽量通过在互联网上搜 +索自行找到答案；或者考虑在其他地方询问建议。比如询问朋友，或者到你平时常去 +的聊天室或论坛发帖咨询。 + +**要有耐心** ：如果你真的很幸运，你可能会在几个小时内收到对你的报告的答复。 +但大多数情况下会花费更多的时间，因为维护者分散在全球各地，因此可能在不同的 +时区——在那里他们已经享受着远离键盘的夜晚。 + +一般来说，内核开发者需要一到五个工作日来回复报告。有时会花费更长的时间，因 +为他们可能正忙于合并窗口、其他工作、参加开发者会议，或者只是在享受一个漫长 +的暑假。 + +“高优先级的问题”（见上面的解释）例外：维护者应该尽快解决这些问题；这就是为 +什么你应该最多等待一个星期（如果是紧急的事情，则只需两天），然后再发送友好 +的提醒。 + +有时维护者可能没有及时回复；有时候可能会出现分歧，例如一个问题是否符合回归 +的条件。在这种情况下，在邮件列表上提出你的顾虑，并请求其他人公开或私下回复 +如何继续推进。如果失败了，可能应该让更高级别的维护者介入。如果是 WiFi 驱动， +那就是无线维护者；如果没有更高级别的维护者，或者其他一切努力都失败了，那 +这可能是一种罕见的、可以让 Linus Torvalds 参与进来的情况。 + +**主动测试** ：每当一个新的主线内核版本的第一个预发布版本（rc1）发布的时候， +去检查一下这个问题是否得到了解决，或者是否有什么重要的变化。在工单中或在 +回复报告的邮件中提及结果（确保所有参与讨论的人都被抄送）。这将表明你的承诺 +和你愿意帮忙。如果问题持续存在，它也会提醒开发者确保他们不会忘记它。其他一 +些不定期的重新测试（例如用rc3、rc5 和最终版本）也是一个好主意，但只有在相关 +的东西发生变化或者你正在写什么东西的时候才报告你的结果。 + +这些些常规的事情就不说了，我们来谈谈报告后如何帮助解决问题的细节。 + +查询和测试请求 +~~~~~~~~~~~~~~~ + +如果你的报告得到了回复则需履行以下责任： + +**检查与你打交道的人** ：大多数情况下，会是维护者或特定代码区域的开发人员对 +你的报告做出回应。但由于问题通常是公开报告的，所以回复的可能是任何人——包括 +那些想要帮忙的人，但最后可能会用他们的问题或请求引导你完全偏离轨道。这很少 +发生，但这是快速上网搜搜看你正在与谁互动是明智之举的许多原因之一。通过这样 +做，你也可以知道你的报告是否被正确的人听到，因为如果讨论没有导致满意的问题 +解决方案而淡出，之后可能需要提醒维护者（见下文）。 + +**查询数据** ：通常你会被要求测试一些东西或提供更多细节。尽快提供所要求的信 +息，因为你已经得到了可能会帮助你的人的注意，你等待的时间越长就有越可能失去 +关注；如果你不在数个工作日内提供信息，甚至可能出现这种结果。 + +**测试请求** ：当你被要求测试一个诊断补丁或可能的修复时，也要尽量及时测试。 +但要做得恰当，一定不要急于求成：混淆事情很容易发生，这会给所有人带来许多困 +惑。例如一个常见的错误是以为应用了一个带修复的建议补丁，但事实上并没有。即 +使是有经验的测试人员也会偶尔发生这样的事情，但当有修复的内核和没有修复的内 +核表现得一样时，他们大多时候会注意到。 + +当没有任何实质性进展时该怎么办 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有些报告不会得到负有相关责任的 Linux 内核开发者的任何反应；或者围绕这个问题 +的讨论有所发展，但渐渐淡出，没有任何实质内容产出。 + +在这种情况下，要等两个星期（最好是三个星期）后再发出友好的提醒：也许当你的 +报告到达时，维护者刚刚离开键盘一段时间，或者有更重要的事情要处理。在写提醒 +信的时候，要善意地问一下，是否还需要你这边提供什么来让事情推进下去。如果报 +告是通过邮件发出来的，那就在邮件的第一行回复你的初始邮件（见上文），其中包 +括下方的原始报告的完整引用：这是少数几种情况下，这样的“TOFU”（Text Over, +Fullquote Under文字在上，完整引用在下）是正确的做法，因为这样所有的收件人都 +会以适当的顺序立即让细节到手头上来。 + +在提醒之后，再等三周的回复。如果你仍然没有得到适当的反馈，你首先应该重新考 +虑你的方法。你是否可能尝试接触了错误的人？是不是报告也许令人反感或者太混乱， +以至于人们决定完全远离它？排除这些因素的最好方法是：把报告给一两个熟悉 +FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于如何继续推进的建议。 +这可能意味着：准备一份更好的报告，让这些人在你发出去之前对它进行审查。这样 +的方法完全可以；只需说明这是关于这个问题的第二份改进的报告，并附上第一份报 +告的链接。 + +如果报告是恰当的，你可以发送第二封提醒信；在其中询问为什么报告没有得到任何 +回复。第二封提醒邮件的好时机是在新 Linux 内核版本的首个预发布版本（'rc1'） +发布后不久，因为无论如何你都应该在那个时候重新测试并提供状态更新（见上文）。 + +如果第二次提醒的结果又在一周内没有任何反应，可以尝试联系上级维护者询问意见： +即使再忙的维护者在这时候也至少应该发过某种确认。 + +记住要做好失望的准备：理想状况下维护者最好对每一个问题报告做出回应，但他们 +只有义务解决之前列出的“高优先级问题”。所以，如果你得到的回复是“谢谢你的报告， +我目前有更重要的问题要处理，在可预见的未来没有时间去研究这个问题”，那请不 +要太沮丧。 + +也有可能在缺陷跟踪器或列表中进行了一些讨论之后，什么都没有发生，提醒也无助 +于激励大家进行修复。这种情况可能是毁灭性的，但在 Linux 内核开发中确实会发生。 +这些和其他得不到帮助的原因在本文结尾处的“为什么有些问题在被报告后没有得到 +任何回应或者仍然没有修复”中进行了解释。 + +如果你没有得到任何帮助或问题最终没有得到解决，不要沮丧：Linux 内核是 FLOSS， +因此你仍然可以自己帮助自己。例如，你可以试着找到其他受影响的人，和他们一 +起合作来解决这个问题。这样的团队可以一起准备一份新的报告，提到团队有多少人， +为什么你们认为这是应该得到解决的事情。也许你们还可以一起缩小确切原因或引 +入回归的变化，这往往会使修复更容易。而且如果运气好的话，团队中可能会有懂点 +编程的人，也许能写出一个修复方案。 + + + +“报告稳定版和长期支持内核线的回归”的参考 +------------------------------------------ + +本小节提供了在稳定版和长期支持内核线中面对回归时需要执行的步骤的详细信息。 + +确保特定版本线仍然受支持 +~~~~~~~~~~~~~~~~~~~~~~~~~ + + *检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 kernel.org 的 + 首页，确保此特定版本线的最新版没有“[EOL]”标记。* + +大多数内核版本线只支持三个月左右，因为延长维护时间会带来相当多的工作。因此， +每年只会选择一个版本来支持至少两年（通常是六年）。这就是为什么你需要检查 +内核开发者是否还支持你关心的版本线。 + +注意，如果 `kernel.org <https://kernel.org/>`_ 在首页上列出了两个“稳定”版本， +你应该考虑切换到较新的版本，而忘掉较旧的版本：对它的支持可能很快就会结束。 +然后，它将被标记为“生命周期结束”（EOL）。达到这个程度的版本线仍然会在 +`kernel.org <https://kernel.org/>`_ 首页上被显示一两周，但不适合用于测试和 +报告。 + +搜索稳定版邮件列表 +~~~~~~~~~~~~~~~~~~~ + + *检查Linux稳定版邮件列表中的现有报告。* + +也许你所面临的问题已经被发现，并且已经或即将被修复。因此，请在 `Linux 稳定 +版邮件列表的档案 <https://lore.kernel.org/stable/>`_ 中搜索类似问题的报告。 +如果你找到任何匹配的问题，可以考虑加入讨论，除非修复工作已经完成并计划很快 +得到应用。 + +用最新版本复现问题 +~~~~~~~~~~~~~~~~~~~ + + *从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍 + 然存在问题，因为问题可能已经在那里被修复了。* + +在投入更多时间到这个过程中之前，你要检查这个问题是否在你关注的版本线的最新 +版本中已经得到了修复。这个内核需要是纯净的，在问题发生之前不应该被污染，正 +如上面已经在测试主线的过程中详细介绍过的一样。 + +您是否是第一次注意到供应商内核的回归？供应商的更改可能会发生变化。你需要重新 +检查排除来这个问题。当您从5.10.4-vendor.42更新到5.10.5-vendor.43时，记录损坏 +的信息。然后在测试了前一段中所述的最新5.10版本之后，检查Linux 5.10.4的普通版本 +是否也可以正常工作。如果问题在那里出现，那就不符合上游回归的条件，您需要切换 +回主逐步指南来报告问题。 + +报告回归 +~~~~~~~~~~ + + *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。 + 大致描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常 + 的版本。然后等待进一步的指示。* + +当报告在稳定版或长期支持内核线内发生的回归（例如在从5.10.4更新到5.10.5时）， +一份简短的报告足以快速报告问题。因此只需要粗略的描述。 + +但是请注意，如果您能够指明引入问题的确切版本，这将对开发人员有很大帮助。因此 +如果有时间的话，请尝试使用普通内核找到该版本。让我们假设发行版发布Linux内核 +5.10.5到5.10.8的更新时发生了故障。那么按照上面的指示，去检查该版本线中的最新 +内核，比如5.10.9。如果问题出现，请尝试普通5.10.5，以确保供应商应用的补丁不会 +干扰。如果问题没有出现，那么尝试5.10.7，然后直到5.10.8或5.10.6（取决于结果） +找到第一个引入问题的版本。在报告中写明这一点，并指出5.10.9仍然存在故障。 + +前一段基本粗略地概述了“二分”方法。一旦报告出来，您可能会被要求做一个正确的 +报告，因为它允许精确地定位导致问题的确切更改（然后很容易被恢复以快速修复问题）。 +因此如果时间允许，考虑立即进行适当的二分。有关如何详细信息，请参阅“对回归的 +特别关照”部分和文档“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”。 + + +“报告仅在旧内核版本线中发生的问题”的参考 +---------------------------------------- + +本节详细介绍了如果无法用主线内核重现问题，但希望在旧版本线（又称稳定版内核和 +长期支持内核）中修复问题时需要采取的步骤。 + +有些修复太复杂 +~~~~~~~~~~~~~~~ + + *请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或 + 太冒险，无法移植到那里。* + +即使是微小的、看似明显的代码变化，有时也会带来新的、完全意想不到的问题。稳 +定版和长期支持内核的维护者非常清楚这一点，因此他们只对这些内核进行符合 +“Documentation/translations/zh_CN/process/stable-kernel-rules.rst”中所列出的 +规则的修改。 + +复杂或有风险的修改不符合条件，因此只能应用于主线。其他的修复很容易被回溯到 +最新的稳定版和长期支持内核，但是风险太大，无法集成到旧版内核中。所以要注意 +你所希望的修复可能是那些不会被回溯到你所关心的版本线的修复之一。在这种情况 +下，你将别无选择，要么忍受这个问题，要么切换到一个较新的 Linux 版本，除非你 +想自己把修复补丁应用到你的内核中。 + +通用准备 +~~~~~~~~~~ + + *执行上面“报告仅在旧内核版本线中发生的问题”一节中的前三个步骤。* + +您需要执行本指南另一节中已经描述的几个步骤。这些步骤将让您： + + * 检查内核开发人员是否仍然维护您关心的Linux内核版本行。 + + * 在Linux稳定邮件列表中搜索退出的报告。 + + * 检查最新版本。 + + +检查代码历史和搜索现有的讨论 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能 + 会告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表， + 寻找讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适 + 合支持。如果支持根本不被考虑，加入最新的讨论，询问是否有可能。* + +在许多情况下，你所处理的问题会发生在主线上，但已在主线上得到了解决。修正它 +的提交也需要被回溯才能解决这个问题。这就是为什么你要搜索它或任何相关讨论。 + + * 首先尝试在存放 Linux 内核源代码的 Git 仓库中找到修复。你可以通过 + `kernel.org 上的网页 + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ + 或 `GitHub 上的镜像 <https://github.com/torvalds/linux>`_ 来实现；如果你 + 有一个本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 来搜索。 + + 如果你找到了修复，请查看提交消息的尾部是否包含了类似这样的“稳定版标签”： + + Cc: <stable@vger.kernel.org> # 5.4+ + + 像上面这行，开发者标记了安全修复可以回传到 5.4 及以后的版本。大多数情况 + 下，它会在两周内被应用到那里，但有时需要更长的时间。 + + * 如果提交没有告诉你任何东西，或者你找不到修复，请再找找关于这个问题的讨论。 + 用你最喜欢的搜索引擎搜索网络，以及 `Linux kernel developers mailing + list 内核开发者邮件列表 <https://lore.kernel.org/lkml/>`_ 的档案。也可以 + 阅读上面的 `定位导致问题的内核区域` 一节，然后按照说明找到导致问题的子系 + 统：它的缺陷跟踪器或邮件列表存档中可能有你要找的答案。 + + * 如果你看到了一个计划的修复，请按上所述在版本控制系统中搜索它，因为提交可 + 能会告诉你是否可以进行回溯。 + + * 检查讨论中是否有任何迹象表明，该修复程序可能风险太大，无法回溯到你关心 + 的版本线。如果是这样的话，你必须忍受这个问题，或者切换到应用了修复的内 + 核版本线。 + + * 如果修复的问题未包含稳定版标签，并且没有讨论过回溯问题，请加入讨论：如 + 果合适的话，请提及你所面对的问题的版本，以及你希望看到它被修复。 + + +请求建议 +~~~~~~~~~ + + *前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题 + 的子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表。* + +如果前面的三个步骤都没有让你更接近解决方案，那么只剩下一个选择：请求建议。 +在你发给可能是问题根源的子系统的维护者的邮件中这样做；抄送子系统的邮件列表 +以及稳定版邮件列表（stable@vger.kernel.org）。 + + +为什么有些问题在报告后没有任何回应或仍未解决？ +=============================================== + +当向 Linux 开发者报告问题时，要注意只有“高优先级的问题”（回归、安全问题、严 +重问题）才一定会得到解决。如果维护者或其他人都失败了，Linus Torvalds 他自己 +会确保这一点。他们和其他内核开发者也会解决很多其他问题。但是要知道，有时他 +们也会不能或不愿帮忙；有时甚至没有人发报告给他们。 + +最好的解释就是那些内核开发者常常是在业余时间为 Linux 内核做出贡献。内核中的 +不少驱动程序都是由这样的程序员编写的，往往只是因为他们想让自己的硬件可以在 +自己喜欢的操作系统上使用。 + +这些程序员大多数时候会很乐意修复别人报告的问题。但是没有人可以强迫他们这样 +做，因为他们是自愿贡献的。 + +还有一些情况下，这些开发者真的很想解决一个问题，但却不能解决：有时他们缺乏 +硬件编程文档来解决问题。这种情况往往由于公开的文档太简陋，或者驱动程序是通 +过逆向工程编写的。 + +业余开发者迟早也会不再关心某驱动。也许他们的测试硬件坏了，被更高级的玩意取 +代了，或者是太老了以至于只能在计算机博物馆里找到。有时开发者根本就不关心他 +们的代码和 Linux 了，因为在他们的生活中一些不同的东西变得更重要了。在某些情 +况下，没有人愿意接手维护者的工作——也没有人可以被强迫，因为对 Linux 内核的贡 +献是自愿的。然而被遗弃的驱动程序仍然存在于内核中：它们对人们仍然有用，删除 +它们可能导致回归。 + +对于那些为 Linux 内核工作而获得报酬的开发者来说，情况并没有什么不同。这些人 +现在贡献了大部分的变更。但是他们的雇主迟早也会停止关注他们的代码或者让程序 +员专注于其他事情。例如，硬件厂商主要通过销售新硬件来赚钱；因此，他们中的不 +少人并没有投入太多时间和精力来维护他们多年前就停止销售的东西的 Linux 内核驱 +动。企业级 Linux 发行商往往持续维护的时间比较长，但在新版本中往往会把对老旧 +和稀有硬件的支持放在一边，以限制范围。一旦公司抛弃了一些代码，往往由业余贡 +献者接手，但正如上面提到的：他们迟早也会放下代码。 + +优先级是一些问题没有被修复的另一个原因，因为维护者相当多的时候是被迫设置这 +些优先级的，因为在 Linux 上工作的时间是有限的。对于业余时间或者雇主给予他们 +的开发人员用于上游内核维护工作的时间也是如此。有时维护人员也会被报告淹没， +即使一个驱动程序几乎完美地工作。为了不被完全缠住，程序员可能别无选择，只能 +对问题报告进行优先级排序而拒绝其中的一些报告。 + +不过这些都不用太过担心，很多驱动都有积极的维护者，他们对尽可能多的解决问题 +相当感兴趣。 + + +结束语 +======= + +与其他免费/自由&开源软件（Free/Libre & Open Source Software，FLOSS）相比， +向 Linux 内核开发者报告问题是很难的：这个文档的长度和复杂性以及字里行间的内 +涵都说明了这一点。但目前就是这样了。这篇文字的主要作者希望通过记录现状来为 +以后改善这种状况打下一些基础。 diff --git a/Documentation/translations/zh_CN/admin-guide/security-bugs.rst b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..b8120391755d --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst @@ -0,0 +1,74 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +安全缺陷 +========= + +Linux内核开发人员非常重视安全性。因此我们想知道何时发现了安全漏洞，以便尽快 +修复和披露。请向Linux内核安全团队报告安全漏洞。 + +联络 +----- + +可以通过电子邮件<security@kernel.org>联系Linux内核安全团队。这是一个安全人员 +的私有列表，他们将帮助验证错误报告并开发和发布修复程序。如果您已经有了一个 +修复，请将其包含在您的报告中，这样可以大大加快进程。安全团队可能会从区域维护 +人员那里获得额外的帮助，以理解和修复安全漏洞。 + +与任何缺陷一样，提供的信息越多，诊断和修复就越容易。如果您不清楚哪些信息有用， +请查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rst”中 +概述的步骤。任何利用漏洞的攻击代码都非常有用，未经报告者同意不会对外发布，除 +非已经公开。 + +请尽可能发送无附件的纯文本电子邮件。如果所有的细节都藏在附件里，那么就很难对 +一个复杂的问题进行上下文引用的讨论。把它想象成一个 +:doc:`常规的补丁提交 <../process/submitting-patches>` （即使你还没有补丁）： +描述问题和影响，列出复现步骤，然后给出一个建议的解决方案，所有这些都是纯文本的。 + +披露和限制信息 +--------------- + +安全列表不是公开渠道。为此，请参见下面的协作。 + +一旦开发出了健壮的补丁，发布过程就开始了。对公开的缺陷的修复会立即发布。 + +尽管我们倾向于在未公开缺陷的修复可用时即发布补丁，但应报告者或受影响方的请求， +这可能会被推迟到发布过程开始后的7日内，如果根据缺陷的严重性需要更多的时间， +则可额外延长到14天。推迟发布修复的唯一有效原因是为了适应QA的逻辑和需要发布 +协调的大规模部署。 + +虽然可能与受信任的个人共享受限信息以开发修复，但未经报告者许可，此类信息不会 +与修复程序一起发布或发布在任何其他披露渠道上。这包括但不限于原始错误报告和 +后续讨论（如有）、漏洞、CVE信息或报告者的身份。 + +换句话说，我们唯一感兴趣的是修复缺陷。提交给安全列表的所有其他资料以及对报告 +的任何后续讨论，即使在解除限制之后，也将永久保密。 + +协调 +------ + +对敏感缺陷（例如那些可能导致权限提升的缺陷）的修复可能需要与私有邮件列表 +<linux-distros@vs.openwall.org>进行协调，以便分发供应商做好准备，在公开披露 +上游补丁时发布一个已修复的内核。发行版将需要一些时间来测试建议的补丁，通常 +会要求至少几天的限制，而供应商更新发布更倾向于周二至周四。若合适，安全团队 +可以协助这种协调，或者报告者可以从一开始就包括linux发行版。在这种情况下，请 +记住在电子邮件主题行前面加上“[vs]”，如linux发行版wiki中所述： +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 + +CVE分配 +-------- + +安全团队通常不分配CVE，我们也不需要它们来进行报告或修复，因为这会使过程不必 +要的复杂化，并可能耽误缺陷处理。如果报告者希望在公开披露之前分配一个CVE编号， +他们需要联系上述的私有linux-distros列表。当在提供补丁之前已有这样的CVE编号时， +如报告者愿意，最好在提交消息中提及它。 + +保密协议 +--------- + +Linux内核安全团队不是一个正式的机构实体，因此无法签订任何保密协议。 diff --git a/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..bc51d7cff9b0 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst @@ -0,0 +1,157 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +受污染的内核 +------------- + +当发生一些在稍后调查问题时可能相关的事件时，内核会将自己标记为“受污染 +（tainted）”的。不用太过担心，大多数情况下运行受污染的内核没有问题；这些信息 +主要在有人想调查某个问题时才有意义的，因为问题的真正原因可能是导致内核受污染 +的事件。这就是为什么来自受污染内核的缺陷报告常常被开发人员忽略，因此请尝试用 +未受污染的内核重现问题。 + +请注意，即使在您消除导致污染的原因（亦即卸载专有内核模块）之后，内核仍将保持 +污染状态，以表示内核仍然不可信。这也是为什么内核在注意到内部问题（“kernel +bug”）、可恢复错误（“kernel oops”）或不可恢复错误（“kernel panic”）时会打印 +受污染状态，并将有关此的调试信息写入日志 ``dmesg`` 输出。也可以通过 +``/proc/`` 中的文件在运行时检查受污染的状态。 + + +BUG、Oops或Panics消息中的污染标志 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在顶部以“CPU:”开头的一行中可以找到受污染的状态；内核是否受到污染和原因会显示 +在进程ID（“PID:”）和触发事件命令的缩写名称（“Comm:”）之后:: + + BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 + Oops: 0002 [#1] SMP PTI + CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1 + Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011 + RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] + [...] + +如果内核在事件发生时没有被污染，您将在那里看到“Not-tainted:”；如果被污染，那 +么它将是“Tainted:”以及字母或空格。在上面的例子中，它看起来是这样的:: + + Tainted: P W O + +下表解释了这些字符的含义。在本例中，由于加载了专有模块（ ``P`` ），出现了 +警告（ ``W`` ），并且加载了外部构建的模块（ ``O`` ），所以内核早些时候受到 +了污染。要解码其他字符，请使用下表。 + + +解码运行时的污染状态 +~~~~~~~~~~~~~~~~~~~~~ + +在运行时，您可以通过读取 ``cat /proc/sys/kernel/tainted`` 来查询受污染状态。 +如果返回 ``0`` ，则内核没有受到污染；任何其他数字都表示受到污染的原因。解码 +这个数字的最简单方法是使用脚本 ``tools/debugging/kernel-chktaint`` ，您的 +发行版可能会将其作为名为 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分提 +供；如果没有，您可以从 +`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ +网站下载此脚本并用 ``sh kernel-chktaint`` 执行，它会在上面引用的日志中有类似 +语句的机器上打印这样的内容:: + + Kernel is Tainted for following reasons: + * Proprietary module was loaded (#0) + * Kernel issued warning (#9) + * Externally-built ('out-of-tree') module was loaded (#12) + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or + https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for + a more details explanation of the various taint flags. + Raw taint value as int/string: 4609/'P W O ' + +你也可以试着自己解码这个数字。如果内核被污染的原因只有一个，那么这很简单， +在本例中您可以通过下表找到数字。如果你需要解码有多个原因的数字，因为它是一 +个位域（bitfield），其中每个位表示一个特定类型的污染的存在或不存在，最好让 +前面提到的脚本来处理。但是如果您需要快速看一下，可以使用这个shell命令来检查 +设置了哪些位:: + + $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done + +污染状态代码表 +~~~~~~~~~~~~~~~ + +=== ===== ====== ======================================================== + 位 日志 数字 内核被污染的原因 +=== ===== ====== ======================================================== + 0 G/P 1 已加载专用模块 + 1 _/F 2 模块被强制加载 + 2 _/S 4 内核运行在不合规范的系统上 + 3 _/R 8 模块被强制卸载 + 4 _/M 16 处理器报告了机器检测异常（MCE） + 5 _/B 32 引用了错误的页或某些意外的页标志 + 6 _/U 64 用户空间应用程序请求的污染 + 7 _/D 128 内核最近死机了，即曾出现OOPS或BUG + 8 _/A 256 ACPI表被用户覆盖 + 9 _/W 512 内核发出警告 + 10 _/C 1024 已加载staging驱动程序 + 11 _/I 2048 已应用平台固件缺陷的解决方案 + 12 _/O 4096 已加载外部构建（“树外”）模块 + 13 _/E 8192 已加载未签名的模块 + 14 _/L 16384 发生软锁定 + 15 _/K 32768 内核已实时打补丁 + 16 _/X 65536 备用污染，为发行版定义并使用 + 17 _/T 131072 内核是用结构随机化插件构建的 +=== ===== ====== ======================================================== + +注：字符 ``_`` 表示空白，以便于阅读表。 + +污染的更详细解释 +~~~~~~~~~~~~~~~~~ + + 0) ``G`` 加载的所有模块都有GPL或兼容许可证， ``P`` 加载了任何专有模块。 + 没有MODULE_LICENSE（模块许可证）或MODULE_LICENSE未被insmod认可为GPL + 兼容的模块被认为是专有的。 + + + 1) ``F`` 任何模块被 ``insmod -f`` 强制加载， ``' '`` 所有模块正常加载。 + + 2) ``S`` 内核运行在不合规范的处理器或系统上：硬件已运行在不受支持的配置中， + 因此无法保证正确执行。内核将被污染，例如： + + - 在x86上：PAE是通过intel CPU（如Pentium M）上的forcepae强制执行的，这些 + CPU不报告PAE，但可能有功能实现，SMP内核在非官方支持的SMP Athlon CPU上 + 运行，MSR被暴露到用户空间中。 + - 在arm上：在某些CPU（如Keystone 2）上运行的内核，没有启用某些内核特性。 + - 在arm64上：CPU之间存在不匹配的硬件特性，引导加载程序以不同的模式引导CPU。 + - 某些驱动程序正在被用在不受支持的体系结构上（例如x86_64以外的其他系统 + 上的scsi/snic，非x86/x86_64/itanium上的scsi/ips，已经损坏了arm64上 + irqchip/irq-gic的固件设置…）。 + + 3) ``R`` 模块被 ``rmmod -f`` 强制卸载， ``' '`` 所有模块都正常卸载。 + + 4) ``M`` 任何处理器报告了机器检测异常， ``' '`` 未发生机器检测异常。 + + 5) ``B`` 页面释放函数发现错误的页面引用或某些意外的页面标志。这表示硬件问题 + 或内核错误；日志中应该有其他信息指示发生此污染的原因。 + + 6) ``U`` 用户或用户应用程序特意请求设置受污染标志，否则应为 ``' '`` 。 + + 7) ``D`` 内核最近死机了，即出现了OOPS或BUG。 + + 8) ``A`` ACPI表被重写。 + + 9) ``W`` 内核之前已发出过警告（尽管有些警告可能会设置更具体的污染标志）。 + + 10) ``C`` 已加载staging驱动程序。 + + 11) ``I`` 内核正在处理平台固件（BIOS或类似软件）中的严重错误。 + + 12) ``O`` 已加载外部构建（“树外”）模块。 + + 13) ``E`` 在支持模块签名的内核中加载了未签名的模块。 + + 14) ``L`` 系统上先前发生过软锁定。 + + 15) ``K`` 内核已经实时打了补丁。 + + 16) ``X`` 备用污染，由Linux发行版定义和使用。 + + 17) ``T`` 内核构建时使用了randstruct插件，它可以有意生成非常不寻常的内核结构 + 布局（甚至是性能病态的布局），这在调试时非常有用。于构建时设置。 diff --git a/Documentation/translations/zh_CN/admin-guide/unicode.rst b/Documentation/translations/zh_CN/admin-guide/unicode.rst new file mode 100644 index 000000000000..b0b08d2b6eb7 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/unicode.rst @@ -0,0 +1,170 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/unicode.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Unicode（统一码）支持 +====================== + + （英文版）上次更新：2005-01-17，版本号 1.4 + +此文档由H. Peter Anvin <unicode@lanana.org>管理，是Linux注册名称与编号管理局 +（Linux Assigned Names And Numbers Authority，LANANA）项目的一部分。 +现行版本请见： + + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst + +简介 +----- + +Linux内核代码已被重写以使用Unicode来将字符映射到字体。下载一个Unicode到字体 +（Unicode-to-font）表，八位字符集与UTF-8模式都将改用此字体来显示。 + +这微妙地改变了八位字符表的语义。现在的四个字符表是： + +=============== =============================== ================ +映射代号 映射名称 Escape代码 (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +特别是 ESC ( U 不再是“直通字体”，因为字体可能与IBM字符集完全不同。 +例如，即使加载了一个Latin-1字体，也允许使用块图形（block graphics）。 + +请注意，尽管这些代码与ISO 2022类似，但这些代码及其用途都与ISO 2022不匹配； +Linux有两个八位代码（G0和G1），而ISO 2022有四个七位代码（G0-G3）。 + +根据Unicode标准/ISO 10646，U+F000到U+F8FF被保留用于操作系统范围内的分配 +（Unicode标准将其称为“团体区域（Corporate Zone）”，因为这对于Linux是不准确 +的，所以我们称之为“Linux区域”）。选择U+F000作为起点，因为它允许直接映射 +区域以2的大倍数开始（以防需要1024或2048个字符的字体）。这就留下U+E000到 +U+EFFF作为最终用户区。 + +[v1.2]：Unicodes范围从U+F000到U+F7FF已经被硬编码为直接映射到加载的字体， +绕过了翻译表。用户定义的映射现在默认为U+F000到U+F0FF，模拟前述行为。实际上， +此范围可能较短；例如，vgacon只能处理256字符（U+F000..U+F0FF）或512字符 +（U+F000..U+F1FF）字体。 + +Linux 区域中定义的实际字符 +--------------------------- + +此外，还定义了Unicode 1.1.4中不存在的以下字符；这些字符由DEC VT图形映射使用。 +[v1.2]此用法已过时，不应再使用；请参见下文。 + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +DEC VT220使用6x10字符矩阵，这些字符在DEC VT图形字符集中形成一个平滑的过渡。 +我省略了扫描5行，因为它也被用作块图形字符，因此被编码为U+2500 FORMS LIGHT +HORIZONTAL。 + +[v1.3]：这些字符已正式添加到Unicode 3.2.0中；它们在U+23BA、U+23BB、U+23BC、 +U+23BD处添加。Linux现在使用新值。 + +[v1.2]：添加了以下字符来表示常见的键盘符号，这些符号不太可能被添加到Unicode +中，因为它们非常讨厌地取决于特定供应商。当然，这是糟糕设计的一个好例子。 + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +克林贡（Klingon）语支持 +------------------------ + +1996年，Linux是世界上第一个添加对人工语言克林贡支持的操作系统，克林贡是由 +Marc Okrand为《星际迷航》电视连续剧创造的。这种编码后来被征募Unicode注册表 +（ConScript Unicode Registry，CSUR）采用，并建议（但最终被拒绝）纳入Unicode +平面一。不过，它仍然是Linux区域中的Linux/CSUR私有分配。 + +这种编码已经得到克林贡语言研究所（Klingon Language Institute）的认可。 +有关更多信息，请联系他们： + + http://www.kli.org/ + +由于Linux CZ开头部分的字符大多是dingbats/symbols/forms类型，而且这是一种 +语言，因此根据标准Unicode惯例，我将它放置在16单元的边界上。 + +.. note:: + + 这个范围现在由征募Unicode注册表正式管理。规范性引用文件为： + + https://www.evertype.com/standards/csur/klingon.html + +克林贡语有一个26个字符的字母表，一个10位数的位置数字书写系统，从左到右 +，从上到下书写。 + +克林贡字母的几种字形已经被提出。但是由于这组符号看起来始终是一致的，只有实际 +的形状不同，因此按照标准Unicode惯例，这些差异被认为是字体变体。 + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written <q> in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written <Q> in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +其他虚构和人工字母 +------------------- + +自从分配了克林贡Linux Unicode块之后，John Cowan <jcowan@reutershealth.com> +和 Michael Everson <everson@evertype.com> 建立了一个虚构和人工字母的注册表。 +征募Unicode注册表请访问： + + https://www.evertype.com/standards/csur/ + +所使用的范围位于最终用户区域的低端，因此无法进行规范化分配，但建议希望对虚构 +字母进行编码的人员使用这些代码，以实现互操作性。对于克林贡语，CSUR采用了Linux +编码。CSUR的人正在推动将Tengwar和Cirth添加到Unicode平面一；将克林贡添加到 +Unicode平面一被拒绝，因此上述编码仍然是官方的。 diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst new file mode 100644 index 000000000000..f1fa71e45c77 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -0,0 +1,126 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core-api_index.rst: + + +=========== +核心API文档 +=========== + +这是核心内核API手册的首页。 非常感谢为本手册转换(和编写!)的文档! + +核心实用程序 +============ + +本节包含通用的和“核心中的核心”文档。 第一部分是 docbook 时期遗留下 +来的大量 kerneldoc 信息；有朝一日，若有人有动力的话，应当把它们拆分 +出来。 + +Todolist: + + kernel-api + workqueue + printk-basics + printk-formats + symbol-namespaces + +数据结构和低级实用程序 +====================== + +在整个内核中使用的函数库。 + +Todolist: + + kobject + kref + assoc_array + xarray + idr + circular-buffers + rbtree + generic-radix-tree + packing + bus-virt-phys-mapping + this_cpu_ops + timekeeping + errseq + +并发原语 +======== + +Linux如何让一切同时发生。 详情请参阅 +:doc:`/locking/index` + +.. toctree:: + :maxdepth: 1 + + irq/index + +Todolist: + + refcount-vs-atomic + local_ops + padata + ../RCU/index + +低级硬件管理 +============ + +缓存管理，CPU热插拔管理等。 + +Todolist: + + cachetlb + cpu_hotplug + memory-hotplug + genericirq + protection-keys + + +内存管理 +======== + +如何在内核中分配和使用内存。请注意，在 +:doc:`/vm/index` 中有更多的内存管理文档。 + +Todolist: + + memory-allocation + unaligned-memory-access + dma-api + dma-api-howto + dma-attributes + dma-isa-lpc + mm-api + genalloc + pin_user_pages + boot-time-mm + gfp_mask-from-fs-io + +内核调试的接口 +============== + +Todolist: + + debug-objects + tracepoint + debugging-via-ohci1394 + +其它文档 +======== + +不适合放在其它地方或尚未归类的文件； + +Todolist: + + librs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/core-api/irq/concepts.rst b/Documentation/translations/zh_CN/core-api/irq/concepts.rst new file mode 100644 index 000000000000..41455bf0f783 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/concepts.rst @@ -0,0 +1,24 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/concepts` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_concepts.rst: + + +=========== +什么是IRQ？ +=========== + +IRQ (Interrupt ReQuest) 指来自设备的中断请求。 +目前，它们可以通过一个引脚或通过一个数据包进入。 +多个设备可以连接到同一个引脚，从而共享一个IRQ。 + +IRQ编号是用来描述硬件中断源的内核标识符。通常它是一个到全局irq_desc数组的索引， +但是除了在linux/interrupt.h中实现的之外，其它细节是体系结构特征相关的。 + +IRQ编号是对机器上可能的中断源的枚举。通常枚举的是系统中所有中断控制器的输入引脚 +编号。在ISA（工业标准体系结构）的情况下所枚举的是两个i8259中断控制器的16个输入引脚。 + +体系结构可以给IRQ号赋予额外的含义，在涉及到硬件手动配置的情况下，我们鼓励这样做。 +ISA IRQ是赋予这种额外含义的一个典型例子。 diff --git a/Documentation/translations/zh_CN/core-api/irq/index.rst b/Documentation/translations/zh_CN/core-api/irq/index.rst new file mode 100644 index 000000000000..910ccabf041f --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/index.rst @@ -0,0 +1,19 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq_index.rst: + + +==== +IRQs +==== + +.. toctree:: + :maxdepth: 1 + + concepts + irq-affinity + irq-domain + irqflags-tracing diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst new file mode 100644 index 000000000000..82a4428f22fd --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst @@ -0,0 +1,76 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-affinity` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-affinity.rst: + + +============== +SMP IRQ 亲和性 +============== + +变更记录: + - 作者：最初由Ingo Molnar <mingo@redhat.com>开始撰写 + - 后期更新维护： Max Krasnyansky <maxk@qualcomm.com> + + +/proc/irq/IRQ#/smp_affinity和/proc/irq/IRQ#/smp_affinity_list指定了哪些CPU能 +够关联到一个给定的IRQ源，这两个文件包含了这些指定cpu的cpu位掩码(smp_affinity)和cpu列 +表(smp_affinity_list)。它不允许关闭所有CPU， 同时如果IRQ控制器不支持中断请求亲和 +(IRQ affinity)，那么所有cpu的默认值将保持不变(即关联到所有CPU). + +/proc/irq/default_smp_affinity指明了适用于所有非激活IRQ的默认亲和性掩码。一旦IRQ被 +分配/激活，它的亲和位掩码将被设置为默认掩码。然后可以如上所述改变它。默认掩码是0xffffffff。 + +下面是一个先将IRQ44(eth1)限制在CPU0-3上，然后限制在CPU4-7上的例子(这是一个8CPU的SMP box) + +:: + + [root@moon 44]# cd /proc/irq/44 + [root@moon 44]# cat smp_affinity + ffffffff + + [root@moon 44]# echo 0f > smp_affinity + [root@moon 44]# cat smp_affinity + 0000000f + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + ... + --- hell ping statistics --- + 6029 packets transmitted, 6027 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.1/0.4 ms + [root@moon 44]# cat /proc/interrupts | grep 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 0 0 0 0 IO-APIC-level eth1 + +从上面一行可以看出，IRQ44只传递给前四个处理器（0-3）。 +现在让我们把这个IRQ限制在CPU(4-7)。 + +:: + + [root@moon 44]# echo f0 > smp_affinity + [root@moon 44]# cat smp_affinity + 000000f0 + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + .. + --- hell ping statistics --- + 2779 packets transmitted, 2777 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.5/585.4 ms + [root@moon 44]# cat /proc/interrupts | 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 1784 1069 1070 1069 IO-APIC-level eth1 + +这次IRQ44只传递给最后四个处理器。 +即CPU0-3的计数器没有变化。 + +下面是一个将相同的irq(44)限制在cpus 1024到1031的例子 + +:: + + [root@moon 44]# echo 1024-1031 > smp_affinity_list + [root@moon 44]# cat smp_affinity_list + 1024-1031 + +需要注意的是，如果要用位掩码来做这件事，就需要32个为0的位掩码来追踪其相关的一个。 diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst new file mode 100644 index 000000000000..3c82dd307a46 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -0,0 +1,227 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-domain` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-domain.rst: + + +======================= +irq_domain 中断号映射库 +======================= + +目前Linux内核的设计使用了一个巨大的数字空间，每个独立的IRQ源都被分配了一个不 +同的数字。 +当只有一个中断控制器时，这很简单，但在有多个中断控制器的系统中，内核必须确保每 +个中断控制器都能得到非重复的Linux IRQ号（数字）分配。 + +注册为唯一的irqchips的中断控制器编号呈现出上升的趋势：例如GPIO控制器等不同 +种类的子驱动程序通过将其中断处理程序建模为irqchips，即实际上是级联中断控制器， +避免了重新实现与IRQ核心系统相同的回调机制。 + +在这里，中断号与硬件中断号离散了所有种类的对应关系：而在过去，IRQ号可以选择， +使它们与硬件IRQ线进入根中断控制器（即实际向CPU发射中断线的组件）相匹配，现 +在这个编号仅仅是一个数字。 + +出于这个原因，我们需要一种机制将控制器本地中断号（即硬件irq编号）与Linux IRQ +号分开。 + +irq_alloc_desc*() 和 irq_free_desc*() API 提供了对irq号的分配，但它们不 +提供任何对控制器本地IRQ(hwirq)号到Linux IRQ号空间的反向映射的支持。 + +irq_domain 库在 irq_alloc_desc*() API 的基础上增加了 hwirq 和 IRQ 号码 +之间的映射。 相比于中断控制器驱动开放编码自己的反向映射方案，我们更喜欢用 +irq_domain来管理映射。 + +irq_domain还实现了从抽象的irq_fwspec结构体到hwirq号的转换（到目前为止是 +Device Tree和ACPI GSI），并且可以很容易地扩展以支持其它IRQ拓扑数据源。 + +irq_domain的用法 +================ + +中断控制器驱动程序通过以下方式创建并注册一个irq_domain。调用 +irq_domain_add_*() 或 irq_domain_create_*()函数之一（每个映射方法都有不 +同的分配器函数，后面会详细介绍）。 函数成功后会返回一个指向irq_domain的指针。 +调用者必须向分配器函数提供一个irq_domain_ops结构体。 + +在大多数情况下，irq_domain在开始时是空的，没有任何hwirq和IRQ号之间的映射。 +通过调用irq_create_mapping()将映射添加到irq_domain中，该函数接受 +irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在，那么它将分配 +一个新的Linux irq_desc，将其与hwirq关联起来，并调用.map()回调，这样驱动 +程序就可以执行任何必要的硬件设置。 + +当接收到一个中断时，应该使用irq_find_mapping()函数从hwirq号中找到 +Linux IRQ号。 + +在调用irq_find_mapping()之前，至少要调用一次irq_create_mapping()函数， +以免描述符不能被分配。 + +如果驱动程序有Linux的IRQ号或irq_data指针，并且需要知道相关的hwirq号（比 +如在irq_chip回调中），那么可以直接从irq_data->hwirq中获得。 + +irq_domain映射的类型 +==================== + +从hwirq到Linux irq的反向映射有几种机制，每种机制使用不同的分配函数。应该 +使用哪种反向映射类型取决于用例。 下面介绍每一种反向映射类型： + +线性映射 +-------- + +:: + + irq_domain_add_linear() + irq_domain_create_linear() + +线性反向映射维护了一个固定大小的表，该表以hwirq号为索引。 当一个hwirq被映射 +时，会给hwirq分配一个irq_desc，并将irq号存储在表中。 + +当最大的hwirq号固定且数量相对较少时，线性图是一个很好的选择（~<256）。 这种 +映射的优点是固定时间查找IRQ号，而且irq_descs只分配给在用的IRQ。 缺点是该表 +必须尽可能大的hwirq号。 + +irq_domain_add_linear()和irq_domain_create_linear()在功能上是等价的， +除了第一个参数不同--前者接受一个Open Firmware特定的 'struct device_node' 而 +后者接受一个更通用的抽象 'struct fwnode_handle' 。 + +大多数驱动应该使用线性映射 + +树状映射 +-------- + +:: + + irq_domain_add_tree() + irq_domain_create_tree() + +irq_domain维护着从hwirq号到Linux IRQ的radix的树状映射。 当一个hwirq被映射时， +一个irq_desc被分配，hwirq被用作radix树的查找键。 + +如果hwirq号可以非常大，树状映射是一个很好的选择，因为它不需要分配一个和最大hwirq +号一样大的表。 缺点是，hwirq到IRQ号的查找取决于表中有多少条目。 + +irq_domain_add_tree()和irq_domain_create_tree()在功能上是等价的，除了第一 +个参数不同——前者接受一个Open Firmware特定的 'struct device_node' ，而后者接受 +一个更通用的抽象 'struct fwnode_handle' 。 + +很少有驱动应该需要这个映射。 + +无映射 +------ + +:: + + irq_domain_add_nomap() + +当硬件中的hwirq号是可编程的时候，就可以采用无映射类型。 在这种情况下，最好将 +Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create_direct_mapping() +会分配一个Linux IRQ号，并调用.map()回调，这样驱动就可以将Linux IRQ号编入硬件中。 + +大多数驱动程序不能使用这个映射。 + +传统映射类型 +------------ + +:: + + irq_domain_add_simple() + irq_domain_add_legacy() + irq_domain_add_legacy_isa() + irq_domain_create_simple() + irq_domain_create_legacy() + +传统映射是已经为 hwirqs 分配了一系列 irq_descs 的驱动程序的特殊情况。 当驱动程 +序不能立即转换为使用线性映射时，就会使用它。 例如，许多嵌入式系统板卡支持文件使用 +一组用于IRQ号的定义（#define），这些定义被传递给struct设备注册。 在这种情况下， +不能动态分配Linux IRQ号，应该使用传统映射。 + +传统映射假设已经为控制器分配了一个连续的IRQ号范围，并且可以通过向hwirq号添加一 +个固定的偏移来计算IRQ号，反之亦然。 缺点是需要中断控制器管理IRQ分配，并且需要为每 +个hwirq分配一个irq_desc，即使它没有被使用。 + +只有在必须支持固定的IRQ映射时，才应使用传统映射。 例如，ISA控制器将使用传统映射来 +映射Linux IRQ 0-15，这样现有的ISA驱动程序就能得到正确的IRQ号。 + +大多数使用传统映射的用户应该使用irq_domain_add_simple()或 +irq_domain_create_simple()，只有在系统提供IRQ范围时才会使用传统域，否则将使用 +线性域映射。这个调用的语义是这样的：如果指定了一个IRQ范围，那么 描述符将被即时分配 +给它，如果没有范围被分配，它将不会执行 irq_domain_add_linear() 或 +irq_domain_create_linear()，这意味着 *no* irq 描述符将被分配。 + +一个简单域的典型用例是，irqchip供应商同时支持动态和静态IRQ分配。 + +为了避免最终出现使用线性域而没有描述符被分配的情况，确保使用简单域的驱动程序在任何 +irq_find_mapping()之前调用irq_create_mapping()是非常重要的，因为后者实际上 +将用于静态IRQ分配情况。 + +irq_domain_add_simple()和irq_domain_create_simple()以及 +irq_domain_add_legacy()和irq_domain_create_legacy()在功能上是等价的，只 +是第一个参数不同--前者接受Open Firmware特定的 'struct device_node' ，而后者 +接受一个更通用的抽象 'struct fwnode_handle' 。 + +IRQ域层级结构 +------------- + +在某些架构上，可能有多个中断控制器参与将一个中断从设备传送到目标CPU。 +让我们来看看x86平台上典型的中断传递路径吧 +:: + + Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +涉及到的中断控制器有三个: + +1) IOAPIC 控制器 +2) 中断重映射控制器 +3) Local APIC 控制器 + +为了支持这样的硬件拓扑结构，使软件架构与硬件架构相匹配，为每个中断控制器建立一 +个irq_domain数据结构，并将这些irq_domain组织成层次结构。 + +在建立irq_domain层次结构时，靠近设备的irq_domain为子域，靠近CPU的 +irq_domain为父域。所以在上面的例子中，将建立如下的层次结构。 +:: + + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +使用irq_domain层次结构的主要接口有四个: + +1) irq_domain_alloc_irqs(): 分配IRQ描述符和与中断控制器相关的资源来传递这些中断。 +2) irq_domain_free_irqs(): 释放IRQ描述符和与这些中断相关的中断控制器资源。 +3) irq_domain_activate_irq(): 激活中断控制器硬件以传递中断。 +4) irq_domain_deactivate_irq(): 停用中断控制器硬件，停止传递中断。 + +为了支持irq_domain层次结构，需要做如下修改: + +1) 一个新的字段 'parent' 被添加到irq_domain结构中；它用于维护irq_domain的层次信息。 +2) 一个新的字段 'parent_data' 被添加到irq_data结构中；它用于建立层次结构irq_data以 + 匹配irq_domain层次结构。irq_data用于存储irq_domain指针和硬件irq号。 +3) 新的回调被添加到irq_domain_ops结构中，以支持层次结构的irq_domain操作。 + +在支持分层irq_domain和分层irq_data准备就绪后，为每个中断控制器建立一个irq_domain结 +构，并为每个与IRQ相关联的irq_domain分配一个irq_data结构。现在我们可以再进一步支持堆 +栈式(层次结构)的irq_chip。也就是说，一个irq_chip与层次结构中的每个irq_data相关联。 +一个子irq_chip可以自己或通过与它的父irq_chip合作来实现一个所需的操作。 + +通过堆栈式的irq_chip，中断控制器驱动只需要处理自己管理的硬件，在需要的时候可以向其父 +irq_chip请求服务。所以我们可以实现更简洁的软件架构。 + +为了让中断控制器驱动程序支持irq_domain层次结构，它需要做到以下几点: + +1) 实现 irq_domain_ops.alloc 和 irq_domain_ops.free +2) 可选择地实现 irq_domain_ops.activate 和 irq_domain_ops.deactivate. +3) 可选择地实现一个irq_chip来管理中断控制器硬件。 +4) 不需要实现irq_domain_ops.map和irq_domain_ops.unmap，它们在层次结构 + irq_domain中是不用的。 + +irq_domain层次结构绝不是x86特有的，大量用于支持其他架构，如ARM、ARM64等。 + +调试功能 +======== + +打开CONFIG_GENERIC_IRQ_DEBUGFS，可让IRQ子系统的大部分内部结构都在debugfs中暴露出来。 diff --git a/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst new file mode 100644 index 000000000000..c889bd0f65d9 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst @@ -0,0 +1,45 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irqflags-tracing` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irqflags-tracing.rst: + + +================= +IRQ-flags状态追踪 +================= + +:Author: 最初由Ingo Molnar <mingo@redhat.com>开始撰写 + +“irq-flags tracing”（中断标志追踪）功能可以 “追踪” hardirq和softirq的状态，它让 +感兴趣的子系统有机会了解到到内核中发生的每一个 +hardirqs-off/hardirqs-on、softirqs-off/softirqs-on事件。 + +CONFIG_TRACE_IRQFLAGS_SUPPORT是通用锁调试代码提供的CONFIG_PROVE_SPIN_LOCKING +和CONFIG_PROVE_RW_LOCKING所需要的。否则将只有CONFIG_PROVE_MUTEX_LOCKING和 +CONFIG_PROVE_RWSEM_LOCKING在一个架构上被提供--这些都是不在IRQ上下文中使用的 +锁API。（rwsems的一个异常是可以解决的） + +架构对这一点的支持当然不属于“微不足道”的范畴，因为很多低级的汇编代码都要处理irq-flags +的状态变化。但是一个架构可以以一种相当直接且无风险的方式启用irq-flags-tracing。 + +架构如果想支持这个，需要先做一些代码组织上的改变: + +- 在他们的arch级Kconfig文件中添加并启用TRACE_IRQFLAGS_SUPPORT。 + +然后还需要做一些功能上的改变来实现对irq-flags-tracing的支持: + +- 在低级入口代码中增加（构建条件）对trace_hardirqs_off()/trace_hardirqs_on() + 函数的调用。锁验证器会密切关注 “real”的irq-flags是否与 “virtual”的irq-flags + 状态相匹配，如果两者不匹配，则会发出警告（并关闭自己）。通常维护arch中 + irq-flags-track的大部分时间都是在这种状态下度过的：看看lockdep的警告，试着 + 找出我们还没有搞定的汇编代码。修复并重复。一旦系统启动，并且在irq-flags跟踪功 + 能中没有出现lockdep警告的情况下，arch支持就完成了。 + +- 如果该架构有不可屏蔽的中断，那么需要通过lockdep_off()/lockdep_on()将这些中 + 断从irq跟踪[和锁验证]机制中排除。 + + 一般来说，在一个架构中，不完整的irq-flags-tracing实现是没有风险的：lockdep + 会检测到这一点，并将自己关闭。即锁验证器仍然可靠。应该不会因为irq-tracing的错 + 误而崩溃。（除非通过修改不该修改的条件来更改汇编或寄存器而破坏其他代码） diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst new file mode 100644 index 000000000000..19fb9c029cfe --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/core` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core.rst: + + +==================================== +CPUFreq核心和CPUFreq通知器的通用说明 +==================================== + +作者: + - Dominik Brodowski <linux@brodo.de> + - David Kimdon <dwhedon@debian.org> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. 目录: + + 1. CPUFreq核心和接口 + 2. CPUFreq通知器 + 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 + +1. CPUFreq核心和接口 +====================== + +cpufreq核心代码位于drivers/cpufreq/cpufreq.c中。这些cpufreq代码为CPUFreq架构的驱 +动程序（那些操作硬件切换频率的代码）以及 "通知器 "提供了一个标准化的接口。 +这些是设备驱动程序或需要了解策略变化的其它内核部分（如 ACPI 热量管理）或所有频率更改（除 +计时代码外），甚至需要强制确定速度限制的通知器（如 ARM 架构上的 LCD 驱动程序）。 +此外， 内核 "常数" loops_per_jiffy会根据频率变化而更新。 + +cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成，以确保 cpufreq 驱 +动程序被正确地注册到核心中，并且驱动程序在 cpufreq_put_cpu 被调用之前不会被卸载。这也保证 +了每个CPU核的cpufreq 策略在使用期间不会被释放。 + +2. CPUFreq 通知器 +==================== + +CPUFreq通知器符合标准的内核通知器接口。 +关于通知器的细节请参阅 linux/include/linux/notifier.h。 + +这里有两个不同的CPUfreq通知器 - 策略通知器和转换通知器。 + + +2.1 CPUFreq策略通知器 +---------------------------- + +当创建或移除策略时，这些都会被通知。 + +阶段是在通知器的第二个参数中指定的。当第一次创建策略时，阶段是CPUFREQ_CREATE_POLICY，当 +策略被移除时，阶段是CPUFREQ_REMOVE_POLICY。 + +第三个参数 ``void *pointer`` 指向一个结构体cpufreq_policy，其包括min，max(新策略的下限和 +上限（单位为kHz）)这几个值。 + + +2.2 CPUFreq转换通知器 +-------------------------------- + +当CPUfreq驱动切换CPU核心频率时，策略中的每个在线CPU都会收到两次通知，这些变化没有任何外部干 +预。 + +第二个参数指定阶段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. + +第三个参数是一个包含如下值的结构体cpufreq_freqs： + +===== ==================== +cpu 受影响cpu的编号 +old 旧频率 +new 新频率 +flags cpufreq驱动的标志 +===== ==================== + +3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 +================================================================== +关于OPP的细节请参阅 Documentation/power/opp.rst + +dev_pm_opp_init_cpufreq_table - + 这个功能提供了一个随时可用的转换程序，用来将OPP层关于可用频率的内部信息翻译成一种容易提供给 + cpufreq的格式。 + + .. Warning:: + + 不要在中断上下文中使用此函数。 + + 例如:: + + soc_pm_init() + { + /* Do things */ + r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); + if (!r) + policy->freq_table = freq_table; + /* Do other things */ + } + + .. note:: + + 该函数只有在CONFIG_PM_OPP之外还启用了CONFIG_CPU_FREQ时才可用。 + +dev_pm_opp_free_cpufreq_table + 释放dev_pm_opp_init_cpufreq_table分配的表。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000000..0ca2cb646666 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpu-drivers` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpu-drivers.rst: + + +======================================= +如何实现一个新的CPUFreq处理器驱动程序？ +======================================= + +作者: + + + - Dominik Brodowski <linux@brodo.de> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. Contents + + 1. 怎么做？ + 1.1 初始化 + 1.2 Per-CPU 初始化 + 1.3 验证 + 1.4 target/target_index 或 setpolicy? + 1.5 target/target_index + 1.6 setpolicy + 1.7 get_intermediate 与 target_intermediate + 2. 频率表助手 + + + +1. 怎么做？ +=========== + +如此，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq +支持？很好，这里有一些至关重要的提示： + + +1.1 初始化 +---------- + +首先，在__initcall_level_7 (module_init())或更靠后的函数中检查这个内核是否 +运行在正确的CPU和正确的芯片组上。如果是，则使用cpufreq_register_driver()向 +CPUfreq核心层注册一个cpufreq_driver结构体。 + +结构体cpufreq_driver应该包含什么成员? + + .name - 驱动的名字。 + + .init - 一个指向per-policy初始化函数的指针。 + + .verify - 一个指向"verification"函数的指针。 + + .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差异见 + 下文。 + +并且可选择 + + .flags - cpufreq核的提示。 + + .driver_data - cpufreq驱动程序的特定数据。 + + .resolve_freq - 返回最适合目标频率的频率。不过并不能改变频率。 + + .get_intermediate 和 target_intermediate - 用于在改变CPU频率时切换到稳定 + 的频率。 + + .get - 返回CPU的当前频率。 + + .bios_limit - 返回HW/BIOS对CPU的最大频率限制值。 + + .exit - 一个指向per-policy清理函数的指针，该函数在cpu热插拔过程的CPU_POST_DEAD + 阶段被调用。 + + .stop_cpu - 一个指向per-policy停止函数的指针，该函数在cpu热插拔过程的CPU_DOWN_PREPARE + 阶段被调用。 + + .suspend - 一个指向per-policy暂停函数的指针，该函数在关中断且在该策略的调节器停止 + 后被调用。 + + .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次开始前被 + 调用。 + + .ready - 一个指向per-policy准备函数的指针，该函数在策略完全初始化之后被调用。 + + .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该函数允许导出值到 + sysfs。 + + .boost_enabled - 如果设置，则启用提升(boost)频率。 + + .set_boost - 一个指向per-policy函数的指针，该函数用来开启/关闭提升(boost)频率功能。 + + +1.2 Per-CPU 初始化 +------------------ + +每当一个新的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.transition_latency | | +| | CPU在两个频率之间切换所需的时间，以 | +| | 纳秒为单位（如适用，否则指定 | +| | CPUFREQ_ETERNAL） | ++-----------------------------------+--------------------------------------+ +|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->cpus | 用与这个CPU一起做DVFS的(在线+离线) | +| | CPU(即与它共享时钟/电压轨)的掩码更新 | +| | 这个 | +| | | ++-----------------------------------+--------------------------------------+ + +对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手可能会有帮 +助。关于它们的更多信息，请参见第2节。 + + +1.3 验证 +-------- + +当用户决定设置一个新的策略(由 “policy,governor,min,max组成”)时，必须对这个策略进行验证， +以便纠正不兼容的值。为了验证这些值，cpufreq_verify_within_limits(``struct cpufreq_policy +*policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数可能会有帮助。 +关于频率表助手的详细内容请参见第2节。 + +您需要确保至少有一个有效频率（或工作范围）在 policy->min 和 policy->max 范围内。如果有必 +要，先增加policy->max，只有在没有办法的情况下，才减少policy->min。 + + +1.4 target 或 target_index 或 setpolicy 或 fast_switch? +------------------------------------------------------- + +大多数cpufreq驱动甚至大多数cpu频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 +可以使用->target()，->target_index()或->fast_switch()回调。 + +有些cpufreq功能的处理器可以自己在某些限制之间切换频率。这些应使用->setpolicy()回调。 + + +1.5. target/target_index +------------------------ + +target_index调用有两个参数：``struct cpufreq_policy * policy``和``unsigned int`` +索引(于列出的频率表)。 + +当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 + +它应该总是在错误的情况下恢复到之前的频率(即policy->restore_freq)，即使我们之前切换到中间频率。 + +已弃用 +---------- +目标调用有三个参数。``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节。 + +1.6. fast_switch +---------------- + +这个函数用于从调度器的上下文进行频率切换。并非所有的驱动都要实现它，因为不允许在这个回调中睡眠。这 +个回调必须经过高度优化，以尽可能快地进行切换。 + +这个函数有两个参数： ``struct cpufreq_policy *policy`` 和 ``unsigned int target_frequency``。 + + +1.7 setpolicy +------------- + +setpolicy调用只需要一个``struct cpufreq_policy * policy``作为参数。需要将处理器内或芯片组内动态频 +率切换的下限设置为policy->min，上限设置为policy->max，如果支持的话，当policy->policy为 +CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 +也可以查看drivers/cpufreq/longrun.c中的参考实现。 + +1.8 get_intermediate 和 target_intermediate +-------------------------------------------- + +仅适用于 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 + +get_intermediate应该返回一个平台想要切换到的稳定的中间频率，target_intermediate()应该将CPU设置为 +该频率，然后再跳转到'index'对应的频率。核心会负责发送通知，驱动不必在target_intermediate()或 +target_index()中处理。 + +在驱动程序不想因为某个目标频率切换到中间频率的情况下，它们可以从get_intermediate()中返回'0'。在这种情况 +下，核心将直接调用->target_index()。 + +注意：->target_index()应该在失败的情况下恢复到policy->restore_freq，因为core会为此发送通知。 + + +2. 频率表助手 +============= + +由于大多数cpufreq处理器只允许被设置为几个特定的频率，因此，一个带有一些函数的 “频率表”可能会辅助处理器驱动 +程序的一些工作。这样的 "频率表" 由一个cpufreq_frequency_table条目构成的数组组成，"driver_data" 中包 +含了驱动程序的具体数值，"frequency" 中包含了相应的频率，并设置了标志。在表的最后，需要添加一个 +cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。而如果想跳过表中的一个条目，则将频率设置为 +CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，但如果它们是cpufreq 核心会对它们进行快速的DVFS， +因为搜索最佳匹配会更快。 + +如果策略在其policy->freq_table字段中包含一个有效的指针，cpufreq表就会被核心自动验证。 + +cpufreq_frequency_table_verify()保证至少有一个有效的频率在policy->min和policy->max范围内，并且所有其他 +标准都被满足。这对->verify调用很有帮助。 + +cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。只要把数值传递给这个函数，这个函数就会返 +回包含CPU要设置的频率的频率表条目。 + +以下宏可以作为cpufreq_frequency_table的迭代器。 + +cpufreq_for_each_entry(pos, table) - 遍历频率表的所有条目。 + +cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包括CPUFREQ_ENTRY_INVALID频率。 +使用参数 "pos"-一个``cpufreq_frequency_table * `` 作为循环变量，使用参数 "table"-作为你想迭代 +的``cpufreq_frequency_table * `` 。 + +例如:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +如果你需要在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 new file mode 100644 index 000000000000..c90d1d8353ed --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpufreq-stats` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpufreq-stats.rst: + + +========================================== +sysfs CPUFreq Stats的一般说明 +========================================== + +用户信息 + + +作者: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> + +.. Contents + + 1. 简介 + 2. 提供的统计数据(举例说明) + 3. 配置cpufreq-stats + + +1. 简介 +=============== + +cpufreq-stats是一个为每个CPU提供CPU频率统计的驱动。 +这些统计数据在/sysfs中以一堆只读接口的形式提供。这个接口（在配置好后）将出现在 +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一个单 +独的目录中，提供给每个CPU。 +各种统计数据将在此目录下形成只读文件。 + +此驱动是独立于任何可能运行在你所用CPU上的特定cpufreq_driver而设计的。因此，它将与所有 +cpufreq_driver一起工作。 + + +2. 提供的统计数据(举例说明) +===================================== + +cpufreq stats提供了以下统计数据（在下面详细解释）。 + +- time_in_state +- total_trans +- trans_table + +所有的统计数据将从统计驱动被载入的时间（或统计被重置的时间）开始，到某一统计数据被读取的时间为止。 +显然，统计驱动不会有任何关于统计驱动载入之前的频率转换信息。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + +只写属性，可用于重置统计计数器。这对于评估不同调节器下的系统行为非常有用，且无需重启。 + + +- **time_in_state** + +此项给出了这个CPU所支持的每个频率所花费的时间。cat输出的每一行都会有"<frequency> +<time>"对，表示这个CPU在<frequency>上花费了<time>个usertime单位的时间。这里的 +usertime单位是10mS（类似于/proc中输出的其他时间）。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state + 3600000 2089 + 3400000 136 + 3200000 34 + 3000000 67 + 2800000 172488 + + +- **total_trans** + +给出了这个CPU上频率转换的总次数。cat的输出将有一个单一的计数，这就是频率转换的总数。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans + 20 + +- **trans_table** + +这将提供所有CPU频率转换的细粒度信息。这里的cat输出是一个二维矩阵，其中一个条目<i, j>（第 +i行，第j列）代表从Freq_i到Freq_j的转换次数。Freq_i行和Freq_j列遵循驱动最初提供给cpufreq +核的频率表的排序顺序，因此可以排序（升序或降序）或不排序。 这里的输出也包含了每行每列的实际 +频率值，以便更好地阅读。 + +如果转换表大于PAGE_SIZE，读取时将返回一个-EFBIG错误。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table + From : To + : 3600000 3400000 3200000 3000000 2800000 + 3600000: 0 5 0 0 0 + 3400000: 4 0 2 0 0 + 3200000: 0 1 0 2 0 + 3000000: 0 0 1 0 3 + 2800000: 0 0 0 2 0 + +3. 配置cpufreq-stats +============================ + +要在你的内核中配置cpufreq-stats:: + + Config Main Menu + Power management options (ACPI, APM) ---> + CPU Frequency scaling ---> + [*] CPU Frequency scaling + [*] CPU frequency translation statistics + + +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被启用以配置cpufreq-stats。 + +"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)提供了包括 +time_in_state、total_trans和trans_table的统计数据。 + +一旦启用了这个选项，并且你的CPU支持cpufrequency，你就可以在/sysfs中看到CPU频率统计。 diff --git a/Documentation/translations/zh_CN/cpu-freq/index.rst b/Documentation/translations/zh_CN/cpu-freq/index.rst new file mode 100644 index 000000000000..65074e211940 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/index.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_index.rst: + + +======================================================= +Linux CPUFreq - Linux(TM)内核中的CPU频率和电压升降代码 +======================================================= + +Author: Dominik Brodowski <linux@brodo.de> + + 时钟升降允许你在运行中改变CPU的时钟速度。这是一个很好的节省电池电量的方法，因为时 + 钟速度越低，CPU消耗的电量越少。 + + +.. toctree:: + :maxdepth: 1 + + core + cpu-drivers + cpufreq-stats + +邮件列表 +------------ +这里有一个 CPU 频率变化的 CVS 提交和通用列表，您可以在这里报告bug、问题或提交补丁。要发 +布消息，请发送电子邮件到 linux-pm@vger.kernel.org。 + +链接 +----- +FTP档案: +* ftp://ftp.linux.org.uk/pub/linux/cpufreq/ + +如何访问CVS仓库: +* http://cvs.arm.linux.org.uk/ + +CPUFreq邮件列表: +* http://vger.kernel.org/vger-lists.html#linux-pm + +SA-1100的时钟和电压标度: +* http://www.lartmaker.nl/projects/scaling diff --git a/Documentation/translations/zh_CN/dev-tools/gcov.rst b/Documentation/translations/zh_CN/dev-tools/gcov.rst new file mode 100644 index 000000000000..3158c9da1318 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/gcov.rst @@ -0,0 +1,264 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/gcov.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +在Linux内核里使用gcov做代码覆盖率检查 +===================================== + +gcov分析核心支持在Linux内核中启用GCC的覆盖率测试工具 gcov_ ，Linux内核 +运行时的代码覆盖率数据会以gcov兼容的格式导出到“gcov”debugfs目录中，可 +以通过gcov的 ``-o`` 选项（如下示例）获得指定文件的代码运行覆盖率统计数据 +（需要跳转到内核编译路径下并且要有root权限）:: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +这将在当前目录中创建带有执行计数注释的源代码文件。 +在获得这些统计文件后，可以使用图形化的gcov前端工具（比如 lcov_ ），来实现 +自动化处理Linux内核的覆盖率运行数据，同时生成易于阅读的HTML格式文件。 + +可能的用途: + +* 调试（用来判断每一行的代码是否已经运行过） +* 测试改进（如何修改测试代码，尽可能地覆盖到没有运行过的代码） +* 内核最小化配置（对于某一个选项配置，如果关联的代码从来没有运行过， + 是否还需要这个配置） + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +准备 +---- + +内核打开如下配置:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +获取整个内核的覆盖率数据，还需要打开:: + + CONFIG_GCOV_PROFILE_ALL=y + +需要注意的是，整个内核开启覆盖率统计会造成内核镜像文件尺寸的增大， +同时内核运行也会变慢一些。 +另外，并不是所有的架构都支持整个内核开启覆盖率统计。 + +代码运行覆盖率数据只在debugfs挂载完成后才可以访问:: + + mount -t debugfs none /sys/kernel/debug + + +定制化 +------ + +如果要单独针对某一个路径或者文件进行代码覆盖率统计，可以在内核相应路 +径的Makefile中增加如下的配置: + +- 单独统计单个文件（例如main.o）:: + + GCOV_PROFILE_main.o := y + +- 单独统计某一个路径:: + + GCOV_PROFILE := y + +如果要在整个内核的覆盖率统计（开启CONFIG_GCOV_PROFILE_ALL）中单独排除 +某一个文件或者路径，可以使用如下的方法:: + + GCOV_PROFILE_main.o := n + +和:: + + GCOV_PROFILE := n + +此机制仅支持链接到内核镜像或编译为内核模块的文件。 + + +相关文件 +-------- + +gcov功能需要在debugfs中创建如下文件: + +``/sys/kernel/debug/gcov`` + gcov相关功能的根路径 + +``/sys/kernel/debug/gcov/reset`` + 全局复位文件:向该文件写入数据后会将所有的gcov统计数据清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + gcov工具可以识别的覆盖率统计数据文件，向该文件写入数据后 + 会将本文件的gcov统计数据清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + gcov工具需要的软连接文件（指向编译时生成的信息统计文件），这个文件是 + 在gcc编译时如果配置了选项 ``-ftest-coverage`` 时生成的。 + + +针对模块的统计 +-------------- + +内核中的模块会动态的加载和卸载，模块卸载时对应的数据会被清除掉。 +gcov提供了一种机制，通过保留相关数据的副本来收集这部分卸载模块的覆盖率数据。 +模块卸载后这些备份数据在debugfs中会继续存在。 +一旦这个模块重新加载，模块关联的运行统计会被初始化成debugfs中备份的数据。 + +可以通过对内核参数gcov_persist的修改来停用gcov对模块的备份机制:: + + gcov_persist = 0 + +在运行时，用户还可以通过写入模块的数据文件或者写入gcov复位文件来丢弃已卸 +载模块的数据。 + + +编译机和测试机分离 +------------------ + +gcov的内核分析插桩支持内核的编译和运行是在同一台机器上，也可以编译和运 +行是在不同的机器上。 +如果内核编译和运行是不同的机器，那么需要额外的准备工作，这取决于gcov工具 +是在哪里使用的: + +.. _gcov-test_zh: + +a) 若gcov运行在测试机上 + + 测试机上面gcov工具的版本必须要跟内核编译机器使用的gcc版本相兼容， + 同时下面的文件要从编译机拷贝到测试机上: + + 从源代码中: + - 所有的C文件和头文件 + + 从编译目录中: + - 所有的C文件和头文件 + - 所有的.gcda文件和.gcno文件 + - 所有目录的链接 + + 特别需要注意，测试机器上面的目录结构跟编译机器上面的目录机构必须 + 完全一致。 + 如果文件是软链接，需要替换成真正的目录文件（这是由make的当前工作 + 目录变量CURDIR引起的）。 + +.. _gcov-build_zh: + +b) 若gcov运行在编译机上 + + 测试用例运行结束后，如下的文件需要从测试机中拷贝到编译机上: + + 从sysfs中的gcov目录中: + - 所有的.gcda文件 + - 所有的.gcno文件软链接 + + 这些文件可以拷贝到编译机的任意目录下，gcov使用-o选项指定拷贝的 + 目录。 + + 比如一个是示例的目录结构如下:: + + /tmp/linux: 内核源码目录 + /tmp/out: 内核编译文件路径（make O=指定） + /tmp/coverage: 从测试机器上面拷贝的数据文件路径 + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +关于编译器的注意事项 +-------------------- + +GCC和LLVM gcov工具不一定兼容。 +如果编译器是GCC，使用 gcov_ 来处理.gcno和.gcda文件，如果是Clang编译器， +则使用 llvm-cov_ 。 + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html + +GCC和Clang gcov之间的版本差异由Kconfig处理的。 +kconfig会根据编译工具链的检查自动选择合适的gcov格式。 + +问题定位 +-------- + +可能出现的问题1 + 编译到链接阶段报错终止 + +问题原因 + 分析标志指定在了源文件但是没有链接到主内核，或者客制化了链接程序 + +解决方法 + 通过在相应的Makefile中使用 ``GCOV_PROFILE := n`` + 或者 ``GCOV_PROFILE_basename.o := n`` 来将链接报错的文件排除掉 + +可能出现的问题2 + 从sysfs复制的文件显示为空或不完整 + +问题原因 + 由于seq_file的工作方式，某些工具（例如cp或tar）可能无法正确地从 + sysfs复制文件。 + +解决方法 + 使用 ``cat`` 读取 ``.gcda`` 文件，使用 ``cp -d`` 复制链接，或者使用附录B + 中所示的机制。 + + +附录A：collect_on_build.sh +-------------------------- + +用于在编译机上收集覆盖率元文件的示例脚本 +（见 :ref:`编译机和测试机分离 a. <gcov-test_zh>` ） + +.. code-block:: sh + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +附录B：collect_on_test.sh +------------------------- + +用于在测试机上收集覆盖率数据文件的示例脚本 +（见 :ref:`编译机和测试机分离 b. <gcov-build_zh>` ） + +.. code-block:: sh + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 <output.tar.gz>" >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst new file mode 100644 index 000000000000..fd73c479917b --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -0,0 +1,35 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/index.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +============ +内核开发工具 +============ + +本文档是有关内核开发工具文档的合集。 +目前这些文档已经整理在一起，不需要再花费额外的精力。 +欢迎任何补丁。 + +.. class:: toc-title + + 目录 + +.. toctree:: + :maxdepth: 2 + + gcov + +Todolist: + + - coccinelle + - sparse + - kcov + - kasan + - ubsan + - kmemleak + - kcsan + - gdb-kernel-debugging + - kgdb + - kselftest + - kunit/index diff --git a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst index dcf803ede85a..3c6db094a63c 100644 --- a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst +++ b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst @@ -6,4 +6,4 @@ .. note:: 如果您发现本文档与原始文件有任何不同或者有翻译问题，请联系该文件的译者， - 或者请求时奎亮的帮助：<alex.shi@linux.alibaba.com>。 + 或者请求时奎亮的帮助：<alexs@kernel.org>。 diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst new file mode 100644 index 000000000000..394a13b438b0 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/contributing.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +如何帮助改进内核文档 +==================== + +在任何软件开发项目中，文档都是重要组成部分。好的文档有助于引入新的开发人员， +并帮助已有的开发人员更有效地工作。如果缺少高质量的文档，大量的时间就会浪费在 +代码的逆向工程和犯本可避免的错误上。 + +不幸的是，内核的文档目前远远不能满足支持如此规模和重要性的项目的需要。 + +本指南适用于希望帮助改善这种状况的贡献者。内核文档的改进可以由开发者在不同的 +技能层级上进行；这也是一条相对简单可以帮助您了解内核过程并在社区中找到一席之 +地的路径。下面的大部分内容是文档维护人员列出的最迫切需要完成的任务。 + +文档待办事项列表 +---------------- + +为了使我们的文档达到应有的水平，需要完成的任务数不胜数。此列表包含许多重要的 +项目，但还远远不够详尽；如果您知道改进文档的其他方法，请不要羞于启齿。 + +消除警告（WARNING） +~~~~~~~~~~~~~~~~~~~ + +文档构建目前出现了数量惊人的警告。虱子多了不痒，债多了不愁；大伙儿忽略了它们， +他们永远不会注意到他们的工作增加了新的警告。因此，消除警告是文档待办事项列表 +中优先级最高的任务之一。这项任务本身相当简单，但必须以正确的方式进行，才能取 +得成功。 + +C代码编译器发出的警告常常会被视为误报，从而导致出现了旨在让编译器闭嘴的补丁。 +文档构建中的警告几乎总是指向真正的问题；要消除这些警告，需要理解问题并从源头上 +解决问题。因此，修复文档警告的补丁不应在标题中直接写“修复警告”；它们应该指明 +真正修复的问题。 + +另一个重点是，文档警告常常由C代码里kernel-doc注释中的问题引起。虽然文档维护 +人员对收到这些修复补丁的副本表示感谢，但是文档树实际上通常并不适合接受这些 +补丁；它们应该被交给相关子系统的维护人员。 + +例如，在一次文档构建中，我几乎是随意选取了一对警告:: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + +（作了断行以便于阅读） + +简单看一下上面给出的源文件，会发现几个kernel-doc注释，如下所示:: + + /** + * devm_devfreq_register_notifier() + - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + * @list: DEVFREQ_TRANSITION_NOTIFIER. + */ + +问题在于缺了一个“*”，这不符合构建系统对C注释块的格式要求。此问题自2016年注释 +被添加以来一直存在——整整四年之久。修复它只需要添加丢失的星号。看一眼该文件的 +历史记录以了解主题行的常规格式是什么样，再使用 ``scripts/get_maintainer.pl`` +来搞清谁应当收到此补丁。生成的补丁如下所示:: + + [PATCH] PM / devfreq: Fix two malformed kerneldoc comments + + Two kerneldoc comments in devfreq.c fail to adhere to the required format, + resulting in these doc-build warnings: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + + Add a couple of missing asterisks and make kerneldoc a little happier. + + Signed-off-by: Jonathan Corbet <corbet@lwn.net> + --- + drivers/devfreq/devfreq.c | 4 ++-- + 1 file changed, 2 insertions(+), 2 deletions(-) + + diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c + index 57f6944d65a6..00c9b80b3d33 100644 + --- a/drivers/devfreq/devfreq.c + +++ b/drivers/devfreq/devfreq.c + @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) + + /** + * devm_devfreq_register_notifier() + - - Resource-managed devfreq_register_notifier() + + * - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); + + /** + * devm_devfreq_unregister_notifier() + - - Resource-managed devfreq_unregister_notifier() + + * - Resource-managed devfreq_unregister_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + -- + 2.24.1 + +整个过程只花了几分钟。当然，我后来发现有人在另一个树中修复了它，这亮出了另一 +个教训：在深入研究问题之前，一定要检查linux-next树，看看问题是否已经修复。 + +其他修复可能需要更长的时间，尤其是那些与缺少文档的结构体成员或函数参数相关的 +修复。这种情况下，需要找出这些成员或参数的作用，并正确描述它们。总之，这种 +任务有时会有点乏味，但它非常重要。如果我们真的可以从文档构建中消除警告，那么 +我们就可以开始期望开发人员开始注意避免添加新的警告了。 + +“迷失的”kernel-doc注释 +~~~~~~~~~~~~~~~~~~~~~~ + +开发者被鼓励去为他们的代码写kernel-doc注释，但是许多注释从未被引入文档构建。 +这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc`` +指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。 + +``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。 + +请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部 +使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中， +否则不应将其引入文档构建中。 + + +修正错字 +~~~~~~~~ + + +修复文档中的排版或格式错误是一种快速学习如何创建和发送修补程序的方法，也是 +一项有用的服务。我总是愿意接受这样的补丁。这也意味着，一旦你修复了一些这种 +错误，请考虑转移到更高级的任务，留下一些拼写错误给下一个初学者解决。 + +请注意，有些并 **不是** 拼写错误，不应该被“修复”： + + - 内核文档中用美式和英式英语拼写皆可，没有必要互相倒换。 + + - 在内核文档中，没必要讨论句点后面应该跟一个还是两个空格的问题。其他一些有 + 合理分歧的地方，比如“牛津逗号”，在这也是跑题的。 + +与对任何项目的任何补丁一样，请考虑您的更改是否真的让事情变得更好。 + +“上古”文档 +~~~~~~~~~~ + +一些内核文档是最新的、被维护的，并且非常有用，有些文件确并非如此。尘封、陈旧 +和不准确的文档可能会误导读者，并对我们的整个文档产生怀疑。任何解决这些问题的 +事情都是非常受欢迎的。 + +无论何时处理文档，请考虑它是否是最新的，是否需要更新，或者是否应该完全删除。 +您可以注意以下几个警告标志： + + - 对2.x内核的引用 + - 指向SourceForge存储库 + - 历史记录除了拼写错误啥也没有持续几年 + - 讨论Git之前时代的工作流 + +当然，最好的办法是更新文档，添加所需的任何信息。这样的工作通常需要与熟悉相关 +子系统的开发人员合作。当有人善意地询问开发人员，并听取他们的回答然后采取 +行动时，开发人员通常更愿意与这些致力于改进文档的人员合作。 + +有些文档已经没希望了；例如，我们偶尔会发现引用了很久以前从内核中删除的代码的 +文档。删除过时的文档会碰见令人惊讶的阻力，但我们无论如何都应该这样做。文档中 +多余的粗枝大叶对任何人都没有帮助。 + +如果一个严重过时的文档中可能有一些有用的信息，而您又无法更新它，那么最好在 +开头添加一个警告。建议使用以下文本:: + + .. warning :: + This document is outdated and in need of attention. Please use + this information with caution, and please consider sending patches + to update it. + +这样的话，至少我们长期受苦的读者会得到文件可能会把他们引入歧途的警告。 + +文档一致性 +~~~~~~~~~~ + +这里的老前辈们会记得上世纪90年代出现在书架上的Linux书籍，它们只是从网上不同 +位置搜来的文档文件的集合。在此之后，（大部分）这些书都得到了改进，但是内核的 +文档仍然主要是建立在这种模型上。它有数千个文件，几乎每个文件都是与其他文件相 +独立编写的。我们没有一个连贯的内核文档；只有数千个独立的文档。 + +我们一直试图通过编篡一套“书籍”来改善这种情况，以为特定读者提供成套文档。这 +包括： + + - Documentation/translations/zh_CN/admin-guide/index.rst + - Documentation/core-api/index.rst + - Documentation/driver-api/index.rst + - Documentation/userspace-api/index.rst + +以及文档本身这本“书”。 + +将文档移到适当的书中是一项重要的任务，需要继续进行。不过这项工作还是有一些 +挑战性。移动文档会给处理这些文档的人带来短期的痛苦；他们对这些更改无甚热情 +也是可以理解的。通常情况下，可以将一个文档移动一下；不过我们真的不想一直移动 +它们。 + +即使所有文件都在正确的位置，我们也只是把一大堆文件变成一群小堆文件。试图将 +所有这些文件组合成一个整体的工作尚未开始。如果你对如何在这方面取得进展有好的 +想法，我们将很高兴了解。 + +样式表（Stylesheet）改进 +~~~~~~~~~~~~~~~~~~~~~~~~ + +随着Sphinx的采用，我们得到了比以前更好的HTML输出。但它仍然需要很大的改进； +Donald Knuth和Edward Tufte可能是映像平平的。这需要调整我们的样式表，以创建 +更具排版效果、可访问性和可读性的输出。 + +请注意：如果你承担这个任务，你将进入经典的两难领域。即使是相对明显的变化， +也会有很多意见和讨论。唉，这就是我们生活的世界的本质。 + +无LaTeX的PDF构建 +~~~~~~~~~~~~~~~~ + +对于拥有大量时间和Python技能的人来说，这绝对是一项不平凡的任务。Sphinx工具链 +相对较小且包含良好；很容易添加到开发系统中。但是构建PDF或EPUB输出需要安装 +LaTeX，它绝对称不上小或包含良好的。消除Latex将是一件很好的事情。 + +最初是希望使用 `rst2pdf <https://rst2pdf.org/>`_ 工具来生成PDF，但结果发现 +无法胜任这项任务。不过rst2pdf的开发工作最近似乎又有了起色，这是个充满希望的 +迹象。如果有开发人员愿意与该项目合作，使rst2pdf可与内核文档构建一起工作， +大家会非常感激。 + +编写更多文档 +~~~~~~~~~~~~ + +当然，内核中许多部分的文档严重不足。如果您有编写一个特定内核子系统文档的相应 +知识并愿意这样做，请不要犹豫，编写并向内核贡献结果吧！数不清的内核开发人员和 +用户会感谢你。 diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst new file mode 100644 index 000000000000..5151953c196f --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/index.rst @@ -0,0 +1,27 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/index.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _doc_guide_zh: + +================ +如何编写内核文档 +================ + +.. toctree:: + :maxdepth: 1 + + sphinx + kernel-doc + parse-headers + contributing + maintainer-profile + +.. only:: 子项目与HTML + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst new file mode 100644 index 000000000000..82ec84470c0b --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -0,0 +1,499 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/kernel-doc.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +编写kernel-doc注释 +================== + +Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用以描述代码的函数、 +类型和设计。将文档嵌入源文件更容易保持文档最新。 + +.. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似，但由于历史原因， + 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循 + 此处描述的风格。 + +.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/docs.rst 。 + +从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的 +类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。 + +.. _Sphinx C 域: http://www.sphinx-doc.org/en/stable/domains.html + +使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出到可加载模块的每个函数都 +应该有一个kernel-doc注释。模块使用的头文件中的函数和数据结构也应该有 +kernel-doc注释。 + +对于其他内核文件（未标记为 ``static`` ）中外部可见的函数，提供kernel-doc格式 +的文档是一个很好的实践。我们也建议为私有（文件 ``static`` ）程序提供kernel-doc +格式的文档，以确保内核源代码布局的一致性。此建议优先级较低，由内核源文件的 +维护者自行决定。 + +如何格式化kernel-doc注释 +------------------------ + +kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取以这种方式 +标记的注释。注释其余部分的格式类似于一个普通的多行注释，左侧有一列星号，以 +``*/`` 行结束。 + +函数和类型的kernel-doc注释应该放在所描述的函数或类型之前，以便最大限度地提高 +更改代码的人同时更改文档的可能性。概述kernel-doc注释可以放在最顶部的任何地方。 + +用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式 +是否正确。例如:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +当请求执行额外的gcc检查时，内核构建将验证文档格式:: + + make W=n + +函数文档 +-------- + +函数和函数式宏的kernel-doc注释的一般格式是:: + + /** + * 函数名() - 函数简要说明. + * @参数1: 描述第一个参数. + * @参数2: 描述第二个参数. + * 可以为参数提供一段 + * 多行描述. + * + * 更详细的描述，进一步讨论函数 函数名(), 这可能对使用或修改它的人有用. + * 以空注释行开始, 内部可以包含空注释行. + * + * 详细描述可以有多个段落. + * + * Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁. + * 可以写多行. + * Return: 描述函数返回值. + * + * 返回值描述也可以有多个段落, + * 并且应该放在注释块的末尾. + */ + +函数名后面的简短描述可以跨多行，并以参数描述、空注释行或注释块结尾结束。 + +函数参数 +~~~~~~~~ + +每个函数参数都应该按照顺序描述，紧跟在函数简要说明之后。不要在函数描述和参数 +之间，也不要在参数之间留空。 + +每个 ``@参数:`` 描述可以跨多行。 + +.. note:: + + 如果 ``@参数`` 描述有多行，则说明的续行应该从上一行的同一列开始:: + + * @参数: 较长说明 + * 的续行 + + 或:: + + * @参数: + * 较长说明 + * 的续行 + +如果函数的参数数目可变，则需用kernel-doc格式对其进行描述:: + + * @...: 描述 + +函数上下文 +~~~~~~~~~~ + +可调用函数的上下文应该在 ``Context`` 节中描述。此节应该包括函数是休眠的还是 +可以从中断上下文调用的，以及它需要什么锁、释放什么锁和期望它的调用者持有什么 +锁。 + +例如:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +返回值 +~~~~~~ + +如有返回值，应在 ``Return`` 节中描述。 + +.. note:: + + #) 您提供的多行描述文本 *不会* 识别换行符，因此如果您想将某些文本预格式化， + 如:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + 它们在最终文档中变成一行:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + 因此，为了在需要的地方换行，您需要使用ReST列表，例如:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) 如果您提供的描述性文本中的行以某个后跟冒号的短语开头，则每一个这种短语 + 都将被视为新的节标题，可能会产生意料不到的效果。 + +结构体、共用体、枚举类型文档 +---------------------------- + +结构体（struct）、共用体（union）、枚举（enum）类型kernel-doc注释的一般格式为:: + + /** + * struct 结构体名 - 简要描述. + * @成员1: 成员1描述. + * @成员2: 成员2描述. + * 可以为成员提供 + * 多行描述. + * + * 结构体的描述. + */ + +可以用 ``union`` 或 ``enum`` 替换上面示例中的 ``struct`` ，以描述共用体或枚举。 +``成员`` 用于表示枚举中的元素或共用体成员。 + +结构体名称后面的简要说明可以跨多行，并以成员说明、空白注释行或注释块结尾结束。 + +成员 +~~~~ + +结构体、共用体和枚举的成员应以与函数参数相同的方式记录；它们后紧跟简短的描述， +并且为多行。 + +在结构体或共用体描述中，可以使用 ``private:`` 和 ``public:`` 注释标签。 +``private:`` 域内的字段不会列在生成的文档中。 + +``private:`` 和 ``public:`` 标签必须紧跟在 ``/*`` 注释标记之后。可以选择是否 +在 ``:`` 和 ``*/`` 结束标记之间包含注释。 + +例子:: + + /** + * struct 张三 - 简短描述 + * @a: 第一个成员 + * @b: 第二个成员 + * @d: 第三个成员 + * + * 详细描述 + */ + struct 张三 { + int a; + int b; + /* private: 仅内部使用 */ + int c; + /* public: 下一个是公有的 */ + int d; + }; + +嵌套的结构体/共用体 +~~~~~~~~~~~~~~~~~~~ + +嵌套的结构体/共用体可像这样记录:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + }; + struct { + void *memb3; + int memb4; + }; + }; + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) 在记录嵌套结构体或共用体时，如果结构体/共用体 ``张三`` 已命名，则其中 + 的成员 ``李四`` 应记录为 ``@张三.李四:`` + + #) 当嵌套结构体/共用体是匿名的时，其中的成员 ``李四`` 应记录为 ``@李四:`` + +行间注释文档 +~~~~~~~~~~~~ + +结构成员也可在定义时以行间注释形式记录。有两种样式，一种是单行注释，其中开始 +``/**`` 和结束 ``*/`` 位于同一行；另一种是多行注释，开头结尾各自位于一行，就 +像所有其他核心文档注释一样:: + + /** + * struct 张三 - 简短描述. + * @张三: 成员张三. + */ + struct 张三 { + int 张三; + /** + * @李四: 成员李四. + */ + int 李四; + /** + * @王五: 成员王五. + * + * 此处，成员描述可以为好几段. + */ + int 王五; + union { + /** @儿子: 单行描述. */ + int 儿子; + }; + /** @赵六: 描述@张三里面的结构体@赵六 */ + struct { + /** + * @赵六.女儿: 描述@张三.赵六里面的@女儿 + */ + int 女儿; + } 赵六; + }; + +Typedef文档 +----------- + +Typedef的kernel-doc文档注释的一般格式为:: + + /** + * typedef 类型名称 - 简短描述. + * + * 类型描述. + */ + +还可以记录带有函数原型的typedef:: + + /** + * typedef 类型名称 - 简短描述. + * @参数1: 参数1的描述 + * @参数2: 参数2的描述 + * + * 类型描述. + * + * Context: 锁（Locking）上下文. + * Return: 返回值的意义. + */ + typedef void (*类型名称)(struct v4l2_ctrl *参数1, void *参数2); + +高亮与交叉引用 +-------------- + +在kernel-doc注释的描述文本中可以识别以下特殊模式，并将其转换为正确的 +reStructuredText标记和 `Sphinx C 域`_ 引用。 + +.. attention:: 以下内容 **仅** 在kernel-doc注释中识别， **不会** 在普通的 + reStructuredText文档中识别。 + +``funcname()`` + 函数引用。 + +``@parameter`` + 函数参数的名称（未交叉引用，仅格式化）。 + +``%CONST`` + 常量的名称（未交叉引用，仅格式化）。 + +````literal```` + 预格式化文本块。输出将使用等距字体。 + + 若你需要使用在kernel-doc脚本或reStructuredText中有特殊含义的字符，则此功能 + 非常有用。 + + 若你需要在函数描述中使用类似于 ``%ph`` 的东西，这特别有用。 + +``$ENVVAR`` + 环境变量名称（未交叉引用，仅格式化）。 + +``&struct name`` + 结构体引用。 + +``&enum name`` + 枚举引用。 + +``&typedef name`` + Typedef引用。 + +``&struct_name->member`` or ``&struct_name.member`` + 结构体或共用体成员引用。交叉引用将链接到结构体或共用体定义，而不是直接到成员。 + +``&name`` + 泛类型引用。请首选上面描述的完整引用方式。此法主要是为了可能未描述的注释。 + +从reStructuredText交叉引用 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +无需额外的语法来从reStructuredText文档交叉引用kernel-do注释中定义的函数和类型。 +只需以 ``()`` 结束函数名，并在类型之前写上 ``struct`` ， ``union`` ， ``enum`` +或 ``typedef`` 。 +例如:: + + See foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. + +若要在交叉引用链接中使用自定义文本，可以通过以下语法进行:: + + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. + +有关更多详细信息，请参阅 `Sphinx C 域`_ 文档。 + +总述性文档注释 +-------------- + +为了促进源代码和注释紧密联合，可以将kernel-doc文档块作为自由形式的注释，而 +不是函数、结构、联合、枚举或typedef的绑定kernel-doc。例如，这可以用于解释 +驱动程序或库代码的操作理论。 + +这是通过使用带有节标题的 ``DOC:`` 节关键字来实现的。 + +总述或高层级文档注释的一般格式为:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +``DOC:`` 后面的标题用作源文件中的标题，但也用作提取文档注释的标识符。因此， +文件中的标题必须是唯一的。 + +包含kernel-doc注释 +================== + +文档注释可以被包含在任何使用专用kernel-doc Sphinx指令扩展的reStructuredText +文档中。 + +kernel-doc指令的格式如下:: + + .. kernel-doc:: source + :option: + +*source* 是相对于内核源代码树的源文件路径。 +支持以下指令选项： + +export: *[source-pattern ...]* + 包括 *source* 中使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的所有 + 函数的文档，无论是在 *source* 中还是在 *source-pattern* 指定的任何文件中。 + + 当kernel-doc注释被放置在头文件中，而 ``EXPORT_SYMBOL`` 和 ``EXPORT_SYMBOL_GPL`` + 位于函数定义旁边时， *source-pattern* 非常有用。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + 包括 *source* 中所有在 *source* 或 *source-pattern* 的任何文件中都没有使用 + ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的函数和类型的文档。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +identifiers: *[ function/type ...]* + 在 *source* 中包含每个 *function* 和 *type* 的文档。如果没有指定 *function* ， + 则 *source* 中所有函数和类型的文档都将包含在内。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +no-identifiers: *[ function/type ...]* + 排除 *source* 中所有 *function* 和 *type* 的文档。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + +functions: *[ function/type ...]* + 这是“identifiers”指令的别名，已弃用。 + +doc: *title* + 包含 *source* 中由 *title* 标题标识的 ``DOC:`` 文档段落。 *title* 中允许 + 空格；不要在 *title* 上加引号。 *title* 仅用作段落的标识符，不包含在输出中。 + 请确保在所附的reStructuredText文档中有适当的标题。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 + +kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 +在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 + +.. _kernel_doc_zh: + +如何使用kernel-doc生成手册（man）页 +----------------------------------- + +如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- :^Documentation :^tools) \ + | scripts/split-man.pl /tmp/man + +一些旧版本的git不支持路径排除语法的某些变体。 +以下命令之一可能适用于这些版本:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ + | scripts/split-man.pl /tmp/man + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ + | scripts/split-man.pl /tmp/man + diff --git a/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst new file mode 100644 index 000000000000..35c88e5b3d83 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/maintainer-profile.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +文档子系统维护人员条目概述 +========================== + +文档“子系统”是内核文档和相关基础设施的中心协调点。它涵盖了 Documentation/ 下 +的文件层级（Documentation/devicetree 除外）、scripts/ 下的各种实用程序，并且 +在某些情况下的也包括 LICENSES/ 。 + +不过值得注意的是，这个子系统的边界比通常更加模糊。许多其他子系统维护人员需要 +保持对 Documentation/ 某些部分的控制，以便于可以更自由地做更改。除此之外， +许多内核文档都以kernel-doc注释的形式出现在源代码中；这些注释通常（但不总是） +由相关的子系统维护人员维护。 + +文档子系统的邮件列表是<linux-doc@vger.kernel.org>。 +补丁应尽量针对docs-next树。 + +提交检查单补遗 +-------------- + +在进行文档更改时，您应当构建文档以测试，并确保没有引入新的错误或警告。生成 +HTML文档并查看结果将有助于避免对文档渲染结果的不必要争执。 + +开发周期的关键节点 +------------------ + +补丁可以随时发送，但在合并窗口期间，响应将比通常慢。文档树往往在合并窗口打开 +之前关闭得比较晚，因为文档补丁导致回归的风险很小。 + +审阅节奏 +-------- + +我（译注：指Jonathan Corbet <corbet@lwn.net>）是文档子系统的唯一维护者，我在 +自己的时间里完成这项工作，所以对补丁的响应有时会很慢。当补丁被合并时（或当我 +决定拒绝合并补丁时），我都会发送通知。如果您在发送补丁后一周内没有收到回复， +请不要犹豫，发送提醒就好。 + diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..a08819e904ed --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -0,0 +1,187 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/parse-headers.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +===================== +包含用户空间API头文件 +===================== + +有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例 +C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号， +Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 +:ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。 +在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅 +``Documentation/userspace-api/media/Makefile`` 。 + +.. _parse_headers_zh: + +parse_headers.pl +---------------- + +脚本名称 +~~~~~~~~ + + +parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 +创建交叉引用。 + + +用法概要 +~~~~~~~~ + + +\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] + +<选项> 可以是： --debug, --help 或 --usage 。 + + +选项 +~~~~ + + + +\ **--debug**\ + + 开启脚本详细模式，在调试时很有用。 + + +\ **--usage**\ + + 打印简短的帮助信息并退出。 + + + +\ **--help**\ + + 打印更详细的帮助信息并退出。 + + +说明 +~~~~ + +通过C头文件或源文件（<C文件>）中为描述API的文档编写的带交叉引用的 ..预格式化 +文本 块将文件转换成重构文本（RST）。它接受一个可选的<例外文件>，其中描述了 +哪些元素将被忽略或指向非默认引用。 + +输出被写入到<输出文件>。 + +它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为它们创建交叉引用。 +它还能够区分用于指定Linux ioctl的 ``#define`` 。 + +<例外文件> 包含两种类型的语句： \ **ignore**\ 或 \ **replace**\ . + +ignore标记的语法为： + + +ignore \ **type**\ \ **name**\ + +The \ **ignore**\ 意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成 +交叉引用。 + + +replace标记的语法为： + + +replace \ **type**\ \ **name**\ \ **new_value**\ + +The \ **replace**\ 味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引 +用，但是它将使用 \ **new_value**\ 来取代默认的替换规则。 + + +这两种语句中， \ **type**\ 可以是以下任一项： + + +\ **ioctl**\ + + ignore 或 replace 语句应用于ioctl定义，如： + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。 + + + +\ **typedef**\ + + ignore 和 replace 语句应用于<C文件>中的typedef语句。 + + + +\ **struct**\ + + ignore 和 replace 语句应用于<C文件>中的结构体名称语句。 + + + +\ **enum**\ + + ignore 和 replace 语句应用于<C文件>中的枚举名称语句。 + + + +\ **symbol**\ + + ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。 + + replace语句中， \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ + 和 \ **struct**\ 类型的 :c:type: 引用；以及 \ **ioctl**\ , \ **define**\ 和 + \ **symbol**\ 类型的 :ref: 。引用的类型也可以在replace语句中显式定义。 + + +示例 +~~~~ + + +ignore define _VIDEODEV2_H + + +忽略<C文件>中的 #define _VIDEODEV2_H 。 + +ignore symbol PRIVATE + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +不会为 \ **PRIVATE**\ 生成交叉引用。 + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。 + + + +缺陷 +~~~~ + + +请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 + +中文翻译问题请找中文翻译维护者。 + + +版权 +~~~~ + + +版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> + +许可证 GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html> + +这是自由软件：你可以自由地修改和重新发布它。 +在法律允许的范围内，**不提供任何保证**。 diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst new file mode 100644 index 000000000000..951595c7d599 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -0,0 +1,415 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/sphinx.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _sphinxdoc_zh: + +简介 +==== + +Linux内核使用 `Sphinx <http://www.sphinx-doc.org/>`_ 来把 ``Documentation`` +下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转 +换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML +或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。 + +reStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 +通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 +格式，但除此之外，它们还被作为reStructuredText处理。 + +最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移， +其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。 + +.. _sphinx_install_zh: + +安装Sphinx +========== + +Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。 + +这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 +:ref:`sphinx-pre-install_zh` 。 + +大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 +或其他一些Python包导致文档构建中断的情况并不少见。 + +避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用 +``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版 +如何打包Python3。 + +.. note:: + + #) 低于1.5版本的Sphinx无法与Python的0.13.1或更高版本docutils一起正常工作。 + 如果您想使用这些版本，那么应该运行 ``pip install 'docutils==0.12'`` 。 + + #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 + ``pip install sphinx_rtd_theme`` 单独安装。 + + #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX + 编写的。它需要安装amsfonts和amsmath宏包，以便显示。 + +总之，如您要安装Sphinx 1.7.9版本，应执行:: + + $ virtualenv sphinx_1.7.9 + $ . sphinx_1.7.9/bin/activate + (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt + +在运行 ``. sphinx_1.7.9/bin/activate`` 之后，提示符将变化，以指示您正在使用新 +环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 +次进入虚拟环境中。 + +图片输出 +-------- + +内核文档构建系统包含一个扩展，可以处理GraphViz和SVG格式的图像（参见 +:ref:`sphinx_kfigure_zh` ）。 + +为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包， +构建系统仍将构建文档，但不会在输出中包含任何图像。 + +PDF和LaTeX构建 +-------------- + +目前只有Sphinx 1.4及更高版本才支持这种构建。 + +对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实 +存在） + +根据发行版的不同，您可能还需要安装一系列 ``texlive`` 软件包，这些软件包提供了 +``XeLaTeX`` 工作所需的最小功能集。 + +.. _sphinx-pre-install_zh: + +检查Sphinx依赖项 +---------------- + +这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行 +版的安装命令:: + + $ ./scripts/sphinx-pre-install + Checking if the needed tools for Fedora release 26 (Twenty Six) are available + Warning: better to also install "texlive-luatex85". + You should run: + + sudo dnf install -y texlive-luatex85 + /usr/bin/virtualenv sphinx_1.7.9 + . sphinx_1.7.9/bin/activate + pip install -r Documentation/sphinx/requirements.txt + + Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + +默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的 +需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依 +赖项则是可选的。 + +它支持两个可选参数： + +``--no-pdf`` + + 禁用PDF检查； + +``--no-virtualenv`` + + 使用Sphinx的系统打包，而不是Python虚拟环境。 + +Sphinx构建 +========== + +生成文档的常用方法是运行 ``make htmldocs`` 或 ``make pdfdocs`` 。还有其它可用 +的格式：请参阅 ``make help`` 的文档部分。生成的文档放在 ``Documentation/output`` +下相应格式的子目录中。 + +要生成文档，显然必须安装Sphinx（ ``sphinx-build`` ）。要让HTML输出更漂亮，可以 +使用Read the Docs Sphinx主题（ ``sphinx_rtd_theme`` ）。对于PDF输出，您还需要 +``XeLaTeX`` 和来自ImageMagick（https://www.imagemagick.org）的 ``convert(1)`` 。 +所有这些软件在大多发行版中都可用或已打包。 + +要传递额外的选项给Sphinx，可以使用make变量 ``SPHINXOPTS`` 。例如，使用 +``make SPHINXOPTS=-v htmldocs`` 获得更详细的输出。 + + +要删除生成的文档，请运行 ``make cleandocs`` 。 + +编写文档 +======== + +添加新文档很容易，只需： + +1. 在 ``Documentation`` 下某处添加一个新的 ``.rst`` 文件。 +2. 从 ``Documentation/index.rst`` 中的Sphinx `主目录树`_ 链接到它。 + +.. _主目录树: http://www.sphinx-doc.org/en/stable/markup/toctree.html + +对于简单的文档（比如您现在正在阅读的文档），这通常已经足够好了，但是对于较大 +的文档，最好创建一个子目录（或者使用现有的子目录）。例如，图形子系统文档位于 +``Documentation/gpu`` 下，拆分为多个 ``.rst`` 文件，并具有从主目录链接来的单 +独索引 ``index.rst`` （有自己的目录树 ``toctree`` ）。 + +请参阅 `Sphinx <http://www.sphinx-doc.org/>`_ 和 `reStructuredText +<http://docutils.sourceforge.net/rst.html>`_ 的文档，以了解如何使用它们。 +特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的 +好地方。还有一些 `Sphinx 特殊标记结构`_ 。 + +.. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.html +.. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.html + +内核文档的具体指南 +------------------ + +这是一些内核文档的具体指南： + +* 请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档 + 应该是纯文本，格式应足够一致，以便可以转换为其他格式。 + +* 将现有文档转换为reStructuredText时，请尽量减少格式更改。 + +* 在转换文档时，还要更新内容，而不仅仅是格式。 + +* 请遵循标题修饰符的顺序： + + 1. ``=`` 文档标题，要有上线:: + + ======== + 文档标题 + ======== + + 2. ``=`` 章:: + + 章标题 + ====== + + 3. ``-`` 节:: + + 节标题 + ------ + + 4. ``~`` 小节:: + + 小节标题 + ~~~~~~~~ + + 尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 + 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。 + +* 对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 + 大的内容，尤其是短代码段； ``.. code-block:: <language>`` 用于需要语法高亮的 + 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。 + + +C域 +--- + +**Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +内核文档的C域有一些附加特性。例如，您可以使用诸如 ``open`` 或 ``ioctl`` 这样的 +通用名称重命名函数的引用名称： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为 +``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。 + +请注意，不需要使用 ``c:func:`` 生成函数文档的交叉引用。由于一些Sphinx扩展的 +神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 ``function()`` +的引用转换为交叉引用。如果在内核文档中看到 ``c:func:`` 的用法，请删除它。 + + +列表 +---- + +我们建议使用 *列式表* 格式。 *列式表* 格式是二级列表。与ASCII艺术相比，它们对 +文本文件的读者来说可能没有那么舒适。但其优点是易于创建或修改，而且修改的差异 +（diff）更有意义，因为差异仅限于修改的内容。 + +*平铺表* 也是一个二级列表，类似于 *列式表* ，但具有一些额外特性： + +* 列范围：使用 ``cspan`` 修饰，可以通过其他列扩展单元格 + +* 行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格 + +* 自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 + ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 + 插入（空）单元格，而不是扩展合并到最后一个单元格。 + +选项： + +* ``:header-rows:`` [int] 标题行计数 +* ``:stub-columns:`` [int] 标题列计数 +* ``:widths:`` [[int] [int] ... ] 列宽 +* ``:fill-cells:`` 插入缺少的单元格，而不是自动合并缺少的单元格 + +修饰： + +* ``:cspan:`` [int] 扩展列 +* ``:rspan:`` [int] 扩展行 + +下面的例子演示了如何使用这些标记。分级列表的第一级是 *表格行* 。 *表格行* 中 +只允许一个标记，即该 *表格行* 中的单元格列表。 *comments* （ ``..`` ）和 +*targets* 例外（例如引用 ``:ref:`最后一行 <last row_zh>``` / :ref:`最后一行 +<last row_zh>` ）。 + +.. code-block:: rst + + .. flat-table:: 表格标题 + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - 行1 + - 字段1.1 + - 字段1.2（自动扩展） + + * - 行2 + - 字段2.1 + - :rspan:`1` :cspan:`1` 字段2.2~3.3 + + * .. _`last row_zh`: + + - 行3 + +渲染效果： + + .. flat-table:: 表格标题 + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - 行1 + - 字段1.1 + - 字段1.2（自动扩展） + + * - 行2 + - 字段2.1 + - :rspan:`1` :cspan:`1` 字段2.2~3.3 + + * .. _`last row_zh`: + + - 行3 + +交叉引用 +-------- + +从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 +要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 +交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选 +的）:: + + 参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。 + 请查看 sphinx.rst ，仅在同级目录中有效。 + 请阅读 ../sphinx.rst ，上级目录中的文件。 + +如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页 +的操作如下:: + + 参见 :doc:`sphinx文档的自定义链接文本 <sphinx>`. + +对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 +个没有任何特殊作用的 ``:doc:`` 用法，请将其转换为文档路径。 + +有关交叉引用kernel-doc函数或类型的信息，请参阅 +Documentation/doc-guide/kernel-doc.rst 。 + +.. _sphinx_kfigure_zh: + +图形图片 +======== + +如果要添加图片，应该使用 ``kernel-figure`` 和 ``kernel-image`` 指令。例如， +要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +.. _svg_image_example_zh: + +.. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +内核figure（和image）指令支持 DOT 格式文件，请参阅 + +* DOT：http://graphviz.org/pdf/dotguide.pdf +* Graphviz：http://www.graphviz.org/content/dot-language + +一个简单的例子（:ref:`hello_dot_file_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/hello.dot + :alt: 你好，世界 + + DOT 示例 + +.. _hello_dot_file_zh: + +.. kernel-figure:: ../../../doc-guide/hello.dot + :alt: 你好，世界 + + DOT 示例 + +嵌入的渲染标记（或语言），如Graphviz的 **DOT** 由 ``kernel-render`` 指令提供:: + + .. kernel-render:: DOT + :alt: 有向图 + :caption: 嵌入式 **DOT** (Graphviz) 代码 + + digraph foo { + "五棵松" -> "国贸"; + } + +如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始 +标记将作为 *文字块* 插入（:ref:`hello_dot_render_zh` ）。 + +.. _hello_dot_render_zh: + +.. kernel-render:: DOT + :alt: 有向图 + :caption: 嵌入式 **DOT** (Graphviz) 代码 + + digraph foo { + "五棵松" -> "国贸"; + } + +*render* 指令包含 *figure* 指令中已知的所有选项，以及选项 ``caption`` 。如果 +``caption`` 有值，则插入一个 *figure* 节点，若无，则插入一个 *image* 节点。 +如果您想引用它，还需要一个 ``caption`` （:ref:`hello_svg_render_zh` ）。 + +嵌入式 **SVG**:: + + .. kernel-render:: SVG + :caption: 嵌入式 **SVG** 标记 + :alt: 右上箭头 + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> + ... + </svg> + +.. _hello_svg_render_zh: + +.. kernel-render:: SVG + :caption: 嵌入式 **SVG** 标记 + :alt: 右上箭头 + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> + </svg> + diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index be6f11176200..d56d6b7092e6 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -1,25 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. raw:: latex \renewcommand\thesection* \renewcommand\thesubsection* +.. _linux_doc_zh: + 中文翻译 ======== -这些手册包含有关如何开发内核的整体信息。内核社区非常庞大，一年下来有数千名开发 -人员做出贡献。 与任何大型社区一样，知道如何完成任务将使得更改合并的过程变得更 -加容易。 -翻译计划: -内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。 +.. note:: + + **翻译计划:** + 内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。 + +许可证文档 +---------- + +下面的文档介绍了Linux内核源代码的许可证（GPLv2）、如何在源代码树中正确标记 +单个文件的许可证、以及指向完整许可证文本的链接。 + +* Documentation/translations/zh_CN/process/license-rules.rst + +用户文档 +-------- + +下面的手册是为内核用户编写的——即那些试图让它在给定系统上以最佳方式工作的 +用户。 .. toctree:: :maxdepth: 2 admin-guide/index + +TODOList: + +* kbuild/index + +固件相关文档 +------------ + +下列文档描述了内核需要的平台固件相关信息。 + +TODOList: + +* firmware-guide/index +* devicetree/index + +应用程序开发人员文档 +-------------------- + +用户空间API手册涵盖了描述应用程序开发人员可见内核接口方面的文档。 + +TODOlist: + +* userspace-api/index + +内核开发简介 +------------ + +这些手册包含有关如何开发内核的整体信息。内核社区非常庞大，一年下来有数千名 +开发人员做出贡献。与任何大型社区一样，知道如何完成任务将使得更改合并的过程 +变得更加容易。 + +.. toctree:: + :maxdepth: 2 + process/index + dev-tools/index + doc-guide/index + kernel-hacking/index + +TODOList: + +* trace/index +* maintainer/index +* fault-injection/index +* livepatch/index +* rust/index + +内核API文档 +----------- + +以下手册从内核开发人员的角度详细介绍了特定的内核子系统是如何工作的。这里的 +大部分信息都是直接从内核源代码获取的，并根据需要添加补充材料（或者至少是在 +我们设法添加的时候——可能不是所有的都是有需要的）。 + +.. toctree:: + :maxdepth: 2 + + core-api/index + cpu-freq/index + iio/index + sound/index filesystems/index + +TODOList: + +* driver-api/index +* locking/index +* accounting/index +* block/index +* cdrom/index +* ide/index +* fb/index +* fpga/index +* hid/index +* i2c/index +* isdn/index +* infiniband/index +* leds/index +* netlabel/index +* networking/index +* pcmcia/index +* power/index +* target/index +* timers/index +* spi/index +* w1/index +* watchdog/index +* virt/index +* input/index +* hwmon/index +* gpu/index +* security/index +* crypto/index +* vm/index +* bpf/index +* usb/index +* PCI/index +* scsi/index +* misc-devices/index +* scheduler/index +* mhi/index + +体系结构无关文档 +---------------- + +TODOList: + +* asm-annotations + +特定体系结构文档 +---------------- + +.. toctree:: + :maxdepth: 2 + + mips/index arm64/index + riscv/index + openrisc/index + +TODOList: + +* arm/index +* ia64/index +* m68k/index +* nios2/index +* parisc/index +* powerpc/index +* s390/index +* sh/index +* sparc/index +* x86/index +* xtensa/index + +其他文档 +-------- + +有几份未排序的文档似乎不适合放在文档的其他部分，或者可能需要进行一些调整和/或 +转换为reStructureText格式，也有可能太旧。 + +TODOList: + +* staging/index +* watch_queue 目录和表格 ---------- diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst new file mode 100644 index 000000000000..ab974faddecf --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -0,0 +1,708 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/hacking.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +============== +内核骇客指北 +============== + +:作者: Rusty Russell + +引言 +===== + +欢迎咱优雅的读者们来阅读Rusty的非常不靠谱的Linux内核骇客（Hacking）指南。本文 +描述了内核代码的常见例程和一般要求：其目标是引导有经验的C程序员入门Linux内核 +开发。我回避了实现细节：这是代码要做的，也忽略了很多有用的例程。 + +在你读这篇文章之前，请理解我从来没有想过要写这篇文章，因为我的资历太低了； +但我一直想读这样的文章，自己写是唯一的方法。我希望它能成长为一个最佳实践、 +通用起点和其他信息的汇编。 + +玩家 +======= + +在任何时候，系统中的每个CPU都可以： + +- 与任何进程无关，服务于硬件中断； + +- 与任何进程无关，服务于软件中断（softirq）或子任务（tasklet）； + +- 运行于内核空间中，与进程（用户上下文）相关联； + +- 在用户空间中运行进程。 + +它们之间有优先级顺序。最下面的两个可以互相抢占，但上面为严格的层次结构： +每个层级只能被上方的抢占。例如，当一个软中断在CPU上运行时，没有其他软中断 +会抢占它，但是硬件中断可以抢占它。不过，系统中的任何其他CPU都是独立执行的。 + +我们将会看到许多方法，用户上下文可以阻止中断，从而成为真正的不可抢占。 + +用户上下文 +------------ + +用户上下文是指当您从系统调用或其他陷阱进入时：就像用户空间一样，您可以被更 +重要的任务和中断抢占。您可以通过调用 :c:func:`schedule()` 进行睡眠。 + +.. note:: + + 在模块加载和卸载以及块设备层上的操作时，你始终处于用户上下文中。 + +在用户上下文中，当前 ``current`` 指针（指示我们当前正在执行的任务）是有效的， +且 :c:func:`in_interrupt()` （ ``include/linux/preempt.h`` ）值为非（false）。 + +.. warning:: + + 请注意，如果您禁用了抢占或软中断（见下文），:c:func:`in_interrupt()` 会 + 返回假阳性。 + +硬件中断（Hard IRQs） +---------------------- + +像定时器、网卡和键盘等都是可能在任意时刻产生中断的真实硬件。内核运行中断 +处理程序，为硬件提供服务。内核确保处理程序永远不会重入：如果相同的中断到达， +它将被排队（或丢弃）。因为它会关闭中断，所以处理程序必须很快：通常它只是 +确认中断，标记一个“软件中断”以执行并退出。 + +您可以通过 :c:func:`in_irq()` 返回真来判断您处于硬件中断状态。 + +.. warning:: + + 请注意，如果中断被禁用，这将返回假阳性（见下文）。 + +软件中断上下文：软中断（Softirqs）与子任务（Tasklets） +------------------------------------------------------- + +当系统调用即将返回用户空间或硬件中断处理程序退出时，任何标记为挂起（通常通 +过硬件中断）的“软件中断”将运行（ ``kernel/softirq.c`` ）。 + +此处完成了许多真正的中断处理工作。在向SMP过渡的早期，只有“bottom halves下半 +部”（BHs）机制，无法利用多个CPU的优势。在从那些一团糟的就电脑切换过来后不久， +我们放弃了这个限制，转而使用“软中断”。 + +``include/linux/interrupt.h`` 列出了不同的软中断。定时器软中断是一个非常重要 +的软中断（ ``include/linux/timer.h`` ）：您可以注册它以在给定时间后为您调用 +函数。 + +软中断通常是一个很难处理的问题，因为同一个软中断将同时在多个CPU上运行。因此， +子任务（ ``include/linux/interrupt.h`` ）更常用：它们是动态可注册的（意味着 +您可以拥有任意数量），并且它们还保证任何子任务都只能在一个CPU上运行，不同的 +子任务也可以同时运行。 + +.. warning:: + + “tasklet”这个名字是误导性的：它们与“任务”无关，可能更多与当时 + 阿列克谢·库兹涅佐夫享用的糟糕伏特加有关。 + +你可以使用 :c:func:`in_softirq()` 宏（ ``include/linux/preempt.h`` ）来确认 +是否处于软中断（或子任务）中。 + +.. warning:: + + 注意，如果持有 :ref:`bottom half lock <local_bh_disable_zh>` 锁，这将返回 + 假阳性。 + +一些基本规则 +================ + +缺少内存保护 + 如果你损坏了内存，无论是在用户上下文还是中断上下文中，整个机器都会崩溃。 + 你确定你不能在用户空间里做你想做的事吗？ + +缺少浮点或MMX + FPU上下文不会被保存；即使在用户上下文中，FPU状态也可能与当前进程不一致： + 您会弄乱某些用户进程的FPU状态。如果真的要这样做，就必须显式地保存/恢复 + 完整的FPU状态（并避免上下文切换）。这通常不是个好主意；请优先用定点算法。 + +严格的堆栈限制 + 对于大多数32位体系结构，根据配置选项的不同内核堆栈大约为3K到6K；对于大 + 多数64位机器，内核堆栈大约为14K，并且经常与中断共享，因此你无法使用全部。 + 应避免深度递归和栈上的巨型本地数组（用动态分配它们来代替）。 + +Linux内核是可移植的 + 就这样吧。您的代码应该是纯64位的，并且不依赖于字节序（endian）。您还应该 + 尽量减少CPU特定的东西，例如内联汇编（inline assembly）应该被干净地封装和 + 最小化以便于移植。一般来说，它应该局限于内核树中有体系结构依赖的部分。 + +输入输出控制（ioctls）：避免编写新的系统调用 +============================================== + +系统调用（system call）通常看起来像这样:: + + asmlinkage long sys_mycall(int arg) + { + return 0; + } + + +首先，在大多数情况下，您无需创建新的系统调用。创建一个字符设备并为其实现适当 +的输入输出控制（ioctls）。这比系统调用灵活得多，不必写进每个体系结构的 +``include/asm/unistd.h`` 和 ``arch/kernel/entry.S`` 文件里，而且更容易被Linus +接受。 + +如果您的程序所做的只是读取或写入一些参数，请考虑实现 :c:func:`sysfs()` 接口。 + +在输入输出控制中，您处于进程的用户上下文。出现错误时，返回一个负的错误参数 +（errno，请参阅 ``include/uapi/asm-generic/errno-base.h`` 、 +``include/uapi/asm-generic/errno.h`` 和 ``include/linux/errno.h`` ），否则返 +回0。 + +在睡眠之后，您应该检查是否出现了信号：Unix/Linux处理信号的方法是暂时退出系统 +调用，并返回 ``-ERESTARTSYS`` 错误。系统调用入口代码将切换回用户上下文，处理 +信号处理程序，然后系统调用将重新启动（除非用户禁用了该功能）。因此，您应该准 +备好处理重新启动，例如若您处理某些数据结构到一半。 + +:: + + if (signal_pending(current)) + return -ERESTARTSYS; + + +如果你要做更长时间的计算：优先考虑用户空间。如果你真的想在内核中做这件事，你 +应该定期检查你是否需要让出CPU（请记得每个CPU都有协作多任务）。 +习惯用法:: + + cond_resched(); /* Will sleep */ + + +接口设计的小注释：UNIX系统调用的格言是“提供机制而不是策略 +Provide mechanism not policy”。 + +死锁的“配方” +==================== + +您不能调用任何可能睡眠的程序，除非： + +- 您处于用户上下文中。 + +- 你未拥有任何自旋锁。 + +- 您已经启用中断（实际上，Andi Kleen说调度代码将为您启用它们，但这可能不是 + 您想要的）。 + +注意，有些函数可能隐式地睡眠：常见的是用户空间访问函数（\*_user）和没有 +``GFP_ATOMIC`` 的内存分配函数。 + +您应该始终打开 ``CONFIG_DEBUG_ATOMIC_SLEEP`` 项来编译内核，如果您违反这些 +规则，它将警告您。如果你 **真的** 违反了规则，你最终会锁住你的电脑。 + +真的会这样。 + + +常用函数/程序 +=============== + +:c:func:`printk()` +------------------ + +定义于 ``include/linux/printk.h`` + +:c:func:`printk()` 将内核消息提供给控制台、dmesg和syslog守护进程。它对于调 +试和报告错误很有用，并且可以在中断上下文中使用，但是使用时要小心：如果机器 +的控制台中充斥着printk消息则会无法使用。它使用与ANSI C printf基本兼容的格式 +字符串，并通过C字符串串联为其提供第一个“优先”参数:: + + printk(KERN_INFO "i = %u\n", i); + + +参见 ``include/linux/kern_levels.h`` ；了解其他 ``KERN_`` 值；syslog将这些值 +解释为级别。特殊用法：打印IP地址使用:: + + __be32 ipaddress; + printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + + +:c:func:`printk()` 内部使用的1K缓冲区，不捕获溢出。请确保足够使用。 + +.. note:: + + 当您开始在用户程序中将printf打成printk时，就知道自己是真正的内核程序员了 + :) + +.. note:: + + 另一个注释：最初的unix第六版源代码在其printf函数的顶部有一个注释：“printf + 不应该用于叽叽喳喳”。你也应该遵循此建议。 + +:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` +--------------------------------------------------------------------------------------------------- + +定义于 ``include/linux/uaccess.h`` / ``asm/uaccess.h`` + +**[睡眠]** + +:c:func:`put_user()` 和 :c:func:`get_user()` 用于从用户空间中获取和向用户空 +间中传出单个值（如int、char或long）。指向用户空间的指针永远不应该直接取消 +引用：应该使用这些程序复制数据。两者都返回 ``-EFAULT`` 或 0。 + +:c:func:`copy_to_user()` 和 :c:func:`copy_from_user()` 更通用：它们从/向用户 +空间复制任意数量的数据。 + +.. warning:: + + 与 :c:func:`put_user()` 和 :c:func:`get_user()` 不同，它们返回未复制的 + 数据量（即0仍然意味着成功）。 + +【是的，这个愚蠢的接口真心让我尴尬。火爆的口水仗大概每年都会发生。 +—— Rusty Russell】 + +这些函数可以隐式睡眠。它不应该在用户上下文之外调用（没有意义）、调用时禁用中断 +或获得自旋锁。 + +:c:func:`kmalloc()`/:c:func:`kfree()` +------------------------------------- + +定义于 ``include/linux/slab.h`` + +**[可能睡眠：见下]** + +这些函数用于动态请求指针对齐的内存块，类似用户空间中的malloc和free，但 +:c:func:`kmalloc()` 需要额外的标志词。重要的值： + +``GFP_KERNEL`` + 可以睡眠和交换以释放内存。只允许在用户上下文中使用，但这是分配内存最可靠 + 的方法。 + +``GFP_ATOMIC`` + 不会睡眠。较 ``GFP_KERNEL`` 更不可靠，但可以从中断上下文调用。你 **应该** + 有一个很好的内存不足错误处理策略。 + +``GFP_DMA`` + 分配低于16MB的ISA DMA。如果你不知道那是什么，那你就不需要了。非常不可靠。 + +如果您看到一个从无效上下文警告消息调用的睡眠的函数，那么您可能在没有 +``GFP_ATOMIC`` 的情况下从中断上下文调用了一个睡眠的分配函数。你必须立即修复， +快点！ + +如果你要分配至少 ``PAGE_SIZE`` （ ``asm/page.h`` 或 ``asm/page_types.h`` ） +字节，请考虑使用 :c:func:`__get_free_pages()` （ ``include/linux/gfp.h`` ）。 +它采用顺序参数（0表示页面大小，1表示双页，2表示四页……）和与上述相同的内存 +优先级标志字。 + +如果分配的字节数超过一页，可以使用 :c:func:`vmalloc()` 。它将在内核映射中分 +配虚拟内存。此块在物理内存中不是连续的，但是MMU（内存管理单元）使它看起来像 +是为您准备好的连续空间（因此它只是看起来对cpu连续，对外部设备驱动程序则不然）。 +如果您真的需要为一些奇怪的设备提供大量物理上连续的内存，那么您就会遇到问题： +Linux对此支持很差，因为正在运行的内核中的内存碎片化会使它变得很困难。最好的 +方法是在引导过程的早期通过 :c:func:`alloc_bootmem()` 函数分配。 + +在创建自己的常用对象缓存之前，请考虑使用 ``include/linux/slab.h`` 中的slab +缓存。 + +:c:macro:`current` +------------------ + +定义于 ``include/asm/current.h`` + +此全局变量（其实是宏）包含指向当前任务结构（task structure）的指针，因此仅在 +用户上下文中有效。例如，当进程进行系统调用时，这将指向调用进程的任务结构。 +在中断上下文中不为空（**not NULL**）。 + +:c:func:`mdelay()`/:c:func:`udelay()` +------------------------------------- + +定义于 ``include/asm/delay.h`` / ``include/linux/delay.h`` + +:c:func:`udelay()` 和 :c:func:`ndelay()` 函数可被用于小暂停。不要对它们使用 +大的值，因为这样会导致溢出——帮助函数 :c:func:`mdelay()` 在这里很有用，或者 +考虑 :c:func:`msleep()`。 + +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +----------------------------------------------------------------------------------------------- + +定义于 ``include/asm/byteorder.h`` + +:c:func:`cpu_to_be32()` 系列函数（其中“32”可以替换为64或16，“be”可以替换为 +“le”）是在内核中进行字节序转换的常用方法：它们返回转换后的值。所有的变体也 +提供反向转换函数： +:c:func:`be32_to_cpu()` 等。 + +这些函数有两个主要的变体：指针变体，例如 :c:func:`cpu_to_be32p()` ，它获取 +指向给定类型的指针，并返回转换后的值。另一个变体是“in-situ”系列，例如 +:c:func:`cpu_to_be32s()` ，它转换指针引用的值，并返回void。 + +:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` +-------------------------------------------------------- + +定义于 ``include/linux/irqflags.h`` + + +这些程序禁用本地CPU上的硬中断，并还原它们。它们是可重入的；在其一个 +``unsigned long flags`` 参数中保存以前的状态。如果您知道中断已启用，那么可 +直接使用 :c:func:`local_irq_disable()` 和 :c:func:`local_irq_enable()`。 + +.. _local_bh_disable_zh: + +:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` +-------------------------------------------------------- + +定义于 ``include/linux/bottom_half.h`` + + +这些程序禁用本地CPU上的软中断，并还原它们。它们是可重入的；如果之前禁用了 +软中断，那么在调用这对函数之后仍然会禁用它们。它们阻止软中断和子任务在当前 +CPU上运行。 + +:c:func:`smp_processor_id()` +---------------------------- + +定义于 ``include/linux/smp.h`` + +:c:func:`get_cpu()` 禁用抢占（这样您就不会突然移动到另一个cpu）并返回当前 +处理器号，介于0和 ``NR_CPUS`` 之间。请注意，CPU编号不一定是连续的。完成后， +使用 :c:func:`put_cpu()` 再次返回。 + +如果您知道您不能被另一个任务抢占（即您处于中断上下文中，或已禁用抢占），您 +可以使用 :c:func:`smp_processor_id()`。 + +``__init``/``__exit``/``__initdata`` +------------------------------------ + +定义于 ``include/linux/init.h`` + +引导之后，内核释放一个特殊的部分；用 ``__init`` 标记的函数和用 ``__initdata`` +标记的数据结构在引导完成后被丢弃：同样地，模块在初始化后丢弃此内存。 +``__exit`` 用于声明只在退出时需要的函数：如果此文件未编译为模块，则该函数将 +被删除。请参阅头文件以使用。请注意，使用 :c:func:`EXPORT_SYMBOL()` 或 +:c:func:`EXPORT_SYMBOL_GPL()` 将标记为 ``__init`` 的函数导出到模块是没有意义 +的——这将出问题。 + + +:c:func:`__initcall()`/:c:func:`module_init()` +---------------------------------------------- + +定义于 ``include/linux/init.h`` / ``include/linux/module.h`` + +内核的许多部分都作为模块（内核的可动态加载部分）良好服务。使用 +:c:func:`module_init()` 和 :c:func:`module_exit()` 宏可以简化代码编写，无需 +``#ifdef`` ，即可以作为模块运行或内置在内核中。 + +:c:func:`module_init()` 宏定义在模块插入时（如果文件编译为模块）或在引导时 +调用哪个函数：如果文件未编译为模块，:c:func:`module_init()` 宏将等效于 +:c:func:`__initcall()` ，它通过链接器的魔力确保在引导时调用该函数。 + +该函数可以返回一个错误值，以导致模块加载失败（不幸的是，如果将模块编译到内核 +中，则此操作无效）。此函数在启用中断的用户上下文中调用，因此可以睡眠。 + +:c:func:`module_exit()` +----------------------- + + +定义于 ``include/linux/module.h`` + +这个宏定义了在模块删除时要调用的函数（如果是编译到内核中的文件，则无用武之地）。 +只有在模块使用计数到零时才会调用它。这个函数也可以睡眠，但不能失败：当它返回 +时，所有的东西都必须清理干净。 + +注意，这个宏是可选的：如果它不存在，您的模块将不可移除（除非 ``rmmod -f`` ）。 + +:c:func:`try_module_get()`/:c:func:`module_put()` +------------------------------------------------- + +定义于 ``include/linux/module.h`` + +这些函数会操作模块使用计数，以防止删除（如果另一个模块使用其导出的符号之一， +则无法删除模块，参见下文）。在调用模块代码之前，您应该在该模块上调用 +:c:func:`try_module_get()` ：若失败，那么该模块将被删除，您应该将其视为不存在。 +若成功，您就可以安全地进入模块，并在完成后调用模块 :c:func:`module_put()` 。 + +大多数可注册结构体都有所有者字段，例如在 +:c:type:`struct file_operations <file_operations>` 结构体中，此字段应设置为 +宏 ``THIS_MODULE`` 。 + +等待队列 ``include/linux/wait.h`` +==================================== + +**[睡眠]** + +等待队列用于等待某程序在条件为真时唤醒另一程序。必须小心使用，以确保没有竞争 +条件。先声明一个 :c:type:`wait_queue_head_t` ，然后对希望等待该条件的进程声明 +一个关于它们自己的 :c:type:`wait_queue_entry_t` ，并将其放入队列中。 + +声明 +----- + +使用 :c:func:`DECLARE_WAIT_QUEUE_HEAD()` 宏声明一个 ``wait_queue_head_t`` ， +或者在初始化代码中使用 :c:func:`init_waitqueue_head()` 程序。 + +排队 +----- + +将自己放在等待队列中相当复杂，因为你必须在检查条件之前将自己放入队列中。有一 +个宏可以来执行此操作： :c:func:`wait_event_interruptible()` +（ ``include/linux/wait.h`` ）第一个参数是等待队列头，第二个参数是计算的表达 +式；当该表达式为true时宏返回0，或者在接收到信号时返回 ``-ERESTARTSYS`` 。 +:c:func:`wait_event()` 版本会忽略信号。 + +唤醒排队任务 +------------- + +调用 :c:func:`wake_up()` （ ``include/linux/wait.h`` ），它将唤醒队列中的所有 +进程。例外情况：如果有一个进程设置了 ``TASK_EXCLUSIVE`` ，队列的其余部分将不 +会被唤醒。这个基本函数的其他变体也可以在同一个头文件中使用。 + +原子操作 +========= + +某些操作在所有平台上都有保证。第一类为操作 :c:type:`atomic_t` +（ ``include/asm/atomic.h`` ）的函数；它包含一个有符号整数（至少32位长）， +您必须使用这些函数来操作或读取 :c:type:`atomic_t` 变量。 +:c:func:`atomic_read()` 和 :c:func:`atomic_set()` 获取并设置计数器，还有 +:c:func:`atomic_add()` ，:c:func:`atomic_sub()` ，:c:func:`atomic_inc()` ， +:c:func:`atomic_dec()` 和 :c:func:`atomic_dec_and_test()` （如果递减为零， +则返回true）。 + +是的。它在原子变量为零时返回true（即!=0）。 + +请注意，这些函数比普通的算术运算速度慢，因此不应过度使用。 + +第二类原子操作是在 ``unsigned long`` （ ``include/linux/bitops.h`` ）上的 +原子位操作。这些操作通常采用指向位模式（bit pattern）的指针，第0位是最低有效 +位。:c:func:`set_bit()`，:c:func:`clear_bit()` 和 :c:func:`change_bit()` 设置、 +清除和更改给定位。:c:func:`test_and_set_bit()` ，:c:func:`test_and_clear_bit()` +和 :c:func:`test_and_change_bit()` 执行相同的操作，但如果之前设置了位，则返回 +true；这些对于原子设置标志特别有用。 + +可以使用大于 ``BITS_PER_LONG`` 位的位索引调用这些操作。但结果在大端序平台上 +不太正常，所以最好不要这样做。 + +符号 +===== + +在内核内部，正常的链接规则仍然适用（即除非用static关键字将符号声明为文件范围， +否则它可以在内核中的任何位置使用）。但是对于模块，会保留一个特殊可导出符号表， +该表将入口点限制为内核内部。模块也可以导出符号。 + +:c:func:`EXPORT_SYMBOL()` +------------------------- + +定义于 ``include/linux/export.h`` + +这是导出符号的经典方法：动态加载的模块将能够正常使用符号。 + +:c:func:`EXPORT_SYMBOL_GPL()` +----------------------------- + +定义于 ``include/linux/export.h`` + + +类似于 :c:func:`EXPORT_SYMBOL()`，只是 :c:func:`EXPORT_SYMBOL_GPL()` 导出的 +符号只能由具有由 :c:func:`MODULE_LICENSE()` 指定GPL兼容许可证的模块看到。这 +意味着此函数被认为是一个内部实现问题，而不是一个真正的接口。一些维护人员和 +开发人员在添加一些新的API或功能时可能却需要导出 EXPORT_SYMBOL_GPL()。 + +:c:func:`EXPORT_SYMBOL_NS()` +---------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL()`` 的变体，允许指定符号命名空间。符号名称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +:c:func:`EXPORT_SYMBOL_NS_GPL()` +-------------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL_GPL()`` 的变体，允许指定符号命名空间。符号名称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +程序与惯例 +=========== + +双向链表 ``include/linux/list.h`` +----------------------------------- + +内核头文件中曾经有三组链表程序，但这一组是赢家。如果你对一个单链表没有特别迫切的 +需求，那么这是一个不错的选择。 + +通常 :c:func:`list_for_each_entry()` 很有用。 + +返回值惯例 +------------ + +对于在用户上下文中调用的代码，违背C语言惯例是很常见的，即返回0表示成功，返回 +负错误值（例如 ``-EFAULT`` ）表示失败。这在一开始可能是不直观的，但在内核中 +相当普遍。 + +使用 :c:func:`ERR_PTR()` （ ``include/linux/err.h`` ）将负错误值编码到指针中， +然后使用 :c:func:`IS_ERR()` 和 :c:func:`PTR_ERR()` 将其再取出：避免为错误值 +使用单独的指针参数。挺讨厌的，但的确是个好方式。 + +破坏编译 +---------- + +Linus和其他开发人员有时会更改开发内核中的函数或结构体名称；这样做不仅是为了 +让每个人都保持警惕，还反映了一个重大的更改（例如，不能再在打开中断的情况下 +调用，或者执行额外的检查，或者不执行以前捕获的检查）。通常这会附带一个linux +内核邮件列表中相当全面的注释；请搜索存档以查看。简单地对文件进行全局替换通常 +会让事情变得 **更糟** 。 + +初始化结构体成员 +------------------ + +初始化结构体的首选方法是使用指定的初始化器，如ISO C99所述。 +例如:: + + static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, + }; + + +这使得很容易查找（grep），并且可以清楚地看到设置了哪些结构字段。你应该这样做， +因为它看起来很酷。 + +GNU 扩展 +---------- + +Linux内核中明确允许GNU扩展。请注意，由于缺乏通用性，一些更复杂的版本并没有 +得到很好的支持，但以下内容被认为是标准的（有关更多详细信息，请参阅GCC info页 +的“C 扩展”部分——是的，实际上是info页，手册页只是info中内容的简短摘要）。 + +- 内联函数 + +- 语句表达式（Statement expressions）（即（{ 和 }）结构）。 + + +- 声明函数/变量/类型的属性（__attribute__） + +- typeof + +- 零长度数组 + +- 宏变量 + +- 空指针运算 + +- 非常量（Non-Constant）初始化程序 + +- 汇编程序指令（在 arch/ 和 include/asm/ 之内） + +- 字符串函数名（__func__）。 + +- __builtin_constant_p() + +在内核中使用long long时要小心，gcc为其生成的代码非常糟糕：除法和乘法在i386上 +不能工作，因为内核环境中缺少用于它的gcc运行时函数。 + +C++ +--- + +在内核中使用C++通常是个坏主意，因为内核不提供必要的运行时环境，并且不为其 +测试包含文件。不过这仍然是可能的，但不建议。如果你真的想这么做，至少别用 +异常处理（exceptions）。 + +#if +--- + +通常认为，在头文件（或.c文件顶部）中使用宏来抽象函数比在源代码中使用“if”预 +处理器语句更干净。 + +把你的东西放进内核里 +====================== + +为了让你的东西更正式、补丁更整洁，还有一些工作要做： + +- 搞清楚你在谁的地界儿上干活。查看源文件的顶部、 ``MAINTAINERS`` 文件以及 + ``CREDITS`` 文件的最后一部分。你应该和此人协调，确保你没有重新发明轮子， + 或者尝试一些已经被拒绝的东西。 + + 确保你把你的名字和电子邮件地址放在你创建或修改的任何文件的顶部。当人们发 + 现一个缺陷，或者想要做出修改时，这是他们首先会看的地方。 + +- 通常你需要一个配置选项来支持你的内核编程。在适当的目录中编辑 ``Kconfig`` 。 + 配置语言很容易通过剪切和粘贴来使用，在 + Documentation/kbuild/kconfig-language.rst 中有完整的文档。 + + 在您对选项的描述中，请确保同时照顾到了专家用户和对此功能一无所知的用户。 + 在此说明任何不兼容和问题。结尾一定要写上“如有疑问，就选N”（或者是“Y”）； + 这是针对那些看不懂你在说什么的人的。 + +- 编辑 ``Makefile`` ：配置变量在这里导出，因此通常你只需添加一行 + “obj-$(CONFIG_xxx) += xxx.o”。语法记录在 + Documentation/kbuild/makefiles.rst 。 + +- 如果你做了一些有意义的事情，那可以把自己放进 ``CREDITS`` ，通常不止一个 + 文件（无论如何你的名字都应该在源文件的顶部）。维护人员意味着您希望在对 + 子系统进行更改时得到询问，并了解缺陷；这意味着对某部分代码做出更多承诺。 + +- 最后，别忘记去阅读 Documentation/process/submitting-patches.rst ， + 也许还有 Documentation/process/submitting-drivers.rst 。 + +Kernel 仙女棒 +=============== + +浏览源代码时的一些收藏。请随意添加到此列表。 + +``arch/x86/include/asm/delay.h``:: + + #define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + + +``include/linux/fs.h``:: + + /* + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a dentry + * pointer with the same return value. + * + * This should be a per-architecture thing, to allow different + * error and pointer decisions. + */ + #define ERR_PTR(err) ((void *)((long)(err))) + #define PTR_ERR(ptr) ((long)(ptr)) + #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) + +``arch/x86/include/asm/uaccess_32.h:``:: + + #define copy_to_user(to,from,n) \ + (__builtin_constant_p(n) ? \ + __constant_copy_to_user((to),(from),(n)) : \ + __generic_copy_to_user((to),(from),(n))) + + +``arch/sparc/kernel/head.S:``:: + + /* + * Sun people can't spell worth damn. "compatibility" indeed. + * At least we *know* we can't spell, and use a spell-checker. + */ + + /* Uh, actually Linus it is I who cannot spell. Too much murky + * Sparc assembly will do this to ya. + */ + C_LABEL(cputypvar): + .asciz "compatibility" + + /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ + .align 4 + C_LABEL(cputypvar_sun4m): + .asciz "compatible" + + +``arch/sparc/lib/checksum.S:``:: + + /* Sun, you just can't beat me, you just can't. Stop trying, + * give up. I'm serious, I am going to kick the living shit + * out of you, game over, lights out. + */ + + +致谢 +===== + +感谢Andi Kleen提出点子，回答我的问题，纠正我的错误，充实内容等帮助。 +感谢Philipp Rumpf做了许多拼写和清晰度修复，以及一些优秀的不明显的点。 +感谢Werner Almesberger对 :c:func:`disable_irq()` 做了一个很好的总结， +Jes Sorensen和Andrea Arcangeli补充了一些注意事项。 +感谢Michael Elizabeth Chastain检查并补充了配置部分。 +感谢Telsa Gwynne教我DocBook。 diff --git a/Documentation/translations/zh_CN/kernel-hacking/index.rst b/Documentation/translations/zh_CN/kernel-hacking/index.rst new file mode 100644 index 000000000000..df530de2278d --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/index.rst @@ -0,0 +1,22 @@ +.. _kernel_hacking_zh: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/index.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +============= +内核骇客指南 +============= + +.. toctree:: + :maxdepth: 2 + + hacking + +TODO + +- locking diff --git a/Documentation/translations/zh_CN/openrisc/index.rst b/Documentation/translations/zh_CN/openrisc/index.rst new file mode 100644 index 000000000000..d722642796c8 --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_index: + + +================= +OpenRISC 体系架构 +================= + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +Todolist: + features + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst new file mode 100644 index 000000000000..e87d0eec281d --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst @@ -0,0 +1,124 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/openrisc_port` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_port: + +============== +OpenRISC Linux +============== + +这是Linux对OpenRISC类微处理器的移植；具体来说，最早移植目标是32位 +OpenRISC 1000系列（或1k）。 + +关于OpenRISC处理器和正在进行中的开发的信息: + + ======= ============================= + 网站 https://openrisc.io + 邮箱 openrisc@lists.librecores.org + ======= ============================= + +--------------------------------------------------------------------- + +OpenRISC工具链和Linux的构建指南 +=============================== + +为了构建和运行Linux for OpenRISC，你至少需要一个基本的工具链，或许 +还需要架构模拟器。 这里概述了准备就位这些部分的步骤。 + +1) 工具链 + +工具链二进制文件可以从openrisc.io或我们的github发布页面获得。不同 +工具链的构建指南可以在openrisc.io或Stafford的工具链构建和发布脚本 +中找到。 + + ====== ================================================= + 二进制 https://github.com/openrisc/or1k-gcc/releases + 工具链 https://openrisc.io/software + 构建 https://github.com/stffrdhrn/or1k-toolchain-build + ====== ================================================= + +2) 构建 + +像往常一样构建Linux内核:: + + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" defconfig + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" + +3) 在FPGA上运行（可选) + +OpenRISC社区通常使用FuseSoC来管理构建和编程SoC到FPGA中。 下面是用 +OpenRISC SoC对De0 Nano开发板进行编程的一个例子。 在构建过程中， +FPGA RTL是从FuseSoC IP核库中下载的代码，并使用FPGA供应商工具构建。 +二进制文件用openocd加载到电路板上。 + +:: + + git clone https://github.com/olofk/fusesoc + cd fusesoc + sudo pip install -e . + + fusesoc init + fusesoc build de0_nano + fusesoc pgm de0_nano + + openocd -f interface/altera-usb-blaster.cfg \ + -f board/or1k_generic.cfg + + telnet localhost 4444 + > init + > halt; load_image vmlinux ; reset + +4) 在模拟器上运行（可选） + +QEMU是一个处理器仿真器，我们推荐它来模拟OpenRISC平台。 请按照QEMU网 +站上的OpenRISC说明，让Linux在QEMU上运行。 你可以自己构建QEMU，但你的 +Linux发行版可能提供了支持OpenRISC的二进制包。 + + ============= ====================================================== + qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== + +--------------------------------------------------------------------- + +术语表 +====== + +代码中使用了以下符号约定以将范围限制在几个特定处理器实现上： + +========= ======================= +openrisc: OpenRISC类型处理器 +or1k: OpenRISC 1000系列处理器 +or1200: OpenRISC 1200处理器 +========= ======================= + +--------------------------------------------------------------------- + +历史 +==== + +2003-11-18 Matjaz Breskvar (phoenix@bsemi.com) + 将linux初步移植到OpenRISC或32架构。 + 所有的核心功能都实现了，并且可以使用。 + +2003-12-08 Matjaz Breskvar (phoenix@bsemi.com) + 彻底改变TLB失误处理。 + 重写异常处理。 + 在默认的initrd中实现了sash-3.6的所有功能。 + 大幅改进的版本。 + +2004-04-10 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修复。 + 支持以太网，http和telnet服务器功能。 + 可以运行许多标准的linux应用程序。 + +2004-06-26 Matjaz Breskvar (phoenix@bsemi.com) + 移植到2.6.x。 + +2004-11-30 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修复和增强功能。 + 增加了opencores framebuffer驱动。 + +2010-10-09 Jonas Bonn (jonas@southpole.se) + 重大重写，使其与上游的Linux 2.6.36看齐。 diff --git a/Documentation/translations/zh_CN/openrisc/todo.rst b/Documentation/translations/zh_CN/openrisc/todo.rst new file mode 100644 index 000000000000..9944ad05473b --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/todo.rst @@ -0,0 +1,20 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/todo` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_todo.rst: + +======== +待办事项 +======== + +OpenRISC Linux的移植已经完全投入使用，并且从 2.6.35 开始就一直在上游同步。 +然而，还有一些剩余的项目需要在未来几个月内完成。 下面是一个即将进行调查的已知 +不尽完美的项目列表，即我们的待办事项列表。 + +- 实现其余的DMA API……dma_map_sg等。 + +- 完成重命名清理工作……代码中提到了or32，这是架构的一个老名字。 我们 + 已经确定的名字是or1k，这个改变正在以缓慢积累的方式进行。 目前，or32相当 + 于or1k。 diff --git a/Documentation/translations/zh_CN/process/1.Intro.rst b/Documentation/translations/zh_CN/process/1.Intro.rst index 10a15f3dc282..4f9284cbe33b 100644 --- a/Documentation/translations/zh_CN/process/1.Intro.rst +++ b/Documentation/translations/zh_CN/process/1.Intro.rst @@ -1,162 +1,170 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process_intro: -介绍 +引言 ==== -执行摘要 +内容提要 -------- -本节的其余部分涵盖了内核开发过程的范围，以及开发人员及其雇主在这方面可能遇 -到的各种挫折。内核代码应该合并到正式的（“主线”）内核中有很多原因，包括对用 -户的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux -内核的代码必须在与GPL兼容的许可证下可用。 +本节的其余部分涵盖了内核开发的过程，以及开发人员及其雇主在这方面可能遇到的 +各种问题。有很多原因使内核代码应被合并到正式的（“主线”）内核中，包括对用户 +的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux内核 +的代码必须在与GPL兼容的许可证下可用。 :ref:`cn_development_process` 介绍了开发过程、内核发布周期和合并窗口的机制。 -涵盖了补丁开发、审查和合并周期中的各个阶段。有一些关于工具和邮件列表的讨论。 -鼓励希望开始内核开发的开发人员作为初始练习跟踪并修复bug。 +涵盖了补丁开发、审查和合并周期中的各个阶段。还有一些关于工具和邮件列表的讨论？ +鼓励希望开始内核开发的开发人员跟踪并修复缺陷以作为初步练习。 -:ref:`cn_development_early_stage` 包括早期项目规划，重点是尽快让开发社区参与 +:ref:`cn_development_early_stage` 包括项目的早期规划，重点是尽快让开发社区 +参与进来。 -:ref:`cn_development_coding` 是关于编码过程的；讨论了其他开发人员遇到的几个 -陷阱。对补丁的一些要求已经涵盖，并且介绍了一些工具，这些工具有助于确保内核 +:ref:`cn_development_coding` 是关于编程过程的；介绍了其他开发人员遇到的几个 +陷阱。也涵盖了对补丁的一些要求，并且介绍了一些工具，这些工具有助于确保内核 补丁是正确的。 -:ref:`cn_development_posting` 讨论发布补丁以供评审的过程。为了让开发社区 -认真对待，补丁必须正确格式化和描述，并且必须发送到正确的地方。遵循本节中的 -建议有助于确保为您的工作提供最好的接纳。 +:ref:`cn_development_posting` 描述发布补丁以供评审的过程。为了让开发社区能 +认真对待，补丁必须被正确格式化和描述，并且必须发送到正确的地方。遵循本节中的 +建议有助于确保您的工作能被较好地接纳。 -:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；该工作 -在这一点上还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节 -提供了一些关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时， -开发人员要注意不要假定任务已经完成。 +:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；工作在这时 +还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节提供了一些 +关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时，开发人员要注意 +不要假定任务已经完成。 -:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题： -使用Git管理补丁和查看其他人发布的补丁。 +:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题：使用Git管理补丁 +和查看其他人发布的补丁。 -:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有带有 -指向资源的链接. +:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有相关资源 +链接。 -这个文件是关于什么的 +这个文档是关于什么的 -------------------- -Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃 -的免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统 -组件，运行在袖珍数字音乐播放器、台式PC、现存最大的超级计算机以及所有类型的 -系统上。它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。 +Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃的 +免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统组件， +运行在袖珍数字音乐播放器、台式电脑、现存最大的超级计算机以及所有类型的系统上。 +它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。 随着Linux的发展，希望参与其开发的开发人员（和公司）的数量也在增加。硬件供应商 希望确保Linux能够很好地支持他们的产品，使这些产品对Linux用户具有吸引力。嵌入 式系统供应商使用Linux作为集成产品的组件，希望Linux能够尽可能地胜任手头的任务。 -分销商和其他基于Linux的软件供应商对Linux内核的功能、性能和可靠性有着明确的 -兴趣。最终用户也常常希望修改Linux，使之更好地满足他们的需求。 +分销商和其他基于Linux的软件供应商切实关心Linux内核的功能、性能和可靠性。最终 +用户也常常希望修改Linux，使之能更好地满足他们的需求。 Linux最引人注目的特性之一是这些开发人员可以访问它；任何具备必要技能的人都可以 改进Linux并影响其开发方向。专有产品不能提供这种开放性，这是自由软件的一个特点。 -但是，如果有什么不同的话，内核比大多数其他自由软件项目更开放。一个典型的三个月 -内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司 -（或者根本没有公司）工作。 +如果有什么不同的话，那就是内核比大多数其他自由软件项目更开放。一个典型的三个 +月内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司（或者根本不 +隶属公司）工作。 -与内核开发社区合作并不是特别困难。但是，尽管如此，许多潜在的贡献者在尝试做 -内核工作时遇到了困难。内核社区已经发展了自己独特的操作方式，使其能够在每天 +与内核开发社区合作并不是特别困难。但尽管如此，仍有许多潜在的贡献者在尝试做 +内核工作时遇到了困难。内核社区已经发展出自己独特的操作方式，使其能够在每天 都要更改数千行代码的环境中顺利运行（并生成高质量的产品）。因此，Linux内核开发 -过程与专有的开发方法有很大的不同也就不足为奇了。 +过程与专有的开发模式有很大的不同也就不足为奇了。 -对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这个背后有充分的 -理由和坚实的经验。一个不了解内核社区的方式的开发人员（或者更糟的是，他们试图 -抛弃或规避内核社区的方式）会有一个令人沮丧的体验。开发社区, 在帮助那些试图学习 -的人的同时，没有时间帮助那些不愿意倾听或不关心开发过程的人。 +对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这背后有充分的 +理由和坚实的经验。一个不了解内核社区工作方式的开发人员（或者更糟的是，他们 +试图抛弃或规避之）会得到令人沮丧的体验。开发社区在帮助那些试图学习的人的同时， +没有时间帮助那些不愿意倾听或不关心开发过程的人。 -希望阅读本文的人能够避免这种令人沮丧的经历。这里有很多材料，但阅读时所做的 +希望阅读本文的人能够避免这种令人沮丧的经历。这些材料很长，但阅读它们时所做的 努力会在短时间内得到回报。开发社区总是需要能让内核变更好的开发人员；下面的 -文本应该帮助您或为您工作的人员加入我们的社区。 +文字应该帮助您或为您工作的人员加入我们的社区。 致谢 ---- -本文件由Jonathan Corbet撰写，corbet@lwn.net。以下人员的建议使之更为完善： +本文档由Jonathan Corbet <corbet@lwn.net> 撰写。以下人员的建议使之更为完善： Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson, -Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß. +Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 这项工作得到了Linux基金会的支持，特别感谢Amanda McPherson，他看到了这项工作 -的价值并把它变成现实。 +的价值并将其变成现实。 代码进入主线的重要性 -------------------- 有些公司和开发人员偶尔会想，为什么他们要费心学习如何与内核社区合作，并将代码 放入主线内核（“主线”是由Linus Torvalds维护的内核，Linux发行商将其用作基础）。 -在短期内，贡献代码看起来像是一种可以避免的开销；仅仅将代码分开并直接支持用户 +在短期内，贡献代码看起来像是一种可以避免的开销；维护独立代码并直接支持用户 似乎更容易。事实上，保持代码独立（“树外”）是在经济上是错误的。 -作为说明树外代码成本的一种方法，下面是内核开发过程的一些相关方面；本文稍后将 -更详细地讨论其中的大部分内容。考虑： +为了说明树外代码成本，下面给出内核开发过程的一些相关方面；本文稍后将更详细地 +讨论其中的大部分内容。请考虑： - 所有Linux用户都可以使用合并到主线内核中的代码。它将自动出现在所有启用它的 - 发行版上。不需要驱动程序磁盘、下载，也不需要为多个发行版的多个版本提供支持； - 对于开发人员和用户来说，这一切都是可行的。并入主线解决了大量的分布和支持问题 + 发行版上。无需驱动程序磁盘、额外下载，也不需要为多个发行版的多个版本提供 + 支持；这一切将方便所有开发人员和用户。并入主线解决了大量的分发和支持问题。 -- 当内核开发人员努力维护一个稳定的用户空间接口时，内部内核API处于不断变化之中. - 缺乏一个稳定的内部接口是一个深思熟虑的设计决策；它允许在任何时候进行基本的改 - 进，并产生更高质量的代码。但该策略的一个结果是，如果要使用新的内核，任何树外 - 代码都需要持续的维护。维护树外代码需要大量的工作才能使代码保持工作状态。 +- 当内核开发人员努力维护一个稳定的用户空间接口时，内核内部API处于不断变化之中。 + 不维持稳定的内部接口是一个慎重的设计决策；它允许在任何时候进行基本的改进， + 并产出更高质量的代码。但该策略导致结果是，若要使用新的内核，任何树外代码都 + 需要持续的维护。维护树外代码会需要大量的工作才能使代码保持正常运行。 - 相反，位于主线中的代码不需要这样做，因为一个简单的规则要求进行API更改的任何 - 开发人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大 - 降低了维护成本。 + 相反，位于主线中的代码不需要这样做，因为基本规则要求进行API更改的任何开发 + 人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大降低 + 了维护成本。 -- 除此之外，内核中的代码通常会被其他开发人员改进。令人惊讶的结果可能来自授权 - 您的用户社区和客户改进您的产品。 +- 除此之外，内核中的代码通常会被其他开发人员改进。您授权的用户社区和客户对您 + 产品的改进可能会令人惊喜。 -- 内核代码在合并到主线之前和之后都要经过审查。不管原始开发人员的技能有多强， +- 内核代码在合并到主线之前和之后都要经过审查。无论原始开发人员的技能有多强， 这个审查过程总是能找到改进代码的方法。审查经常发现严重的错误和安全问题。 - 这对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益 - 匪浅。树外代码是低质量代码。 + 对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益匪浅。 + 树外代码是低质量代码。 - 参与开发过程是您影响内核开发方向的方式。旁观者的抱怨会被听到，但是活跃的 开发人员有更强的声音——并且能够实现使内核更好地满足其需求的更改。 - 当单独维护代码时，总是存在第三方为类似功能提供不同实现的可能性。如果发生 - 这种情况，合并代码将变得更加困难——甚至到了不可能的地步。然后，您将面临以下 - 令人不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户 - 迁移到树内版本。 + 这种情况，合并代码将变得更加困难——甚至成为不可能。之后，您将面临以下令人 + 不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户迁移 + 到树内版本。 -- 代码的贡献是使整个过程工作的根本。通过贡献代码，您可以向内核添加新功能，并 - 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者 - 正在考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功 - 的最好方法之一。 +- 代码的贡献是使整个流程工作的根本。通过贡献代码，您可以向内核添加新功能，并 + 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者正在 + 考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功的 + 最好方法之一。 上述所有理由都适用于任何树外内核代码，包括以专有的、仅二进制形式分发的代码。 -然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。这些包括： +然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。包括： -- 围绕专有内核模块分发的法律问题充其量是模糊的；相当多的内核版权所有者认为， - 大多数仅限二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共 - 许可证（下面将详细介绍）。您的作者不是律师，本文档中的任何内容都不可能被 +- 围绕专有内核模块分发的法律问题其实较为模糊；相当多的内核版权所有者认为， + 大多数仅二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共 + 许可证（下面将详细介绍）。本文作者不是律师，本文档中的任何内容都不可能被 视为法律建议。封闭源代码模块的真实法律地位只能由法院决定。但不管怎样，困扰 这些模块的不确定性仍然存在。 - 二进制模块大大增加了调试内核问题的难度，以至于大多数内核开发人员甚至都不会 尝试。因此，只分发二进制模块将使您的用户更难从社区获得支持。 -- 对于只支持二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持 - 的每个发行版和每个内核版本提供一个版本的模块。为了提供相当全面的覆盖范围， +- 对于仅二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持的 + 每个发行版和每个内核版本提供不同版本的模块。为了提供较为全面的覆盖范围， 可能需要一个模块的几十个构建，并且每次升级内核时，您的用户都必须单独升级 - 您的模块。 + 这些模块。 -- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码。由于该代码根本不可 - 用，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。 +- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码中。由于该代码根本 + 不可得，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。 -尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容，因为他们 +尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容；因为他们 相信自己正在商用一种使用冻结内核版本的独立产品，在发布后不需要再进行开发。 这个论点忽略了广泛的代码审查的价值以及允许用户向产品添加功能的价值。但这些 -产品也有有限的商业寿命，之后必须发布新版本的产品。在这一点上，代码在主线上 -并得到良好维护的供应商将能够更好地占位，以使新产品快速上市。 +产品的商业寿命有限，之后必须发布新版本的产品。在这一点上，代码在主线上并得到 +良好维护的供应商将能够更好地占位，以使新产品快速上市。 许可 ---- @@ -164,23 +172,24 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß. 代码是根据一些许可证提供给Linux内核的，但是所有代码都必须与GNU通用公共许可 证（GPLV2）的版本2兼容，该版本是覆盖整个内核分发的许可证。在实践中，这意味 着所有代码贡献都由GPLv2（可选地，语言允许在更高版本的GPL下分发）或3子句BSD -许可（New BSD License, 译者注）覆盖。任何不包含在兼容许可证中的贡献都不会 +许可（New BSD License，译者注）覆盖。任何不包含在兼容许可证中的贡献都不会 被接受到内核中。 贡献给内核的代码不需要（或请求）版权分配。合并到主线内核中的所有代码都保留 其原始所有权；因此，内核现在拥有数千个所有者。 -这种所有权结构的一个暗示是，任何改变内核许可的尝试都注定会失败。很少有实际 -的场景可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，特 -别是，在可预见的将来，不可能迁移到GPL的版本3。 +这种所有权结构也暗示着，任何改变内核许可的尝试都注定会失败。很少有实际情况 +可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，尤其是在 +可预见的将来，许可证不大可能迁移到GPL的版本3。 -所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或匿名）贡献 -者的代码。所有贡献者都需要在他们的代码上“sign off”，声明代码可以在GPL下与内 -核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为内核造成版权 -相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码）不能被接受。 +所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或化名）贡献 +者的代码。所有贡献者都需要在他们的代码上“sign off（签发）”，声明代码可以 +在GPL下与内核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为 +内核造成版权相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码） +不能被接受。 -有关版权相关问题的问题在Linux开发邮件列表中很常见。这样的问题通常会得到不少 -答案，但要记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于 -Linux源代码的法律问题，那么与了解该领域的律师交流是无法替代的。依靠从技术 -邮件列表中获得的答案是一件冒险的事情。 +有关版权问题的提问在Linux开发邮件列表中很常见。这样的问题通常会得到不少答案， +但请记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于Linux源代码 +的法律问题，没有什么可以代替咨询了解这一领域的律师。依赖从技术邮件列表中获得 +的答案是一件冒险的事情。 diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index ebe2e0254b3e..229629e305ca 100644 --- a/Documentation/translations/zh_CN/process/2.Process.rst +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -1,17 +1,24 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/2.Process.rst <development_process>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process: -开发流程如何工作 +开发流程如何进行 ================ -90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较 -少。由于拥有数以百万计的用户群，并且在一年的时间里有大约2000名开发人员参与 -进来，内核因此必须发展许多流程来保持开发的顺利进行。要成为流程的有效组成 -部分，需要对流程的工作方式有一个扎实的理解。 +90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较少。 +由于拥有数以百万计的用户群，且每年有大约2000名开发人员参与进来，内核因此必须 +发展出许多既定流程来保证开发的顺利进行。要参与到流程中来，需要对此流程的进行 +方式有一个扎实的理解。 总览 ---- @@ -20,112 +27,113 @@ 内核版本。最近的发布历史记录如下： ====== ================= - 4.11 四月 30, 2017 - 4.12 七月 2, 2017 - 4.13 九月 3, 2017 - 4.14 十一月 12, 2017 - 4.15 一月 28, 2018 - 4.16 四月 1, 2018 + 5.0 2019年3月3日 + 5.1 2019年5月5日 + 5.2 2019年7月7日 + 5.3 2019年9月15日 + 5.4 2019年11月24日 + 5.5 2020年1月6日 ====== ================= -每4.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的4.x -版本包含大约13000个变更集，变更了几十万行代码。因此，4.x是Linux内核开发的前 +每个5.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的5.x +版本包含大约13000个变更集，变更了几十万行代码。因此，5.x是Linux内核开发的前 沿；内核使用滚动开发模型，不断集成重大变化。 -对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开始，“合并 -窗口”被打开。当时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内 +对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开头，“合并 +窗口”被打开。这时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内 核中。在这段时间内，新开发周期的大部分变更（以及所有主要变更）将以接近每天 1000次变更（“补丁”或“变更集”）的速度合并。 -（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是 -提前收集、测试和分级的。稍后将详细描述该过程的工作方式）。 +（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是经 +提前收集、测试和分级的。稍后将详细描述该过程的工作方式。） 合并窗口持续大约两周。在这段时间结束时，LinusTorvalds将声明窗口已关闭，并 -释放第一个“rc”内核。例如，对于目标为4.14的内核，在合并窗口结束时发生的释放 -将被称为4.14-rc1。RC1版本是一个信号，表示合并新特性的时间已经过去，稳定下一 -个内核的时间已经开始。 +释放第一个“rc”内核。例如，对于目标为5.6的内核，在合并窗口结束时发生的释放 +将被称为5.6-rc1。-rc1 版本是一个信号，表示合并新特性的时间已经过去，稳定下一 +个内核的时间已经到来。 在接下来的6到10周内，只有修复问题的补丁才应该提交给主线。有时会允许更大的 -更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往会受到不 +更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往受不到 友好的接待。一般来说，如果您错过了给定特性的合并窗口，最好的做法是等待下一 -个开发周期。（对于以前不支持的硬件，偶尔会对驱动程序进行例外；如果它们不 -改变已有代码，则不会导致回归，并且应该可以随时安全地添加）。 +个开发周期。（偶尔会对未支持硬件的驱动程序进行例外；如果它们不改变已有代码， +则不会导致回归，应该可以随时被安全地加入）。 随着修复程序进入主线，补丁速度将随着时间的推移而变慢。Linus大约每周发布一次 -新的-rc内核；一个正常的系列将在-rc6和-rc9之间，内核被认为足够稳定并最终发布。 +新的-rc内核；在内核被认为足够稳定并最终发布前，一般会达到-rc6到-rc9之间。 然后，整个过程又重新开始了。 -例如，这里是4.16的开发周期进行情况（2018年的所有日期）: +例如，这里是5.4的开发周期进行情况（2019年）: ============== ============================== - 一月 28 4.15 稳定版发布 - 二月 11 4.16-rc1, 合并窗口关闭 - 二月 18 4.16-rc2 - 二月 25 4.16-rc3 - 三月 4 4.16-rc4 - 三月 11 4.16-rc5 - 三月 18 4.16-rc6 - 三月 25 4.16-rc7 - 四月 1 4.16 稳定版发布 + 九月 15 5.3 稳定版发布 + 九月 30 5.4-rc1 合并窗口关闭 + 十月 6 5.4-rc2 + 十月 13 5.4-rc3 + 十月 20 5.4-rc4 + 十月 27 5.4-rc5 + 十一月 3 5.4-rc6 + 十一月 10 5.4-rc7 + 十一月 17 5.4-rc8 + 十一月 24 5.4 稳定版发布 ============== ============================== -开发人员如何决定何时结束开发周期并创建稳定的版本？使用的最重要的指标是以前 -版本的回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被 -认为是特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。 +开发人员如何决定何时结束开发周期并创建稳定版本？最重要的指标是以前版本的 +回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被认为是 +特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。 开发人员的目标是在稳定发布之前修复所有已知的回归。在现实世界中，这种完美是 -很难实现的；在这种规模的项目中，变量太多了。有一点，延迟最终版本只会使问题 -变得更糟；等待下一个合并窗口的一堆更改将变大，从而在下次创建更多的回归错误。 -因此，大多数4.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。 +很难实现的；在这种规模的项目中，变数太多了。需要说明的是，延迟最终版本只会 +使问题变得更糟；等待下一个合并窗口的更改将变多，导致下次出现更多的回归错误。 +因此，大多数5.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。 -一旦一个稳定的版本发布，它正在进行的维护工作就被移交给“稳定团队”，目前由 -Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发布稳定版本的更 -新。要加入更新版本，补丁程序必须（1）修复一个重要的bug，（2）已经合并到 -下一个开发主线中。内核通常会在超过其初始版本的一个以上的开发周期内接收稳定 -的更新。例如，4.13内核的历史如下 +一旦一个稳定的版本发布，它的持续维护工作就被移交给“稳定团队”，目前由 +Greg Kroah-Hartman领导。稳定团队将使用5.x.y编号方案不定期地发布稳定版本的 +更新。要合入更新版本，补丁必须（1）修复一个重要的缺陷，且（2）已经合并到 +下一个开发版本主线中。内核通常会在其初始版本后的一个以上的开发周期内收到 +稳定版更新。例如，5.2内核的历史如下（2019年）： ============== =============================== - 九月 3 4.13 稳定版发布 - 九月 13 4.13.1 - 九月 20 4.13.2 - 九月 27 4.13.3 - 十月 5 4.13.4 - 十月 12 4.13.5 + 七月 7 5.2 稳定版发布 + 七月 13 5.2.1 + 七月 21 5.2.2 + 七月 26 5.2.3 + 七月 28 5.2.4 + 七月 31 5.2.5 ... ... - 十一月 24 4.13.16 + 十月 11 5.2.21 ============== =============================== -4.13.16是4.13版本的最终稳定更新。 +5.2.21是5.2版本的最终稳定更新。 有些内核被指定为“长期”内核；它们将得到更长时间的支持。在本文中，当前的长期 内核及其维护者是： - ====== ====================== ============================== - 3.16 Ben Hutchings (长期稳定内核) - 4.1 Sasha Levin - 4.4 Greg Kroah-Hartman (长期稳定内核) - 4.9 Greg Kroah-Hartman - 4.14 Greg Kroah-Hartman - ====== ====================== ============================== + ====== ================================ ================ + 3.16 Ben Hutchings （长期稳定内核） + 4.4 Greg Kroah-Hartman & Sasha Levin （长期稳定内核） + 4.9 Greg Kroah-Hartman & Sasha Levin + 4.14 Greg Kroah-Hartman & Sasha Levin + 4.19 Greg Kroah-Hartman & Sasha Levin + 5.4 Greg Kroah-Hartman & Sasha Levin + ====== ================================ ================ -为长期支持选择内核纯粹是维护人员有必要和时间来维护该版本的问题。目前还没有 -为即将发布的任何特定版本提供长期支持的已知计划。 +长期支持内核的选择纯粹是维护人员是否有需求和时间来维护该版本的问题。 +目前还没有为即将发布的任何特定版本提供长期支持的已知计划。 补丁的生命周期 -------------- 补丁不会直接从开发人员的键盘进入主线内核。相反，有一个稍微复杂（如果有些非 正式）的过程，旨在确保对每个补丁进行质量审查，并确保每个补丁实现了一个在主线 -中需要的更改。对于小的修复，这个过程可能会很快发生，或者，在大的和有争议的 -变更的情况下，会持续数年。许多开发人员的挫折来自于对这个过程缺乏理解或者 -试图绕过它。 +中需要的更改。对于小的修复，这个过程可能会很快完成，，而对于较大或有争议的 +变更，可能会持续数年。许多开发人员的沮丧来自于对这个过程缺乏理解或者试图绕过它。 -为了减少这种挫折感，本文将描述补丁如何进入内核。下面是一个介绍，它以某种 -理想化的方式描述了这个过程。更详细的过程将在后面的章节中介绍。 +为了减少这种挫败，本文将描述补丁如何进入内核。下面的介绍以一种较为理想化的 +方式描述了这个过程。更详细的过程将在后面的章节中介绍。 -补丁程序经历的阶段通常是： +补丁通常要经历以下阶段： -- 设计。这就是补丁的真正需求——以及满足这些需求的方式——的所在。设计工作通常 +- 设计。这就是补丁的真正需求——以及满足这些需求的方式——所在。设计工作通常 是在不涉及社区的情况下完成的，但是如果可能的话，最好是在公开的情况下完成 这项工作；这样可以节省很多稍后再重新设计的时间。 @@ -134,53 +142,51 @@ Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发 - 更广泛的评审。当补丁接近准备好纳入主线时，它应该被相关的子系统维护人员 接受——尽管这种接受并不能保证补丁会一直延伸到主线。补丁将出现在维护人员的 - 子系统树中，并进入 -next 树（如下所述）。当流程工作时，此步骤将导致对补丁 - 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作集成而导致的任何 + 子系统树中，并进入 -next 树（如下所述）。当流程进行时，此步骤将会对补丁 + 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作合并而导致的任何 问题。 -- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最高优先级。 - 如果您的补丁程序得到了关于所需更改的反馈，那么您应该进行这些更改，或者为 - 不应该进行这些更改的原因辩护。如果您的补丁没有评审意见，但没有被其相应的 - 子系统或驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核，使 - 其干净地应用，并不断地将其发送以供审查和合并。 +- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最优先工作。 + 如果您的补丁得到了需要更改的反馈，那么您应该进行这些更改，或者解释为何 + 不应该进行这些更改。如果您的补丁没有评审意见，也没有被其相应的子系统或 + 驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核使其可被正常 + 应用，并不断地发送它以供审查和合并。 - 合并到主线。最终，一个成功的补丁将被合并到由LinusTorvalds管理的主线存储库 - 中。此时可能会出现更多的评论和/或问题；开发人员应对这些问题并解决出现的 - 任何问题很重要。 + 中。此时可能会出现更多的评论和/或问题；对开发人员来说应对这些问题并解决 + 出现的任何问题仍很重要。 -- 稳定版发布。可能受补丁影响的用户数量现在很大，因此可能再次出现新的问题。 +- 稳定版发布。大量用户可能受此补丁影响，因此可能再次出现新的问题。 - 长期维护。虽然开发人员在合并代码后可能会忘记代码，但这种行为往往会给开发 - 社区留下不良印象。合并代码消除了一些维护负担，因为其他代码将修复由API - 更改引起的问题。但是，如果代码要长期保持有用，原始开发人员应该继续为 - 代码负责。 + 社区留下不良印象。合并代码消除了一些维护负担，因为其他人将修复由API更改 + 引起的问题。但是，如果代码要长期保持可用，原始开发人员应该继续为代码负责。 -内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个 -“合并到主线”步骤。这种方法总是会让所有相关人员感到沮丧。 +内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个“合并到 +主线”步骤。这种方法总是会让所有相关人员感到沮丧。 补丁如何进入内核 ---------------- 只有一个人可以将补丁合并到主线内核存储库中：LinusTorvalds。但是，在进入 2.6.38内核的9500多个补丁中，只有112个（大约1.3%）是由Linus自己直接选择的。 -内核项目已经发展到一个规模，没有一个开发人员可以在没有支持的情况下检查和 -选择每个补丁。内核开发人员处理这种增长的方式是通过使用围绕信任链构建的 -助理系统。 +内核项目已经发展到一个没有一个开发人员可以在没有支持的情况下检查和选择每个 +补丁的规模。内核开发人员处理这种增长的方式是使用围绕信任链构建的助理系统。 -内核代码库在逻辑上被分解为一组子系统：网络、特定的体系结构支持、内存管理、 -视频设备等。大多数子系统都有一个指定的维护人员，开发人员对该子系统中的代码 -负有全部责任。这些子系统维护者（松散地）是他们所管理的内核部分的守护者； -他们（通常）会接受一个补丁以包含到主线内核中。 +内核代码库在逻辑上被分解为一组子系统：网络、特定体系结构支持、内存管理、视 +频设备等。大多数子系统都有一个指定的维护人员，其总体负责该子系统中的代码。 +这些子系统维护者（松散地）是他们所管理的内核部分的“守门员”；他们（通常） +会接受一个补丁以包含到主线内核中。 -子系统维护人员每个人都使用git源代码管理工具管理自己版本的内核源代码树。Git -等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 +子系统维护人员每个人都管理着自己版本的内核源代码树，通常（并非总是）使用Git。 +Git等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 信息和其他元数据。在任何给定的时间，维护人员都可以确定他或她的存储库中的哪 些补丁在主线中找不到。 -当合并窗口打开时，顶级维护人员将要求Linus从其存储库中“拉出”他们为合并选择 +当合并窗口打开时，顶级维护人员将要求Linus从存储库中“拉出”他们为合并选择 的补丁。如果Linus同意，补丁流将流向他的存储库，成为主线内核的一部分。 -Linus对拉操作中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 -关注。但是，作为一般规则，Linus相信子系统维护人员不会向上游发送坏补丁。 +Linus对拉取中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 +关注。但是一般来说，Linus相信子系统维护人员不会向上游发送坏补丁。 子系统维护人员反过来也可以从其他维护人员那里获取补丁。例如，网络树是由首先 在专用于网络设备驱动程序、无线网络等的树中积累的补丁构建的。此存储链可以 @@ -195,26 +201,26 @@ Next 树 子系统树链引导补丁流到内核，但它也提出了一个有趣的问题：如果有人想查看为 下一个合并窗口准备的所有补丁怎么办？开发人员将感兴趣的是，还有什么其他的 -更改有待解决，以查看是否存在需要担心的冲突；例如，更改核心内核函数原型的 +更改有待解决，以了解是否存在需要担心的冲突；例如，更改核心内核函数原型的 修补程序将与使用该函数旧形式的任何其他修补程序冲突。审查人员和测试人员希望 -在所有这些变更到达主线内核之前，能够访问它们的集成形式中的变更。您可以从所有 -有趣的子系统树中提取更改，但这将是一项大型且容易出错的工作。 +在所有这些变更到达主线内核之前，能够访问它们的集成形式的变更。您可以从所有 +相关的子系统树中提取更改，但这将是一项复杂且容易出错的工作。 -答案以-next树的形式出现，在这里子系统树被收集以供测试和审查。Andrew Morton -维护的这些旧树被称为“-mm”（用于内存管理，这就是它的启动名字）。-mm 树集成了 -一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。 +解决方案以-next树的形式出现，在这里子系统树被收集以供测试和审查。这些树中 +由Andrew Morton维护的较老的一个，被称为“-mm”（用于内存管理，创建时为此）。 +-mm 树集成了一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。 除此之外，-mm 还包含大量由Andrew直接选择的补丁。这些补丁可能已经发布在邮件 -列表上，或者它们可能应用于内核中没有指定子系统树的部分。结果，-mm 作为一种 -最后手段的子系统树运行；如果没有其他明显的路径可以让补丁进入主线，那么它很 -可能以-mm 结束。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接 +列表上，或者它们可能应用于内核中未指定子系统树的部分。同时，-mm 作为最后 +手段的子系统树；如果没有其他明显的路径可以让补丁进入主线，那么它很可能最 +终选择-mm 树。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接 发送到Linus。在典型的开发周期中，大约5-10%的补丁通过-mm 进入主线。 -当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到，地址： +当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到： https://www.ozlabs.org/~akpm/mmotm/ -然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。 +然而，使用MMOTM树可能会十分令人头疼；它甚至可能无法编译。 下一个周期补丁合并的主要树是linux-next，由Stephen Rothwell 维护。根据设计 linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和 @@ -228,49 +234,48 @@ Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个 Staging 树 ---------- -内核源代码树包含drivers/staging/directory，其中有许多驱动程序或文件系统的 -子目录正在被添加到内核树中。它们然需要更多的工作的时候可以保留在 -driver/staging目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合 -Linux内核编码或质量标准的驱动程序的方法，但人们可能希望使用它们并跟踪开发。 +内核源代码树包含drivers/staging/目录，其中有许多驱动程序或文件系统的子目录 +正在被添加到内核树中。它们在仍然需要更多的修正的时候可以保留在driver/staging/ +目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合Linux内核编码或 +质量标准的驱动程序的方法，人们可能希望使用它们并跟踪开发。 -Greg Kroah Hartman 目前负责维护staging 树。仍需要工作的驱动程序将发送给他， +Greg Kroah Hartman 目前负责维护staging 树。仍需要修正的驱动程序将发送给他， 每个驱动程序在drivers/staging/中都有自己的子目录。除了驱动程序源文件之外， -目录中还应该有一个TODO文件。todo文件列出了驱动程序需要接受的挂起的工作， +目录中还应该有一个TODO文件。TODO文件列出了驱动程序需要接受的暂停的工作， 以及驱动程序的任何补丁都应该抄送的人员列表。当前的规则要求，staging的驱动 程序必须至少正确编译。 -Staging 是一种相对容易的方法，可以让新的驱动程序进入主线，幸运的是，他们会 -引起其他开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾； -staging中没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用 -staging驱动程序。因此，在成为一名合适的主线驱动的路上，staging 充其量只是 -一个停留。 +Staging 是一种让新的驱动程序进入主线的相对容易的方法，它们会幸运地引起其他 +开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾；staging中 +没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用staging驱动 +程序。因此，在成为一个合适的主线驱动的路上，staging 仅是一个中转站。 工具 ---- 从上面的文本可以看出，内核开发过程在很大程度上依赖于在不同方向上聚集补丁的 能力。如果没有适当强大的工具，整个系统将无法在任何地方正常工作。关于如何使用 -这些工具的教程远远超出了本文档的范围，但是还是有一些指南的空间。 +这些工具的教程远远超出了本文档的范围，但还是用一点篇幅介绍一些关键点。 到目前为止，内核社区使用的主要源代码管理系统是git。Git是在自由软件社区中开发 的许多分布式版本控制系统之一。它非常适合内核开发，因为它在处理大型存储库和 -大量补丁时性能非常好。它还有一个难以学习和使用的名声，尽管随着时间的推移它 -变得更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不 -将它用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。 +大量补丁时性能非常好。它也以难以学习和使用而著称，尽管随着时间的推移它变得 +更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不将它 +用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。 -现在几乎所有的Linux发行版都打包了Git。主页位于： +现在几乎所有的Linux发行版都打包了Git。Git主页位于： https://git-scm.com/ -那个页面有指向文档和教程的指针。 +此页面包含了文档和教程的链接。 -在不使用git的内核开发人员中，最流行的选择几乎肯定是mercurial： +在不使用git的内核开发人员中，最流行的选择几乎肯定是Mercurial： http://www.seleric.com/mercurial/ Mercurial与Git共享许多特性，但它提供了一个界面，许多人觉得它更易于使用。 -另一个值得了解的工具是quilt: +另一个值得了解的工具是Quilt: https://savannah.nongnu.org/projects/quilt @@ -282,79 +287,79 @@ Quilt 是一个补丁管理系统，而不是源代码管理系统。它不会 邮件列表 -------- -大量的Linux内核开发工作是通过邮件列表完成的。如果不在某个地方加入至少一个列表， -就很难成为社区中一个功能完备的成员。但是，Linux邮件列表对开发人员来说也是一个 -潜在的危险，他们可能会被一堆电子邮件淹没，违反Linux列表上使用的约定，或者 -两者兼而有之。 +大量的Linux内核开发工作是通过邮件列表完成的。如果不加入至少一个某个列表， +就很难成为社区中的一个“全功能”成员。但是，Linux邮件列表对开发人员来说也是 +一个潜在的危险，他们可能会被一堆电子邮件淹没、违反Linux列表上使用的约定， +或者两者兼而有之。 大多数内核邮件列表都在vger.kernel.org上运行；主列表位于： http://vger.kernel.org/vger-lists.html -不过，也有一些列表托管在别处；其中一些列表位于lists.redhat.com。 +不过，也有一些列表托管在别处；其中一些列表位于 +redhat.com/mailman/listinfo。 -当然，内核开发的核心邮件列表是linux-kernel。这个名单是一个令人生畏的地方； -每天的信息量可以达到500条，噪音很高，谈话技术性很强，参与者并不总是表现出 +当然，内核开发的核心邮件列表是linux-kernel。这个列表是一个令人生畏的地方： +每天的信息量可以达到500条，噪音很高，谈话技术性很强，且参与者并不总是表现出 高度的礼貌。但是，没有其他地方可以让内核开发社区作为一个整体聚集在一起； -避免使用此列表的开发人员将错过重要信息。 +不使用此列表的开发人员将错过重要信息。 -有一些提示可以帮助在linux-kernel生存： +以下一些提示可以帮助在linux-kernel生存： -- 将邮件转移到单独的文件夹，而不是主邮箱。我们必须能够持续地忽略洪流。 +- 将邮件转移到单独的文件夹，而不是主邮箱文件夹。我们必须能够持续地忽略洪流。 -- 不要试图跟踪每一次谈话-其他人都不会。重要的是要对感兴趣的主题（尽管请 - 注意，长时间的对话可以在不更改电子邮件主题行的情况下偏离原始主题）和参与 - 的人进行筛选。 +- 不要试图跟上每一次谈话——没人会这样。重要的是要筛选感兴趣的主题（但请注意 + 长时间的对话可能会偏离原来的主题，尽管未改变电子邮件的主题）和参与的人。 -- 不要挑事。如果有人试图激起愤怒的反应，忽略他们。 +- 不要回复挑事的人。如果有人试图激起愤怒，请忽略他们。 -- 当响应Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留 - cc:header。如果没有强有力的理由（如明确的请求），则不应删除收件人。一定要 - 确保你要回复的人在cc:list中。这个惯例也使你不必在回复邮件时明确要求被抄送。 +- 当回复Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留 + Cc: 抄送头。如果没有确实的理由（如明确的请求），则不应删除收件人。一定要 + 确保你要回复的人在抄送列表中。这个惯例也使你不必在回复邮件时明确要求被抄送。 -- 在提出问题之前，搜索列表档案（和整个网络）。有些开发人员可能会对那些显然 +- 在提出问题之前，搜索列表存档（和整个网络）。有些开发人员可能会对那些显然 没有完成家庭作业的人感到不耐烦。 -- 避免贴顶帖（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难 +- 避免顶部回复（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难 理解，印象也很差。 -- 询问正确的邮件列表。linux-kernel 可能是通用的讨论点，但它不是从所有子系统 - 中寻找开发人员的最佳场所。 +- 在正确的邮件列表发问。linux-kernel 可能是通用的讨论场所，但它不是寻找所有 + 子系统开发人员的最佳场所。 -最后一点——找到正确的邮件列表——是开发人员出错的常见地方。在Linux内核上提出与 -网络相关的问题的人几乎肯定会收到一个礼貌的建议，转而在netdev列表上提出， -因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、 -video4linux、ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码 -一起打包的MAINTAINERS文件。 +最后一点——找到正确的邮件列表——是开发人员常出错的地方。在linux-kernel上 +提出与网络相关的问题的人几乎肯定会收到一个礼貌的建议，转到netdev列表上提出， +因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、video4linux、 +ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码一起打包的 +MAINTAINERS文件。 开始内核开发 ------------ -关于如何开始内核开发过程的问题很常见——来自个人和公司。同样常见的是错误，这 -使得关系的开始比必须的更困难。 +关于如何开始内核开发过程的问题很常见——个人和公司皆然。同样常见的是失误，这 +使得关系的开始比本应的更困难。 公司通常希望聘请知名的开发人员来启动开发团队。实际上，这是一种有效的技术。 -但它也往往是昂贵的，而且没有增长经验丰富的内核开发人员储备。考虑到时间的 -投入，可以让内部开发人员加快Linux内核的开发速度。花这个时间可以让雇主拥有 -一批了解内核和公司的开发人员，他们也可以帮助培训其他人。从中期来看，这往往 -是更有利可图的方法。 +但它也往往是昂贵的，而且对增加有经验的内核开发人员的数量没有多大帮助。考 +虑到时间投入，可以让内部开发人员加快Linux内核的开发速度。利用这段时间可以 +让雇主拥有一批既了解内核又了解公司的开发人员，还可以帮助培训其他人。从中期 +来看，这通常是更有利可图的方法。 可以理解的是，单个开发人员往往对起步感到茫然。从一个大型项目开始可能会很 -吓人；人们往往想先用一些较小的东西来测试水域。这是一些开发人员开始创建修补 -拼写错误或轻微编码风格问题的补丁的地方。不幸的是，这样的补丁会产生一定程度 -的噪音，这会分散整个开发社区的注意力，因此，越来越多的人看不起它们。希望向 -社区介绍自己的新开发人员将无法通过这些方式获得他们想要的那种接待。 +吓人；人们往往想先用一些较小的东西来试试水。由此，一些开发人员开始创建修补 +拼写错误或轻微编码风格问题的补丁。不幸的是，这样的补丁会产生一定程度的噪音， +这会分散整个开发社区的注意力，因此，它们越来越被人不看重。希望向社区介绍 +自己的新开发人员将无法通过这些方式获得他们期待的反响。 -Andrew Morton 为有抱负的内核开发人员提供了这个建议 +Andrew Morton 为有抱负的内核开发人员提供了如下建议 :: - 所有内核初学者的No.1项目肯定是“确保内核在所有的机器上，你可以触摸 - 到的，始终运行良好" 通常这样做的方法是与其他人一起解决问题（这 - 可能需要坚持！）但这很好——这是内核开发的一部分 + 所有内核开发者的第一个项目肯定应该是“确保内核在您可以操作的所有 + 机器上始终完美运行”。通常的方法是和其他人一起解决问题（这可能需 + 要坚持！），但就是如此——这是内核开发的一部分。 (http://lwn.net/articles/283982/) -在没有明显问题需要解决的情况下，建议开发人员查看当前的回归和开放式错误列表. -解决需要修复的问题没有任何缺点；通过解决这些问题，开发人员将获得处理过程的 -经验，同时与开发社区的其他人建立尊重。 +在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷 +列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得 +经验，同时与开发社区的其他成员建立相互尊重。 diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst index b8676aec6005..de53dd12e911 100644 --- a/Documentation/translations/zh_CN/process/3.Early-stage.rst +++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_early_stage: @@ -9,45 +16,45 @@ ======== 当考虑一个Linux内核开发项目时，很可能会直接跳进去开始编码。然而，与任何重要 -的项目一样，成功的许多基础最好是在第一行代码编写之前就做好了。在早期计划和 -沟通中花费一些时间可以节省更多的时间。 +的项目一样，许多成功的基础最好是在第一行代码编写之前就打下。在早期计划和 +沟通中花费一些时间可以在之后节省更多的时间。 -详述问题 +搞清问题 -------- -与任何工程项目一样，成功的内核增强从要解决的问题的清晰描述开始。在某些情况 -下，这个步骤很容易：例如，当某个特定硬件需要驱动程序时。不过，在其他方面， -将实际问题与建议的解决方案混淆是很有诱惑力的，这可能会导致困难。 +与任何工程项目一样，成功的内核改善从清晰描述要解决的问题开始。在某些情况 +下，这个步骤很容易：例如当某个特定硬件需要驱动程序时。不过，在其他情况下， +很容易将实际问题与建议的解决方案混在一起，这可能会导致麻烦。 -举个例子：几年前，使用Linux音频的开发人员寻求一种方法来运行应用程序，而不因 -系统延迟过大而导致退出或其他工件。他们得到的解决方案是一个内核模块，旨在连 -接到Linux安全模块（LSM）框架中；这个模块可以配置为允许特定的应用程序访问 -实时调度程序。这个模块被实现并发送到Linux内核邮件列表，在那里它立即遇到问题。 +举个例子：几年前，Linux音频的开发人员寻求一种方法来运行应用程序，而不会因 +系统延迟过大而导致退出或其他问题。他们得到的解决方案是一个连接到Linux安全 +模块（LSM）框架中的内核模块；这个模块可以配置为允许特定的应用程序访问实时 +调度程序。这个模块被实现并发到linux-kernel邮件列表，在那里它立即遇到了麻烦。 对于音频开发人员来说，这个安全模块足以解决他们当前的问题。但是，对于更广泛的 内核社区来说，这被视为对LSM框架的滥用（LSM框架并不打算授予他们原本不具备的 进程特权），并对系统稳定性造成风险。他们首选的解决方案包括短期的通过rlimit 机制进行实时调度访问，以及长期的减少延迟的工作。 -然而，音频社区看不到他们实施的特定解决方案的过去；他们不愿意接受替代方案。 +然而，音频社区无法超越他们实施的特定解决方案来看问题；他们不愿意接受替代方案。 由此产生的分歧使这些开发人员对整个内核开发过程感到失望；其中一个开发人员返回 -到音频列表并发布了以下内容： +到audio列表并发布了以下内容： - 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。 - 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数人 - 的话。 + 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。 + 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数 + 人的话。 （http://lwn.net/articles/131776/） -实际情况不同；与特定模块相比，内核开发人员更关心系统稳定性、长期维护以及找到 -正确的问题解决方案。这个故事的寓意是把重点放在问题上——而不是具体的解决方案 -上——并在投入创建代码之前与开发社区讨论这个问题。 +实际情况却是不同的；与特定模块相比，内核开发人员更关心系统稳定性、长期维护 +以及找到问题的正确解决方案。这个故事的寓意是把重点放在问题上——而不是具体的 +解决方案上——并在开始编写代码之前与开发社区讨论这个问题。 因此，在考虑一个内核开发项目时，我们应该得到一组简短问题的答案： - - 究竟需要解决的问题是什么？ + - 需要解决的问题究竟是什么？ - - 受此问题影响的用户是谁？解决方案应该解决哪些用例？ + - 受此问题影响的用户有哪些？解决方案应该解决哪些使用案例？ - 内核现在为何没能解决这个问题？ @@ -62,100 +69,100 @@ - 很可能问题是由内核以您不理解的方式解决的。Linux内核很大，具有许多不明显 的特性和功能。并不是所有的内核功能都像人们所希望的那样有文档记录，而且很 - 容易遗漏一些东西。你的作者发出了一个完整的驱动程序，复制了一个新作者不 - 知道的现有驱动程序。重新设计现有轮子的代码不仅浪费，而且不会被接受到主线 + 容易遗漏一些东西。某作者发布了一个完整的驱动程序，重复了一个其不 + 知道的现有驱动程序。重新发明现有轮子的代码不仅浪费，而且不会被接受到主线 内核中。 - - 建议的解决方案中可能有一些元素不适用于主线合并。在编写代码之前，最好先 - 了解这样的问题。 + - 建议的解决方案中可能有一些要素不适合并入主线。在编写代码之前，最好先了解 + 这样的问题。 - 其他开发人员完全有可能考虑过这个问题；他们可能有更好的解决方案的想法，并且 可能愿意帮助创建这个解决方案。 在内核开发社区的多年经验给了我们一个明确的教训：闭门设计和开发的内核代码总是 有一些问题，这些问题只有在代码发布到社区中时才会被发现。有时这些问题很严重， -需要数月或数年的努力才能使代码达到内核社区的标准。一些例子包括： +需要数月或数年的努力才能使代码达到内核社区的标准。例如： - 设计并实现了单处理器系统的DeviceScape网络栈。只有使其适合于多处理器系统， - 才能将其合并到主线中。在代码中改装锁等等是一项困难的任务；因此，这段代码 + 才能将其合并到主线中。在代码中修改锁等等是一项困难的任务；因此，这段代码 （现在称为mac80211）的合并被推迟了一年多。 - Reiser4文件系统包含许多功能，核心内核开发人员认为这些功能应该在虚拟文件 系统层中实现。它还包括一些特性，这些特性在不将系统暴露于用户引起的死锁的 - 情况下是不容易实现的。这些问题的最新发现——以及对其中一些问题的拒绝——已经 - 导致Reiser4远离了主线内核。 + 情况下是不容易实现的。这些问题过迟发现——以及拒绝处理其中一些问题——已经 + 导致Reiser4置身主线内核之外。 - Apparmor安全模块以被认为不安全和不可靠的方式使用内部虚拟文件系统数据结构。 - 这种担心（包括其他）使Apparmor多年不在主线上。 + 这种担心（包括其他）使Apparmor多年来无法进入主线。 -在每一种情况下，通过与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。 +在这些情况下，与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。 -找谁交流 --------- +找谁交流？ +---------- 当开发人员决定公开他们的计划时，下一个问题是：我们从哪里开始？答案是找到正确 的邮件列表和正确的维护者。对于邮件列表，最好的方法是在维护者(MAINTAINERS)文件 -中查找要发布的相关位置。如果有一个合适的子系统列表，那么发布它通常比在Linux -内核上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发人员，并且 -环境可能具支持性。 +中查找要发布的相关位置。如果有一个合适的子系统列表，那么其上发布通常比在 +linux-kernel上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发 +人员，并且环境可能具支持性。 -找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不总 -是最新的，并且并非所有子系统都在那里表示。实际上，维护者文件中列出的人员可能 +找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不 +是最新的，并且并非所有子系统都在那里显示。实际上，维护者文件中列出的人员可能 不是当前实际担任该角色的人员。因此，当对联系谁有疑问时，一个有用的技巧是使用 -git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁， -如果有人的话，谁会在这些补丁上加上用线签名的。这些人将是帮助新开发项目的最佳 -人选。 +git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁、 +谁会在这些补丁上加上Signed-off-by行签名（如有）。这些人将是帮助新开发项目的 +最佳人选。 -找到合适的维护者的任务有时是非常具有挑战性的，以至于内核开发人员添加了一个 -脚本来简化过程： +找到合适的维护者有时是非常具有挑战性的，以至于内核开发人员添加了一个脚本来 +简化这个过程： :: .../scripts/get_maintainer.pl -当给定“-f”选项时，此脚本将返回给定文件或目录的当前维护者。如果在命令行上传递 -了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节 -get_maintainer.pl搜索维护者的难易程度；请小心使用更具攻击性的选项，因为最终 +当给定“-f”选项时，此脚本将返回指定文件或目录的当前维护者。如果在命令行上 +给出了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节 +get_maintainer.pl搜索维护者的严格程度；请小心使用更激进的选项，因为最终结果 可能会包括对您正在修改的代码没有真正兴趣的开发人员。 -如果所有其他方法都失败了，那么与Andrew Morton交谈可以成为一种有效的方法来跟踪 -特定代码段的维护人员。 +如果所有其他方法都失败了，那么与Andrew Morton交流是跟踪特定代码段维护人员 +的一种有效方法。 何时邮寄？ ---------- -如果可能的话，在早期阶段发布你的计划只会有帮助。描述正在解决的问题以及已经 +如果可能的话，在早期阶段发布你的计划只会更有帮助。描述正在解决的问题以及已经 制定的关于如何实施的任何计划。您可以提供的任何信息都可以帮助开发社区为项目 提供有用的输入。 -在这个阶段可能发生的一件令人沮丧的事情不是敌对的反应，而是很少或根本没有 -反应。可悲的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划和很少 -代码（甚至代码前景）支持他们的人；（3）没有人有义务审查或评论别人发表的 -想法。除此之外，高级设计常常隐藏一些问题，这些问题只有在有人真正尝试实现 -这些设计时才会被发现；因此，内核开发人员宁愿看到代码。 +在这个阶段可能发生的一件令人沮丧的事情不是得到反对意见，而是很少或根本没有 +反馈。令人伤心的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划但 +代码（甚至代码设想）很少的人去支持他们；（3）没有人有义务审查或评论别人发表 +的想法。除此之外，高层级的设计常常隐藏着一些问题，这些问题只有在有人真正尝试 +实现这些设计时才会被发现；因此，内核开发人员宁愿看到代码。 -如果发表评论的请求在评论的方式上没有什么效果，不要假设这意味着对项目没有 -兴趣。不幸的是，你也不能假设你的想法没有问题。在这种情况下，最好的做法是 -继续进行，把你的进展随时通知社区。 +如果发布请求评论（RFC）并没得到什么有用的评论，不要以为这意味着无人对此项目 +有兴趣，同时你也不能假设你的想法没有问题。在这种情况下，最好的做法是继续进 +行，把你的进展随时通知社区。 获得官方认可 ----------------------- -如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样，显然，在您将 -公司的计划或代码发布到公共邮件列表之前，必须获得适当授权的经理的许可。发布 -不确定是否兼容GPL的代码可能是有特别问题的；公司的管理层和法律人员越早能够就 -发布内核开发项目达成一致，对参与的每个人都越好。 +如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样；显然，在您将 +公司的计划或代码发布到公共邮件列表之前，必须获得有适当权利经理的许可。发布 +不确定是否兼容GPL的代码尤其会带来问题；公司的管理层和法律人员越早能够就发布 +内核开发项目达成一致，对参与的每个人都越好。 一些读者可能会认为他们的核心工作是为了支持还没有正式承认存在的产品。将雇主 的计划公布在公共邮件列表上可能不是一个可行的选择。在这种情况下，有必要考虑 保密是否真的是必要的；通常不需要把开发计划关在门内。 -也就是说，有些情况下，一家公司在开发过程的早期就不能合法地披露其计划。拥有 -经验丰富的内核开发人员的公司可以选择以开环的方式进行，前提是他们以后能够避免 +的确，有些情况下一家公司在开发过程的早期无法合法地披露其计划。拥有经验丰富 +的内核开发人员的公司可能选择以开环的方式进行开发，前提是他们以后能够避免 严重的集成问题。对于没有这种内部专业知识的公司，最好的选择往往是聘请外部 -开发商根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种 -情况； +开发者根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种 +情况；更多信息参见： - http://www.linuxfoundation.org/en/NDA_program + http://www.linuxfoundation.org/nda/ 这种审查通常足以避免以后出现严重问题，而无需公开披露项目。 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 66cd8ee07606..94f7f866f103 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -1,155 +1,160 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_coding: 使代码正确 ====================== -虽然对于一个坚实的、面向社区的设计过程有很多话要说，但是任何内核开发项目的 -证明都在生成的代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中 +虽然一个坚实的、面向社区的设计过程有很多值得说道的，但是任何内核开发项目工作 +的证明都反映在代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中 的代码。所以这段代码的质量决定了项目的最终成功。 -本节将检查编码过程。我们将从内核开发人员出错的几种方式开始。然后重点将转移 -到正确的事情和可以帮助这个任务的工具上。 +本节将检查编码过程。我们将从内核开发人员常犯的几种错误开始。然后重点将转移 +到正确的做法和相关有用的工具上。 陷阱 ---- -编码风格 +代码风格 ******** -内核长期以来都有一种标准的编码风格，如 +内核长期以来都有其标准的代码风格，如 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -中所述。在大部分时间里，该文件中描述的政策被认为至多是建议性的。因此，内核 -中存在大量不符合编码风格准则的代码。代码的存在会给内核开发人员带来两个独立 -的危害。 - -首先，要相信内核编码标准并不重要，也不强制执行。事实上，如果没有按照标准对代 -码进行编码，那么向内核添加新代码是非常困难的；许多开发人员甚至会在审查代码之 -前要求对代码进行重新格式化。一个与内核一样大的代码库需要一些统一的代码，以使 -开发人员能够快速理解其中的任何部分。所以已经没有空间来存放奇怪的格式化代码了。 - -偶尔，内核的编码风格会与雇主的强制风格发生冲突。在这种情况下，内核的风格必须 -在代码合并之前获胜。将代码放入内核意味着以多种方式放弃一定程度的控制权——包括 -控制代码的格式化方式。 - -另一个陷阱是假定已经在内核中的代码迫切需要编码样式的修复。开发人员可能会开始 -生成重新格式化补丁，作为熟悉过程的一种方式，或者作为将其名称写入内核变更日志 -的一种方式，或者两者兼而有之。但是纯编码风格的修复被开发社区视为噪音；它们往 -往受到冷遇。因此，最好避免使用这种类型的补丁。由于其他原因，在处理一段代码的 -同时修复它的样式是很自然的，但是编码样式的更改不应该仅为了更改而进行。 - -编码风格的文档也不应该被视为绝对的法律，这是永远不会被违反的。如果有一个很好 -的理由反对这种样式（例如，如果拆分为适合80列限制的行，那么它的可读性就会大大 -降低），那么就这样做。 - -请注意，您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，自动重新格式 -化部分代码，并查看完整的文件，以发现编码样式错误、拼写错误和可能的改进。它还 -可以方便地进行排序，包括对齐变量/宏、回流文本和其他类似任务。有关详细信息，请 -参阅文件 :ref:`Documentation/process/clang-format.rst <clangformat>` +中所述。在多数时候，该文档中描述的准则至多被认为是建议性的。因此，内核中存在 +大量不符合代码风格准则的代码。这种代码的存在会给内核开发人员带来两方面的危害。 + +首先，相信内核代码标准并不重要，也不强制执行。但事实上，如果没有按照标准 +编写代码，那么新代码将很难加入到内核中；许多开发人员甚至会在审查代码之前要求 +对代码进行重新格式化。一个像内核这么大的代码库需要一些统一格式的代码，以使 +开发人员能够快速理解其中的任何部分。所以再也经不起奇怪格式的代码的折腾了。 + +内核的代码风格偶尔会与雇主的强制风格发生冲突。在这种情况下，必须在代码合并 +之前遵从内核代码风格。将代码放入内核意味着以多种方式放弃一定程度的控制权—— +包括控制代码样式。 + +另一个危害是认为已经在内核中的代码迫切需要修复代码样式。开发者可能会开始编写 +重新格式化补丁，作为熟悉开发过程的一种方式，或者作为将其名字写入内核变更日志 +的一种方式，或者两者兼而有之。但是纯代码风格的修复被开发社区视为噪音，它们往 +往受到冷遇。因此，最好避免编写这种类型的补丁。在由于其他原因处理一段代码的 +同时顺带修复其样式是很自然的，但是不应该仅为了更改代码样式而更改之。 + +代码风格文档也不应该被视为绝对不可违反的规则。如果有一个足够的理由反对这种 +样式（例如为了80列限制拆分行会导致可读性大大降低），那么就这样做吧。 + +注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 +化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 +可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 +信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>` 抽象层 ****** 计算机科学教授教学生以灵活性和信息隐藏的名义广泛使用抽象层。当然，内核广泛 -地使用了抽象；任何涉及数百万行代码的项目都不能做到这一点并存活下来。但经验 -表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用于所需的级别， +地使用了抽象；任何涉及数百万行代码的项目都必须做到这一点以存续下来。但经验 +表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用在适当层级， 不要过度。 -在一个简单的级别上，考虑一个函数的参数，该参数总是由所有调用方作为零传递。 -我们可以保留这个论点: 以防有人最终需要使用它提供的额外灵活性。不过，到那时， -实现这个额外参数的代码很有可能以某种从未被注意到的微妙方式被破坏——因为它从 -未被使用过。或者，当需要额外的灵活性时，它不会以符合程序员早期期望的方式来 -这样做。内核开发人员通常会提交补丁来删除未使用的参数；一般来说，首先不应该 -添加这些参数。 +简单点，先考虑一个调用时始终只有一个参数且总为零的函数。我们可以保留这个参数， +以在需要使用它时提供的额外灵活性。不过，在那时实现了这个额外参数的代码很有 +可能以某种从未被注意到的微妙方式被破坏——因为它从未被使用过。或者当需要额外 +的灵活性时，它并未以符合程序员当初期望的方式来实现。内核开发人员通常会提交 +补丁来删除未使用的参数；一般来说，一开始就不应该添加这些参数。 -隐藏硬件访问的抽象层——通常允许大量的驱动程序在多个操作系统中使用——尤其不受 +隐藏硬件访问的抽象层——通常为了允许大量的驱动程序兼容多个操作系统——尤其不受 欢迎。这样的层使代码变得模糊，可能会造成性能损失；它们不属于Linux内核。 -另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么现在是时候 -问一下，事实上，将这些代码中的一些提取到单独的库中，或者在更高的层次上实现 -这些功能是否有意义。在整个内核中复制相同的代码没有价值。 +另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么是时候 +了解一下：是否需要将这些代码中的部分提取到单独的库中，或者在更高的层次上 +实现这些功能。在整个内核中复制相同的代码没有价值。 #ifdef 和预处理 *************** -C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种有效地将大量灵 -活性编码到源文件中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来 -说更难读取，对编译器来说更难检查正确性。大量的预处理器几乎总是代码需要一些 +C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种将大量灵活性加入 +源代码中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来说更难阅读， +对编译器来说更难检查正确性。使用了大量预处理器几乎总是代码需要一些 清理工作的标志。 -使用ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望 -看到代码被大量地撒上ifdef块。作为一般规则，ifdef的使用应尽可能限制在头文件 -中。有条件编译的代码可以限制函数，如果代码不存在，这些函数就会变成空的。然后 -编译器将悄悄地优化对空函数的调用。结果是代码更加清晰，更容易理解。 +使用#ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望 +看到代码被铺满#ifdef块。一般规定，ifdef的使用应尽可能限制在头文件中。条件 +编译代码可以限制函数，如果代码不存在，这些函数就直接变成空的。然后编译器将 +悄悄地优化对空函数的调用。使得代码更加清晰，更容易理解。 -C预处理器宏存在许多危险，包括可能对具有副作用且没有类型安全性的表达式进行多 -重评估。如果您试图定义宏，请考虑创建一个内联函数。结果相同的代码，但是内联 -函数更容易读取，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。 +C预处理器宏存在许多危险性，包括可能对具有副作用且没有类型安全的表达式进行多 +重评估。如果您试图定义宏，请考虑创建一个内联函数替代。结果相同的代码，内联 +函数更容易阅读，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。 内联函数 ******** 不过，内联函数本身也存在风险。程序员可以倾心于避免函数调用和用内联函数填充源 文件所固有的效率。然而，这些功能实际上会降低性能。因为它们的代码在每个调用站 -点都被复制，所以它们最终会增加编译内核的大小。反过来，这会对处理器的内存缓存 -造成压力，从而大大降低执行速度。通常，内联函数应该非常小，而且相对较少。毕竟， -函数调用的成本并不高；大量内联函数的创建是过早优化的典型例子。 +点都被复制一遍，所以最终会增加编译内核的大小。此外，这也对处理器的内存缓存 +造成压力，从而大大降低执行速度。通常内联函数应该非常小，而且相对较少。毕竟 +函数调用的成本并不高；大量创建内联函数是过早优化的典型例子。 -一般来说，内核程序员会忽略缓存效果，这会带来危险。在开始的数据结构课程中，经 -典的时间/空间权衡通常不适用于当代硬件。空间就是时间，因为一个大的程序比一个 +一般来说，内核程序员会自冒风险忽略缓存效果。在数据结构课程开头中的经典 +时间/空间权衡通常不适用于当代硬件。空间 *就是* 时间，因为一个大的程序比一个 更紧凑的程序运行得慢。 -最近的编译器在决定一个给定函数是否应该被内联方面扮演着越来越积极的角色。 -因此，“inline”关键字的自由放置可能不仅仅是过度的，它也可能是无关的。 +较新的编译器越来越激进地决定一个给定函数是否应该内联。因此，随意放置使用 +“inline”关键字可能不仅仅是过度的，也可能是无用的。 锁 ** -2006年5月，“deviceescape”网络堆栈在GPL下发布，并被纳入主线内核。这是一个受 -欢迎的消息；对Linux中无线网络的支持充其量被认为是不合格的，而deviceescape -堆栈提供了修复这种情况的承诺。然而，直到2007年6月（2.6.22），这段代码才真 +2006年5月，“deviceescape”网络堆栈在前呼后拥下以GPL发布，并被纳入主线内核。 +这是一个受欢迎的消息；Linux中对无线网络的支持充其量被认为是不合格的，而 +Deviceescape堆栈承诺修复这种情况。然而直到2007年6月（2.6.22），这段代码才真 正进入主线。发生了什么？ -这段代码显示了许多闭门造车的迹象。但一个特别大的问题是，它并不是设计用于多 -处理器系统。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁 -方案的改造。 +这段代码出现了许多闭门造车的迹象。但一个大麻烦是，它并不是为多处理器系统而 +设计。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁方案的 +改造。 曾经，Linux内核代码可以在不考虑多处理器系统所带来的并发性问题的情况下进行 -开发。然而，现在，这个文件是写在双核笔记本电脑上的。即使在单处理器系统上， +开发。然而现在，这个文档就是在双核笔记本电脑上写的。即使在单处理器系统上， 为提高响应能力所做的工作也会提高内核内的并发性水平。编写内核代码而不考虑锁 -的日子已经过去很长了。 +的日子早已远去。 可以由多个线程并发访问的任何资源（数据结构、硬件寄存器等）必须由锁保护。新 -的代码应该记住这一要求；事后改装锁是一项相当困难的任务。内核开发人员应该花 -时间充分了解可用的锁原语，以便为作业选择正确的工具。显示对并发性缺乏关注的 -代码进入主线将很困难。 +的代码应该谨记这一要求；事后修改锁是一项相当困难的任务。内核开发人员应该花 +时间充分了解可用的锁原语，以便为工作选择正确的工具。对并发性缺乏关注的代码 +很难进入主线。 回归 **** -最后一个值得一提的危险是：它可能会引起改变（这可能会带来很大的改进），从而 -导致现有用户的某些东西中断。这种变化被称为“回归”，回归已经成为主线内核最不 -受欢迎的。除少数例外情况外，如果回归不能及时修正，会导致回归的变化将被取消。 -最好首先避免回归。 +最后一个值得一提的危险是回归：它可能会引起导致现有用户的某些东西中断的改变 +（这也可能会带来很大的改进）。这种变化被称为“回归”，回归已经成为主线内核 +最不受欢迎的问题。除了少数例外情况，如果回归不能及时修正，会导致回归的修改 +将被取消。最好首先避免回归发生。 -人们常常争论，如果回归让更多人可以工作，远超过产生问题，那么回归是合理的。 -如果它破坏的一个系统却为十个系统带来新的功能，为什么不进行更改呢？2007年7月， +人们常常争论，如果回归带来的功能远超过产生的问题，那么回归是否为可接受的。 +如果它破坏了一个系统却为十个系统带来新的功能，为何不改改态度呢？2007年7月， Linus对这个问题给出了最佳答案: :: - 所以我们不会通过引入新问题来修复错误。那样的谎言很疯狂，没有人知道 - 你是否真的有进展。是前进两步，后退一步，还是向前一步，向后两步？ + + 所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道 + 是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？ （http://lwn.net/articles/243460/） -一种特别不受欢迎的回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， +特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， 就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们 -不能以不兼容的方式进行更改，所以必须第一次正确地进行更改。因此，用户空间界面 -总是需要大量的思考、清晰的文档和广泛的审查。 +不能以不兼容的方式进行更改，所以必须一次就对。因此，用户空间接口总是需要大量 +的思考、清晰的文档和广泛的审查。 代码检查工具 @@ -157,13 +162,13 @@ Linus对这个问题给出了最佳答案: 至少目前，编写无错误代码仍然是我们中很少人能达到的理想状态。不过，我们希望做 的是，在代码进入主线内核之前，尽可能多地捕获并修复这些错误。为此，内核开发人 -员已经组装了一系列令人印象深刻的工具，可以自动捕获各种各样的模糊问题。计算机 +员已经提供了一系列令人印象深刻的工具，可以自动捕获各种各样的隐藏问题。计算机 发现的任何问题都是一个以后不会困扰用户的问题，因此，只要有可能，就应该使用 自动化工具。 -第一步只是注意编译器产生的警告。当代版本的GCC可以检测（并警告）大量潜在错误。 -通常，这些警告都指向真正的问题。提交以供审阅的代码通常不会产生任何编译器警告。 -在消除警告时，注意了解真正的原因，并尽量避免“修复”，使警告消失而不解决其原因。 +第一步是注意编译器产生的警告。当前版本的GCC可以检测（并警告）大量潜在错误。 +通常，这些警告都指向真正的问题。提交以供审阅的代码一般不会产生任何编译器警告。 +在消除警告时，注意了解真正的原因，并尽量避免仅“修复”使警告消失而不解决其原因。 请注意，并非所有编译器警告都默认启用。使用“make KCFLAGS=-W”构建内核以 获得完整集合。 @@ -172,45 +177,43 @@ Linus对这个问题给出了最佳答案: 子菜单中。对于任何用于开发或测试目的的内核，都应该启用其中几个选项。特别是， 您应该打开： - - 启用 ENABLE_MUST_CHECK and FRAME_WARN 以获得一组额外的警告，以解决使用不 - 推荐使用的接口或忽略函数的重要返回值等问题。这些警告生成的输出可能是冗长 - 的，但您不必担心来自内核其他部分的警告。 + - FRAME_WARN 获取大于给定数量的堆栈帧的警告。 + 这些警告生成的输出可能比较冗长，但您不必担心来自内核其他部分的警告。 - - DEBUG_OBJECTS 将添加代码，以跟踪内核创建的各种对象的生存期，并在出现问题时 - 发出警告。如果要添加创建（和导出）自己的复杂对象的子系统，请考虑添加对对象 - 调试基础结构的支持。 + - DEBUG_OBJECTS 将添加代码以跟踪内核创建的各种对象的生命周期，并在出现问题 + 时发出警告。如果你要添加创建（和导出）关于其自己的复杂对象的子系统，请 + 考虑打开对象调试基础结构的支持。 - DEBUG_SLAB 可以发现各种内存分配和使用错误；它应该用于大多数开发内核。 - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP and DEBUG_MUTEXES 会发现许多常见的 - 锁定错误. + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBUG_MUTEXES 会发现许多常见的 + 锁错误。 -还有很多其他调试选项，其中一些将在下面讨论。其中一些具有显著的性能影响，不应 -一直使用。但是，在学习可用选项上花费的一些时间可能会在短期内得到多次回报。 +还有很多其他调试选项，其中一些将在下面讨论。其中一些有显著的性能影响，不应 +一直使用。在学习可用选项上花费一些时间，可能会在短期内得到许多回报。 -其中一个较重的调试工具是锁定检查器或“lockdep”。该工具将跟踪系统中每个锁 +其中一个较重的调试工具是锁检查器或“lockdep”。该工具将跟踪系统中每个锁 （spinlock或mutex）的获取和释放、获取锁的相对顺序、当前中断环境等等。然后， -它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况，等等。换句话 -说，lockdep可以找到许多场景，在这些场景中，系统很少会死锁。在部署的系统中， -这种问题可能会很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式 -发现问题。具有任何类型的非普通锁定的代码在提交包含前应在启用lockdep的情况 -下运行。 +它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况等等。换句话 +说，lockdep可以找到许多导致系统死锁的场景。在部署的系统中，这种问题可能会 +很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式发现问题。具有 +任何类型的非普通锁的代码在提交合并前应在启用lockdep的情况下运行测试。 作为一个勤奋的内核程序员，毫无疑问，您将检查任何可能失败的操作（如内存分配） -的返回状态。然而，事实上，最终的故障恢复路径可能完全没有经过测试。未测试的 -代码往往会被破坏；如果所有这些错误处理路径都被执行了几次，那么您可能对代码 +的返回状态。然而，事实上，最终的故障复现路径可能完全没有经过测试。未测试的 +代码往往会出问题；如果所有这些错误处理路径都被执行了几次，那么您可能对代码 更有信心。 内核提供了一个可以做到这一点的错误注入框架，特别是在涉及内存分配的情况下。 -启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码 +启用故障注入后，内存分配的可配置失败的百分比；这些失败可以限定在特定的代码 范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响 应。有关如何使用此工具的详细信息，请参阅 Documentation/fault-injection/fault-injection.rst。 -使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员 -用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需 -要一组位标志的地方传递整数值等等。sparse必须单独安装(如果您的分发服务器没 -有将其打包，可以在 https://sparse.wiki.kernel.org/index.php/Main_page)找到, +“sparse”静态分析工具可以发现其他类型的错误。sparse可以警告程序员用户空间 +和内核空间地址之间的混淆、大端序与小端序的混淆、在需要一组位标志的地方传递 +整数值等等。sparse必须单独安装(如果您的分发服务器没有将其打包， +可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）, 然后可以通过在make命令中添加“C=1”在代码上运行它。 “Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` @@ -221,8 +224,8 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁” 其他类型的可移植性错误最好通过为其他体系结构编译代码来发现。如果没有S/390系统 -或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的 -大型交叉编译器： +或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一大堆用于x86系统的 +交叉编译器： https://www.kernel.org/pub/tools/crosstool/ @@ -233,22 +236,22 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁” 文档通常比内核开发规则更为例外。即便如此，足够的文档将有助于简化将新代码合并 到内核中的过程，使其他开发人员的生活更轻松，并对您的用户有所帮助。在许多情况 -下，文件的添加已基本上成为强制性的。 +下，添加文档已基本上是强制性的。 任何补丁的第一个文档是其关联的变更日志。日志条目应该描述正在解决的问题、解决 方案的形式、处理补丁的人员、对性能的任何相关影响，以及理解补丁可能需要的任何 -其他内容。确保changelog说明了为什么补丁值得应用；大量开发人员未能提供这些信息。 +其他内容。确保变更日志说明了*为什么*补丁值得应用；大量开发者未能提供这些信息。 -任何添加新用户空间界面的代码（包括新的sysfs或/proc文件）都应该包含该界面的 -文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅 -Documentation/ABI/README，了解如何格式化此文档以及需要提供哪些信息。 +任何添加新用户空间接口的代码——包括新的sysfs或/proc文件——都应该包含该接口 +的文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅 +Documentation/ABI/README，了解如何此文档格式以及需要提供哪些信息。 -文件 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` -描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文件添加适当的 +文档 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文档添加适当的 条目。 -任何新的配置选项都必须附有帮助文本，帮助文本清楚地解释了这些选项以及用户可能 -希望何时选择它们。 +任何新的配置选项都必须附有帮助文本，帮助文本需清楚地解释这些选项以及用户可能 +希望何时使用它们。 许多子系统的内部API信息通过专门格式化的注释进行记录；这些注释可以通过 “kernel-doc”脚本以多种方式提取和格式化。如果您在具有kerneldoc注释的子系统中 @@ -257,31 +260,31 @@ Documentation/ABI/README，了解如何格式化此文档以及需要提供哪 来说是一个有用的活动。这些注释的格式以及如何创建kerneldoc模板的一些信息可以在 :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 -任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。再一次， -对新代码的期望比过去更高；合并未注释的代码将更加困难。这就是说，人们几乎不希望 -用语言注释代码。代码本身应该是可读的，注释解释了更微妙的方面。 +任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。同时， +对新代码的要求比过去更高；合并未注释的代码将更加困难。这就是说，人们并不期望 +详细注释的代码。代码本身应该是自解释的，注释阐释了更微妙的方面。 某些事情应该总是被注释。使用内存屏障时，应附上一行文字，解释为什么需要设置内存 -屏障。数据结构的锁定规则通常需要在某个地方解释。一般来说，主要数据结构需要全面 -的文档。应该指出单独代码位之间不明显的依赖性。任何可能诱使代码看门人进行错误的 -“清理”的事情都需要一个注释来说明为什么要这样做。等等。 +屏障。数据结构的锁规则通常需要在某个地方解释。一般来说，主要数据结构需要全面 +的文档。应该指出代码中分立的位之间不明显的依赖性。任何可能诱使代码管理人进行 +错误的“清理”的事情都需要一个注释来说明为什么要这样做。等等。 内部API更改 ----------- -内核提供给用户空间的二进制接口不能被破坏，除非在最严重的情况下。相反，内核的 -内部编程接口是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核 -API，或者仅仅因为它不满足你的需求而不使用特定的功能，这可能是API需要改变的一 -个标志。作为内核开发人员，您有权进行此类更改。 +内核提供给用户空间的二进制接口不能被破坏，除非逼不得已。而内核的内部编程接口 +是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核API，或者仅 +仅因为它不满足你的需求导致无法使用特定的功能，这可能是API需要改变的一个标志。 +作为内核开发人员，您有权进行此类更改。 -当然, 可以进行API更改，但它们必须是合理的。因此，任何进行内部API更改的补丁都 -应该附带一个关于更改内容和必要原因的描述。这种变化也应该分解成一个单独的补丁， -而不是埋在一个更大的补丁中。 +的确可以进行API更改，但更改必须是合理的。因此任何进行内部API更改的补丁都应该 +附带关于更改内容和必要原因的描述。这种变化也应该拆分成一个单独的补丁，而不是 +埋在一个更大的补丁中。 另一个要点是，更改内部API的开发人员通常要负责修复内核树中被更改破坏的任何代码。 -对于一个广泛使用的函数，这个职责可以导致成百上千的变化，其中许多变化可能与其他 -开发人员正在做的工作相冲突。不用说，这可能是一项大工作，所以最好确保理由是 +对于一个广泛使用的函数，这个责任可以导致成百上千的变化，其中许多变化可能与其他 +开发人员正在做的工作相冲突。不用说，这可能是一项大工程，所以最好确保理由是 可靠的。请注意，coccinelle工具可以帮助进行广泛的API更改。 在进行不兼容的API更改时，应尽可能确保编译器捕获未更新的代码。这将帮助您确保找 diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 9ff9945f918c..b0c65614844d 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -1,150 +1,157 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_posting: 发布补丁 ======== -迟早，当您的工作准备好提交给社区进行审查，并最终包含到主线内核中时。不出所料， +您的工作迟早会准备好提交给社区进行审查，并最终包含到主线内核中。毫不稀奇， 内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使 -参与其中的每个人的生活更加轻松。本文件将试图合理详细地涵盖这些期望；更多信息 -也可在以下文件中找到 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`, -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` -和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`. +参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息 +也可在以下文档中找到 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`， +:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` +和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。 何时邮寄 -------- -在补丁完全“准备好”之前，有一个不断的诱惑来避免发布补丁。对于简单的补丁， -这不是问题。但是，如果正在完成的工作很复杂，那么在工作完成之前从社区获得 -反馈就可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至使Git树 -可用，以便感兴趣的开发人员可以随时赶上您的工作。 +在补丁完全“准备好”之前，避免发布补丁是一种持续的诱惑。对于简单的补丁，这 +不是问题。但是如果正在完成的工作很复杂，那么在工作完成之前从社区获得反馈就 +可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至维护一个可用的Git +树，以便感兴趣的开发人员可以随时赶上您的工作。 -当发布还没有准备好包含的代码时，最好在发布本身中这样说。还应提及任何有待完成 -的主要工作和任何已知问题。很少有人会看到那些被认为是半生不熟的补丁，但是那些 -人会想到他们可以帮助你把工作推向正确的方向。 +当发布中有尚未准备好被包含的代码，最好在发布中说明。还应提及任何有待完成的 +主要工作和任何已知问题。很少有人会愿意看那些被认为是半生不熟的补丁，但是 +那些愿意的人会带着他们的点子来一起帮助你把工作推向正确的方向。 创建补丁之前 ------------ -在考虑将补丁发送到开发社区之前，有许多事情应该做。这些包括： +在考虑将补丁发送到开发社区之前，有许多事情应该做。包括： - - 尽可能地测试代码。利用内核的调试工具，确保内核使用所有合理的配置选项组合 - 进行构建，使用跨编译器为不同的体系结构进行构建等。 + - 尽可能地测试代码。利用内核的调试工具，确保内核使用了所有可能的配置选项组合 + 进行构建，使用交叉编译器为不同的体系结构进行构建等。 - - 确保您的代码符合内核编码风格指南。 + - 确保您的代码符合内核代码风格指南。 - 您的更改是否具有性能影响？如果是这样，您应该运行基准测试来显示您的变更的 影响（或好处）；结果的摘要应该包含在补丁中。 - 确保您有权发布代码。如果这项工作是为雇主完成的，雇主对这项工作具有所有权， - 并且必须同意根据GPL对其进行放行。 + 并且必须同意根据GPL对其进行发布。 一般来说，在发布代码之前进行一些额外的思考，几乎总是能在短时间内得到回报。 补丁准备 -------- -准备发布补丁可能是一个惊人的工作量，但再次尝试节省时间在这里通常是不明智的， -即使在短期内。 +准备补丁发布的工作量可能很惊人，但在此尝试节省时间通常是不明智的，即使在短期 +内亦然。 -必须针对内核的特定版本准备补丁。作为一般规则，补丁程序应该基于Linus的Git树中 -的当前主线。当以主线为基础时，从一个众所周知的发布点开始——一个稳定的或RC的 -发布——而不是在一个主线分支任意点。 +必须针对内核的特定版本准备补丁。一般来说，补丁应该基于Linus的Git树中的当前 +主线。当以主线为基础时，请从一个众所周知的发布点开始——如稳定版本或 -rc +版本发布点——而不是在一个任意的主线分支点。 -但是，可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。 -根据补丁的区域以及其他地方的情况，针对这些其他树建立补丁可能需要大量的工作来 +也可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。 +根据补丁的区域以及其他地方的情况，针对其他树建立的补丁可能需要大量的工作来 解决冲突和处理API更改。 只有最简单的更改才应格式化为单个补丁；其他所有更改都应作为一系列逻辑更改进行。 分割补丁是一门艺术；一些开发人员花了很长时间来弄清楚如何按照社区期望的方式来 -做。然而，有一些经验法则可以大大帮助： +分割。不过，这些经验法则也许有帮助： - - 您发布的补丁程序系列几乎肯定不会是工作系统中的一系列更改。相反，您所做的 - 更改需要在最终形式中加以考虑，然后以有意义的方式进行拆分。开发人员对离散的、 - 自包含的更改感兴趣，而不是您获取这些更改的路径。 + - 您发布的补丁系列几乎肯定不会是开发过程中版本控制系统中的一系列更改。相反， + 需要对您所做更改的最终形式加以考虑，然后以有意义的方式进行拆分。开发人员对 + 离散的、自包含的更改感兴趣，而不是您创造这些更改的原始路径。 - - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（“向此 - 结构添加字段”）或大的（例如，添加一个重要的新驱动程序），但它们在概念上 - 应该是小的，并且可以接受一行描述。每个补丁都应该做一个特定的更改，可以单独 - 检查并验证它所做的事情。 + - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（如“向 + 此结构体添加字段”）或大的（如添加一个重要的新驱动程序），但它们在概念上 + 应该是小的，并且可以在一行内简述。每个补丁都应该做一个特定的、可以单独 + 检查并验证它所做的事情的更改。 - - 作为重申上述准则的一种方法：不要在同一补丁中混合不同类型的更改。如果一个 - 补丁修复了一个关键的安全漏洞，重新排列了一些结构，并重新格式化了代码，那么 - 很有可能它会被忽略，而重要的修复将丢失。 + - 换种方式重申上述准则，也就是说：不要在同一补丁中混合不同类型的更改。如果 + 一个补丁修复了一个关键的安全漏洞，又重新排列了一些结构，还重新格式化了代 + 码，那么它很有可能会被忽略，从而导致重要的修复丢失。 - - 每个补丁都应该产生一个内核，它可以正确地构建和运行；如果补丁系列在中间被 - 中断，那么结果应该仍然是一个工作的内核。补丁系列的部分应用是使用 - “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么对于 - 那些从事追踪问题的高尚工作的开发人员和用户来说，将使他们的生活更加艰难。 + - 每个补丁都应该能创建一个可以正确地构建和运行的内核；如果补丁系列在中间被 + 断开，那么结果仍应是一个正常工作的内核。部分应用一系列补丁是使用 + “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么将使 + 那些从事追踪问题的高尚工作的开发人员和用户的生活更加艰难。 - - 不过，不要过分。一位开发人员曾经将一组编辑内容作为500个单独的补丁发布到一个 - 文件中，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大， - 只要它仍然包含一个单一的逻辑变更。 + - 不要过分分割。一位开发人员曾经将一组针对单个文件的编辑分成500个单独的补丁 + 发布，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大， + 只要它仍然包含一个单一的 *逻辑* 变更。 - - 用一系列补丁添加一个全新的基础设施是很有诱惑力的，但是在系列中的最后一个 - 补丁启用整个补丁之前，该基础设施是不使用的。如果可能的话，应该避免这种 - 诱惑；如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的 - 补丁，即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即 - 激活该代码。 + - 用一系列补丁添加一个全新的基础设施，但是该设施在系列中的最后一个补丁启用 + 整个变更之前不能使用，这看起来很诱人。如果可能的话，应该避免这种诱惑； + 如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的补丁， + 即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即激活该 + 代码。 -创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要花费 -大量的时间和思考。但是，如果做得好，这是一段很好的时间。 +创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要 +花费大量的时间和思考。但是如果做得好，花费的时间就是值得的。 补丁格式和更改日志 ------------------ 所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都 -需要被格式化成一条消息，它可以快速而清晰地将其目的传达给世界其他地方。为此， +需要被格式化成一条消息，以快速而清晰地将其目的传达到世界其他地方。为此， 每个补丁将由以下部分组成： - - 命名补丁作者的可选“from”行。只有当你通过电子邮件传递别人的补丁时，这一行 - 才是必要的，但是如果有疑问，添加它不会有任何伤害。 + - 可选的“From”行，表明补丁作者。只有当你通过电子邮件发送别人的补丁时，这一行 + 才是必须的，但是为防止疑问加上它也不会有什么坏处。 - - 一行描述补丁的作用。对于没有其他上下文的读者来说，此消息应该足够了解补丁 - 的范围；这是将在“短格式”变更日志中显示的行。此消息通常首先用相关的子系统 - 名称格式化，然后是补丁的目的。例如： + - 一行描述，说明补丁的作用。对于在没有其他上下文的情况下看到该消息的读者来说， + 该消息应足以确定修补程序的范围；此行将显示在“short form（简短格式）”变更 + 日志中。此消息通常需要先加上子系统名称前缀，然后是补丁的目的。例如： - :: + :: - gpio: fix build on CONFIG_GPIO_SYSFS=n + gpio: fix build on CONFIG_GPIO_SYSFS=n - - 一个空白行，后面是补丁内容的详细描述。这个描述可以是必需的；它应该说明补丁 + - 一行空白，后接补丁内容的详细描述。此描述可以是任意需要的长度；它应该说明补丁 的作用以及为什么它应该应用于内核。 - - 一个或多个标记行，至少有一个由补丁作者的：signed-off-by 签名。签名将在下面 - 更详细地描述。 + - 一个或多个标记行，至少有一个由补丁作者的 Signed-off-by 签名。标记将在下面 + 详细描述。 -上面的项目一起构成补丁的变更日志。写一篇好的变更日志是一门至关重要但常常被 -忽视的艺术；值得花一点时间来讨论这个问题。当你写一个变更日志时，你应该记住 -有很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否 -应该包括补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核， -bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知道内核如何变化的用户。 -等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。 +上面的项目一起构成补丁的变更日志。写一则好的变更日志是一门至关重要但常常被 +忽视的艺术；值得花一点时间来讨论这个问题。当你编写变更日志时，你应该记住有 +很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否 +应该合并补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核， +缺陷搜寻人员想知道补丁是否导致他们正在追查的问题，以及想知道内核如何变化的 +用户等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。 -为此，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。 +在结尾，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。 然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了 -一个bug，请引用引入该bug的commit（如果可能，请在引用commits时同时提供commit id -和标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他 -人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么就这么 -说。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。一般 -来说，你越能把自己放在每个阅读你的changelog的人的位置上，changelog（和内核 +一个缺陷，请引用引入该缺陷的提交（如果可能，请在引用提交时同时提供其 id 和 +标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他 +人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么应当 +说明。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。 +一般来说，你越把自己放在每个阅读你变更日志的人的位置上，变更日志（和内核 作为一个整体）就越好。 -不用说，变更日志应该是将变更提交到修订控制系统时使用的文本。接下来是： +不消说，变更日志是将变更提交到版本控制系统时使用的文本。接下来将是： - - 补丁本身，采用统一的（“-u”）补丁格式。将“-p”选项用于diff将使函数名与更改 - 相关联，从而使结果补丁更容易被其他人读取。 + - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与 + 更改相关联，从而使结果补丁更容易被其他人读取。 -您应该避免在补丁中包括对不相关文件（例如，由构建过程生成的文件或编辑器 -备份文件）的更改。文档目录中的文件“dontdiff”在这方面有帮助；使用“-X”选项将 +您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器 +备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将 其传递给diff。 -上面提到的标签用于描述各种开发人员如何与这个补丁的开发相关联。 +上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` 文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下： @@ -154,87 +161,87 @@ bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知 常用的标签有： - - Signed-off-by: 这是一个开发人员的证明，他或她有权提交补丁以包含到内核中。 - 这是开发来源认证协议，其全文可在 + - Signed-off-by: 这是一个开发人员的证明，证明他或她有权提交补丁以包含到内核 + 中。这表明同意开发者来源认证协议，其全文见 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - 中找到，如果没有适当的签字，则不能合并到主线中。 + 如果没有合适的签字，则不能合并到主线中。 - Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上 - 工作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为 - Co-developed-by: 表示作者身份，所以每个共同开发人, 必须紧跟在相关合作作者 - 的签名之后。具体内容和示例可以在以下文件中找到 + 工作时，它用于给出共同作者（除了 From: 所给出的作者之外）。由于 + Co-developed-by: 表示作者身份，所以每个共同开发人，必须紧跟在相关合作作者 + 的Signed-off-by之后。具体内容和示例见以下文件 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - Acked-by: 表示另一个开发人员（通常是相关代码的维护人员）同意补丁适合包含 在内核中。 - - Tested-by: 声明指定的人已经测试了补丁并发现它可以工作。 + - Tested-by: 声明某人已经测试了补丁并确认它可以工作。 - - Reviewed-by: 指定的开发人员已经审查了补丁的正确性；有关详细信息，请参阅 + - Reviewed-by: 表示某开发人员已经审查了补丁的正确性；有关详细信息，请参阅 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于提供感谢。 + - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于表示感谢。 - - Cc：指定的人收到了补丁的副本，并有机会对此发表评论。 + - Cc：指定某人收到了补丁的副本，并有机会对此发表评论。 -在补丁中添加标签时要小心：只有cc:才适合在没有指定人员明确许可的情况下添加。 +在补丁中添加标签时要小心：只有Cc:才适合在没有指定人员明确许可的情况下添加。 发送补丁 -------- -在邮寄补丁之前，您还需要注意以下几点： +在寄出补丁之前，您还需要注意以下几点： - - 您确定您的邮件发送程序不会损坏补丁吗？有免费的空白更改或由邮件客户端 - 执行的行包装的补丁不会在另一端复原，并且通常不会进行任何详细检查。如果有 - 任何疑问，把补丁寄给你自己，让你自己相信它是完好无损的。 + - 您确定您的邮件发送程序不会损坏补丁吗？被邮件客户端更改空白或修饰了行的补丁 + 无法被另一端接受，并且通常不会进行任何详细检查。如果有任何疑问，先把补丁寄 + 给你自己，让你自己确定它是完好无损的。 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` - 提供了一些有用的提示，可以让特定的邮件客户机工作以发送补丁。 + 提供了一些有用的提示，可以让特定的邮件客户端正常发送补丁。 - - 你确定你的补丁没有愚蠢的错误吗？您应该始终通过scripts/checkpatch.pl运行 - 补丁程序，并解决它提出的投诉。请记住，checkpatch.pl虽然是大量思考内核 - 补丁应该是什么样子的体现，但它并不比您聪明。如果修复checkpatch.pl投诉会 + - 你确定你的补丁没有荒唐的错误吗？您应该始终通过scripts/checkpatch.pl检查 + 补丁程序，并解决它提出的问题。请记住，checkpatch.pl，虽然体现了对内核补丁 + 应该是什么样的大量思考，但它并不比您聪明。如果修复checkpatch.pl给的问题会 使代码变得更糟，请不要这样做。 补丁应始终以纯文本形式发送。请不要将它们作为附件发送；这使得审阅者在答复中更难 引用补丁的部分。相反，只需将补丁直接放到您的消息中。 -邮寄补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核 -鼓励人们错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。 +寄出补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核 +鼓励人们甚至错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。 尤其是，副本应发送至： - - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的第一个地方。 + - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的首选地方。 - 其他在同一领域工作的开发人员，尤其是那些现在可能在那里工作的开发人员。使用 git查看还有谁修改了您正在处理的文件，这很有帮助。 - - 如果您对错误报告或功能请求做出响应，也可以抄送原始发送人。 + - 如果您对某错误报告或功能请求做出响应，也可以抄送原始发送人。 - - 将副本发送到相关邮件列表，或者，如果没有其他应用，则发送到Linux内核列表。 + - 将副本发送到相关邮件列表，或者若无相关列表，则发送到linux-kernel列表。 - - 如果您正在修复一个bug，请考虑该修复是否应进入下一个稳定更新。如果是这样， - stable@vger.kernel.org 应该得到补丁的副本。另外，在补丁本身的标签中添加 - 一个“cc:stable@vger.kernel.org”；这将使稳定团队在修复进入主线时收到通知。 + - 如果您正在修复一个缺陷，请考虑该修复是否应进入下一个稳定更新。如果是这样， + 补丁副本也应发到stable@vger.kernel.org 。另外，在补丁本身的标签中添加一个 + “Cc: stable@vger.kernel.org”；这将使稳定版团队在修复进入主线时收到通知。 -当为一个补丁选择接收者时，最好知道你认为谁最终会接受这个补丁并将其合并。虽然 -可以将补丁直接发送给LinusTorvalds并让他合并，但通常情况下不会这样做。Linus -很忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您 -的补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁目标。 +当为一个补丁选择接收者时，最好清楚你认为谁最终会接受这个补丁并将其合并。虽然 +可以将补丁直接发给Linus Torvalds并让他合并，但通常情况下不会这样做。Linus很 +忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您的 +补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁接收者。 -补丁需要好的主题行。补丁程序行的规范格式如下： +补丁需要好的主题行。补丁主题行的规范格式如下： :: [PATCH nn/mm] subsys: one-line description of the patch -其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的名称。 -显然，一个单独的补丁可以省略nn/mm。 +其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的 +名称。当然，一个单独的补丁可以省略nn/mm。 -如果您有一系列重要的补丁，那么通常将介绍性描述作为零部分发送。不过，这种约定 -并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会使它进入内核变更日志。 +如果您有一系列重要的补丁，那么通常发送一个简介作为第〇部分。不过，这个约定 +并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会进入内核变更日志。 因此，请确保补丁本身具有完整的变更日志信息。 一般来说，多部分补丁的第二部分和后续部分应作为对第一部分的回复发送，以便它们 在接收端都连接在一起。像git和coilt这样的工具有命令，可以通过适当的线程发送 -一组补丁。但是，如果您有一个长系列，并且正在使用git，请远离–chain reply-to -选项，以避免创建异常深的嵌套。 +一组补丁。但是，如果您有一长串补丁，并正使用git，请不要使用–-chain-reply-to +选项，以避免创建过深的嵌套。 diff --git a/Documentation/translations/zh_CN/process/6.Followthrough.rst b/Documentation/translations/zh_CN/process/6.Followthrough.rst index f509e077e1cb..2a127e737b6a 100644 --- a/Documentation/translations/zh_CN/process/6.Followthrough.rst +++ b/Documentation/translations/zh_CN/process/6.Followthrough.rst @@ -1,145 +1,152 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_followthrough: 跟进 ==== -在这一点上，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能 -的增加，已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大 -错误之一是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下 -一个阶段，可能还需要做很多工作。 +此时，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能的增加， +已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大错误之一 +是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下一个阶段， +可能还需要做很多工作。 -一个补丁在第一次发布时就非常出色，没有改进的余地,这是很罕见的。内核开发流程 -认识到这一事实，因此，它非常注重对已发布代码的改进。作为代码的作者，您应该与 +一个补丁在首次发布时就非常出色、没有改进的余地，这是很罕见的。内核开发流程已 +认识到这一事实，因此它非常注重对已发布代码的改进。作为代码的作者，您应该与 内核社区合作，以确保您的代码符合内核的质量标准。如果不参与这个过程，很可能会 -阻止将补丁包含到主线中。 +无法将补丁合并到主线中。 与审阅者合作 ------------ 任何意义上的补丁都会导致其他开发人员在审查代码时发表大量评论。对于许多开发 -人员来说，与审查人员合作可能是内核开发过程中最令人生畏的部分。但是，如果你 +人员来说，与审阅人员合作可能是内核开发过程中最令人生畏的部分。但是如果你 记住一些事情，生活会变得容易得多： - - 如果你已经很好地解释了你的补丁，评论人员会理解它的价值，以及为什么你会 - 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：五年或十年后 - 用这个代码维护一个内核会是什么感觉？你可能被要求做出的许多改变——从编码风格 - 的调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将在 - 开发中。 + - 如果你已经很好地解释了你的补丁，审阅人员会理解它的价值，以及为什么你会 + 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：在五年或十年后 + 维护含有此代码的内核会怎么样？你可能被要求做出的许多改变——从编码风格的 + 调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将 + 在开发中。 - 代码审查是一项艰苦的工作，这是一项相对吃力不讨好的工作；人们记得谁编写了 - 内核代码，但对于那些审查它的人来说，几乎没有什么持久的名声。因此，评论 + 内核代码，但对于那些审查它的人来说，几乎没有什么长久的名声。因此，审阅 人员可能会变得暴躁，尤其是当他们看到同样的错误被一遍又一遍地犯下时。如果 - 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，抵制以同样方式回应的冲动。 - 代码审查是关于代码的，而不是关于人的，代码审查人员不会亲自攻击您。 + 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，请抑制以同样方式回应的冲动。 + 代码审查是关于代码的，而不是关于人的，代码审阅人员不会亲自攻击您。 - - 同样，代码审查人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。 + - 同样，代码审阅人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。 内核开发人员通常希望今后几年能在内核上工作，但他们明白他们的雇主可能会改 变。他们真的，几乎毫无例外地，致力于创造他们所能做到的最好的内核；他们并 没有试图给雇主的竞争对手造成不适。 -所有这些归根结底都是，当审阅者向您发送评论时，您需要注意他们正在进行的技术 -观察。不要让他们的表达方式或你自己的骄傲阻止这种事情的发生。当你在一个补丁 -上得到评论时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求 -您修复的内容。然后回复审稿人：谢谢他们，并描述你将如何回答他们的问题。 +所有这些归根结底就是，当审阅者向您发送评论时，您需要注意他们正在进行的技术 +评论。不要让他们的表达方式或你自己的骄傲阻止此事。当你在一个补丁上得到评论 +时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求您修复的内 +容。然后回复审阅者：谢谢他们，并描述你将如何回答他们的问题。 请注意，您不必同意审阅者建议的每个更改。如果您认为审阅者误解了您的代码，请 解释到底发生了什么。如果您对建议的更改有技术上的异议，请描述它并证明您对该 -问题的解决方案是正确的。如果你的解释有道理，审稿人会接受的。不过，如果你的 -解释不能证明是有说服力的，尤其是当其他人开始同意审稿人的观点时，请花些时间 -重新考虑一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某个 -问题根本是错误的，或者你甚至没有解决正确的问题。 +问题的解决方案是正确的。如果你的解释有道理，审阅者会接受的。不过，如果你的 +解释证明缺乏说服力，尤其是当其他人开始同意审稿人的观点时，请花些时间重新考虑 +一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某些东西完全 +是错误的，或者你甚至没有解决正确的问题。 -Andrew Morton建议，每一条不会导致代码更改的评论都应该导致额外的代码注释； -这可以帮助未来的评论人员避免出现第一次出现的问题。 +Andrew Morton建议，每一个不会导致代码更改的审阅评论都应该产生一个额外的代码 +注释；这可以帮助未来的审阅人员避免第一次出现的问题。 -一个致命的错误是忽视评论，希望它们会消失。他们不会走的。如果您在没有对之前 -收到的注释做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。 +一个致命的错误是忽视评论，希望它们会消失。它们不会走的。如果您在没有对之前 +收到的评论做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。 说到重新发布代码：请记住，审阅者不会记住您上次发布的代码的所有细节。因此， -提醒审查人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更 +提醒审阅人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更 日志是提供此类信息的好地方。审阅者不必搜索列表档案来熟悉上次所说的内容； -如果您帮助他们开始运行，当他们重新访问您的代码时，他们的心情会更好。 +如果您帮助他们直接开始，当他们重新查看您的代码时，心情会更好。 如果你已经试着做正确的事情，但事情仍然没有进展呢？大多数技术上的分歧都可以 -通过讨论来解决，但有时人们只需要做出决定。如果你真的认为这个决定对你不利， -你可以试着向更高的权力上诉。在这篇文章中，更高的权力倾向于Andrew Morton。 -Andrew在内核开发社区中受i很大的尊重；他经常为似乎被绝望地阻塞事情清障。 -尽管如此，对Andrew的呼吁不应轻而易举，也不应在所有其他替代方案都被探索之前 -使用。当然，记住，他也可能不同意你的意见。 +通过讨论来解决，但有时人们仍需要做出决定。如果你真的认为这个决定对你不利， +你可以试着向有更高权力的人上诉。对于本文，更高权力的人是 Andrew Morton 。 +Andrew 在内核开发社区中非常受尊敬；他经常为似乎被绝望阻塞的事情清障。尽管 +如此，不应轻易就直接找 Andrew ，也不应在所有其他替代方案都被尝试之前找他。 +当然，记住，他也可能不同意你的意见。 接下来会发生什么 ---------------- -如果一个补丁被认为是添加到内核中的一件好事，并且一旦大多数审查问题得到解决， -下一步通常是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都 -有自己的工作方式。特别是，可能有不止一棵树——一棵树，也许，专门用于计划下一 -个合并窗口的补丁，另一棵树用于长期工作。 +如果一个补丁被认为适合添加到内核中，并且大多数审查问题得到解决，下一步通常 +是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都有自己的 +工作方式。特别是可能有不止一棵树——也许一棵树专门用于计划下一个合并窗口的 +补丁，另一棵树用于长期工作。 -对于应用于没有明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树 -通常以-mm结尾。影响多个子系统的补丁也可以最终通过-mm树。 +对于应用到不属于明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树 +通常上溯到-mm。影响多个子系统的补丁也可以最终进入-mm树。 包含在子系统树中可以提高补丁的可见性。现在，使用该树的其他开发人员将默认获 得补丁。子系统树通常也为Linux提供支持，使其内容对整个开发社区可见。在这一点 上，您很可能会从一组新的审阅者那里得到更多的评论；这些评论需要像上一轮那样 -得到回答。 +得到回应。 -在这一点上也会发生什么，这取决于你的补丁的性质，是与其他人正在做的工作发生 +在这时也会发生点什么，这取决于你的补丁的性质，是否与其他人正在做的工作发生 冲突。在最坏的情况下，严重的补丁冲突可能会导致一些工作被搁置，以便剩余的补丁 可以成形并合并。另一些时候，冲突解决将涉及到与其他开发人员合作，可能还会 在树之间移动一些补丁，以确保所有的应用都是干净的。这项工作可能是一件痛苦的 -事情，但要计算您的福祉：在Linux下一棵树出现之前，这些冲突通常只在合并窗口 -中出现，必须迅速解决。现在可以在合并窗口打开之前，在空闲时解决这些问题。 +事情，但也需庆幸现在的幸福：在linux-next树出现之前，这些冲突通常只在合并窗口 +中出现，必须迅速解决。现在可以在合并窗口打开之前的空闲时间解决这些问题。 有朝一日，如果一切顺利，您将登录并看到您的补丁已经合并到主线内核中。祝贺你！ -然而，一旦庆祝活动完成（并且您已经将自己添加到维护人员文件中），就值得记住 -一个重要的小事实：工作仍然没有完成。并入主线带来了自身的挑战。 +然而，一旦庆祝完了（并且您已经将自己添加到维护人员文件中），就一定要记住 +一个重要的小事实：工作仍然没有完成。并入主线也带来了它的挑战。 -首先，补丁的可见性再次提高。可能会有新一轮的开发者评论，他们以前不知道这 -个补丁。忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是， -要抵制这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。 +首先，补丁的可见性再次提高。可能会有以前不知道这个补丁的开发者的新一轮评论。 +忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是，要抵制 +这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。 -不过，更重要的是：将代码包含在主线中会将代码交给更大的一组测试人员。即使您 -为尚未提供的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核 -中。当然，如果有测试人员，也会有错误报告。 +不过，更重要的是：将代码包含在主线中会将代码交给更多的一些测试人员。即使您 +为尚未可用的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核 +中。当然，如果有测试人员，也可能会有错误报告。 -最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现很多不舒服的眼睛盯着 -你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复）， +最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现多到让你不舒服的眼睛盯 +着你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复）， 那么在稳定期内，您的补丁几乎肯定会被移除。除了否定您为使补丁进入主线所做的 -所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难合并。 +所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难被合并。 -在处理完任何回归之后，可能还有其他普通的bug需要处理。稳定期是修复这些错误并 -确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回答错误 +在处理完任何回归之后，可能还有其他普通缺陷需要处理。稳定期是修复这些错误并 +确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回应错误 报告，并尽可能解决问题。这就是稳定期的目的；一旦解决了旧补丁的任何问题，就 -可以开始创建酷的新补丁。 +可以开始尽情创建新补丁。 -别忘了，还有其他里程碑也可能会创建bug报告：下一个主线稳定版本，当著名的发行 -商选择包含补丁的内核版本时，等等。继续响应这些报告是您工作的基本骄傲。但是， -如果这不是足够的动机，那么也值得考虑的是，开发社区会记住那些在合并后对代码 -失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会在身边维护它为假 -设来评估它。 +别忘了，还有其他节点也可能会创建缺陷报告：下一个主线稳定版本，当著名的发行 +商选择包含您补丁的内核版本时等等。继续响应这些报告是您工作的基本素养。但是 +如果这不能提供足够的动机，那么也需要考虑：开发社区会记住那些在合并后对代码 +失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会持续维护它为前提 +来评估它。 其他可能发生的事情 ------------------ -有一天，你可以打开你的邮件客户端，看到有人给你寄了一个代码补丁。毕竟，这是 +某天，当你打开你的邮件客户端时，看到有人给你寄了一个代码补丁。毕竟，这是 让您的代码公开存在的好处之一。如果您同意这个补丁，您可以将它转发给子系统 -维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己 -的签准），或者回复一个Acked-by，让原始发送者向上发送它。 +维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己的 +signoff ），或者回复一个 Acked-by: 让原始发送者向上发送它。 -如果您不同意补丁，请发送一个礼貌的回复，解释原因。如果可能的话，告诉作者需要 -做哪些更改才能让您接受补丁。对于代码的编写者和维护者所反对的合并补丁，存在着 -一定的阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最 -终会经过你身边并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。 -除了Linus。 +如果您不同意补丁，请礼貌地回复，解释原因。如果可能的话，告诉作者需要做哪些 +更改才能让您接受补丁。合并代码的编写者和维护者所反对的补丁的确存在着一定的 +阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最终会 +绕过你并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。可能除 +了Linus。 在非常罕见的情况下，您可能会看到完全不同的东西：另一个开发人员发布了针对您 -的问题的不同解决方案。在这一点上，两个补丁中的一个可能不会合并，“我的在这里 -是第一个”不被认为是一个令人信服的技术论据。如果有人的补丁取代了你的补丁而进 -入了主线，那么只有一种方法可以回应你：高兴你的问题得到解决，继续你的工作。 -以这种方式把一个人的工作推到一边可能会伤害和气馁，但是在他们忘记了谁的补丁 -真正被合并很久之后，社区会记住你的反应。 +的问题的不同解决方案。在这时，两个补丁之一可能不会被合并，“我的补丁首先 +发布”不被认为是一个令人信服的技术论据。如果有别人的补丁取代了你的补丁而进 +入了主线，那么只有一种方法可以回应你：很高兴你的问题解决了，请继续工作吧。 +以这种方式把某人的工作推到一边可能导致伤心和气馁，但是社区会记住你的反应， +即使很久以后他们已经忘记了谁的补丁真正被合并。 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 2f0ef750746f..6d0dadae13b1 100644 --- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_advancedtopics: @@ -15,110 +22,112 @@ --------------- 内核使用分布式版本控制始于2002年初，当时Linus首次开始使用专有的Bitkeeper应用 -程序。虽然bitkeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式 -版本控制可以立即加速内核开发项目。在当前的时代，有几种免费的比特保持器替代品。 -无论好坏，内核项目都将Git作为其选择的工具。 +程序。虽然BitKeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式 +版本控制可以立即加速内核开发项目。现在有好几种免费的BitKeeper替代品。 +但无论好坏，内核项目都已经选择了Git作为其工具。 -使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增加。Git -也有其粗糙的边缘和一定的危险，它是一个年轻和强大的工具，仍然在其开发人员完善 +使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增长。Git也 +有其粗糙的边角和一定的危险性，它是一个年轻和强大的工具，仍然在其开发人员完善 中。本文档不会试图教会读者如何使用git；这会是个巨长的文档。相反，这里的重点 -将是Git如何特别适合内核开发过程。想要加快Git的开发人员可以在以下网站上找到 -更多信息： +将是Git如何特别适合内核开发过程。想要加快用Git速度的开发人员可以在以下网站上 +找到更多信息： https://git-scm.com/ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html -在尝试使用它使补丁可供其他人使用之前，第一要务是阅读上述站点，对Git的工作 -方式有一个扎实的了解。使用Git的开发人员应该能够获得主线存储库的副本，探索 -修订历史，提交对树的更改，使用分支等。了解Git用于重写历史的工具（如Rebase） -也很有用。Git有自己的术语和概念；Git的新用户应该了解refs、远程分支、索引、 -快进合并、推拉、分离头等。一开始可能有点吓人，但这些概念不难通过一点学习来 +同时网上也能找到各种各样的教程。 + +在尝试使用它生成补丁供他人使用之前，第一要务是阅读上述网页，对Git的工作方式 +有一个扎实的了解。使用Git的开发人员应能进行拉取主线存储库的副本，查询修订 +历史，提交对树的更改，使用分支等操作。了解Git用于重写历史的工具（如rebase） +也很有用。Git有自己的术语和概念；Git的新用户应该了解引用、远程分支、索引、 +快进合并、推拉、游离头等。一开始可能有点吓人，但这些概念不难通过一点学习来 理解。 使用git生成通过电子邮件提交的补丁是提高速度的一个很好的练习。 -当您准备好开始安装Git树供其他人查看时，您当然需要一个可以从中提取的服务器。 -如果您有一个可以访问Internet的系统，那么使用git守护进程设置这样的服务器相 -对简单。否则，免费的公共托管网站（例如github）开始出现在网络上。成熟的开发 -人员可以在kernel.org上获得一个帐户，但这些帐户并不容易找到；有关更多信息， -请参阅 https://kernel.org/faq/ +当您准备好开始建立Git树供其他人查看时，无疑需要一个可以从中拉取的服务器。 +如果您有一个可以访问因特网的系统，那么使用git-daemon设置这样的服务器相对 +简单。同时，免费的公共托管网站（例如github）也开始出现在网络上。成熟的开发 +人员可以在kernel.org上获得一个帐户，但这些帐户并不容易得到；更多有关信息， +请参阅 https://kernel.org/faq/ 。 正常的Git工作流程涉及到许多分支的使用。每一条开发线都可以分为单独的“主题 -分支”，并独立维护。Git的分支机构很便宜，没有理由不免费使用它们。而且，在 -任何情况下，您都不应该在任何您打算让其他人从中受益的分支中进行开发。应该 -小心地创建公开可用的分支；当它们处于完整的形式并准备好运行时(而不是之前）， -合并开发分支的补丁。 +分支”，并独立维护。Git的分支很容易使用，没有理由不使用它们。而且，在任何 +情况下，您都不应该在任何您打算让其他人从中拉取的分支中进行开发。应该小心地 +创建公开可用的分支；当开发分支处于完整状态并已准备好时(而不是之前）才合并 +开发分支的补丁。 Git提供了一些强大的工具，可以让您重写开发历史。一个不方便的补丁（比如说， 一个打破二分法的补丁，或者有其他一些明显的缺陷）可以在适当的位置修复，或者 -完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线之上写的 -一样，即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另 -一个分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。 +完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线上写的一样， +即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另一个 +分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。 -然而，过度使用这种能力可能会导致其他问题，而不仅仅是对创建完美项目历史的 -简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望）的内核树变 -为未经测试的内核树。但是，除此之外，如果开发人员没有对项目历史的共享视图， -他们就无法轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将 -使这些开发人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他 -人的历史在此后通常被认为是不可变的。 +然而，过度使用这种功能可能会导致其他问题，而不仅仅是对创建完美项目历史的 +简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望如此）的内核树 +变为未经测试的内核树。除此之外，如果开发人员没有共享项目历史，他们就无法 +轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将使这些开发 +人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他地方的历史 +在此后通常被认为是不可变的。 因此，一旦将一组更改推送到公开可用的服务器上，就不应该重写这些更改。如果您 -尝试强制进行不会导致快进合并（即不共享同一历史记录的更改）的更改，Git将尝 -试强制执行此规则。可以重写此检查，有时可能需要重写导出的树。在树之间移动变 -更集以避免Linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为 -什么开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的 -高级状态时才转移到公共分支中的原因之一。 +尝试强制进行无法快进合并的更改（即不共享同一历史记录的更改），Git将尝试强制 +执行此规则。这可能覆盖检查，有时甚至需要重写导出的树。在树之间移动变更集以 +避免linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为什么 +开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的较新 +状态时才转移到公共分支中的原因之一。 当主线（或其他一组变更所基于的树）前进时，很容易与该树合并以保持领先地位。 对于一个私有的分支，rebasing 可能是一个很容易跟上另一棵树的方法，但是一旦 -一棵树被导出到全世界，rebasing就不是一个选项。一旦发生这种情况，就必须进行 -完全合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱 -历史。在这种情况下，建议的技术是不经常合并，通常只在特定的发布点（如主线-rc -发布）合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。 -在这种情况下，git rerere 工具很有用；它记住合并冲突是如何解决的，这样您就 -不必重复相同的工作。 +一棵树被导出到外界，rebasing就不可取了。一旦发生这种情况，就必须进行完全 +合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱历史。 +在这种情况下建议的做法是不要频繁合并，通常只在特定的发布点（如主线-rc发布） +合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。在 +这种情况下，git“rerere”工具很有用；它能记住合并冲突是如何解决的，这样您 +就不必重复相同的工作。 关于Git这样的工具的一个最大的反复抱怨是：补丁从一个存储库到另一个存储库的 大量移动使得很容易陷入错误建议的变更中，这些变更避开审查雷达进入主线。当内 -核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未查看或 -主题外的补丁可能会影响您将来获取树的能力。引用Linus: +核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未审阅或 +主题外的补丁可能会影响您将来让树被拉取的能力。引用Linus的话: :: - 你可以给我发补丁，但要我从你哪里取一个Git补丁，我需要知道你知道 - 你在做什么，我需要能够相信事情而不去检查每个个人改变。 + 你可以给我发补丁，但当我从你那里拉取一个Git补丁时，我需要知道你清楚 + 自己在做什么，我需要能够相信事情而 *无需* 手动检查每个单独的更改。 （http://lwn.net/articles/224135/）。 为了避免这种情况，请确保给定分支中的所有补丁都与相关主题紧密相关；“驱动程序 修复”分支不应更改核心内存管理代码。而且，最重要的是，不要使用Git树来绕过 -审查过程。不时的将树的摘要发布到相关的列表中，当时间合适时，请求 -Linux-next 中包含该树。 +审查过程。不时的将树的摘要发布到相关的列表中，在合适时候请求linux-next中 +包含该树。 -如果其他人开始发送补丁以包含到您的树中，不要忘记查看它们。还要确保您维护正确 -的作者信息； ``git am`` 工具在这方面做得最好，但是如果它通过第三方转发给您， -您可能需要在补丁中添加“From：”行。 +如果其他人开始发送补丁以包含到您的树中，不要忘记审阅它们。还要确保您维护正确 +的作者信息； git “am”工具在这方面做得最好，但是如果补丁通过第三方转发给您， +您可能需要在补丁中添加“From:”行。 -请求pull操作时，请务必提供所有相关信息：树的位置、要拉的分支以及拉操作将导致 -的更改。在这方面，git request pull 命令非常有用；它将按照其他开发人员的预期 -格式化请求，并检查以确保您记住了将这些更改推送到公共服务器。 +请求拉取时，请务必提供所有相关信息：树的位置、要拉取的分支以及拉取将导致的 +更改。在这方面 git request-pull 命令非常有用；它将按照其他开发人员所期望的 +格式化请求，并检查以确保您已记得将这些更改推送到公共服务器。 -审查补丁 +审阅补丁 -------- -一些读者当然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员 -也应该检查补丁。当然，学习如何在内核环境中编程没有比查看其他人发布的代码更好 -的方法了。此外，审阅者永远供不应求；通过查看代码，您可以对整个流程做出重大贡献。 +一些读者显然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员 +也应该审阅补丁。当然，没有比查看其他人发布的代码更好的方法来学习如何在内核环境 +中编程了。此外，审阅者永远供不应求；通过审阅代码，您可以对整个流程做出重大贡献。 -审查代码可能是一个令人生畏的前景，特别是对于一个新的内核开发人员来说，他们 +审查代码可能是一副令人生畏的图景，特别是对一个新的内核开发人员来说，他们 可能会对公开询问代码感到紧张，而这些代码是由那些有更多经验的人发布的。不过， -即使是最有经验的开发人员编写的代码也可以得到改进。也许对评审员（所有评审员） -最好的建议是：把评审评论当成问题而不是批评。询问“在这条路径中如何释放锁？” +即使是最有经验的开发人员编写的代码也可以得到改进。也许对（所有）审阅者最好 +的建议是：把审阅评论当成问题而不是批评。询问“在这条路径中如何释放锁？” 总是比说“这里的锁是错误的”更好。 -不同的开发人员将从不同的角度审查代码。一些主要关注的是编码样式以及代码行是 -否有尾随空格。其他人将主要关注补丁作为一个整体实现的变更是否对内核有好处。 -然而，其他人会检查是否存在锁定问题、堆栈使用过度、可能的安全问题、在其他 -地方发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有 -类型的检查，如果它们导致更好的代码进入内核，都是受欢迎和值得的。 +不同的开发人员将从不同的角度审查代码。部分人会主要关注代码风格以及代码行是 +否有尾随空格。其他人会主要关注补丁作为一个整体实现的变更是否对内核有好处。 +同时也有人会检查是否存在锁问题、堆栈使用过度、可能的安全问题、在其他地方 +发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有类型 +的检查，只要它们能引导更好的代码进入内核，都是受欢迎和值得的。 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 90cec3de6106..71c3e30efc6f 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -1,7 +1,13 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_conclusion: @@ -9,56 +15,56 @@ ======== 关于Linux内核开发和相关主题的信息来源很多。首先是在内核源代码分发中找到的 -文档目录。顶级 :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` -文件是一个重要的起点 +文档目录。顶级 +:ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` +文件是一个重要的起点； :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` -和 :ref:`process/submitting-drivers.rst <submittingdrivers>` +和 :ref:`Documentation/transaltions/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` 也是所有内核开发人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制 -记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（ -尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 +记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档 +（尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 -不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 https://lwn.net/ -作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到： +不同的网站在各个细节层次上讨论内核开发。本文作者想谦虚地建议用 https://lwn.net/ +作为来源；有关许多特定内核主题的信息可以通过以下网址的 LWN 内核索引找到： - http://lwn.net/kernel/index/ + http://lwn.net/kernel/index/ 除此之外，内核开发人员的一个宝贵资源是： - https://kernelnewbies.org/ + https://kernelnewbies.org/ -当然，我们不应该忘记 https://kernel.org/ 这是内核发布信息的最终位置。 +当然，也不应该忘记 https://kernel.org/ ，这是内核发布信息的最终位置。 关于内核开发有很多书： - Linux设备驱动程序，第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman）。 - 在线：http://lwn.net/kernel/ldd3/ + 《Linux设备驱动程序》第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman） + 线上版本在 http://lwn.net/kernel/ldd3/ - Linux内核开发（Robert Love）。 + 《Linux内核设计与实现》（Robert Love） - 了解Linux内核（Daniel Bovet和Marco Cesati）。 + 《深入理解Linux内核》(Daniel Bovet和Marco Cesati） -然而，所有这些书都有一个共同的缺点：当它们上架时，它们往往有些过时，而且它们 -已经上架一段时间了。不过，在那里还可以找到相当多的好信息。 +然而，所有这些书都有一个共同的缺点：它们上架时就往往有些过时，而且已经上架 +一段时间了。不过，在那里还是可以找到相当多的好信息。 有关git的文档，请访问： - https://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - https://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 结论 ==== -祝贺所有通过这篇冗长的文件的人。希望它能够帮助您理解Linux内核是如何开发的， +祝贺所有通过这篇冗长的文档的人。希望它能够帮助您理解Linux内核是如何开发的， 以及您如何参与这个过程。 -最后，重要的是参与。任何开源软件项目都不超过其贡献者投入其中的总和。Linux内核 -的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它变得 -更好。内核是一个主要的例子，说明当成千上万的人为了一个共同的目标一起工作时， -可以做些什么。 +最后，重要的是参与。任何开源软件项目都不会超过其贡献者投入其中的总和。Linux +内核的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它 +变得更好。内核是一个最成功的例子，说明了当成千上万的人为了一个共同的目标一起 +工作时，可以做出什么。 -不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是，同样 +不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是同样 重要的是，Linux生态系统中的大多数其他参与者可以通过为内核做出贡献而受益。使 代码进入主线是提高代码质量、降低维护和分发成本、提高对内核开发方向的影响程度 -等的关键。这是一种人人都赢的局面。踢开你的编辑，来加入我们吧，你会非常受 -欢迎的。 +等的关键。这是一种共赢的局面。启动你的编辑器，来加入我们吧；你会非常受欢迎的。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 8051a7b322c5..39e9c88fbaa6 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -13,11 +13,11 @@ 与Linux 内核社区一起工作 ======================== -那么你想成为Linux内核开发人员？ 欢迎！ 不但从技术意义上讲有很多关于内核的知识 -需要学，而且了解我们社区的工作方式也很重要。 阅读这些文章可以让您以更轻松地, -麻烦最少的方式将更改合并到内核。 +你想成为Linux内核开发人员吗？欢迎之至！在学习许多关于内核的技术知识的同时， +了解我们社区的工作方式也很重要。阅读这些文档可以让您以更轻松的、麻烦更少的 +方式将更改合并到内核。 -以下是每位开发人员应阅读的基本指南。 +以下是每位开发人员都应阅读的基本指南： .. toctree:: :maxdepth: 1 @@ -47,7 +47,7 @@ management-style embargoed-hardware-issues -这些是一些总体技术指南，由于缺乏更好的地方，现在已经放在这里 +这些是一些总体性技术指南，由于不大好分类而放在这里： .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 7bb9d4165ed3..42f0635ca70a 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -62,12 +62,10 @@ CMAGIC 0x0111 user ``include/linux/ MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` PTY_MAGIC 0x5001 ``drivers/char/pty.c`` PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -79,14 +77,12 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 50386e0e42e7..a64858d321fc 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -82,24 +82,22 @@ Linux内核补丁提交清单 请参阅 ``Documentation/ABI/README`` 。更改用户空间接口的补丁应该抄送 linux-api@vger.kernel.org。 -20) 检查是否全部通过 ``make headers_check`` 。 - -21) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` +20) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 如果新代码是实质性的，那么添加子系统特定的故障注入可能是合适的。 -22) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +21) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大量噪声，但对于查找诸如“警告：有符号和无符号之间的比较”之类的错误 很有用。 -23) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 +22) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 及VM、VFS和其他子系统中的各种更改一起工作。 -24) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 +23) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 释来解释它们正在执行的操作及其原因的逻辑。 -25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +24) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` -26) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 +25) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况 下测试以下多个构建[并非所有这些都同时存在，只是它们的各种/随机组合]： diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/riscv/boot-image-header.rst new file mode 100644 index 000000000000..241bf9c1bcbe --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/boot-image-header.rst @@ -0,0 +1,67 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/boot-image-header` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_boot-image-header.rst: + + +========================== +RISC-V Linux启动镜像文件头 +========================== + +:Author: Atish Patra <atish.patra@wdc.com> +:Date: 20 May 2019 + +此文档仅描述RISC-V Linux 启动文件头的详情。 + +TODO: + 写一个完整的启动指南。 + +在解压后的Linux内核镜像中存在以下64字节的文件头:: + + u32 code0; /* Executable code */ + u32 code1; /* Executable code */ + u64 text_offset; /* Image load offset, little endian */ + u64 image_size; /* Effective Image size, little endian */ + u64 flags; /* kernel flags, little endian */ + u32 version; /* Version of this header */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ + u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ + u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ + u32 res3; /* Reserved for PE COFF offset */ + +这种头格式与PE/COFF文件头兼容，并在很大程度上受到ARM64文件头的启发。因此，ARM64 +和RISC-V文件头可以在未来合并为一个共同的头。 + +注意 +==== + +- 将来也可以复用这个文件头，用来对RISC-V的EFI桩提供支持。为了使内核镜像如同一个 + EFI应用程序一样加载，EFI规范中规定在内核镜像的开始需要PE/COFF镜像文件头。为了 + 支持EFI桩，应该用“MZ”魔术字符替换掉code0，并且res3（偏移量未0x3c）应指向PE/COFF + 文件头的其余部分. + +- 表示文件头版本号的Drop-bit位域 + + ========== ========== + Bits 0:15 次要 版本 + Bits 16:31 主要 版本 + ========== ========== + + 这保持了新旧版本之间的兼容性。 + 当前版本被定义为0.2。 + +- 从版本0.2开始，结构体成员“magic”就已经被弃用，在之后的版本中，可能会移除掉它。 + 最初，该成员应该与ARM64头的“magic”成员匹配，但遗憾的是并没有。 + “magic2”成员代替“magic”成员与ARM64头相匹配。 + +- 在当前的文件头，标志位域只剩下了一个位。 + + ===== ============================== + Bit 0 内核字节序。1 if BE, 0 if LE. + ===== ============================== + +- 对于引导加载程序加载内核映像来说，image_size成员对引导加载程序而言是必须的，否 + 则将引导失败。 diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst new file mode 100644 index 000000000000..db13b1101490 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_index: + + +=============== +RISC-V 体系结构 +=============== + +.. toctree:: + :maxdepth: 1 + + boot-image-header + pmu + patch-acceptance + + +.. only:: subproject and html + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst new file mode 100644 index 000000000000..9fd1c8216763 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/patch-acceptance` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_patch-acceptance: + + +arch/riscv 开发者维护指南 +========================= + +概述 +---- +RISC-V指令集体系结构是公开开发的： +正在进行的草案可供所有人查看和测试实现。新模块或者扩展草案可能会在开发过程中发 +生更改---有时以不兼容的方式对以前的草案进行更改。这种灵活性可能会给RISC-V Linux +维护者带来挑战。Linux开发过程更喜欢经过良好检查和测试的代码，而不是试验代码。我 +们希望推广同样的规则到即将被内核合并的RISC-V相关代码。 + +附加的提交检查单 +---------------- +我们仅接受相关标准已经被RISC-V基金会标准为“已批准”或“已冻结”的扩展或模块的补丁。 +（开发者当然可以维护自己的Linux内核树，其中包含所需代码扩展草案的代码。） + +此外，RISC-V规范允许爱好者创建自己的自定义扩展。这些自定义拓展不需要通过RISC-V +基金会的任何审核或批准。为了避免将爱好者一些特别的RISC-V拓展添加进内核代码带来 +的维护复杂性和对性能的潜在影响，我们将只接受RISC-V基金会正式冻结或批准的的扩展 +补丁。（开发者当然可以维护自己的Linux内核树，其中包含他们想要的任何自定义扩展 +的代码。） diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst new file mode 100644 index 000000000000..22dcf3a9ca6e --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/pmu.rst @@ -0,0 +1,233 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/pmu` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_pmu: + + +======================== +RISC-V平台上对PMUs的支持 +======================== + +Alan Kao <alankao@andestech.com>, Mar 2018 + +简介 +------------ + +截止本文撰写时，在The RISC-V ISA Privileged Version 1.10中提到的 perf_event +相关特性如下: +（详情请查阅手册） + +* [m|s]counteren +* mcycle[h], cycle[h] +* minstret[h], instret[h] +* mhpeventx, mhpcounterx[h] + +仅有以上这些功能，移植perf需要做很多工作，究其原因是缺少以下通用架构的性能 +监测特性: + +* 启用/停用计数器 + 在我们这里，计数器一直在自由运行。 +* 计数器溢出引起的中断 + 规范中没有这种功能。 +* 中断指示器 + 不可能所有的计数器都有很多的中断端口，所以需要一个中断指示器让软件来判断 + 哪个计数器刚好溢出。 +* 写入计数器 + 由于内核不能修改计数器，所以会有一个SBI来支持这个功能[1]。 另外，一些厂商 + 考虑实现M-S-U型号机器的硬件扩展来直接写入计数器。 + +这篇文档旨在为开发者提供一个在内核中支持PMU的简要指南。下面的章节简要解释了 +perf' 机制和待办事项。 + +你可以在这里查看以前的讨论[1][2]。 另外，查看附录中的相关内核结构体可能会有 +帮助。 + + +1. 初始化 +--------- + +*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针，它包含了根据perf内部 +约定的各种方法和PMU-specific参数。人们应该声明这样的实例来代表PMU。 默认情况 +下， *riscv_pmu* 指向一个常量结构体 *riscv_base_pmu* ，它对基准QEMU模型有非常 +基础的支持。 + + +然后他/她可以将实例的指针分配给 *riscv_pmu* ，这样就可以利用已经实现的最小逻 +辑，或者创建他/她自己的 *riscv_init_platform_pmu* 实现。 + +换句话说，现有的 *riscv_base_pmu* 源只是提供了一个参考实现。 开发者可以灵活地 +决定多少部分可用，在最极端的情况下，他们可以根据自己的需要定制每一个函数。 + + +2. Event Initialization +----------------------- + +当用户启动perf命令来监控一些事件时，首先会被用户空间的perf工具解释为多个 +*perf_event_open* 系统调用，然后进一步调用上一步分配的 *event_init* 成员函数 +的主体。 在 *riscv_base_pmu* 的情况下，就是 *riscv_event_init* 。 + +该功能的主要目的是将用户提供的事件翻译成映射图，从而可以直接对HW-related的控 +制寄存器或计数器进行操作。该翻译基于 *riscv_pmu* 中提供的映射和方法。 + +注意，有些功能也可以在这个阶段完成: + +(1) 中断设置，这个在下一节说； +(2) 特限级设置(仅用户空间、仅内核空间、两者都有)； +(3) 析构函数设置。 通常应用 *riscv_destroy_event* 即可； +(4) 对非采样事件的调整，这将被函数应用，如 *perf_adjust_period* ，通常如下:: + + if (!is_sampling_event(event)) { + hwc->sample_period = x86_pmu.max_period; + hwc->last_period = hwc->sample_period; + local64_set(&hwc->period_left, hwc->sample_period); + } + + +在 *riscv_base_pmu* 的情况下，目前只提供了（3）。 + + +3. 中断 +------- + +3.1. 中断初始化 + +这种情况经常出现在 *event_init* 方案的开头。通常情况下，这应该是一个代码段，如:: + + int x86_reserve_hardware(void) + { + int err = 0; + + if (!atomic_inc_not_zero(&pmc_refcount)) { + mutex_lock(&pmc_reserve_mutex); + if (atomic_read(&pmc_refcount) == 0) { + if (!reserve_pmc_hardware()) + err = -EBUSY; + else + reserve_ds_buffers(); + } + if (!err) + atomic_inc(&pmc_refcount); + mutex_unlock(&pmc_reserve_mutex); + } + + return err; + } + +而神奇的是 *reserve_pmc_hardware* ，它通常做原子操作，使实现的IRQ可以从某个全局函 +数指针访问。 而 *release_pmc_hardware* 的作用正好相反，它用在上一节提到的事件分配 +器中。 + + (注：从所有架构的实现来看，*reserve/release* 对总是IRQ设置，所以 *pmc_hardware* + 似乎有些误导。 它并不处理事件和物理计数器之间的绑定，这一点将在下一节介绍。) + +3.2. IRQ结构体 + +基本上，一个IRQ运行以下伪代码:: + + for each hardware counter that triggered this overflow + + get the event of this counter + + // following two steps are defined as *read()*, + // check the section Reading/Writing Counters for details. + count the delta value since previous interrupt + update the event->count (# event occurs) by adding delta, and + event->hw.period_left by subtracting delta + + if the event overflows + sample data + set the counter appropriately for the next overflow + + if the event overflows again + too frequently, throttle this event + fi + fi + + end for + + 然而截至目前，没有一个RISC-V的实现为perf设计了中断，所以具体的实现要在未来完成。 + +4. Reading/Writing 计数 +----------------------- + +它们看似差不多，但perf对待它们的态度却截然不同。 对于读，在 *struct pmu* 中有一个 +*read* 接口，但它的作用不仅仅是读。 根据上下文，*read* 函数不仅要读取计数器的内容 +（event->count），还要更新左周期到下一个中断（event->hw.period_left）。 + + 但 perf 的核心不需要直接写计数器。 写计数器隐藏在以下两点的抽象化之后， + 1） *pmu->start* ，从字面上看就是开始计数，所以必须把计数器设置成一个合适的值，以 + 便下一次中断； + 2）在IRQ里面，应该把计数器设置成同样的合理值。 + +在RISC-V中，读操作不是问题，但写操作就需要费些力气了，因为S模式不允许写计数器。 + + +5. add()/del()/start()/stop() +----------------------------- + +基本思想: add()/del() 向PMU添加/删除事件，start()/stop() 启动/停止PMU中某个事件 +的计数器。 所有这些函数都使用相同的参数: *struct perf_event *event* 和 *int flag* 。 + +把 perf 看作一个状态机，那么你会发现这些函数作为这些状态之间的状态转换过程。 +定义了三种状态（event->hw.state）: + +* PERF_HES_STOPPED: 计数停止 +* PERF_HES_UPTODATE: event->count是最新的 +* PERF_HES_ARCH: 依赖于体系结构的用法，。。。我们现在并不需要它。 + +这些状态转换的正常流程如下: + +* 用户启动一个 perf 事件，导致调用 *event_init* 。 +* 当被上下文切换进来的时候，*add* 会被 perf core 调用，并带有一个标志 PERF_EF_START， + 也就是说事件被添加后应该被启动。 在这个阶段，如果有的话，一般事件会被绑定到一个物 + 理计数器上。当状态变为PERF_HES_STOPPED和PERF_HES_UPTODATE，因为现在已经停止了, + （软件）事件计数不需要更新。 + + - 然后调用 *start* ，并启用计数器。 + 通过PERF_EF_RELOAD标志，它向计数器写入一个适当的值（详细情况请参考上一节）。 + 如果标志不包含PERF_EF_RELOAD，则不会写入任何内容。 + 现在状态被重置为none，因为它既没有停止也没有更新（计数已经开始）。 + +*当被上下文切换出来时被调用。 然后，它检查出PMU中的所有事件，并调用 *stop* 来更新它们 + 的计数。 + + - *stop* 被 *del* 和perf核心调用，标志为PERF_EF_UPDATE，它经常以相同的逻辑和 *read* + 共用同一个子程序。 + 状态又一次变为PERF_HES_STOPPED和PERF_HES_UPTODATE。 + + - 这两对程序的生命周期: *add* 和 *del* 在任务切换时被反复调用；*start* 和 *stop* 在 + perf核心需要快速停止和启动时也会被调用，比如在调整中断周期时。 + +目前的实现已经足够了，将来可以很容易地扩展到功能。 + +A. 相关结构体 +------------- + +* struct pmu: include/linux/perf_event.h +* struct riscv_pmu: arch/riscv/include/asm/perf_event.h + + 两个结构体都被设计为只读。 + + *struct pmu* 定义了一些函数指针接口，它们大多以 *struct perf_event* 作为主参数，根据 + perf的内部状态机处理perf事件（详情请查看kernel/events/core.c）。 + + *struct riscv_pmu* 定义了PMU的具体参数。 命名遵循所有其它架构的惯例。 + +* struct perf_event: include/linux/perf_event.h +* struct hw_perf_event + + 表示 perf 事件的通用结构体，以及硬件相关的细节。 + +* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h + + 保存事件状态的结构有两个固定成员。 + 事件的数量和事件的数组。 + +参考文献 +-------- + +[1] https://github.com/riscv/riscv-linux/pull/124 + +[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA diff --git a/Documentation/translations/zh_CN/sound/hd-audio/controls.rst b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst new file mode 100644 index 000000000000..54c028ab9a40 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Chinese translator: Huang Jianghui <huangjianghui@uniontech.com> +--------------------------------------------------------------------- +.. include:: ../../disclaimer-zh_CN.rst +以下为正文 +--------------------------------------------------------------------- +====================================== +高清音频编解码器特定混音器控件 +====================================== + + +此文件解释特定于编解码器的混音器控件. + +瑞昱编解码器 +------------ + +声道模式 + 这是一个用于更改环绕声道设置的枚举控件,仅在环绕声道打开时显示出现。 + 它给出要使用的通道数:"2ch","4ch","6ch"，和"8ch"。根据配置，这还控 + 制多I/O插孔的插孔重分配。 + +自动静音模式 + 这是一个枚举控件，用于更改耳机和线路输出插孔的自动静音行为。如果内 + 置扬声器、耳机和/或线路输出插孔在机器上可用，则显示该控件。当只有 + 耳机或者线路输出的时候，它给出”禁用“和”启用“状态。当启用后，插孔插 + 入后扬声器会自动静音。 + + 当耳机和线路输出插孔都存在时，它给出”禁用“、”仅扬声器“和”线路输出+扬 + 声器“。当”仅扬声器“被选择，插入耳机或者线路输出插孔可使扬声器静音， + 但不会使线路输出静音。当线路输出+扬声器被选择，插入耳机插孔会同时使扬 + 声器和线路输出静音。 + + +矽玛特编解码器 +-------------- + +模拟环回 + 此控件启用/禁用模拟环回电路。只有在编解码器提示中将”lookback“设置为真 + 时才会出现(见HD-Audio.txt)。请注意，在某些编解码器上，模拟环回和正常 + PCM播放是独占的,即当此选项打开时，您将听不到任何PCM流。 + +交换中置/低频 + 交换中置和低频通道顺序，通常情况下，左侧对应中置，右侧对应低频,启动此 + 项后，左边低频，右边中置。 + +耳机作为线路输出 + 当此控制开启时，将耳机视为线路输出插孔。也就是说，耳机不会自动静音其他 + 线路输出，没有耳机放大器被设置到引脚上。 + +麦克风插口模式、线路插孔模式等 + 这些枚举控制输入插孔引脚的方向和偏置。根据插孔类型，它可以设置为”麦克风 + 输入“和”线路输入“以确定输入偏置,或者当引脚是环绕声道的多I/O插孔时，它 + 可以设置为”线路输出“。 + + +威盛编解码器 +------------ + +智能5.1 + 一个枚举控件，用于为环绕输出重新分配多个I/O插孔的任务。当它打开时，相应 + 的输入插孔（通常是线路输入和麦克风输入）被切换为环绕和中央低频输出插孔。 + +独立耳机 + 启用此枚举控制时，耳机输出从单个流（第三个PCM，如hw:0,2）而不是主流路由。 + 如果耳机DAC与侧边或中央低频通道DAC共享，则DAC将自动切换到耳机。 + +环回混合 + 一个用于确定是否启动了模拟环回路由的枚举控件。当它启用后，模拟环回路由到 + 前置通道。同样，耳机与扬声器输出也采用相同的路径。作为一个副作用，当设置 + 此模式后，单个音量控制将不再适用于耳机和扬声器，因为只有一个DAC连接到混 + 音器小部件。 + +动态电源控制 + 此控件决定是否启动每个插孔的动态电源控制检测。启用时，根据插孔的插入情况 + 动态更改组件的电源状态（D0/D3）以节省电量消耗。但是，如果您的系统没有提 + 供正确的插孔检测，这将无法工作;在这种情况下，请关闭此控件。 + +插孔检测 + 此控件仅为VT1708编解码器提供，它不会为每个插孔插拔提供适当的未请求事件。 + 当此控件打开，驱动将轮询插孔检测，以便耳机自动静音可以工作，而关闭此控 + 件将降低功耗。 + + +科胜讯编解码器 +-------------- + +自动静音模式 + 见瑞昱解码器 + + + +模拟编解码器 +------------ + +通道模式 + 这是一个用于更改环绕声道设置的枚举控件,仅在环绕声道可用时显示。它提供了能 + 被使用的通道数:”2ch“、”4ch“和”6ch“。根据配置，这还控制多I/O插孔的插孔重 + 分配。 + +独立耳机 + 启动此枚举控制后，耳机输出从单个流（第三个PCM，如hw:0,2）而不是主流路由。 diff --git a/Documentation/translations/zh_CN/sound/hd-audio/index.rst b/Documentation/translations/zh_CN/sound/hd-audio/index.rst new file mode 100644 index 000000000000..d9885d53b069 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../sound/hd-audio/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +高清音频 +======== + +.. toctree:: + :maxdepth: 2 + + controls diff --git a/Documentation/translations/zh_CN/sound/index.rst b/Documentation/translations/zh_CN/sound/index.rst new file mode 100644 index 000000000000..28d5dca34a63 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../sound/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +==================== +Linux 声音子系统文档 +==================== + +.. toctree:: + :maxdepth: 2 + + hd-audio/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/usb/gadget_configfs.rst b/Documentation/usb/gadget_configfs.rst index 158e48dab586..e4566ffb223f 100644 --- a/Documentation/usb/gadget_configfs.rst +++ b/Documentation/usb/gadget_configfs.rst @@ -140,7 +140,7 @@ is an arbitrary string allowed in a filesystem, e.g.:: Each function provides its specific set of attributes, with either read-only or read-write access. Where applicable they need to be written to as appropriate. -Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. +Please refer to Documentation/ABI/testing/configfs-usb-gadget for more information. 4. Associating the functions with their configurations ------------------------------------------------------ diff --git a/Documentation/usb/mtouchusb.rst b/Documentation/usb/mtouchusb.rst index d1111b74bf75..5ae1f74fe74b 100644 --- a/Documentation/usb/mtouchusb.rst +++ b/Documentation/usb/mtouchusb.rst @@ -1,4 +1,4 @@ -================ +================ mtouchusb driver ================ diff --git a/Documentation/usb/usb-serial.rst b/Documentation/usb/usb-serial.rst index 8fa7dbd3da9a..69586aeb60bb 100644 --- a/Documentation/usb/usb-serial.rst +++ b/Documentation/usb/usb-serial.rst @@ -1,4 +1,4 @@ -========== +========== USB serial ========== diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst index 988c832166cd..0b8541fda4d8 100644 --- a/Documentation/usb/usbip_protocol.rst +++ b/Documentation/usb/usbip_protocol.rst @@ -2,15 +2,15 @@ USB/IP protocol =============== -PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! -28 Jun 2011 +Architecture +============ The USB/IP protocol follows a server/client architecture. The server exports the -USB devices and the clients imports them. The device driver for the exported +USB devices and the clients import them. The device driver for the exported USB device runs on the client machine. The client may ask for the list of the exported USB devices. To get the list the -client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST +client opens a TCP/IP connection to the server, and sends an OP_REQ_DEVLIST packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent in one or more pieces at the low level transport layer). The server sends back the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the @@ -30,7 +30,7 @@ TCP/IP connection is closed. | | Once the client knows the list of exported USB devices it may decide to use one -of them. First the client opens a TCP/IP connection towards the server and +of them. First the client opens a TCP/IP connection to the server and sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the import was successful the TCP/IP connection remains open and will be used to transfer the URB traffic between the client and the server. The client may @@ -84,17 +84,61 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. | <---------------------------------------------- | | . | | : | + +For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB +submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in +function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c). + +:: + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | USBIP_CMD_SUBMIT(seqnum = p) | + | ----------------------------------------------> | | | | USBIP_CMD_UNLINK | + | (seqnum = p+1, unlink_seqnum = p) | | ----------------------------------------------> | | | | USBIP_RET_UNLINK | + | (seqnum = p+1, status = -ECONNRESET) | + | <---------------------------------------------- | + | | + | Note: No USBIP_RET_SUBMIT(seqnum = p) | + | <--X---X---X---X---X---X---X---X---X---X---X--- | + | . | + | : | + | | + | USBIP_CMD_SUBMIT(seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = q) | + | <---------------------------------------------- | + | | + | USBIP_CMD_UNLINK | + | (seqnum = q+1, unlink_seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | (seqnum = q+1, status = 0) | | <---------------------------------------------- | | | The fields are in network (big endian) byte order meaning that the most significant byte (MSB) is stored at the lowest address. +Protocol Version +================ + +The documented USBIP version is v1.1.1. The binary representation of this +version in message headers is 0x0111. + +This is defined in tools/usb/usbip/configure.ac + +Message Format +============== OP_REQ_DEVLIST: Retrieve the list of exported USB devices. @@ -102,7 +146,7 @@ OP_REQ_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | | | | | devices. | @@ -116,7 +160,7 @@ OP_REP_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | +-----------+--------+------------+---------------------------------------------------+ @@ -165,8 +209,8 @@ OP_REP_DEVLIST: | 0x143 | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ | 0x144 | | m_0 | From now on each interface is described, all | -| | | | together bNumInterfaces times, with the | -| | | | the following 4 fields: | +| | | | together bNumInterfaces times, with the following | +| | | | 4 fields: | +-----------+--------+------------+---------------------------------------------------+ | | 1 | | bInterfaceClass | +-----------+--------+------------+---------------------------------------------------+ @@ -177,7 +221,7 @@ OP_REP_DEVLIST: | 0x147 | 1 | | padding byte for alignment, shall be set to zero | +-----------+--------+------------+---------------------------------------------------+ | 0xC + | | | The second exported USB device starts at i=1 | -| i*0x138 + | | | with the busid field. | +| i*0x138 + | | | with the path field. | | m_(i-1)*4 | | | | +-----------+--------+------------+---------------------------------------------------+ @@ -187,7 +231,7 @@ OP_REQ_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8003 | Command code: import a remote USB device. | +-----------+--------+------------+---------------------------------------------------+ @@ -206,7 +250,7 @@ OP_REP_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0003 | Reply code: Reply to import. | +-----------+--------+------------+---------------------------------------------------+ @@ -254,158 +298,156 @@ OP_REP_IMPORT: | 0x13E | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ -USBIP_CMD_SUBMIT: - Submit an URB +The following four commands have a common basic header called +'usbip_header_basic', and their headers, called 'usbip_header' (before +transfer_buffer payload), have the same length, therefore paddings are needed. -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000001 | command: Submit an URB | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: the sequence number of the URB to submit | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | transfer_flags: possible values depend on the | -| | | | URB transfer type, see below | -+-----------+--------+------------+---------------------------------------------------+ -| 0x18 | 4 | | transfer_buffer_length | -+-----------+--------+------------+---------------------------------------------------+ -| 0x1C | 4 | | start_frame: specify the selected frame to | -| | | | transmit an ISO frame, ignored if URB_ISO_ASAP | -| | | | is specified at transfer_flags | -+-----------+--------+------------+---------------------------------------------------+ -| 0x20 | 4 | | number_of_packets: number of ISO packets | -+-----------+--------+------------+---------------------------------------------------+ -| 0x24 | 4 | | interval: maximum time for the request on the | -| | | | server-side host controller | -+-----------+--------+------------+---------------------------------------------------+ -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | -| | | | zeros if not used | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | | | URB data. For ISO transfers the padding between | -| | | | each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ +usbip_header_basic: ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 4 | command | ++-----------+--------+---------------------------------------------------+ +| 4 | 4 | seqnum: sequential number that identifies requests| +| | | and corresponding responses; | +| | | incremented per connection | ++-----------+--------+---------------------------------------------------+ +| 8 | 4 | devid: specifies a remote USB device uniquely | +| | | instead of busnum and devnum; | +| | | for client (request), this value is | +| | | ((busnum << 16) | devnum); | +| | | for server (response), this shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0xC | 4 | direction: | +| | | | +| | | - 0: USBIP_DIR_OUT | +| | | - 1: USBIP_DIR_IN | +| | | | +| | | only used by client, for server this shall be 0 | ++-----------+--------+---------------------------------------------------+ +| 0x10 | 4 | ep: endpoint number | +| | | only used by client, for server this shall be 0; | +| | | for UNLINK, this shall be 0 | ++-----------+--------+---------------------------------------------------+ - +-------------------------+------------+---------+-----------+----------+-------------+ - | Allowed transfer_flags | value | control | interrupt | bulk | isochronous | - +=========================+============+=========+===========+==========+=============+ - | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_ISO_ASAP | 0x00000002 | no | no | no | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ - | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes | - +-------------------------+------------+---------+-----------+----------+-------------+ +USBIP_CMD_SUBMIT: + Submit an URB ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | transfer_flags: possible values depend on the | +| | | URB transfer_flags (refer to URB doc in | +| | | Documentation/driver-api/usb/URB.rst) | +| | | but with URB_NO_TRANSFER_DMA_MAP masked. Refer to | +| | | function usbip_pack_cmd_submit and function | +| | | tweak_transfer_flags in drivers/usb/usbip/ | +| | | usbip_common.c. The following fields may also ref | +| | | to function usbip_pack_cmd_submit and URB doc | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | transfer_buffer_length: | +| | | use URB transfer_buffer_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x24 | 4 | interval: maximum time for the request on the | +| | | server-side host controller | ++-----------+--------+---------------------------------------------------+ +| 0x28 | 8 | setup: data bytes for USB setup, filled with | +| | | zeros if not used. | ++-----------+--------+---------------------------------------------------+ +| 0x30 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_OUT then n equals | +| | | transfer_buffer_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ USBIP_RET_SUBMIT: Reply for submitting an URB -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000003 | command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: URB sequence number | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | status: zero for successful URB transaction, | -| | | | otherwise some kind of error happened. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x18 | 4 | n | actual_length: number of URB data bytes | -+-----------+--------+------------+---------------------------------------------------+ -| 0x1C | 4 | | start_frame: for an ISO frame the actually | -| | | | selected frame for transmit. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x20 | 4 | | number_of_packets | -+-----------+--------+------------+---------------------------------------------------+ -| 0x24 | 4 | | error_count | -+-----------+--------+------------+---------------------------------------------------+ -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | -| | | | zeros if not used | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000003 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: zero for successful URB transaction, | +| | | otherwise some kind of error happened. | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | actual_length: number of URB data bytes; | +| | | use URB actual_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x24 | 4 | error_count | ++-----------+--------+---------------------------------------------------+ +| 0x28 | 8 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0x30 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_IN then n equals | +| | | actual_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ USBIP_CMD_UNLINK: Unlink an URB -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000002 | command: URB unlink command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: URB sequence number to unlink: | -| | | | | -| | | | FIXME: | -| | | | is this so? | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number: zero | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | seqnum: the URB sequence number given previously | -| | | | at USBIP_CMD_SUBMIT.seqnum field | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ USBIP_RET_UNLINK: Reply for URB unlink -+-----------+--------+------------+---------------------------------------------------+ -| Offset | Length | Value | Description | -+===========+========+============+===================================================+ -| 0 | 4 | 0x00000004 | command: reply for the URB unlink command | -+-----------+--------+------------+---------------------------------------------------+ -| 4 | 4 | | seqnum: the unlinked URB sequence number | -+-----------+--------+------------+---------------------------------------------------+ -| 8 | 4 | | devid | -+-----------+--------+------------+---------------------------------------------------+ -| 0xC | 4 | | direction: | -| | | | | -| | | | - 0: USBIP_DIR_OUT | -| | | | - 1: USBIP_DIR_IN | -+-----------+--------+------------+---------------------------------------------------+ -| 0x10 | 4 | | ep: endpoint number | -+-----------+--------+------------+---------------------------------------------------+ -| 0x14 | 4 | | status: This is the value contained in the | -| | | | urb->status in the URB completition handler. | -| | | | | -| | | | FIXME: | -| | | | a better explanation needed. | -+-----------+--------+------------+---------------------------------------------------+ -| 0x30 | n | | URB data bytes. For ISO transfers the padding | -| | | | between each ISO packets is not transmitted. | -+-----------+--------+------------+---------------------------------------------------+ ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: This is similar to the status of | +| | | USBIP_RET_SUBMIT (share the same memory offset). | +| | | When UNLINK is successful, status is -ECONNRESET; | +| | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT | +| | | status is 0 | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ + +EXAMPLE +======= + + The following data is captured from wire with Human Interface Devices (HID) + payload + +:: + + CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000 + CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000 + ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000 diff --git a/Documentation/userspace-api/ebpf/index.rst b/Documentation/userspace-api/ebpf/index.rst new file mode 100644 index 000000000000..473dfba78116 --- /dev/null +++ b/Documentation/userspace-api/ebpf/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Userspace API +================== + +eBPF is a kernel mechanism to provide a sandboxed runtime environment in the +Linux kernel for runtime extension and instrumentation without changing kernel +source code or loading kernel modules. eBPF programs can be attached to various +kernel subsystems, including networking, tracing and Linux security modules +(LSM). + +For internal kernel documentation on eBPF, see Documentation/bpf/index.rst. + +.. toctree:: + :maxdepth: 1 + + syscall diff --git a/Documentation/userspace-api/ebpf/syscall.rst b/Documentation/userspace-api/ebpf/syscall.rst new file mode 100644 index 000000000000..ea9918084221 --- /dev/null +++ b/Documentation/userspace-api/ebpf/syscall.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Syscall +------------ + +:Authors: - Alexei Starovoitov <ast@kernel.org> + - Joe Stringer <joe@wand.net.nz> + - Michael Kerrisk <mtk.manpages@gmail.com> + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. + +bpf() subcommand reference +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Preamble + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Commands + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index d29b020e5622..0b5eefed027e 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -18,9 +18,11 @@ place where this information is gathered. no_new_privs seccomp_filter + landlock unshare spec_ctrl accelerators/ocxl + ebpf/index ioctl/index iommu media/index diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 599bd4493944..9bfc2b510c64 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -209,7 +209,6 @@ Code Seq# Include File Comments linux/fs.h, 'X' all fs/ocfs2/ocfs_fs.h conflict! 'X' 01 linux/pktcdvd.h conflict! -'Y' all linux/cyclades.h 'Z' 14-15 drivers/message/fusion/mptctl.h '[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices <mailto:gregkh@linuxfoundation.org> @@ -245,6 +244,7 @@ Code Seq# Include File Comments 'i' 00-3F linux/i2o-dev.h conflict! 'i' 0B-1F linux/ipmi.h conflict! 'i' 80-8F linux/i8k.h +'i' 90-9F `linux/iio/*.h` IIO 'j' 00-3F linux/joystick.h 'k' 00-0F linux/spi/spidev.h conflict! 'k' 00-05 video/kyro.h conflict! @@ -327,6 +327,8 @@ Code Seq# Include File Comments 0xA4 00-1F uapi/asm/sgx.h <mailto:linux-sgx@vger.kernel.org> 0xA5 01 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator <mailto:luzmaximilian@gmail.com> +0xA5 20-2F linux/surface_aggregator/dtx.h Microsoft Surface DTX driver + <mailto:luzmaximilian@gmail.com> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h @@ -347,6 +349,7 @@ Code Seq# Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xB6 all linux/fpga-dfl.h 0xB7 all uapi/linux/remoteproc_cdev.h <mailto:linux-remoteproc@vger.kernel.org> +0xB7 all uapi/linux/nsfs.h <mailto:Andrei Vagin <avagin@openvz.org>> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h 0xCA 10-2F uapi/misc/ocxl.h diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst new file mode 100644 index 000000000000..62c9361a3c7f --- /dev/null +++ b/Documentation/userspace-api/landlock.rst @@ -0,0 +1,311 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> +.. Copyright © 2019-2020 ANSSI +.. Copyright © 2021 Microsoft Corporation + +===================================== +Landlock: unprivileged access control +===================================== + +:Author: Mickaël Salaün +:Date: March 2021 + +The goal of Landlock is to enable to restrict ambient rights (e.g. global +filesystem access) for a set of processes. Because Landlock is a stackable +LSM, it makes possible to create safe security sandboxes as new security layers +in addition to the existing system-wide access-controls. This kind of sandbox +is expected to help mitigate the security impact of bugs or +unexpected/malicious behaviors in user space applications. Landlock empowers +any process, including unprivileged ones, to securely restrict themselves. + +Landlock rules +============== + +A Landlock rule describes an action on an object. An object is currently a +file hierarchy, and the related filesystem actions are defined with `access +rights`_. A set of rules is aggregated in a ruleset, which can then restrict +the thread enforcing it, and its future children. + +Defining and enforcing a security policy +---------------------------------------- + +We first need to create the ruleset that will contain our rules. For this +example, the ruleset will contain rules that only allow read actions, but write +actions will be denied. The ruleset then needs to handle both of these kind of +actions. + +.. code-block:: c + + int ruleset_fd; + struct landlock_ruleset_attr ruleset_attr = { + .handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM, + }; + + ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); + if (ruleset_fd < 0) { + perror("Failed to create a ruleset"); + return 1; + } + +We can now add a new rule to this ruleset thanks to the returned file +descriptor referring to this ruleset. The rule will only allow reading the +file hierarchy ``/usr``. Without another rule, write actions would then be +denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the +``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file +descriptor. + +.. code-block:: c + + int err; + struct landlock_path_beneath_attr path_beneath = { + .allowed_access = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR, + }; + + path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); + if (path_beneath.parent_fd < 0) { + perror("Failed to open file"); + close(ruleset_fd); + return 1; + } + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, + &path_beneath, 0); + close(path_beneath.parent_fd); + if (err) { + perror("Failed to update ruleset"); + close(ruleset_fd); + return 1; + } + +We now have a ruleset with one rule allowing read access to ``/usr`` while +denying all other handled accesses for the filesystem. The next step is to +restrict the current thread from gaining more privileges (e.g. thanks to a SUID +binary). + +.. code-block:: c + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + return 1; + } + +The current thread is now ready to sandbox itself with the ruleset. + +.. code-block:: c + + if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + return 1; + } + close(ruleset_fd); + +If the `landlock_restrict_self` system call succeeds, the current thread is now +restricted and this policy will be enforced on all its subsequently created +children as well. Once a thread is landlocked, there is no way to remove its +security policy; only adding more restrictions is allowed. These threads are +now in a new Landlock domain, merge of their parent one (if any) with the new +ruleset. + +Full working code can be found in `samples/landlock/sandboxer.c`_. + +Layers of file path access rights +--------------------------------- + +Each time a thread enforces a ruleset on itself, it updates its Landlock domain +with a new layer of policy. Indeed, this complementary policy is stacked with +the potentially other rulesets already restricting this thread. A sandboxed +thread can then safely add more constraints to itself with a new enforced +ruleset. + +One policy layer grants access to a file path if at least one of its rules +encountered on the path grants the access. A sandboxed thread can only access +a file path if all its enforced policy layers grant the access as well as all +the other system access controls (e.g. filesystem DAC, other LSM policies, +etc.). + +Bind mounts and OverlayFS +------------------------- + +Landlock enables to restrict access to file hierarchies, which means that these +access rights can be propagated with bind mounts (cf. +:doc:`/filesystems/sharedsubtree`) but not with :doc:`/filesystems/overlayfs`. + +A bind mount mirrors a source file hierarchy to a destination. The destination +hierarchy is then composed of the exact same files, on which Landlock rules can +be tied, either via the source or the destination path. These rules restrict +access when they are encountered on a path, which means that they can restrict +access to multiple file hierarchies at the same time, whether these hierarchies +are the result of bind mounts or not. + +An OverlayFS mount point consists of upper and lower layers. These layers are +combined in a merge directory, result of the mount point. This merge hierarchy +may include files from the upper and lower layers, but modifications performed +on the merge hierarchy only reflects on the upper layer. From a Landlock +policy point of view, each OverlayFS layers and merge hierarchies are +standalone and contains their own set of files and directories, which is +different from bind mounts. A policy restricting an OverlayFS layer will not +restrict the resulted merged hierarchy, and vice versa. Landlock users should +then only think about file hierarchies they want to allow access to, regardless +of the underlying filesystem. + +Inheritance +----------- + +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain +restrictions from its parent. This is similar to the seccomp inheritance (cf. +:doc:`/userspace-api/seccomp_filter`) or any other LSM dealing with task's +:manpage:`credentials(7)`. For instance, one process's thread may apply +Landlock rules to itself, but they will not be automatically applied to other +sibling threads (unlike POSIX thread credential changes, cf. +:manpage:`nptl(7)`). + +When a thread sandboxes itself, we have the guarantee that the related security +policy will stay enforced on all this thread's descendants. This allows +creating standalone and modular security policies per application, which will +automatically be composed between themselves according to their runtime parent +policies. + +Ptrace restrictions +------------------- + +A sandboxed process has less privileges than a non-sandboxed process and must +then be subject to additional restrictions when manipulating another process. +To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target +process, a sandboxed process should have a subset of the target process rules, +which means the tracee must be in a sub-domain of the tracer. + +Kernel interface +================ + +Access rights +------------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: fs_access + +Creating a new ruleset +---------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_create_ruleset + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: landlock_ruleset_attr + +Extending a ruleset +------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_add_rule + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: landlock_rule_type landlock_path_beneath_attr + +Enforcing a ruleset +------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_restrict_self + +Current limitations +=================== + +File renaming and linking +------------------------- + +Because Landlock targets unprivileged access controls, it is needed to properly +handle composition of rules. Such property also implies rules nesting. +Properly handling multiple layers of ruleset, each one of them able to restrict +access to files, also implies to inherit the ruleset restrictions from a parent +to its hierarchy. Because files are identified and restricted by their +hierarchy, moving or linking a file from one directory to another implies to +propagate the hierarchy constraints. To protect against privilege escalations +through renaming or linking, and for the sake of simplicity, Landlock currently +limits linking and renaming to the same directory. Future Landlock evolutions +will enable more flexibility for renaming and linking, with dedicated ruleset +flags. + +Filesystem topology modification +-------------------------------- + +As for file renaming and linking, a sandboxed thread cannot modify its +filesystem topology, whether via :manpage:`mount(2)` or +:manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. + +Special filesystems +------------------- + +Access to regular files and directories can be restricted by Landlock, +according to the handled accesses of a ruleset. However, files that do not +come from a user-visible filesystem (e.g. pipe, socket), but can still be +accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly +restricted. Likewise, some special kernel filesystems such as nsfs, which can +be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly +restricted. However, thanks to the `ptrace restrictions`_, access to such +sensitive ``/proc`` files are automatically restricted according to domain +hierarchies. Future Landlock evolutions could still enable to explicitly +restrict such paths with dedicated ruleset flags. + +Ruleset layers +-------------- + +There is a limit of 64 layers of stacked rulesets. This can be an issue for a +task willing to enforce a new ruleset in complement to its 64 inherited +rulesets. Once this limit is reached, sys_landlock_restrict_self() returns +E2BIG. It is then strongly suggested to carefully build rulesets once in the +life of a thread, especially for applications able to launch other applications +that may also want to sandbox themselves (e.g. shells, container managers, +etc.). + +Memory usage +------------ + +Kernel memory allocated to create rulesets is accounted and can be restricted +by the :doc:`/admin-guide/cgroup-v1/memory`. + +Questions and answers +===================== + +What about user space sandbox managers? +--------------------------------------- + +Using user space process to enforce restrictions on kernel resources can lead +to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of +the OS code and state +<https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_). + +What about namespaces and containers? +------------------------------------- + +Namespaces can help create sandboxes but they are not designed for +access-control and then miss useful features for such use case (e.g. no +fine-grained restrictions). Moreover, their complexity can lead to security +issues, especially when untrusted processes can manipulate them (cf. +`Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_). + +Additional documentation +======================== + +* :doc:`/security/landlock` +* https://landlock.io + +.. Links +.. _samples/landlock/sandboxer.c: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst index c7309a2fcbce..d5e014ce19b5 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -35,7 +35,7 @@ device information, applications call the ioctl with a pointer to a struct :c:type:`cec_caps`. The driver fills the structure and returns the information to the application. The ioctl never fails. -.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.6cm}| .. c:type:: cec_caps @@ -63,7 +63,7 @@ returns the information to the application. The ioctl never fails. - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` macro. -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _cec-capabilities: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst index 13116b0b5c17..0e19855730e1 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst @@ -39,7 +39,7 @@ provide a pointer to a cec_connector_info struct which will be populated by the kernel with the info provided by the adapter's driver. This ioctl is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_connector_info @@ -59,7 +59,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. * - } - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _connector-type: @@ -82,7 +82,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. Information about the connector can be found in :ref:`cec-drm-connector-info`. -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. c:type:: cec_drm_connector_info diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst index c760c07b6b3f..f3293a589dd6 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst @@ -67,7 +67,7 @@ logical address types are already defined will return with error ``EBUSY``. .. c:type:: cec_log_addrs -.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}| .. cssclass:: longtable @@ -150,7 +150,7 @@ logical address types are already defined will return with error ``EBUSY``. give the CEC framework more information about the device type, even though the framework won't use it directly in the CEC message. -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-log-addrs-flags: @@ -186,7 +186,7 @@ logical address types are already defined will return with error ``EBUSY``. All other messages are ignored. -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-versions: @@ -211,7 +211,7 @@ logical address types are already defined will return with error ``EBUSY``. - 6 - CEC version according to the HDMI 2.0 standard. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-prim-dev-types: @@ -256,7 +256,7 @@ logical address types are already defined will return with error ``EBUSY``. - 7 - Use for a video processor device. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-log-addr-types: @@ -304,7 +304,7 @@ logical address types are already defined will return with error ``EBUSY``. Control). -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-all-dev-types-flags: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst index 736fda5ad73d..71d6a9e81f75 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst @@ -44,7 +44,7 @@ two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with the same state). In that case the intermediate state changes were lost but it is guaranteed that the state did change in between the two events. -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}| .. c:type:: cec_event_state_change @@ -74,7 +74,7 @@ it is guaranteed that the state did change in between the two events. .. c:type:: cec_event_lost_msgs -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| .. flat-table:: struct cec_event_lost_msgs :header-rows: 0 @@ -93,7 +93,7 @@ it is guaranteed that the state did change in between the two events. replied to within a second according to the CEC specification, this is more than enough. -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_event @@ -128,7 +128,7 @@ it is guaranteed that the state did change in between the two events. * - } - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-events: @@ -201,7 +201,7 @@ it is guaranteed that the state did change in between the two events. if the 5V is high, then an initial event will be generated for that filehandle. -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}| .. _cec-event-flags: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst index 663bdef8d6da..5fe105a13a6e 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -72,7 +72,7 @@ always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. Available initiator modes are: -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-mode-initiator_e: @@ -106,7 +106,7 @@ Available initiator modes are: Available follower modes are: -.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| +.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}| .. _cec-mode-follower_e: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index b2fc051e99f4..bd7f7e7235cb 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -84,7 +84,7 @@ physical address, but the cable is still connected and CEC still works. In order to detect/wake up the device it is allowed to send poll and 'Image/Text View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). -.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8cm}| .. c:type:: cec_msg @@ -196,7 +196,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). supports this, otherwise it is always 0. This counter is only valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. -.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| +.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1cm}| .. _cec-msg-flags: @@ -229,7 +229,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). capability. If that is not set, then the ``EPERM`` error code is returned. -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-tx-status: @@ -298,7 +298,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The transmit timed out. This should not normally happen and this indicates a driver problem. -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-rx-status: diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index 064c8c5a1943..b0efce40471f 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -44,7 +44,7 @@ error injection status:: # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message - # <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost + # any[,<mode>] rx-arb-lost [<poll>] generate a POLL message to trigger an arbitration lost # # TX error injection settings: # tx-ignore-nack-until-eom ignore early NACKs until EOM diff --git a/Documentation/userspace-api/media/dvb/fe-type-t.rst b/Documentation/userspace-api/media/dvb/fe-type-t.rst index e8499d482700..e8986254897f 100644 --- a/Documentation/userspace-api/media/dvb/fe-type-t.rst +++ b/Documentation/userspace-api/media/dvb/fe-type-t.rst @@ -11,7 +11,7 @@ fe_type_t type, defined as: .. c:type:: fe_type -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: Frontend types :header-rows: 1 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst index 0c4c5d2cfcb2..d56ee6669ab9 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst @@ -39,7 +39,7 @@ ioctl never fails. .. c:type:: media_device_info -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_device_info :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst index 92dd8ecd538c..73bda02498af 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst @@ -50,7 +50,7 @@ id's until they get an error. .. c:type:: media_entity_desc -.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| +.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}| .. flat-table:: struct media_entity_desc :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst index 3bc98a6a2ec5..381804a91c99 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst @@ -54,7 +54,7 @@ returned during the enumeration process. .. c:type:: media_links_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_links_enum :header-rows: 0 @@ -82,7 +82,7 @@ returned during the enumeration process. .. c:type:: media_pad_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_pad_desc :header-rows: 0 @@ -109,7 +109,7 @@ returned during the enumeration process. .. c:type:: media_link_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_link_desc :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst index 8f8b3b586edd..77ea5c5e9d7f 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst @@ -46,7 +46,7 @@ other values untouched. If the ``topology_version`` remains the same, the ioctl should fill the desired arrays with the media graph elements. -.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}| .. c:type:: media_v2_topology @@ -119,7 +119,7 @@ desired arrays with the media graph elements. converted to a 64-bits integer. It can be zero. if zero, the ioctl won't store the links. It will just update ``num_links`` -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_entity @@ -156,7 +156,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_interface @@ -189,7 +189,7 @@ desired arrays with the media graph elements. - Used only for device node interfaces. See :c:type:`media_v2_intf_devnode` for details. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_intf_devnode @@ -206,7 +206,7 @@ desired arrays with the media graph elements. - ``minor`` - Device node minor number. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_pad @@ -241,7 +241,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_link diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst index e1e4043b3b1c..0a26397bd01d 100644 --- a/Documentation/userspace-api/media/mediactl/media-types.rst +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -5,7 +5,7 @@ Types and flags used to represent the media graph elements ========================================================== -.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. _media-entity-functions: .. _MEDIA-ENT-F-UNKNOWN: @@ -251,7 +251,7 @@ Types and flags used to represent the media graph elements - The entity represents a connector. -.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| +.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{4.8cm}| .. _media-intf-type: .. _MEDIA-INTF-T-DVB-FE: diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index aafbfda1f401..28ed94088015 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -25,7 +25,7 @@ the remote via /dev/input/event devices. .. _rc_standard_keymap: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: IR default keymapping :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 1b0fdc160533..e991ba73d873 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -157,7 +157,7 @@ of appropriately sized buffers for each use case). struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| .. cssclass:: longtable @@ -314,7 +314,7 @@ struct v4l2_buffer struct v4l2_plane ================= -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| .. cssclass:: longtable @@ -389,7 +389,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -452,16 +452,16 @@ Buffer Flags .. raw:: latex - \small + \footnotesize -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| .. cssclass:: longtable .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 3 1 4 + :widths: 65 18 70 * .. _`V4L2-BUF-FLAG-MAPPED`: @@ -585,7 +585,7 @@ Buffer Flags - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is set. It is typically used with stateless decoders where multiple output buffers each decode to a slice of the decoded frame. Applications can set this flag when queueing the output buffer @@ -681,7 +681,7 @@ Buffer Flags enum v4l2_memory ================ -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| .. flat-table:: :header-rows: 0 @@ -715,7 +715,7 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| .. flat-table:: :header-rows: 0 @@ -751,8 +751,6 @@ struct v4l2_timecode Timecode Types -------------- -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -780,7 +778,7 @@ Timecode Types Timecode Flags -------------- -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 126f66482a0d..26a4ace42ca5 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -17,10 +17,6 @@ PAL and by SDTV in general. The default transfer function is range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 170M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -98,10 +94,6 @@ default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: Rec. 709 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -225,10 +217,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: sRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -308,9 +296,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: opRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -373,10 +358,6 @@ definition television (UHDTV). The default transfer function is ``V4L2_YCBCR_ENC_BT2020``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: BT.2020 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -478,9 +459,6 @@ is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: DCI-P3 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -532,9 +510,6 @@ quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 240M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -603,9 +578,6 @@ limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: NTSC 1953 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -683,9 +655,6 @@ range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: EBU Tech. 3213 Chromaticities :header-rows: 1 :stub-columns: 0 diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index 8c263c5a85d8..ea0435182e44 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -51,6 +51,7 @@ applicable to all devices. ext-ctrls-fm-tx ext-ctrls-fm-rx ext-ctrls-detect + ext-ctrls-colorimetry fourcc format planar-apis diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 4e5652eb6126..f8d0b923da20 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -154,10 +154,13 @@ Control IDs ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` Enables a power line frequency filter to avoid flicker. Possible values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). + + ========================================== == + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 + ========================================== == ``V4L2_CID_HUE_AUTO`` ``(boolean)`` Enables automatic hue control by the device. The effect of setting @@ -197,7 +200,7 @@ Control IDs -.. tabularcolumns:: |p{5.5cm}|p{12cm}| +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-meta.rst b/Documentation/userspace-api/media/v4l/dev-meta.rst index 8ec3a73dcae4..0e7e1ee1471a 100644 --- a/Documentation/userspace-api/media/v4l/dev-meta.rst +++ b/Documentation/userspace-api/media/v4l/dev-meta.rst @@ -49,7 +49,7 @@ to 0. .. c:type:: v4l2_meta_format -.. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| .. flat-table:: struct v4l2_meta_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index 07cc92564c16..4f4b23b95b9b 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -37,6 +37,10 @@ capturing and overlay. Optionally these drivers may also permit capturing and overlay with a single file descriptor for compatibility with V4L and earlier versions of V4L2. [#f1]_ +A common application of two file descriptors is the X11 +:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. +While the X server controls video overlay, the application can take +advantage of memory mapping and DMA. Querying Capabilities ===================== @@ -289,11 +293,6 @@ To start or stop the frame buffer overlay applications call the :ref:`VIDIOC_OVERLAY` ioctl. .. [#f1] - A common application of two file descriptors is the XFree86 - :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. - While the X server controls video overlay, the application can take - advantage of memory mapping and DMA. - In the opinion of the designers of this API, no driver writer taking the efforts to support simultaneous capturing and overlay will restrict this ability by requiring a single file descriptor, as in diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index 3f43a01ba938..58f97c3a7792 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -97,7 +97,7 @@ VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. -.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}| .. c:type:: v4l2_vbi_format @@ -180,7 +180,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does - This array is reserved for future extensions. Drivers and applications must set it to zero. -.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}| .. _vbifmt-flags: diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst index 207216d5e6a5..b1dadc24561f 100644 --- a/Documentation/userspace-api/media/v4l/dev-rds.rst +++ b/Documentation/userspace-api/media/v4l/dev-rds.rst @@ -91,8 +91,6 @@ RDS datastructures .. c:type:: v4l2_rds_data -.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| - .. flat-table:: struct v4l2_rds_data :header-rows: 0 :stub-columns: 0 @@ -133,7 +131,7 @@ RDS datastructures .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index 80b25a7e8017..928884dfe09d 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -80,7 +80,7 @@ data transfer, set by the driver in order to inform application. .. c:type:: v4l2_sdr_format -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_sdr_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index f0df144c9f63..97ec2b115c71 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -108,7 +108,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}| .. cssclass:: longtable @@ -213,9 +213,9 @@ Sliced VBI services .. raw:: latex - \scriptsize + \footnotesize -.. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| +.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 1 @@ -253,13 +253,7 @@ Sliced VBI services :ref:`en300294` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -282,6 +276,21 @@ format while i/o is in progress (between a :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first :c:func:`read()` or :c:func:`write()` call). +.. _v4l2-sliced-wss-625-payload: + +V4L2_SLICED_WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + Reading and writing sliced VBI data =================================== @@ -298,7 +307,7 @@ struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. struct v4l2_sliced_vbi_data --------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}| .. flat-table:: :header-rows: 0 @@ -455,7 +464,7 @@ number). struct v4l2_mpeg_vbi_fmt_ivtv ----------------------------- -.. tabularcolumns:: |p{1.0cm}|p{3.8cm}|p{1.0cm}|p{11.2cm}| +.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -490,7 +499,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field ------------------------------------------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -519,7 +528,11 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -560,13 +573,16 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 one line of unspecified data that should be ignored by applications. +.. raw:: latex + + \normalsize .. _v4l2-mpeg-vbi-itv0-1: struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}| .. flat-table:: :header-rows: 0 @@ -587,7 +603,7 @@ struct v4l2_mpeg_vbi_ITV0 struct v4l2_mpeg_vbi_itv0_line ------------------------------ -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -609,7 +625,7 @@ struct v4l2_mpeg_vbi_itv0_line Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index 2aa8157efae1..fd1de0a73a9f 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -209,9 +209,11 @@ list entity names and pad numbers). .. raw:: latex + \begingroup \scriptsize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| +.. tabularcolumns:: |p{2.0cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}| .. _sample-pipeline-config: @@ -298,7 +300,7 @@ list entity names and pad numbers). .. raw:: latex - \normalsize + \endgroup 1. Initial state. The sensor source pad format is set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index caa05fbbd396..33243ecb5033 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -72,7 +72,11 @@ and radio devices supporting a set of related functions like video capturing, video overlay and VBI capturing. See :ref:`open` for an introduction. -.. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm} +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}| .. cssclass:: longtable @@ -148,6 +152,10 @@ introduction. - ``-`` - See above. +.. raw:: latex + + \normalsize + The ``audios`` field was replaced by ``capabilities`` flag ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or outputs. To determine their number applications can enumerate audio diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index c05a2d2c675d..4c5061aa9cd4 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -32,6 +32,7 @@ enum v4l2_exposure_auto_type - should ignore such requests. Possible values are: +.. tabularcolumns:: |p{7.1cm}|p{10.4cm}| .. flat-table:: :header-rows: 0 @@ -81,7 +82,7 @@ enum v4l2_exposure_metering - Determines how the camera measures the amount of light available for the frame exposure. Possible values are: -.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| +.. tabularcolumns:: |p{8.7cm}|p{8.7cm}| .. flat-table:: :header-rows: 0 @@ -173,7 +174,7 @@ enum v4l2_exposure_metering - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` control value. -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -199,7 +200,7 @@ enum v4l2_exposure_metering - enum v4l2_auto_focus_range - Determines auto focus distance range for which lens may be adjusted. -.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.9cm}|p{10.6cm}| .. flat-table:: :header-rows: 0 @@ -274,7 +275,7 @@ enum v4l2_auto_n_preset_white_balance - representation. The following white balance presets are listed in order of increasing color temperature. -.. tabularcolumns:: |p{7.2 cm}|p{10.3cm}| +.. tabularcolumns:: |p{7.4cm}|p{10.1cm}| .. flat-table:: :header-rows: 0 @@ -384,7 +385,9 @@ enum v4l2_scene_mode - \small -.. tabularcolumns:: |p{5.9cm}|p{11.5cm}| +.. tabularcolumns:: |p{5.9cm}|p{11.6cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 @@ -519,6 +522,7 @@ enum v4l2_scene_mode - have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation. +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index 01e3b1a3fb99..3fc04daa9ffb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -34,7 +34,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_sps -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| .. flat-table:: struct v4l2_ctrl_h264_sps :header-rows: 0 @@ -96,6 +100,10 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` +.. raw:: latex + + \normalsize + .. _h264_sps_constraints_set_flags: ``Sequence Parameter Set Constraints Set Flags`` @@ -171,7 +179,9 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_pps -.. cssclass:: longtable +.. raw:: latex + + \small .. flat-table:: struct v4l2_ctrl_h264_pps :header-rows: 0 @@ -212,43 +222,57 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` +.. raw:: latex + + \normalsize + .. _h264_pps_flags: ``Picture Parameter Set Flags`` -.. cssclass:: longtable +.. raw:: latex + + \begingroup + \scriptsize + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{9.8cm}|p{1.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 1 1 2 + :widths: 10 1 4 * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` - - 0x00000001 + - 0x0001 - * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` - - 0x00000002 + - 0x0002 - * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000004 + - 0x0004 - * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00000008 + - 0x0008 - * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 + - 0x0010 - * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` - - 0x00000020 + - 0x0020 - * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` - - 0x00000040 + - 0x0040 - * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - Indicates that ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + - 0x0080 + - ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` must be used for this picture. +.. raw:: latex + + \endgroup + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)`` Specifies the scaling matrix (as extracted from the bitstream) for the associated H264 slice data. The bitstream parameters are @@ -259,7 +283,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_scaling_matrix -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.6cm}|p{4.8cm}|p{11.9cm}| .. flat-table:: struct v4l2_ctrl_h264_scaling_matrix :header-rows: 0 @@ -290,7 +318,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_slice_params -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| .. flat-table:: struct v4l2_ctrl_h264_slice_params :header-rows: 0 @@ -333,11 +365,11 @@ Stateless Codec Control ID * - __u8 - ``num_ref_idx_l0_active_minus1`` - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. + set to the value of num_ref_idx_l0_default_active_minus1 * - __u8 - ``num_ref_idx_l1_active_minus1`` - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. + set to the value of num_ref_idx_l1_default_active_minus1 * - __u8 - ``reserved`` - Applications and drivers must set this to zero. @@ -351,6 +383,10 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Slice Parameter Flags <h264_slice_flags>` +.. raw:: latex + + \normalsize + .. _h264_slice_flags: ``Slice Parameter Set Flags`` @@ -378,7 +414,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_pred_weights -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.9cm}|p{4.9cm}|p{7.5cm}| .. flat-table:: struct v4l2_ctrl_h264_pred_weights :header-rows: 0 @@ -396,9 +436,17 @@ Stateless Codec Control ID - The weight factors at index 0 are the weight factors for the reference list 0, the one at index 1 for the reference list 1. +.. raw:: latex + + \normalsize + .. c:type:: v4l2_h264_weight_factors -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{11.8cm}| .. flat-table:: struct v4l2_h264_weight_factors :header-rows: 0 @@ -418,6 +466,10 @@ Stateless Codec Control ID - ``chroma_offset[32][2]`` - +.. raw:: latex + + \normalsize + ``Picture Reference`` .. c:type:: v4l2_h264_reference @@ -440,7 +492,11 @@ Stateless Codec Control ID ``Reference Fields`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.4cm}|p{0.8cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -458,6 +514,10 @@ Stateless Codec Control ID - The frame (or the top/bottom fields, if it's a field pair) is used for short-term reference. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)`` Specifies the decode parameters (as extracted from the bitstream) for the associated H264 slice data. This includes the necessary @@ -469,7 +529,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_decode_params -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| .. flat-table:: struct v4l2_ctrl_h264_decode_params :header-rows: 0 @@ -524,11 +588,19 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` +.. raw:: latex + + \normalsize + .. _h264_decode_params_flags: ``Decode Parameters Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{8.3cm}|p{2.1cm}|p{6.9cm}| .. flat-table:: :header-rows: 0 @@ -545,9 +617,17 @@ Stateless Codec Control ID - 0x00000004 - +.. raw:: latex + + \normalsize + .. c:type:: v4l2_h264_dpb_entry -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.9cm}|p{11.4cm}| .. flat-table:: struct v4l2_h264_dpb_entry :header-rows: 0 @@ -583,11 +663,19 @@ Stateless Codec Control ID - ``flags`` - See :ref:`DPB Entry Flags <h264_dpb_flags>` +.. raw:: latex + + \normalsize + .. _h264_dpb_flags: ``DPB Entries Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.7cm}|p{2.1cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 @@ -607,6 +695,10 @@ Stateless Codec Control ID - 0x00000008 - The DPB entry is a single field or a complementary field pair. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)`` Specifies the decoding mode to use. Currently exposes slice-based and frame-based decoding but new modes might be added later on. @@ -619,7 +711,11 @@ Stateless Codec Control ID .. c:type:: v4l2_stateless_h264_decode_mode -.. cssclass:: longtable +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| .. flat-table:: :header-rows: 0 @@ -644,6 +740,10 @@ Stateless Codec Control ID selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` control shall not be set. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_START_CODE (enum)`` Specifies the H264 slice start code expected for each slice. This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE @@ -655,23 +755,32 @@ Stateless Codec Control ID .. c:type:: v4l2_stateless_h264_start_code -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.9cm}|p{0.4cm}|p{9.0cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 1 1 2 + :widths: 4 1 4 * - ``V4L2_STATELESS_H264_START_CODE_NONE`` - 0 - Selecting this value specifies that H264 slices are passed - to the driver without any start code. + to the driver without any start code. The bitstream data should be + according to :ref:`h264` 7.3.1 NAL unit syntax, hence contains + emulation prevention bytes when required. * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B`` - 1 - Selecting this value specifies that H264 slices are expected to be prefixed by Annex B start codes. According to :ref:`h264` valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. +.. raw:: latex + + \normalsize .. _codec-stateless-fwht: @@ -683,9 +792,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_fwht_params -.. cssclass:: longtable +.. raw:: latex + + \small -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| +.. tabularcolumns:: |p{1.4cm}|p{3.9cm}|p{12.0cm}| .. flat-table:: struct v4l2_ctrl_fwht_params :header-rows: 0 @@ -724,16 +835,20 @@ Stateless Codec Control ID - ``quantization`` - The quantization range, from enum :c:type:`v4l2_quantization`. +.. raw:: latex + \normalsize .. _fwht-flags: FWHT Flags ========== -.. cssclass:: longtable +.. raw:: latex -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.3cm}|p{8.0cm}| .. flat-table:: :header-rows: 0 @@ -778,7 +893,7 @@ FWHT Flags - Set if this is an I-frame. * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` - 0x00070000 - - The number of color components - 1. + - The number of color components minus one. * - ``V4L2_FWHT_FL_PIXENC_MSK`` - 0x00180000 - The mask for the pixel encoding. @@ -791,3 +906,341 @@ FWHT Flags * - ``V4L2_FWHT_FL_PIXENC_HSV`` - 0x00180000 - Set if the pixel encoding is HSV. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp8: + +``V4L2_CID_STATELESS_VP8_FRAME (struct)`` + Specifies the frame parameters for the associated VP8 parsed frame data. + This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for VP8. + The bitstream parameters are defined according to :ref:`vp8`. + +.. c:type:: v4l2_ctrl_vp8_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{4.6cm}|p{5.7cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp8_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp8_segment` + - ``segment`` + - Structure with segment-based adjustments metadata. + * - struct :c:type:`v4l2_vp8_loop_filter` + - ``lf`` + - Structure with loop filter level adjustments metadata. + * - struct :c:type:`v4l2_vp8_quantization` + - ``quant`` + - Structure with VP8 dequantization indices metadata. + * - struct :c:type:`v4l2_vp8_entropy` + - ``entropy`` + - Structure with VP8 entropy coder probabilities metadata. + * - struct :c:type:`v4l2_vp8_entropy_coder_state` + - ``coder_state`` + - Structure with VP8 entropy coder state. + * - __u16 + - ``width`` + - The width of the frame. Must be set for all frames. + * - __u16 + - ``height`` + - The height of the frame. Must be set for all frames. + * - __u8 + - ``horizontal_scale`` + - Horizontal scaling factor. + * - __u8 + - ``vertical_scaling factor`` + - Vertical scale. + * - __u8 + - ``version`` + - Bitstream version. + * - __u8 + - ``prob_skip_false`` + - Indicates the probability that the macroblock is not skipped. + * - __u8 + - ``prob_intra`` + - Indicates the probability that a macroblock is intra-predicted. + * - __u8 + - ``prob_last`` + - Indicates the probability that the last reference frame is used + for inter-prediction + * - __u8 + - ``prob_gf`` + - Indicates the probability that the golden reference frame is used + for inter-prediction + * - __u8 + - ``num_dct_parts`` + - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. + * - __u32 + - ``first_part_size`` + - Size of the first partition, i.e. the control partition. + * - __u32 + - ``first_part_header_bits`` + - Size in bits of the first partition header portion. + * - __u32 + - ``dct_part_sizes[8]`` + - DCT coefficients sizes. + * - __u64 + - ``last_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``flags`` + - See :ref:`Frame Flags <vp8_frame_flags>` + +.. raw:: latex + + \normalsize + +.. _vp8_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{9.8cm}|p{0.8cm}|p{6.7cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_FRAME_FLAG_KEY_FRAME`` + - 0x01 + - Indicates if the frame is a key frame. + * - ``V4L2_VP8_FRAME_FLAG_EXPERIMENTAL`` + - 0x02 + - Experimental bitstream. + * - ``V4L2_VP8_FRAME_FLAG_SHOW_FRAME`` + - 0x04 + - Show frame flag, indicates if the frame is for display. + * - ``V4L2_VP8_FRAME_FLAG_MB_NO_SKIP_COEFF`` + - 0x08 + - Enable/disable skipping of macroblocks with no non-zero coefficients. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_GOLDEN`` + - 0x10 + - Sign of motion vectors when the golden frame is referenced. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_ALT`` + - 0x20 + - Sign of motion vectors when the alt frame is referenced. + +.. c:type:: v4l2_vp8_entropy_coder_state + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| + +.. flat-table:: struct v4l2_vp8_entropy_coder_state + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``range`` + - coder state value for "Range" + * - __u8 + - ``value`` + - coder state value for "Value"- + * - __u8 + - ``bit_count`` + - number of bits left. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_segment + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.2cm}|p{4.0cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_vp8_segment + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``quant_update[4]`` + - Signed quantizer value update. + * - __s8 + - ``lf_update[4]`` + - Signed loop filter level value update. + * - __u8 + - ``segment_probs[3]`` + - Segment probabilities. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Segment Flags <vp8_segment_flags>` + +.. _vp8_segment_flags: + +``Segment Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{10cm}|p{1.0cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_SEGMENT_FLAG_ENABLED`` + - 0x01 + - Enable/disable segment-based adjustments. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates if the macroblock segmentation map is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_FEATURE_DATA`` + - 0x04 + - Indicates if the segment feature data is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_DELTA_VALUE_MODE`` + - 0x08 + - If is set, the segment feature data mode is delta-value. + If cleared, it's absolute-value. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_vp8_loop_filter + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{3.9cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_vp8_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_frm_delta[4]`` + - Reference adjustment (signed) delta value. + * - __s8 + - ``mb_mode_delta[4]`` + - Macroblock prediction mode adjustment (signed) delta value. + * - __u8 + - ``sharpness_level`` + - Sharpness level + * - __u8 + - ``level`` + - Filter level + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Loop Filter Flags <vp8_loop_filter_flags>` + +.. _vp8_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_LF_ADJ_ENABLE`` + - 0x01 + - Enable/disable macroblock-level loop filter adjustment. + * - ``V4L2_VP8_LF_DELTA_UPDATE`` + - 0x02 + - Indicates if the delta values used in an adjustment are updated. + * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` + - 0x04 + - If set, indicates the filter type is simple. + If cleared, the filter type is normal. + +.. c:type:: v4l2_vp8_quantization + +.. tabularcolumns:: |p{1.5cm}|p{3.5cm}|p{12.3cm}| + +.. flat-table:: struct v4l2_vp8_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``y_ac_qi`` + - Luma AC coefficient table index. + * - __s8 + - ``y_dc_delta`` + - Luma DC delta vaue. + * - __s8 + - ``y2_dc_delta`` + - Y2 block DC delta value. + * - __s8 + - ``y2_ac_delta`` + - Y2 block AC delta value. + * - __s8 + - ``uv_dc_delta`` + - Chroma DC delta value. + * - __s8 + - ``uv_ac_delta`` + - Chroma AC delta value. + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_entropy + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_vp8_entropy + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``coeff_probs[4][8][3][11]`` + - Coefficient update probabilities. + * - __u8 + - ``y_mode_probs[4]`` + - Luma mode update probabilities. + * - __u8 + - ``uv_mode_probs[3]`` + - Chroma mode update probabilities. + * - __u8 + - ``mv_probs[2][19]`` + - MV decoding update probabilities. + * - __u8 + - ``padding[3]`` + - Applications and drivers must set this to zero. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 00944e97d638..b0de4e6e7ebd 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -392,7 +392,7 @@ enum v4l2_mpeg_audio_mode_extension - which subbands are in intensity stereo. All other subbands are coded in stereo. Layer III is not (yet) supported. Possible values are: - +.. tabularcolumns:: |p{9.1cm}|p{8.4cm}| .. flat-table:: :header-rows: 0 @@ -580,7 +580,7 @@ enum v4l2_mpeg_video_bitrate_mode - ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` - Video bitrate in bits per second. + Average video bitrate in bits per second. ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` Peak video bitrate in bits per second. Must be larger or equal to @@ -605,7 +605,7 @@ enum v4l2_mpeg_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. raw:: latex @@ -615,12 +615,12 @@ enum v4l2_mpeg_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the :ref:`VBV (MPEG1/2/4) <v4l2-mpeg-video-vbv-size>` or :ref:`CPB (H264) buffer size <v4l2-mpeg-video-h264-cpb-size>` control. @@ -674,11 +674,64 @@ enum v4l2_mpeg_video_frame_skip_mode - is currently displayed (decoded). This value is reset to 0 whenever the decoder is started. +``V4L2_CID_MPEG_VIDEO_DEC_CONCEAL_COLOR (integer64)`` + This control sets the conceal color in YUV color space. It describes + the client preference of the error conceal color in case of an error + where the reference frame is missing. The decoder should fill the + reference buffer with the preferred color and use it for future + decoding. The control is using 16 bits per channel. + Applicable to decoders. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - + - 8bit format + - 10bit format + - 12bit format + * - Y luminance + - Bit 0:7 + - Bit 0:9 + - Bit 0:11 + * - Cb chrominance + - Bit 16:23 + - Bit 16:25 + - Bit 16:27 + * - Cr chrominance + - Bit 32:39 + - Bit 32:41 + - Bit 32:43 + * - Must be zero + - Bit 48:63 + - Bit 48:63 + - Bit 48:63 + ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` If enabled the decoder expects to receive a single slice per buffer, otherwise the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs. +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE (boolean)`` + If the display delay is enabled then the decoder is forced to return + a CAPTURE buffer (decoded frame) after processing a certain number + of OUTPUT buffers. The delay can be set through + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY``. This + feature can be used for example for generating thumbnails of videos. + Applicable to the decoder. + +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY (integer)`` + Display delay value for decoder. The decoder is forced to + return a decoded frame after the set 'display delay' number of + frames. If this number is low it may result in frames returned out + of display order, in addition the hardware may still be using the + returned buffer as a reference picture for subsequent frames. + +``V4L2_CID_MPEG_VIDEO_AU_DELIMITER (boolean)`` + If enabled then, AUD (Access Unit Delimiter) NALUs will be generated. + That could be useful to find the start of a frame without having to + fully parse each NALU. Applicable to the H264 and HEVC encoders. + ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` Enable writing sample aspect ratio in the Video Usability Information. Applicable to the H264 encoder. @@ -873,7 +926,11 @@ enum v4l2_mpeg_video_h264_profile - The profile information for H264. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -916,7 +973,9 @@ enum v4l2_mpeg_video_h264_profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_HIGH`` - Constrained High profile +.. raw:: latex + \normalsize .. _v4l2-mpeg-video-mpeg2-profile: @@ -927,7 +986,11 @@ enum v4l2_mpeg_video_mpeg2_profile - The profile information for MPEG2. Applicable to MPEG2 codecs. Possible values are: +.. raw:: latex + \small + +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -947,6 +1010,9 @@ enum v4l2_mpeg_video_mpeg2_profile - - Multi-view profile (MVP) +.. raw:: latex + + \normalsize .. _v4l2-mpeg-video-mpeg4-profile: @@ -957,7 +1023,11 @@ enum v4l2_mpeg_video_mpeg4_profile - The profile information for MPEG4. Applicable to the MPEG4 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{11.8cm}|p{5.7cm}| .. flat-table:: :header-rows: 0 @@ -972,9 +1042,11 @@ enum v4l2_mpeg_video_mpeg4_profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` - Simple Scalable profile * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` - - + - Advanced Coding Efficiency profile +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` The maximum number of reference pictures used for encoding. @@ -1030,7 +1102,7 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - \small -.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| +.. tabularcolumns:: |p{13.5cm}|p{4.0cm}| .. flat-table:: :header-rows: 0 @@ -1425,7 +1497,7 @@ enum v4l2_mpeg_video_h264_fmo_change_dir - Specifies a direction of the slice group change for raster and wipe maps. Applicable to the H264 encoder. Possible values are: - +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| .. flat-table:: :header-rows: 0 @@ -1549,9 +1621,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_ctrl_mpeg2_slice_params -.. cssclass:: longtable +.. tabularcolumns:: |p{5.6cm}|p{4.6cm}|p{7.1cm}| -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| +.. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_mpeg2_slice_params :header-rows: 0 @@ -1594,7 +1666,7 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| +.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}| .. flat-table:: struct v4l2_mpeg2_sequence :header-rows: 0 @@ -1625,9 +1697,13 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_mpeg2_picture +.. raw:: latex + + \small + .. cssclass:: longtable -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| +.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}| .. flat-table:: struct v4l2_mpeg2_picture :header-rows: 0 @@ -1675,6 +1751,10 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - ``progressive_frame`` - Indicates whether the current frame is progressive. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` Specifies quantization matrices (as extracted from the bitstream) for the associated MPEG-2 slice data. @@ -1686,9 +1766,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_ctrl_mpeg2_quantization -.. cssclass:: longtable +.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}| -.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| +.. cssclass:: longtable .. raw:: latex @@ -1739,6 +1819,10 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - non-intra-coded frames, in zigzag scanning order. Only relevant for non-4:2:0 YUV formats. +.. raw:: latex + + \normalsize + ``V4L2_CID_FWHT_I_FRAME_QP (integer)`` Quantization parameter for an I frame for FWHT. Valid range: from 1 to 31. @@ -1747,329 +1831,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - Quantization parameter for a P frame for FWHT. Valid range: from 1 to 31. -.. _v4l2-mpeg-vp8: - -``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)`` - Specifies the frame parameters for the associated VP8 parsed frame data. - This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for VP8. - The bitstream parameters are defined according to :ref:`vp8`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_vp8_frame_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_vp8_frame_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_vp8_segment_header` - - ``segment_header`` - - Structure with segment-based adjustments metadata. - * - struct :c:type:`v4l2_vp8_loopfilter_header` - - ``loopfilter_header`` - - Structure with loop filter level adjustments metadata. - * - struct :c:type:`v4l2_vp8_quantization_header` - - ``quant_header`` - - Structure with VP8 dequantization indices metadata. - * - struct :c:type:`v4l2_vp8_entropy_header` - - ``entropy_header`` - - Structure with VP8 entropy coder probabilities metadata. - * - struct :c:type:`v4l2_vp8_entropy_coder_state` - - ``coder_state`` - - Structure with VP8 entropy coder state. - * - __u16 - - ``width`` - - The width of the frame. Must be set for all frames. - * - __u16 - - ``height`` - - The height of the frame. Must be set for all frames. - * - __u8 - - ``horizontal_scale`` - - Horizontal scaling factor. - * - __u8 - - ``vertical_scaling factor`` - - Vertical scale. - * - __u8 - - ``version`` - - Bitstream version. - * - __u8 - - ``prob_skip_false`` - - Indicates the probability that the macroblock is not skipped. - * - __u8 - - ``prob_intra`` - - Indicates the probability that a macroblock is intra-predicted. - * - __u8 - - ``prob_last`` - - Indicates the probability that the last reference frame is used - for inter-prediction - * - __u8 - - ``prob_gf`` - - Indicates the probability that the golden reference frame is used - for inter-prediction - * - __u8 - - ``num_dct_parts`` - - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. - * - __u32 - - ``first_part_size`` - - Size of the first partition, i.e. the control partition. - * - __u32 - - ``first_part_header_bits`` - - Size in bits of the first partition header portion. - * - __u32 - - ``dct_part_sizes[8]`` - - DCT coefficients sizes. - * - __u64 - - ``last_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``golden_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``alt_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``flags`` - - See :ref:`Frame Header Flags <vp8_frame_header_flags>` - -.. _vp8_frame_header_flags: - -``Frame Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME`` - - 0x01 - - Indicates if the frame is a key frame. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL`` - - 0x02 - - Experimental bitstream. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME`` - - 0x04 - - Show frame flag, indicates if the frame is for display. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF`` - - 0x08 - - Enable/disable skipping of macroblocks with no non-zero coefficients. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN`` - - 0x10 - - Sign of motion vectors when the golden frame is referenced. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT`` - - 0x20 - - Sign of motion vectors when the alt frame is referenced. - -.. c:type:: v4l2_vp8_entropy_coder_state - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_coder_state - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``range`` - - - * - __u8 - - ``value`` - - - * - __u8 - - ``bit_count`` - - - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_segment_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_segment_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``quant_update[4]`` - - Signed quantizer value update. - * - __s8 - - ``lf_update[4]`` - - Signed loop filter level value update. - * - __u8 - - ``segment_probs[3]`` - - Segment probabilities. - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Segment Header Flags <vp8_segment_header_flags>` - -.. _vp8_segment_header_flags: - -``Segment Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED`` - - 0x01 - - Enable/disable segment-based adjustments. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP`` - - 0x02 - - Indicates if the macroblock segmentation map is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA`` - - 0x04 - - Indicates if the segment feature data is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE`` - - 0x08 - - If is set, the segment feature data mode is delta-value. - If cleared, it's absolute-value. - -.. c:type:: v4l2_vp8_loopfilter_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_loopfilter_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``ref_frm_delta[4]`` - - Reference adjustment (signed) delta value. - * - __s8 - - ``mb_mode_delta[4]`` - - Macroblock prediction mode adjustment (signed) delta value. - * - __u8 - - ``sharpness_level`` - - Sharpness level - * - __u8 - - ``level`` - - Filter level - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>` - -.. _vp8_loopfilter_header_flags: - -``Loopfilter Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE`` - - 0x01 - - Enable/disable macroblock-level loop filter adjustment. - * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE`` - - 0x02 - - Indicates if the delta values used in an adjustment are updated. - * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` - - 0x04 - - If set, indicates the filter type is simple. - If cleared, the filter type is normal. - -.. c:type:: v4l2_vp8_quantization_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_quantization_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``y_ac_qi`` - - Luma AC coefficient table index. - * - __s8 - - ``y_dc_delta`` - - Luma DC delta vaue. - * - __s8 - - ``y2_dc_delta`` - - Y2 block DC delta value. - * - __s8 - - ``y2_ac_delta`` - - Y2 block AC delta value. - * - __s8 - - ``uv_dc_delta`` - - Chroma DC delta value. - * - __s8 - - ``uv_ac_delta`` - - Chroma AC delta value. - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_entropy_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``coeff_probs[4][8][3][11]`` - - Coefficient update probabilities. - * - __u8 - - ``y_mode_probs[4]`` - - Luma mode update probabilities. - * - __u8 - - ``uv_mode_probs[3]`` - - Chroma mode update probabilities. - * - __u8 - - ``mv_probs[2][19]`` - - MV decoding update probabilities. - * - __u8 - - ``padding[3]`` - - Applications and drivers must set this to zero. - .. raw:: latex \normalsize @@ -2096,6 +1857,11 @@ MFC 5.1 Control IDs feature can be used for example for generating thumbnails of videos. Applicable to the H264 decoder. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` Display delay value for H264 decoder. The decoder is forced to return a decoded frame after the set 'display delay' number of @@ -2103,6 +1869,11 @@ MFC 5.1 Control IDs of display order, in addition the hardware may still be using the returned buffer as a reference picture for subsequent frames. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` The number of reference pictures used for encoding a P picture. Applicable to the H264 encoder. @@ -2187,7 +1958,7 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{9.4cm}|p{8.1cm}| .. raw:: latex @@ -2197,12 +1968,12 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control. @@ -2231,7 +2002,7 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - Force a frame type for the next queued buffer. Applicable to encoders. Possible values are: -.. tabularcolumns:: |p{9.5cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.9cm}|p{7.6cm}| .. flat-table:: :header-rows: 0 @@ -2267,6 +2038,7 @@ enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - are: +.. tabularcolumns:: |p{11.5cm}|p{6.0cm}| .. flat-table:: :header-rows: 0 @@ -2292,11 +2064,11 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - Select the algorithm to use for the Luma Spatial Filter (default ``1D_HOR``). Possible values: -.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| +.. tabularcolumns:: |p{13.1cm}|p{4.4cm}| .. raw:: latex - \small + \footnotesize .. flat-table:: :header-rows: 0 @@ -2317,8 +2089,6 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - \normalsize - - .. _chroma-spatial-filter-type: ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` @@ -2328,8 +2098,11 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - Select the algorithm for the Chroma Spatial Filter (default ``1D_HOR``). Possible values are: +.. raw:: latex -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| + \footnotesize + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -2340,7 +2113,9 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` - One-dimensional horizontal +.. raw:: latex + \normalsize .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: @@ -2351,7 +2126,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - Sets the Temporal Filter mode (default ``MANUAL``). Possible values are: +.. raw:: latex + \footnotesize .. flat-table:: :header-rows: 0 @@ -2362,7 +2139,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` - Choose the filter automatically +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default @@ -2377,6 +2156,11 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - Median Filter Type (default ``OFF``). Possible values are: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -2393,7 +2177,9 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` - Diagonal filter +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` Threshold above which the luminance median filter is enabled @@ -2470,7 +2256,7 @@ enum v4l2_vp8_num_ref_frames - The number of reference pictures for encoding P frames. Possible values are: -.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. raw:: latex @@ -2525,7 +2311,7 @@ enum v4l2_vp8_golden_frame_sel - \scriptsize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -2735,7 +2521,7 @@ enum v4l2_mpeg_video_hevc_hier_coding_type - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 @@ -2804,7 +2590,7 @@ enum v4l2_mpeg_video_hevc_profile - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -2830,47 +2616,21 @@ enum v4l2_mpeg_video_hevc_profile - enum v4l2_mpeg_video_hevc_level - Selects the desired level for HEVC encoder. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` - - Level 5.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` - - Level 5.2 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` - - Level 6.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` - - Level 6.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` - - Level 6.2 - -.. raw:: latex - - \normalsize - +================================== ========= +``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` Level 1.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` Level 2.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` Level 2.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` Level 3.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` Level 3.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` Level 4.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` Level 4.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` Level 5.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` Level 5.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` Level 5.2 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` Level 6.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` Level 6.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` Level 6.2 +================================== ========= ``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` Indicates the number of evenly spaced subintervals, called ticks, within @@ -2889,24 +2649,10 @@ enum v4l2_mpeg_video_hevc_tier - this flag to 1 indicates High tier. High tier is for applications requiring high bit rates. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` - - Main tier. - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` - - High tier. - -.. raw:: latex - - \normalsize +================================== ========== +``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` Main tier. +``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` High tier. +================================== ========== ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` @@ -2962,7 +2708,7 @@ enum v4l2_mpeg_video_hevc_hier_refresh_type - \footnotesize -.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| +.. tabularcolumns:: |p{6.2cm}|p{11.3cm}| .. flat-table:: :header-rows: 0 @@ -3042,7 +2788,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - \footnotesize -.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| .. flat-table:: :header-rows: 0 @@ -3102,6 +2848,12 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_sps +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_sps @@ -3176,10 +2928,18 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``flags`` - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` +.. raw:: latex + + \normalsize + .. _hevc_sps_flags: ``Sequence Parameter Set Flags`` +.. raw:: latex + + \small + .. cssclass:: longtable .. flat-table:: @@ -3215,6 +2975,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00000100 - +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` Specifies the Picture Parameter Set fields (as extracted from the bitstream) for the associated HEVC slice data. @@ -3224,6 +2988,8 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_pps +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_pps @@ -3278,7 +3044,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - ``Picture Parameter Set Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small .. flat-table:: :header-rows: 0 @@ -3343,6 +3111,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00040000 - +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` Specifies various slice-specific parameters, especially from the NAL unit header, general slice segment header and weighted prediction parameter @@ -3353,6 +3125,12 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_slice_params +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_slice_params @@ -3455,11 +3233,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``flags`` - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` +.. raw:: latex + + \normalsize + .. _hevc_slice_params_flags: ``Slice Parameters Flags`` -.. cssclass:: longtable +.. raw:: latex + + \scriptsize .. flat-table:: :header-rows: 0 @@ -3494,9 +3278,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00000100 - +.. raw:: latex + + \normalsize + .. c:type:: v4l2_hevc_dpb_entry -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| .. flat-table:: struct v4l2_hevc_dpb_entry :header-rows: 0 @@ -3528,9 +3320,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``padding[2]`` - Applications and drivers must set this to zero. +.. raw:: latex + + \normalsize + .. c:type:: v4l2_hevc_pred_weight_table -.. cssclass:: longtable +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| .. flat-table:: struct v4l2_hevc_pred_weight_table :header-rows: 0 @@ -3571,6 +3371,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``padding[6]`` - Applications and drivers must set this to zero. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` Specifies the decoding mode to use. Currently exposes slice-based and frame-based decoding but new modes might be added later on. @@ -3588,7 +3392,11 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_mpeg_video_hevc_decode_mode -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -3605,6 +3413,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - The OUTPUT buffer must contain all slices needed to decode the frame. The OUTPUT buffer must also contain both fields. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` Specifies the HEVC slice start code expected for each slice. This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE @@ -3621,7 +3433,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_mpeg_video_hevc_start_code -.. cssclass:: longtable +.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 @@ -3631,7 +3443,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` - 0 - Selecting this value specifies that HEVC slices are passed - to the driver without any start code. + to the driver without any start code. The bitstream data should be + according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence + contains emulation prevention bytes when required. * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` - 1 - Selecting this value specifies that HEVC slices are expected @@ -3646,3 +3460,21 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - so this has to come from client. This is applicable to H264 and valid Range is from 0 to 63. Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. + +``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` + Specifies the maximum number of Long Term Reference (LTR) frames at any + given time that the encoder can keep. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` + After setting this control the frame that will be queued next + will be marked as a Long Term Reference (LTR) frame + and given this LTR index which ranges from 0 to LTR_COUNT-1. + This is applicable to the H264 and HEVC encoders. + Source Rec. ITU-T H.264 (06/2019); Table 7.9 + +``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` + Specifies the Long Term Reference (LTR) frame(s) to be used for + encoding the next frame queued after setting this control. + This provides a bitmask which consists of bits [0, LTR_COUNT-1]. + This is applicable to the H264 and HEVC encoders. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst new file mode 100644 index 000000000000..1e7265155715 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _colorimetry-controls: + +***************************** +Colorimetry Control Reference +***************************** + +The Colorimetry class includes controls for High Dynamic Range +imaging for representing colors in digital images and video. The +controls should be used for video and image encoding and decoding +as well as in HDMI receivers and transmitters. + +Colorimetry Control IDs +----------------------- + +.. _colorimetry-control-id: + +``V4L2_CID_COLORIMETRY_CLASS (class)`` + The Colorimetry class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_COLORIMETRY_HDR10_CLL_INFO (struct)`` + The Content Light Level defines upper bounds for the nominal target + brightness light level of the pictures. + +.. c:type:: v4l2_ctrl_hdr10_cll_info + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_cll_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``max_content_light_level`` + - The upper bound for the maximum light level among all individual + samples for the pictures of a video sequence, cd/m\ :sup:`2`. + When equal to 0 no such upper bound is present. + * - __u16 + - ``max_pic_average_light_level`` + - The upper bound for the maximum average light level among the + samples for any individual picture of a video sequence, + cd/m\ :sup:`2`. When equal to 0 no such upper bound is present. + +``V4L2_CID_COLORIMETRY_HDR10_MASTERING_DISPLAY (struct)`` + The mastering display defines the color volume (the color primaries, + white point and luminance range) of a display considered to be the + mastering display for the current video content. + +.. c:type:: v4l2_ctrl_hdr10_mastering_display + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_mastering_display + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``display_primaries_x[3]`` + - Specifies the normalized x chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to the Red color primary. + * - __u16 + - ``display_primaries_y[3]`` + - Specifies the normalized y chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to Red color primary. + * - __u16 + - ``white_point_x`` + - Specifies the normalized x chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u16 + - ``white_point_y`` + - Specifies the normalized y chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u32 + - ``max_luminance`` + - Specifies the nominal maximum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. + * - __u32 + - ``min_luminance`` + - specifies the nominal minimum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst index a6f696bf89dd..d2794e03ac6d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst @@ -99,7 +99,7 @@ enum v4l2_dv_it_content_type - or an analog source. The enum v4l2_dv_it_content_type defines the possible content types: -.. tabularcolumns:: |p{7.3cm}|p{10.4cm}| +.. tabularcolumns:: |p{7.3cm}|p{10.2cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst index ad4b878cd034..d22c5efb806a 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst @@ -63,6 +63,7 @@ Flash Control IDs presence of some faults. See V4L2_CID_FLASH_FAULT. +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -73,14 +74,16 @@ Flash Control IDs * - ``V4L2_FLASH_LED_MODE_FLASH`` - Flash mode. * - ``V4L2_FLASH_LED_MODE_TORCH`` - - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + - Torch mode. + + See V4L2_CID_FLASH_TORCH_INTENSITY. ``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` Defines the source of the flash LED strobe. -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index e07a2dbcd65d..60f9a09422d6 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -64,13 +64,12 @@ JPEG Control IDs .. _jpeg-quality-control: ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off - between image quality and size. It provides simpler method for - applications to control image quality, without a need for direct - reconfiguration of luminance and chrominance quantization tables. In - cases where a driver uses quantization tables configured directly by - an application, using interfaces defined elsewhere, - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by + Determines trade-off between image quality and size. + It provides simpler method for applications to control image quality, + without a need for direct reconfiguration of luminance and chrominance + quantization tables. In cases where a driver uses quantization tables + configured directly by an application, using interfaces defined + elsewhere, ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by driver to 0. The value range of this control is driver-specific. Only positive, diff --git a/Documentation/userspace-api/media/v4l/field-order.rst b/Documentation/userspace-api/media/v4l/field-order.rst index 54548ea4308c..9a0ed8fc550f 100644 --- a/Documentation/userspace-api/media/v4l/field-order.rst +++ b/Documentation/userspace-api/media/v4l/field-order.rst @@ -62,7 +62,7 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}| .. cssclass:: longtable diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index acad5f3ca0c1..6dba70da822b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -7,7 +7,13 @@ Compressed Formats .. _compressed-formats: -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.8cm}|p{1.2cm}|p{10.3cm}| + +.. cssclass:: longtable .. flat-table:: Compressed Image Formats :header-rows: 1 @@ -147,22 +153,17 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8_FRAME`` - 'VP8F' - - VP8 parsed frame, as extracted from the container. - This format is adapted for stateless video decoders that implement a - VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + - VP8 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement an + VP8 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`. + through the ``V4L2_CID_STATELESS_VP8_FRAME`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp8>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-VP9: - ``V4L2_PIX_FMT_VP9`` @@ -220,3 +221,7 @@ Compressed Formats Metadata associated with the frame to decode is required to be passed through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index eb551b57557e..65520c3af7cf 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -36,10 +36,10 @@ Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, .. raw:: latex \begingroup - \tiny + \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| +.. tabularcolumns:: |p{3.5cm}|p{0.96cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}| .. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 @@ -220,6 +220,16 @@ the second byte and Y'\ :sub:`7-0` in the third byte. - Y'\ :sub:`7-0` - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-YUV24: + + - ``V4L2_PIX_FMT_YUV24`` + - 'YUV3' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - -\ + .. note:: - The alpha component is expected to contain a meaningful value that can be @@ -234,6 +244,12 @@ the second byte and Y'\ :sub:`7-0` in the third byte. These formats, commonly referred to as YUYV or YUY2, subsample the chroma components horizontally by 2, storing 2 pixels in 4 bytes. +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + .. flat-table:: Packed YUV 4:2:2 Formats :header-rows: 1 :stub-columns: 0 @@ -301,6 +317,10 @@ components horizontally by 2, storing 2 pixels in 4 bytes. - Y'\ :sub:`3` - Cb\ :sub:`2` +.. raw:: latex + + \normalsize + **Color Sample Location:** Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` horizontally. @@ -312,6 +332,12 @@ horizontally. This format subsamples the chroma components horizontally by 4, storing 8 pixels in 12 bytes. +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{2.9cm}|p{0.8cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| + .. flat-table:: Packed YUV 4:1:1 Formats :header-rows: 1 :stub-columns: 0 @@ -348,11 +374,15 @@ pixels in 12 bytes. - Y'\ :sub:`6` - Y'\ :sub:`7` +.. raw:: latex + + \normalsize + .. note:: Do not confuse ``V4L2_PIX_FMT_Y41P`` with :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from - "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*". + "YUV 4:1:1 **packed**", while YUV411P stands for "YUV 4:1:1 **planar**". **Color Sample Location:** Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index c9231e18859b..0b879c0da713 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -17,7 +17,11 @@ you think your format should be listed in a standard format section please make a proposal on the linux-media mailing list. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. raw:: latex + + \small .. _reserved-formats: @@ -256,3 +260,7 @@ please make a proposal on the linux-media mailing list. of tiles, resulting in 32-aligned resolutions for the luminance plane and 16-aligned resolutions for the chrominance plane (with 2x2 subsampling). + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 897676ee2c9d..48b0f787274c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -655,12 +655,7 @@ nomenclature that instead use the order of components as seen in a 24- or .. raw:: latex - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}| - + \small .. flat-table:: RGB Formats With 8 Bits Per Component :header-rows: 1 @@ -765,7 +760,7 @@ nomenclature that instead use the order of components as seen in a 24- or .. raw:: latex - \endgroup + \normalsize Deprecated RGB Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst index 15f1900cd914..3322b0600f1d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst @@ -9,7 +9,9 @@ V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') ********************************************************************************************************************************************** +==================== 10-bit Bayer formats +==================== Description =========== @@ -25,7 +27,11 @@ Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.8cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: @@ -333,3 +339,7 @@ Each cell is one byte. - R\ :sub:`0323high` - G\ :sub:`0324low` - G\ :sub:`0324high`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst index dc52e827b5d3..fd5feb415531 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst @@ -33,7 +33,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index a2f8ebfceb84..b6e79e2f8ce4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -31,7 +31,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst index 7e5d45f30cab..4f5120a6c678 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst @@ -11,7 +11,9 @@ V4L2_PIX_FMT_SRGGB14 ('RG14'), V4L2_PIX_FMT_SGRBG14 ('GR14'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +======================================== 14-bit Bayer formats expanded to 16 bits +======================================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index e25baedfca77..3572e42adb22 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -36,9 +36,11 @@ Each cell is one byte. .. raw:: latex + \begingroup \footnotesize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{1.8cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.1cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| +.. tabularcolumns:: |p{1.6cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{3.5cm}|p{3.5cm}|p{3.5cm}| .. flat-table:: :header-rows: 0 @@ -141,5 +143,5 @@ Each cell is one byte. .. raw:: latex - \normalsize + \endgroup diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst index 93a210e22592..2f2f1ef430d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst @@ -11,7 +11,9 @@ V4L2_PIX_FMT_SRGGB16 ('RG16'), V4L2_PIX_FMT_SGRBG16 ('GR16'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +==================== 16-bit Bayer formats +==================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst index 81e72f115994..02061c5a9778 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst @@ -10,8 +10,9 @@ V4L2_PIX_FMT_SRGGB8 ('RGGB'), V4L2_PIX_FMT_SGRBG8 ('GRBG'), V4L2_PIX_FMT_SGBRG8 *************************************************************************************************************************** +=================== 8-bit Bayer formats - +=================== Description =========== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index 977facc3a1f4..ad4da988c3a3 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst @@ -13,7 +13,7 @@ describing all planes of that format. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.0cm}|p{11.9cm}| .. c:type:: v4l2_plane_pix_format @@ -52,7 +52,7 @@ describing all planes of that format. \small -.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| +.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}| .. c:type:: v4l2_pix_format_mplane diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 71e828093310..9c423ffe02f9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -4,7 +4,7 @@ Single-planar format structure ****************************** -.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}| .. c:type:: v4l2_pix_format @@ -205,7 +205,7 @@ Single-planar format structure the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm}| .. _format-flags: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 0c8c5e0a380e..91942c4f0967 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -19,6 +19,12 @@ are often referred to as greyscale formats. - `0` denotes padding bits set to 0. +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{3.6cm}|p{3.0cm}|p{1.3cm}|p{2.6cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}| + .. flat-table:: Luma-Only Image Formats :header-rows: 1 :stub-columns: 0 @@ -119,6 +125,10 @@ are often referred to as greyscale formats. - ... - ... +.. raw:: latex + + \normalsize + .. note:: For the Y16 and Y16_BE formats, the actual sampling precision may be lower diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index 1e0db602cc1b..090c091affd2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -48,6 +48,12 @@ relationship between the luma and chroma line padding and stride. All components are stored with the same number of bits per component. +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{5.2cm}|p{1.0cm}|p{1.5cm}|p{1.9cm}|p{1.2cm}|p{1.8cm}|p{2.7cm}| + .. flat-table:: Overview of Semi-Planar YUV Formats :header-rows: 1 :stub-columns: 0 @@ -146,12 +152,14 @@ All components are stored with the same number of bits per component. - Yes - Linear -.. note:: +.. raw:: latex + + \normalsize - .. [1] Order of chroma samples in the second plane - .. [2] Indicates if planes have to be contiguous in memory or can be - disjoint - .. [3] Macroblock size in pixels +.. [1] Order of chroma samples in the second plane +.. [2] Indicates if planes have to be contiguous in memory or can be + disjoint +.. [3] Macroblock size in pixels **Color Sample Location:** @@ -481,6 +489,12 @@ relationship between the luma and chroma line padding and stride. All components are stored with the same number of bits per component. +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.0cm}|p{1.1cm}|p{1.5cm}|p{2.2cm}|p{1.2cm}|p{3.7cm}| + .. flat-table:: Overview of Fully Planar YUV Formats :header-rows: 1 :stub-columns: 0 @@ -565,11 +579,13 @@ All components are stored with the same number of bits per component. - Y, Cr, Cb - No -.. note:: +.. raw:: latex + + \normalsize - .. [4] Order of luma and chroma planes - .. [5] Indicates if planes have to be contiguous in memory or can be - disjoint +.. [4] Order of luma and chroma planes +.. [5] Indicates if planes have to be contiguous in memory or can be + disjoint **Color Sample Location:** diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 7f16cbe46e5c..bd68588b2683 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -5,10 +5,12 @@ Media Bus Formats ================= -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_mbus_framefmt +.. tabularcolumns:: |p{2.0cm}|p{4.0cm}|p{11.3cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_mbus_framefmt :header-rows: 0 :stub-columns: 0 @@ -113,6 +115,8 @@ Media Bus Formats .. _v4l2-mbus-framefmt-flags: +.. tabularcolumns:: |p{6.5cm}|p{1.6cm}|p{9.2cm}| + .. flat-table:: v4l2_mbus_framefmt Flags :header-rows: 0 :stub-columns: 0 @@ -204,7 +208,7 @@ The following tables list existing packed RGB formats. .. it switches to long table, and there's no way to override it. -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-rgb: @@ -1567,8 +1571,8 @@ The following tables list existing packed RGB formats. - MEDIA_BUS_FMT_RGB101010_1X30 - 0x1018 - - - 0 - - 0 + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -1890,7 +1894,7 @@ JEIDA defined bit mapping will be named .. raw:: latex - \tiny + \small .. _v4l2-mbus-pixelcode-rgb-lvds: @@ -2152,7 +2156,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-bayer: @@ -3005,7 +3009,7 @@ the following codes. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8: @@ -7210,7 +7214,7 @@ The following table list existing packed 36bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{4.1cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-36bit: @@ -7398,7 +7402,7 @@ The following table list existing packed 48bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-48bit: @@ -7851,7 +7855,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{9.9cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7884,7 +7888,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 @@ -7909,7 +7913,7 @@ This section lists all metadata formats. The following table lists the existing metadata formats. -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Metadata formats :header-rows: 1 diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst index 3a834d050110..1cb1531c1e52 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst @@ -6,10 +6,16 @@ Selection flags *************** -.. tabularcolumns:: |p{5.2cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.6cm}| - .. _v4l2-selection-flags-table: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.2cm}| + +.. cssclass:: longtable + .. flat-table:: Selection flag definitions :header-rows: 1 :stub-columns: 0 @@ -42,3 +48,7 @@ Selection flags inside the subdevice to all further processing steps. - No - Yes + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst index e877ebbdb32e..b46bae984f35 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst @@ -12,7 +12,13 @@ of the two interfaces they are used. .. _v4l2-selection-targets-table: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{7.4cm}|p{1.2cm}|p{1.4cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{6.2cm}|p{1.4cm}|p{7.3cm}|p{1.2cm}|p{0.8cm}| + +.. cssclass:: longtable .. flat-table:: Selection target definitions :header-rows: 1 @@ -69,3 +75,7 @@ of the two interfaces they are used. modified by hardware. - Yes - No + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/vbi_525.svg b/Documentation/userspace-api/media/v4l/vbi_525.svg index b01086d466a6..1951de29a111 100644 --- a/Documentation/userspace-api/media/v4l/vbi_525.svg +++ b/Documentation/userspace-api/media/v4l/vbi_525.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="208.73068mm" height="51.395489mm" - viewBox="0 0 739.59691 182.11" + viewBox="0 0 788.90338 194.25067" sodipodi:docname="vbi_525.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_625.svg b/Documentation/userspace-api/media/v4l/vbi_625.svg index 41c1ce920d14..21f524de3aed 100644 --- a/Documentation/userspace-api/media/v4l/vbi_625.svg +++ b/Documentation/userspace-api/media/v4l/vbi_625.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="209.46608mm" height="51.576824mm" - viewBox="0 0 742.20265 182.75252" + viewBox="0 0 791.6828 194.93604" sodipodi:docname="vbi_625.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_hsync.svg b/Documentation/userspace-api/media/v4l/vbi_hsync.svg index 7fcf12a7ece0..d360251e5f20 100644 --- a/Documentation/userspace-api/media/v4l/vbi_hsync.svg +++ b/Documentation/userspace-api/media/v4l/vbi_hsync.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="192.39857mm" height="146.83536mm" - viewBox="0 0 681.72724 520.28277" + viewBox="0 0 727.17572 554.96826" sodipodi:docname="vbi_hsync.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" inkscape:zoom="1.5350601" diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index b06e5b528e11..f98f18c9e91c 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -72,7 +72,7 @@ than the number requested. .. c:type:: v4l2_create_buffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_create_buffers :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 00c31410d4e4..551ac9d3c6ef 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -45,7 +45,7 @@ overlay devices. .. c:type:: v4l2_cropcap -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_cropcap :header-rows: 0 @@ -96,7 +96,7 @@ overlay devices. .. _v4l2-rect-crop: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_rect :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst index bde6e952b267..1a1e093936f1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst @@ -75,7 +75,7 @@ is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. _name-v4l2-dbg-match: @@ -101,7 +101,7 @@ instructions. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_dbg_chip_info @@ -127,7 +127,7 @@ instructions. - Reserved fields, both application and driver must set these to 0. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _name-chip-match-types: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst index e1a6abe705bd..53f10c7319b2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst @@ -85,7 +85,7 @@ It is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_dbg_match @@ -131,7 +131,7 @@ instructions. - The value read from, or to be written into the register. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _chip-match-types: diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst index fd71ceece037..7ccae3b91616 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -59,7 +59,7 @@ In principle, these ioctls are optional, not all drivers may support them. They introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders (as further documented in :ref:`decoder`). -.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| +.. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}| .. c:type:: v4l2_decoder_cmd @@ -129,7 +129,9 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod - -.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}| + +.. cssclass:: longtable .. _decoder-cmds: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index 634af717c8ba..6eb40073c906 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -37,11 +37,10 @@ structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. -.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| - .. c:type:: v4l2_event -.. cssclass: longtable +.. tabularcolumns:: |p{3.0cm}|p{3.4cm}|p{10.9cm}| + .. flat-table:: struct v4l2_event :header-rows: 0 @@ -98,7 +97,7 @@ call. zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.2cm}|p{2.6cm}|p{8.5cm}| .. cssclass:: longtable @@ -188,7 +187,7 @@ call. - Base event number for driver-private events. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_vsync @@ -202,7 +201,7 @@ call. - The upcoming field. See enum :c:type:`v4l2_field`. -.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{10.8cm}| .. c:type:: v4l2_event_ctrl @@ -252,7 +251,7 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_frame_sync @@ -266,7 +265,7 @@ call. - The sequence number of the frame being received. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_src_change @@ -281,7 +280,7 @@ call. :ref:`src-changes-flags`. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_motion_det @@ -310,7 +309,7 @@ call. automatically assigned to the default region 0. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _ctrl-changes-flags: @@ -335,7 +334,7 @@ call. step or the default value of the control changed. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _src-changes-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst index 27bd6a83e42c..8ced100bb156 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst @@ -55,7 +55,7 @@ the desired pad number in the struct zero the ``reserved`` array. Attempts to query capabilities on a pad that doesn't support them will return an ``EINVAL`` error code. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.2cm}|p{12.9cm}| .. c:type:: v4l2_bt_timings_cap @@ -96,7 +96,7 @@ that doesn't support them will return an ``EINVAL`` error code. Drivers must set the array to zero. -.. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}| +.. tabularcolumns:: |p{4.4cm}|p{3.6cm}|p{9.3cm}| .. c:type:: v4l2_dv_timings_cap @@ -128,7 +128,7 @@ that doesn't support them will return an ``EINVAL`` error code. * - } - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. _dv-bt-cap-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 5673606711b4..2b5867a68b31 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -66,7 +66,7 @@ These ioctls are optional, not all drivers may support them. They were introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem encoders (as further documented in :ref:`encoder`). -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_encoder_cmd @@ -89,7 +89,7 @@ encoders (as further documented in :ref:`encoder`). the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-cmds: @@ -133,7 +133,7 @@ encoders (as further documented in :ref:`encoder`). the encoder is already running, this command does nothing. No flags are defined for this command. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst index 20730cd4f6ef..a91c1a3f0e32 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst @@ -67,7 +67,7 @@ return an ``EINVAL`` error code. .. c:type:: v4l2_enum_dv_timings -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_enum_dv_timings :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index 2b3fa9c23146..000c154b0f98 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -71,10 +71,12 @@ the ``mbus_code`` field is handled differently: formats shall not depend on the active configuration of the video device or device pipeline. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_fmtdesc +.. cssclass:: longtable + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + .. flat-table:: struct v4l2_fmtdesc :header-rows: 0 :stub-columns: 0 @@ -135,7 +137,9 @@ the ``mbus_code`` field is handled differently: zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}| + +.. cssclass:: longtable .. _fmtdesc-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst index 1f0949726045..34cd39feaeaa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst @@ -99,8 +99,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmival_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmival_stepwise :header-rows: 0 :stub-columns: 0 @@ -119,7 +117,7 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmivalenum -.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| +.. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}| .. flat-table:: struct v4l2_frmivalenum :header-rows: 0 @@ -154,7 +152,6 @@ application should zero out all members except for the *IN* fields. - * - __u32 - ``reserved[2]`` - - - Reserved space for future use. Must be zeroed by drivers and applications. @@ -164,7 +161,7 @@ Enums .. c:type:: v4l2_frmivaltypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmivaltypes :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst index c9a36bcf699f..7271fe37ce3f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst @@ -89,8 +89,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsize_discrete -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_discrete :header-rows: 0 :stub-columns: 0 @@ -106,8 +104,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsize_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_stepwise :header-rows: 0 :stub-columns: 0 @@ -135,7 +131,7 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsizeenum -.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}| .. flat-table:: struct v4l2_frmsizeenum :header-rows: 0 @@ -173,7 +169,7 @@ Enums .. c:type:: v4l2_frmsizetypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmsizetypes :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst index a0764fca8d18..e385929bed62 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst @@ -40,7 +40,7 @@ fields, and zero out the ``reserved`` array of a struct This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_frequency_band @@ -108,7 +108,7 @@ of the corresponding tuner/modulator is set. Applications and drivers must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _band-modulation: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst index 0f62e681a827..d5f0535bd866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst @@ -38,7 +38,7 @@ fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}| .. c:type:: v4l2_input @@ -101,7 +101,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}| .. _input-type: @@ -123,7 +123,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input is a touch device for capturing raw touch data. -.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| +.. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}| .. _input-status: @@ -194,7 +194,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - VTR time constant. [?] -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}| .. _input-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst index 91fcf99094d2..06ee8386ae86 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst @@ -39,7 +39,7 @@ when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_output @@ -96,7 +96,7 @@ shall begin at index zero, incrementing by one until the driver returns zero. -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.5cm}|p{0.6cm}|p{9.2cm}| .. _output-type: @@ -118,7 +118,7 @@ shall begin at index zero, incrementing by one until the driver returns - The video output will be copied to a :ref:`video overlay <overlay>`. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.4cm}|p{8.5cm}| .. _output-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst index b5704e8cf909..6af71b74d42e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst @@ -47,7 +47,7 @@ or output. [#f1]_ .. c:type:: v4l2_standard -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_standard :header-rows: 0 @@ -86,7 +86,7 @@ or output. [#f1]_ .. c:type:: v4l2_fract -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fract :header-rows: 0 @@ -100,7 +100,7 @@ or output. [#f1]_ - ``denominator`` - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _v4l2-std-id: diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst index 212377c90442..982e8bcd9c47 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst @@ -112,7 +112,7 @@ Examples .. c:type:: v4l2_exportbuffer -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_exportbuffer :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst index 4c93bd55bd97..bf61db04d12e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -49,7 +49,7 @@ ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_audio @@ -79,7 +79,7 @@ return the actual new audio mode. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-capability: @@ -99,7 +99,7 @@ return the actual new audio mode. - Automatic Volume Level mode is supported. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-mode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst index 194f22493517..9ab15add2911 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst @@ -58,7 +58,7 @@ as ``VIDIOC_G_AUDOUT`` does. .. c:type:: v4l2_audioout -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_audioout :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst index 0ac1509e41cc..570d98308dc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst @@ -71,7 +71,7 @@ When cropping is not supported then no parameters are changed and .. c:type:: v4l2_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_crop :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst index 4f1bed53fad5..80e8c63d530f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst @@ -57,7 +57,7 @@ These ioctls work only with user controls. For other control classes the .. c:type:: v4l2_control -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_control :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst index 760a33d43b7d..6518d857c131 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst @@ -82,10 +82,12 @@ EBUSY EPERM ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_bt_timings +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_bt_timings :header-rows: 0 :stub-columns: 0 @@ -171,7 +173,7 @@ EPERM - Reserved for future extensions. Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}| .. c:type:: v4l2_dv_timings @@ -194,7 +196,7 @@ EPERM * - } - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _dv-timing-types: @@ -213,7 +215,9 @@ EPERM - 0 - BT.656/1120 timings -.. tabularcolumns:: |p{4.5cm}|p{12.8cm}| +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. cssclass:: longtable .. _dv-bt-standards: @@ -236,7 +240,9 @@ EPERM There are no horizontal syncs/porches at all in this format. Total blanking timings must be set in hsync or vsync fields only. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| + +.. cssclass:: longtable .. _dv-bt-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst index 39d523a449a7..fc5535c50d61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst @@ -100,7 +100,7 @@ EDID is no longer available. .. c:type:: v4l2_edid -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_edid :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst index 7698e65ccccf..c6792bbe3d04 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst @@ -54,7 +54,7 @@ will be zero. Currently this ioctl is only defined for MPEG-2 program streams and video elementary streams. -.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| +.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}| .. c:type:: v4l2_enc_idx @@ -81,7 +81,7 @@ video elementary streams. their ``offset``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_enc_idx_entry @@ -113,7 +113,7 @@ video elementary streams. - Reserved for future extensions. Drivers must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _enc-idx-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index b9c62affbb5a..3ba22983d21f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -118,11 +118,15 @@ correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can still cause this situation. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}| .. c:type:: v4l2_ext_control -.. cssclass: longtable +.. raw:: latex + + \footnotesize + +.. cssclass:: longtable .. flat-table:: struct v4l2_ext_control :header-rows: 0 @@ -134,11 +138,12 @@ still cause this situation. - Identifies the control, set by the application. * - __u32 - ``size`` - - The total size in bytes of the payload of this control. This is - normally 0, but for pointer controls this should be set to the - size of the memory containing the payload, or that will receive - the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is - less than is required to store the payload result, then it is set + - The total size in bytes of the payload of this control. + * - :cspan:`2` The ``size`` field is normally 0, but for pointer + controls this should be set to the size of the memory that contains + the payload or that will receive the payload. + If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value + is less than is required to store the payload result, then it is set to a value large enough to store the payload result and ``ENOSPC`` is returned. @@ -212,6 +217,18 @@ still cause this situation. - ``p_fwht_params`` - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. + * - struct :c:type:`v4l2_ctrl_vp8_frame` * + - ``p_vp8_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_VP8_FRAME``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -221,7 +238,11 @@ still cause this situation. * - } - -.. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}| +.. raw:: latex + + \normalsize + +.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}| .. c:type:: v4l2_ext_controls @@ -235,29 +256,18 @@ still cause this situation. * - union { - (anonymous) * - __u32 - - ``ctrl_class`` - - The control class to which all controls belong, see - :ref:`ctrl-class`. Drivers that use a kernel framework for - handling controls will also accept a value of 0 here, meaning that - the controls can belong to any control class. Whether drivers - support this can be tested by setting ``ctrl_class`` to 0 and - calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that - succeeds, then the driver supports this feature. - * - __u32 - ``which`` - Which value of the control to get/set/try. - ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of + the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that these controls have to be retrieved from a request or tried/set for a request. In the latter case the ``request_fd`` field contains the file descriptor of the request that should be used. If the device does not support requests, then ``EACCES`` will be returned. - .. note:: - - When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only - get the default value of the control, you cannot set or try it. + When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only + get the default value of the control, you cannot set or try it. For backwards compatibility you can also use a control class here (see :ref:`ctrl-class`). In that case all controls have to @@ -265,9 +275,12 @@ still cause this situation. just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and that require a control class here. You can test for such drivers - by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling - VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the - driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + by setting ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0. + If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + * - __u32 + - ``ctrl_class`` + - Deprecated name kept for backwards compatibility. Use ``which`` instead. * - } - * - __u32 @@ -275,7 +288,8 @@ still cause this situation. - The number of controls in the controls array. May also be zero. * - __u32 - ``error_idx`` - - Set by the driver in case of an error. If the error is associated + - Index of the failing control. Set by the driver in case of an error. + * - :cspan:`2` If the error is associated with a particular control, then ``error_idx`` is set to the index of that control. If the error is not related to a specific control, or the validation step failed (see below), then @@ -334,7 +348,9 @@ still cause this situation. Ignored if ``count`` equals zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}| + +.. cssclass:: longtable .. _ctrl-class: @@ -394,6 +410,10 @@ still cause this situation. - 0xa40000 - The class containing stateless codec controls. These controls are described in :ref:`codec-stateless-controls`. + * - ``V4L2_CTRL_CLASS_COLORIMETRY`` + - 0xa50000 + - The class containing colorimetry controls. These controls are + described in :ref:`colorimetry-controls`. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index dc1f16343b22..b6cc1a823207 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -75,7 +75,7 @@ jeopardize the system security, its stability or even damage the hardware, therefore only the superuser can set the parameters for a destructive video overlay. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_framebuffer @@ -207,7 +207,7 @@ destructive video overlay. - ``priv`` - Reserved. Drivers and applications must set this field to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-cap: @@ -255,7 +255,7 @@ destructive video overlay. chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst index 7e9f8475ea63..675c385e5aca 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst @@ -89,7 +89,7 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical .. c:type:: v4l2_format -.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| +.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}| .. flat-table:: struct v4l2_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst index 5445a4a442e4..0d037665a89e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst @@ -51,7 +51,7 @@ structure. When the requested frequency is not possible the driver assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a write-only ioctl, it does not return the actual new frequency. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_frequency diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst index 93ed111dfcb9..d4565d2cc1f5 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst @@ -54,7 +54,7 @@ stored in the JPEG-encoded fields. These define how the JPEG field is encoded. If you omit them, applications assume you've used standard encoding. You usually do want to add them. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. c:type:: v4l2_jpegcompression @@ -91,7 +91,7 @@ encoding. You usually do want to add them. control is exposed by a driver applications should use it instead and ignore this field. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _jpeg-markers: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst index 2ac2473e341b..6bdf925f9a4a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst @@ -60,7 +60,7 @@ context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_modulator @@ -119,8 +119,9 @@ To change the radio frequency the Drivers and applications must set the array to zero. +.. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _modulator-txsubchans: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 724f7fa7bae1..8b5600fbf013 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -56,7 +56,7 @@ To get and set the streaming parameters applications call the pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}| .. c:type:: v4l2_streamparm @@ -85,10 +85,9 @@ union holding separate parameters for input and output devices. - ``raw_data``\ [200] - A place holder for future extensions. * - } - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_captureparm @@ -147,7 +146,7 @@ union holding separate parameters for input and output devices. the array to zero. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_outputparm @@ -207,7 +206,7 @@ union holding separate parameters for input and output devices. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-caps: @@ -222,7 +221,7 @@ union holding separate parameters for input and output devices. field. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst index d72a0c716fca..3031256159c3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst @@ -45,7 +45,7 @@ with a pointer to this variable. .. c:type:: v4l2_priority -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_priority :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst index 9a9e589cce77..2b5b27260741 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst @@ -129,7 +129,7 @@ Selection targets and flags are documented in .. c:type:: v4l2_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_selection :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst index 752f7f5fae73..90d40f6af57b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -45,7 +45,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. .. c:type:: v4l2_sliced_vbi_cap -.. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}| .. flat-table:: struct v4l2_sliced_vbi_cap :header-rows: 0 @@ -122,7 +122,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. \scriptsize -.. tabularcolumns:: |p{3.5cm}|p{1.0cm}|p{2.0cm}|p{2.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}| .. _vbi-services: @@ -162,13 +162,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. :ref:`itu1119` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -176,10 +170,27 @@ the sliced VBI API is unsupported or ``type`` is invalid. - 0x4401 - :cspan:`2` Set of services applicable to 625 line systems. + .. raw:: latex \normalsize +.. _v4l2-sliced-vbi-cap-wss-625-payload: + +V4L2_SLICED_VBI_CAP WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst index 116e66c01556..b0522f1ff7a4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst @@ -59,7 +59,7 @@ to zero. The term 'tuner' means SDR receiver in this context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}| + .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}| .. c:type:: v4l2_tuner @@ -182,7 +182,7 @@ To change the radio frequency the Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. c:type:: v4l2_tuner_type @@ -205,7 +205,7 @@ To change the radio frequency the - 5 - Tuner controls the RF part of a Software Digital Radio (SDR) -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}| .. _tuner-capability: @@ -296,7 +296,7 @@ To change the radio frequency the instead of 62.5 kHz. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-rxsubchans: @@ -334,7 +334,7 @@ To change the radio frequency the - The tuner receives an RDS channel. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-audmode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index b512b1fbf9a3..63e23f6f95ee 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -38,10 +38,12 @@ pointer to a struct :c:type:`v4l2_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an ``EINVAL`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| - .. c:type:: v4l2_capability +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_capability :header-rows: 0 :stub-columns: 0 @@ -130,7 +132,7 @@ specification the ioctl returns an ``EINVAL`` error code. zero. -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.6cm}|p{7.7cm}| .. _device-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 82f61f1e2fb8..8a285daedc6a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -94,7 +94,7 @@ inclusive. See also the examples in :ref:`control`. -.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}| .. _v4l2-queryctrl: @@ -172,7 +172,7 @@ See also the examples in :ref:`control`. zero. -.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}| .. _v4l2-query-ext-ctrl: @@ -272,7 +272,7 @@ See also the examples in :ref:`control`. the array to zero. -.. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. _v4l2-querymenu: @@ -306,10 +306,13 @@ See also the examples in :ref:`control`. - Reserved for future extensions. Drivers must set the array to zero. +.. c:type:: v4l2_ctrl_type -.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| +.. raw:: latex -.. c:type:: v4l2_ctrl_type + \footnotesize + +.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}| .. cssclass:: longtable @@ -486,13 +489,23 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP8_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8 + frame parameters for stateless video decoders. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex -.. _control-flags: + \normalsize + +.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}| .. cssclass:: longtable +.. _control-flags: + .. flat-table:: Control Flags :header-rows: 0 :stub-columns: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index c1c88e00b106..50ea72043bb0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -71,7 +71,7 @@ aborting or finishing any DMA in progress, an implicit .. c:type:: v4l2_requestbuffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_requestbuffers :header-rows: 0 @@ -109,8 +109,6 @@ aborting or finishing any DMA in progress, an implicit - A place holder for future extensions. Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| - .. _v4l2-buf-capabilities: .. _V4L2-BUF-CAP-SUPPORTS-MMAP: .. _V4L2-BUF-CAP-SUPPORTS-USERPTR: @@ -120,6 +118,12 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.1cm}|p{2.2cm}|p{7.0cm}| + .. cssclass:: longtable .. flat-table:: V4L2 Buffer Capabilities Flags @@ -157,6 +161,10 @@ aborting or finishing any DMA in progress, an implicit :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. +.. raw:: latex + + \normalsize + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst index 1948f31c2dbc..ed10f380579a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst @@ -58,7 +58,7 @@ set. If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` error code is returned and no seek takes place. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_hw_freq_seek diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 17acf3fd8396..3703943b412f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -61,7 +61,7 @@ multiple pads of the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval_enum :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index 8016fba7023f..c25a9896df0e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -63,7 +63,7 @@ information about try formats. .. c:type:: v4l2_subdev_frame_size_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_size_enum :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 1fd950e34a0b..417f1a19bcc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -48,7 +48,7 @@ information about the try formats. .. c:type:: v4l2_subdev_mbus_code_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_mbus_code_enum :header-rows: 0 @@ -79,7 +79,11 @@ information about the try formats. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{7.7cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.8cm}|p{2.2cm}|p{6.3cm}| .. _v4l2-subdev-mbus-code-flags: @@ -124,6 +128,10 @@ information about the try formats. ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. See :ref:`v4l2-mbus-format` on how to do this. +.. raw:: latex + + \normalsize + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index 2d78b4f5928d..bd15c0a5a66b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -78,7 +78,7 @@ modified format should be as close as possible to the original request. .. c:type:: v4l2_subdev_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_crop :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 90b9bbfb61dd..7acdbb939d89 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -81,7 +81,7 @@ doesn't match the device capabilities. They must instead modify the format to match what the hardware can provide. The modified format should be as close as possible to the original request. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_subdev_format @@ -107,7 +107,7 @@ should be as close as possible to the original request. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _v4l2-subdev-format-whence: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index 3a50f8b2843d..d7fe7543c506 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -76,7 +76,7 @@ the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index f35b9562df21..f9172a42f036 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -70,7 +70,7 @@ Selection targets and flags are documented in .. c:type:: v4l2_subdev_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_selection :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst index 949d9775b03d..9b8d8644ec0f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst @@ -38,7 +38,7 @@ a struct :c:type:`v4l2_subdev_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns ``ENOTTY`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| .. c:type:: v4l2_subdev_capability @@ -75,7 +75,7 @@ the driver is not compatible with this specification the ioctl returns - ``reserved``\ [14] - Reserved for future extensions. Set to 0 by the V4L2 core. -.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| .. _subdevice-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst index d1ad35164033..a6fc3c5fe99d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst @@ -39,7 +39,7 @@ Description Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by using the :ref:`VIDIOC_DQEVENT` ioctl. -.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}| .. c:type:: v4l2_event_subscription @@ -71,7 +71,7 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. the array to zero. -.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}| .. _event-flags: diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index 0ed170c6e720..f59940352faa 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -147,6 +147,9 @@ replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index bd9165241b6c..6efb41cc8072 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -250,14 +250,14 @@ Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (or ``poll()``) on a seccomp notification fd to receive a ``struct seccomp_notif``, which contains five members: the input length of the structure, a unique-per-filter ``id``, the ``pid`` of the task which triggered this request (which may be 0 if the -task is in a pid ns not visible from the listener's pid namespace), a ``flags`` -member which for now only has ``SECCOMP_NOTIF_FLAG_SIGNALED``, representing -whether or not the notification is a result of a non-fatal signal, and the -``data`` passed to seccomp. Userspace can then make a decision based on this -information about what to do, and ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` a -response, indicating what should be returned to userspace. The ``id`` member of -``struct seccomp_notif_resp`` should be the same ``id`` as in ``struct -seccomp_notif``. +task is in a pid ns not visible from the listener's pid namespace). The +notification also contains the ``data`` passed to seccomp, and a filters flag. +The structure should be zeroed out prior to calling the ioctl. + +Userspace can then make a decision based on this information about what to do, +and ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` a response, indicating what should be +returned to userspace. The ``id`` member of ``struct seccomp_notif_resp`` should +be the same ``id`` as in ``struct seccomp_notif``. It is worth noting that ``struct seccomp_data`` contains the values of register arguments to the syscall, but does not contain pointers to memory. The task's diff --git a/Documentation/virt/kvm/amd-memory-encryption.rst b/Documentation/virt/kvm/amd-memory-encryption.rst index 469a6308765b..5c081c8c7164 100644 --- a/Documentation/virt/kvm/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/amd-memory-encryption.rst @@ -22,7 +22,7 @@ to SEV:: [ecx]: Bits[31:0] Number of encrypted guests supported simultaneously -If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015 +If support for SEV is present, MSR 0xc001_0010 (MSR_AMD64_SYSCFG) and MSR 0xc001_0015 (MSR_K7_HWCR) can be used to determine if it can be enabled:: 0xc001_0010: @@ -148,6 +148,9 @@ measurement. Since the guest owner knows the initial contents of the guest at boot, the measurement can be verified by comparing it to what the guest owner expects. +If len is zero on entry, the measurement blob length is written to len and +uaddr is unused. + Parameters (in): struct kvm_sev_launch_measure Returns: 0 on success, -negative on error @@ -271,6 +274,9 @@ report containing the SHA-256 digest of the guest memory and VMSA passed through commands and signed with the PEK. The digest returned by the command should match the digest used by the guest owner with the KVM_SEV_LAUNCH_MEASURE. +If len is zero on entry, the measurement blob length is written to len and +uaddr is unused. + Parameters (in): struct kvm_sev_attestation Returns: 0 on success, -negative on error @@ -284,6 +290,143 @@ Returns: 0 on success, -negative on error __u32 len; }; +11. KVM_SEV_SEND_START +---------------------- + +The KVM_SEV_SEND_START command can be used by the hypervisor to create an +outgoing guest encryption context. + +If session_len is zero on entry, the length of the guest session information is +written to session_len and all other fields are not used. + +Parameters (in): struct kvm_sev_send_start + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_send_start { + __u32 policy; /* guest policy */ + + __u64 pdh_cert_uaddr; /* platform Diffie-Hellman certificate */ + __u32 pdh_cert_len; + + __u64 plat_certs_uaddr; /* platform certificate chain */ + __u32 plat_certs_len; + + __u64 amd_certs_uaddr; /* AMD certificate */ + __u32 amd_certs_len; + + __u64 session_uaddr; /* Guest session information */ + __u32 session_len; + }; + +12. KVM_SEV_SEND_UPDATE_DATA +---------------------------- + +The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the +outgoing guest memory region with the encryption context creating using +KVM_SEV_SEND_START. + +If hdr_len or trans_len are zero on entry, the length of the packet header and +transport region are written to hdr_len and trans_len respectively, and all +other fields are not used. + +Parameters (in): struct kvm_sev_send_update_data + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_send_update_data { + __u64 hdr_uaddr; /* userspace address containing the packet header */ + __u32 hdr_len; + + __u64 guest_uaddr; /* the source memory region to be encrypted */ + __u32 guest_len; + + __u64 trans_uaddr; /* the destination memory region */ + __u32 trans_len; + }; + +13. KVM_SEV_SEND_FINISH +------------------------ + +After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be +issued by the hypervisor to delete the encryption context. + +Returns: 0 on success, -negative on error + +14. KVM_SEV_SEND_CANCEL +------------------------ + +After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the +SEND_CANCEL command to stop a migration. This is necessary so that a cancelled +migration can restart with a new target later. + +Returns: 0 on success, -negative on error + +15. KVM_SEV_RECEIVE_START +------------------------- + +The KVM_SEV_RECEIVE_START command is used for creating the memory encryption +context for an incoming SEV guest. To create the encryption context, the user must +provide a guest policy, the platform public Diffie-Hellman (PDH) key and session +information. + +Parameters: struct kvm_sev_receive_start (in/out) + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_receive_start { + __u32 handle; /* if zero then firmware creates a new handle */ + __u32 policy; /* guest's policy */ + + __u64 pdh_uaddr; /* userspace address pointing to the PDH key */ + __u32 pdh_len; + + __u64 session_uaddr; /* userspace address which points to the guest session information */ + __u32 session_len; + }; + +On success, the 'handle' field contains a new handle and on error, a negative value. + +For more details, see SEV spec Section 6.12. + +16. KVM_SEV_RECEIVE_UPDATE_DATA +------------------------------- + +The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy +the incoming buffers into the guest memory region with encryption context +created during the KVM_SEV_RECEIVE_START. + +Parameters (in): struct kvm_sev_receive_update_data + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_receive_update_data { + __u64 hdr_uaddr; /* userspace address containing the packet header */ + __u32 hdr_len; + + __u64 guest_uaddr; /* the destination guest memory region */ + __u32 guest_len; + + __u64 trans_uaddr; /* the incoming buffer memory region */ + __u32 trans_len; + }; + +17. KVM_SEV_RECEIVE_FINISH +-------------------------- + +After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be +issued by the hypervisor to make the guest ready for execution. + +Returns: 0 on success, -negative on error + References ========== diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 307f2fcf1b02..7fcb2fd38f42 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -55,7 +55,7 @@ not cause harm to the host, their actual behavior is not guaranteed by the API. See "General description" for details on the ioctl usage model that is supported by KVM. -It is important to note that althought VM ioctls may only be issued from +It is important to note that although VM ioctls may only be issued from the process that created the VM, a VM's lifecycle is associated with its file descriptor, not its creator (process). In other words, the VM and its resources, *including the associated address space*, are not freed @@ -204,7 +204,7 @@ Errors: ====== ============================================================ EFAULT the msr index list cannot be read from or written to - E2BIG the msr index list is to be to fit in the array specified by + E2BIG the msr index list is too big to fit in the array specified by the user. ====== ============================================================ @@ -3116,6 +3116,18 @@ optional features it should have. This will cause a reset of the cpu registers to their initial values. If this is not called, KVM_RUN will return ENOEXEC for that vcpu. +The initial values are defined as: + - Processor state: + * AArch64: EL1h, D, A, I and F bits set. All other bits + are cleared. + * AArch32: SVC, A, I and F bits set. All other bits are + cleared. + - General Purpose registers, including PC and SP: set to 0 + - FPSIMD/NEON registers: set to 0 + - SVE registers: set to 0 + - System registers: Reset to their architecturally defined + values as for a warm reset to EL1 (resp. SVC) + Note that because some registers reflect machine topology, all vcpus should be created before this ioctl is invoked. @@ -3335,7 +3347,8 @@ The top 16 bits of the control field are architecture specific control flags which can include the following: - KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64] - - KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390, arm64] + - KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390] + - KVM_GUESTDBG_USE_HW: using hardware debug events [arm64] - KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86] - KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86] - KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390] @@ -3358,6 +3371,9 @@ indicating the number of supported registers. For ppc, the KVM_CAP_PPC_GUEST_DEBUG_SSTEP capability indicates whether the single-step debug event (KVM_GUESTDBG_SINGLESTEP) is supported. +Also when supported, KVM_CAP_SET_GUEST_DEBUG2 capability indicates the +supported KVM_GUESTDBG_* bits in the control field. + When debug events exit the main run loop with the reason KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run structure containing architecture specific debug information. @@ -3690,31 +3706,105 @@ which is the maximum number of possibly pending cpu-local interrupts. Queues an SMI on the thread's vcpu. -4.97 KVM_CAP_PPC_MULTITCE -------------------------- +4.97 KVM_X86_SET_MSR_FILTER +---------------------------- -:Capability: KVM_CAP_PPC_MULTITCE -:Architectures: ppc -:Type: vm +:Capability: KVM_X86_SET_MSR_FILTER +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_msr_filter +:Returns: 0 on success, < 0 on error -This capability means the kernel is capable of handling hypercalls -H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user -space. This significantly accelerates DMA operations for PPC KVM guests. -User space should expect that its handlers for these hypercalls -are not going to be called if user space previously registered LIOBN -in KVM (via KVM_CREATE_SPAPR_TCE or similar calls). +:: -In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest, -user space might have to advertise it for the guest. For example, -IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is -present in the "ibm,hypertas-functions" device-tree property. + struct kvm_msr_filter_range { + #define KVM_MSR_FILTER_READ (1 << 0) + #define KVM_MSR_FILTER_WRITE (1 << 1) + __u32 flags; + __u32 nmsrs; /* number of msrs in bitmap */ + __u32 base; /* MSR index the bitmap starts at */ + __u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */ + }; -The hypercalls mentioned above may or may not be processed successfully -in the kernel based fast path. If they can not be handled by the kernel, -they will get passed on to user space. So user space still has to have -an implementation for these despite the in kernel acceleration. + #define KVM_MSR_FILTER_MAX_RANGES 16 + struct kvm_msr_filter { + #define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0) + #define KVM_MSR_FILTER_DEFAULT_DENY (1 << 0) + __u32 flags; + struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES]; + }; -This capability is always enabled. +flags values for ``struct kvm_msr_filter_range``: + +``KVM_MSR_FILTER_READ`` + + Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap + indicates that a read should immediately fail, while a 1 indicates that + a read for a particular MSR should be handled regardless of the default + filter action. + +``KVM_MSR_FILTER_WRITE`` + + Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap + indicates that a write should immediately fail, while a 1 indicates that + a write for a particular MSR should be handled regardless of the default + filter action. + +``KVM_MSR_FILTER_READ | KVM_MSR_FILTER_WRITE`` + + Filter both read and write accesses to MSRs using the given bitmap. A 0 + in the bitmap indicates that both reads and writes should immediately fail, + while a 1 indicates that reads and writes for a particular MSR are not + filtered by this range. + +flags values for ``struct kvm_msr_filter``: + +``KVM_MSR_FILTER_DEFAULT_ALLOW`` + + If no filter range matches an MSR index that is getting accessed, KVM will + fall back to allowing access to the MSR. + +``KVM_MSR_FILTER_DEFAULT_DENY`` + + If no filter range matches an MSR index that is getting accessed, KVM will + fall back to rejecting access to the MSR. In this mode, all MSRs that should + be processed by KVM need to explicitly be marked as allowed in the bitmaps. + +This ioctl allows user space to define up to 16 bitmaps of MSR ranges to +specify whether a certain MSR access should be explicitly filtered for or not. + +If this ioctl has never been invoked, MSR accesses are not guarded and the +default KVM in-kernel emulation behavior is fully preserved. + +Calling this ioctl with an empty set of ranges (all nmsrs == 0) disables MSR +filtering. In that mode, ``KVM_MSR_FILTER_DEFAULT_DENY`` is invalid and causes +an error. + +As soon as the filtering is in place, every MSR access is processed through +the filtering except for accesses to the x2APIC MSRs (from 0x800 to 0x8ff); +x2APIC MSRs are always allowed, independent of the ``default_allow`` setting, +and their behavior depends on the ``X2APIC_ENABLE`` bit of the APIC base +register. + +If a bit is within one of the defined ranges, read and write accesses are +guarded by the bitmap's value for the MSR index if the kind of access +is included in the ``struct kvm_msr_filter_range`` flags. If no range +cover this particular access, the behavior is determined by the flags +field in the kvm_msr_filter struct: ``KVM_MSR_FILTER_DEFAULT_ALLOW`` +and ``KVM_MSR_FILTER_DEFAULT_DENY``. + +Each bitmap range specifies a range of MSRs to potentially allow access on. +The range goes from MSR index [base .. base+nmsrs]. The flags field +indicates whether reads, writes or both reads and writes are filtered +by setting a 1 bit in the bitmap for the corresponding MSR index. + +If an MSR access is not permitted through the filtering, it generates a +#GP inside the guest. When combined with KVM_CAP_X86_USER_SPACE_MSR, that +allows user space to deflect and potentially handle various MSR accesses +into user space. + +If a vCPU is in running state while this ioctl is invoked, the vCPU may +experience inconsistent filtering behavior on MSR accesses. 4.98 KVM_CREATE_SPAPR_TCE_64 ---------------------------- @@ -4713,7 +4803,7 @@ KVM_PV_VM_VERIFY 4.126 KVM_X86_SET_MSR_FILTER ---------------------------- -:Capability: KVM_X86_SET_MSR_FILTER +:Capability: KVM_CAP_X86_MSR_FILTER :Architectures: x86 :Type: vm ioctl :Parameters: struct kvm_msr_filter @@ -4855,7 +4945,7 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. -4.128 KVM_XEN_HVM_GET_ATTR +4.127 KVM_XEN_HVM_GET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO @@ -4867,7 +4957,7 @@ KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Allows Xen VM attributes to be read. For the structure and types, see KVM_XEN_HVM_SET_ATTR above. -4.129 KVM_XEN_VCPU_SET_ATTR +4.128 KVM_XEN_VCPU_SET_ATTR --------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO @@ -4929,7 +5019,7 @@ KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST or RUNSTATE_offline) to set the current accounted state as of the adjusted state_entry_time. -4.130 KVM_XEN_VCPU_GET_ATTR +4.129 KVM_XEN_VCPU_GET_ATTR --------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO @@ -6233,6 +6323,45 @@ KVM_RUN_BUS_LOCK flag is used to distinguish between them. This capability can be used to check / enable 2nd DAWR feature provided by POWER10 processor. +7.24 KVM_CAP_VM_COPY_ENC_CONTEXT_FROM +------------------------------------- + +Architectures: x86 SEV enabled +Type: vm +Parameters: args[0] is the fd of the source vm +Returns: 0 on success; ENOTTY on error + +This capability enables userspace to copy encryption context from the vm +indicated by the fd to the vm this is called on. + +This is intended to support in-guest workloads scheduled by the host. This +allows the in-guest workload to maintain its own NPTs and keeps the two vms +from accidentally clobbering each other with interrupts and the like (separate +APIC/MSRs/etc). + +7.25 KVM_CAP_SGX_ATTRIBUTE +-------------------------- + +:Architectures: x86 +:Target: VM +:Parameters: args[0] is a file handle of a SGX attribute file in securityfs +:Returns: 0 on success, -EINVAL if the file handle is invalid or if a requested + attribute is not supported by KVM. + +KVM_CAP_SGX_ATTRIBUTE enables a userspace VMM to grant a VM access to one or +more priveleged enclave attributes. args[0] must hold a file handle to a valid +SGX attribute file corresponding to an attribute that is supported/restricted +by KVM (currently only PROVISIONKEY). + +The SGX subsystem restricts access to a subset of enclave attributes to provide +additional security for an uncompromised kernel, e.g. use of the PROVISIONKEY +is restricted to deter malware from using the PROVISIONKEY to obtain a stable +system fingerprint. To prevent userspace from circumventing such restrictions +by running an enclave in a VM, KVM prevents access to privileged attributes by +default. + +See Documentation/x86/sgx/2.Kernel-internals.rst for more details. + 8. Other capabilities. ====================== @@ -6586,7 +6715,7 @@ accesses that would usually trigger a #GP by KVM into the guest will instead get bounced to user space through the KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. -8.27 KVM_X86_SET_MSR_FILTER +8.27 KVM_CAP_X86_MSR_FILTER --------------------------- :Architectures: x86 @@ -6727,3 +6856,38 @@ vcpu_info is set. 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. + +8.31 KVM_CAP_PPC_MULTITCE +------------------------- + +:Capability: KVM_CAP_PPC_MULTITCE +:Architectures: ppc +:Type: vm + +This capability means the kernel is capable of handling hypercalls +H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user +space. This significantly accelerates DMA operations for PPC KVM guests. +User space should expect that its handlers for these hypercalls +are not going to be called if user space previously registered LIOBN +in KVM (via KVM_CREATE_SPAPR_TCE or similar calls). + +In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest, +user space might have to advertise it for the guest. For example, +IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is +present in the "ibm,hypertas-functions" device-tree property. + +The hypercalls mentioned above may or may not be processed successfully +in the kernel based fast path. If they can not be handled by the kernel, +they will get passed on to user space. So user space still has to have +an implementation for these despite the in kernel acceleration. + +This capability is always enabled. + +8.32 KVM_CAP_PTP_KVM +-------------------- + +:Architectures: arm64 + +This capability indicates that the KVM virtual PTP service is +supported in the host. A VMM can check whether the service is +available to the guest on migration. diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index 3e2b2aba90fc..78a9b670aafe 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -10,3 +10,4 @@ ARM hyp-abi psci pvtime + ptp_kvm diff --git a/Documentation/virt/kvm/arm/ptp_kvm.rst b/Documentation/virt/kvm/arm/ptp_kvm.rst new file mode 100644 index 000000000000..aecdc80ddcd8 --- /dev/null +++ b/Documentation/virt/kvm/arm/ptp_kvm.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +PTP_KVM support for arm/arm64 +============================= + +PTP_KVM is used for high precision time sync between host and guests. +It relies on transferring the wall clock and counter value from the +host to the guest using a KVM-specific hypercall. + +* ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID: 0x86000001 + +This hypercall uses the SMC32/HVC32 calling convention: + +ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID + ============== ======== ===================================== + Function ID: (uint32) 0x86000001 + Arguments: (uint32) KVM_PTP_VIRT_COUNTER(0) + KVM_PTP_PHYS_COUNTER(1) + Return Values: (int32) NOT_SUPPORTED(-1) on error, or + (uint32) Upper 32 bits of wall clock time (r0) + (uint32) Lower 32 bits of wall clock time (r1) + (uint32) Upper 32 bits of counter (r2) + (uint32) Lower 32 bits of counter (r3) + Endianness: No Restrictions. + ============== ======== ===================================== diff --git a/Documentation/virt/kvm/devices/arm-vgic-its.rst b/Documentation/virt/kvm/devices/arm-vgic-its.rst index 6c304fd2b1b4..d257eddbae29 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-its.rst +++ b/Documentation/virt/kvm/devices/arm-vgic-its.rst @@ -80,7 +80,7 @@ KVM_DEV_ARM_VGIC_GRP_CTRL -EFAULT Invalid guest ram access -EBUSY One or more VCPUS are running -EACCES The virtual ITS is backed by a physical GICv4 ITS, and the - state is not available + state is not available without GICv4.1 ======= ========================================================== KVM_DEV_ARM_VGIC_GRP_ITS_REGS diff --git a/Documentation/virt/kvm/devices/arm-vgic-v3.rst b/Documentation/virt/kvm/devices/arm-vgic-v3.rst index 5dd3bff51978..51e5e5762571 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-v3.rst +++ b/Documentation/virt/kvm/devices/arm-vgic-v3.rst @@ -228,7 +228,7 @@ Groups: KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the VGIC, no additional parameter in - kvm_device_attr.addr. + kvm_device_attr.addr. Must be called after all VCPUs have been created. KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES save all LPI pending bits into guest RAM pending tables. diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index 0aa4817b466d..1fc860c007a3 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -38,25 +38,24 @@ the mmu-lock on x86. Currently, the page fault can be fast in one of the following two cases: 1. Access Tracking: The SPTE is not present, but it is marked for access - tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to - restore the saved R/X bits. This is described in more detail later below. + tracking. That means we need to restore the saved R/X bits. This is + described in more detail later below. -2. Write-Protection: The SPTE is present and the fault is - caused by write-protect. That means we just need to change the W bit of - the spte. +2. Write-Protection: The SPTE is present and the fault is caused by + write-protect. That means we just need to change the W bit of the spte. -What we use to avoid all the race is the SPTE_HOST_WRITEABLE bit and -SPTE_MMU_WRITEABLE bit on the spte: +What we use to avoid all the race is the Host-writable bit and MMU-writable bit +on the spte: -- SPTE_HOST_WRITEABLE means the gfn is writable on host. -- SPTE_MMU_WRITEABLE means the gfn is writable on mmu. The bit is set when - the gfn is writable on guest mmu and it is not write-protected by shadow - page write-protection. +- Host-writable means the gfn is writable in the host kernel page tables and in + its KVM memslot. +- MMU-writable means the gfn is writable in the guest's mmu and it is not + write-protected by shadow page write-protection. On fast page fault path, we will use cmpxchg to atomically set the spte W -bit if spte.SPTE_HOST_WRITEABLE = 1 and spte.SPTE_WRITE_PROTECT = 1, or -restore the saved R/X bits if VMX_EPT_TRACK_ACCESS mask is set, or both. This -is safe because whenever changing these bits can be detected by cmpxchg. +bit if spte.HOST_WRITEABLE = 1 and spte.WRITE_PROTECT = 1, to restore the saved +R/X bits if for an access-traced spte, or both. This is safe because whenever +changing these bits can be detected by cmpxchg. But we need carefully check these cases: @@ -185,17 +184,17 @@ See the comments in spte_has_volatile_bits() and mmu_spte_update(). Lockless Access Tracking: This is used for Intel CPUs that are using EPT but do not support the EPT A/D -bits. In this case, when the KVM MMU notifier is called to track accesses to a -page (via kvm_mmu_notifier_clear_flush_young), it marks the PTE as not-present -by clearing the RWX bits in the PTE and storing the original R & X bits in -some unused/ignored bits. In addition, the SPTE_SPECIAL_MASK is also set on the -PTE (using the ignored bit 62). When the VM tries to access the page later on, -a fault is generated and the fast page fault mechanism described above is used -to atomically restore the PTE to a Present state. The W bit is not saved when -the PTE is marked for access tracking and during restoration to the Present -state, the W bit is set depending on whether or not it was a write access. If -it wasn't, then the W bit will remain clear until a write access happens, at -which time it will be set using the Dirty tracking mechanism described above. +bits. In this case, PTEs are tagged as A/D disabled (using ignored bits), and +when the KVM MMU notifier is called to track accesses to a page (via +kvm_mmu_notifier_clear_flush_young), it marks the PTE not-present in hardware +by clearing the RWX bits in the PTE and storing the original R & X bits in more +unused/ignored bits. When the VM tries to access the page later on, a fault is +generated and the fast page fault mechanism described above is used to +atomically restore the PTE to a Present state. The W bit is not saved when the +PTE is marked for access tracking and during restoration to the Present state, +the W bit is set depending on whether or not it was a write access. If it +wasn't, then the W bit will remain clear until a write access happens, at which +time it will be set using the Dirty tracking mechanism described above. 3. Reference ------------ diff --git a/Documentation/virt/kvm/mmu.rst b/Documentation/virt/kvm/mmu.rst index 5bfe28b0728e..20d85daed395 100644 --- a/Documentation/virt/kvm/mmu.rst +++ b/Documentation/virt/kvm/mmu.rst @@ -171,8 +171,8 @@ Shadow pages contain the following information: shadow pages) so role.quadrant takes values in the range 0..3. Each quadrant maps 1GB virtual address space. role.access: - Inherited guest access permissions in the form uwx. Note execute - permission is positive, not negative. + Inherited guest access permissions from the parent ptes in the form uwx. + Note execute permission is positive, not negative. role.invalid: 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 diff --git a/Documentation/virt/kvm/s390-diag.rst b/Documentation/virt/kvm/s390-diag.rst index eaac4864d3d6..ca85f030eb0b 100644 --- a/Documentation/virt/kvm/s390-diag.rst +++ b/Documentation/virt/kvm/s390-diag.rst @@ -84,3 +84,36 @@ If the function code specifies 0x501, breakpoint functions may be performed. This function code is handled by userspace. This diagnose function code has no subfunctions and uses no parameters. + + +DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield +--------------------------------------------------------- + +General register 1 contains the target CPU address. + +In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs, +DIAGNOSE with function code 0x9c may improve system performance by +yielding the host CPU on which the guest CPU is running to be assigned +to another guest CPU, preferably the logical CPU containing the specified +target CPU. + + +DIAG 'X'9C forwarding ++++++++++++++++++++++ + +The guest may send a DIAGNOSE 0x9c in order to yield to a certain +other vcpu. An example is a Linux guest that tries to yield to the vcpu +that is currently holding a spinlock, but not running. + +However, on the host the real cpu backing the vcpu may itself not be +running. +Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to +the backing cpu will hopefully cause that cpu, and thus subsequently +the guest's vcpu, to be scheduled. + + +diag9c_forwarding_hz + KVM kernel parameter allowing to specify the maximum number of DIAGNOSE + 0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c + forwarding storm. + A value of 0 turns the forwarding off. diff --git a/Documentation/virt/kvm/vcpu-requests.rst b/Documentation/virt/kvm/vcpu-requests.rst index 5feb3706a7ae..af1b37441e0a 100644 --- a/Documentation/virt/kvm/vcpu-requests.rst +++ b/Documentation/virt/kvm/vcpu-requests.rst @@ -118,10 +118,12 @@ KVM_REQ_MMU_RELOAD necessary to inform each VCPU to completely refresh the tables. This request is used for that. -KVM_REQ_PENDING_TIMER +KVM_REQ_UNBLOCK - This request may be made from a timer handler run on the host on behalf - of a VCPU. It informs the VCPU thread to inject a timer interrupt. + This request informs the vCPU to exit kvm_vcpu_block. It is used for + example from timer handlers that run on the host on behalf of a vCPU, + or in order to update the interrupt routing and ensure that assigned + devices will wake up the vCPU. KVM_REQ_UNHALT diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst index 4e67c2e9bbed..2175465c9bf2 100644 --- a/Documentation/vm/page_owner.rst +++ b/Documentation/vm/page_owner.rst @@ -47,7 +47,7 @@ size change due to this facility. text data bss dec hex filename 48800 2445 644 51889 cab1 mm/page_alloc.o - 6574 108 29 6711 1a37 mm/page_owner.o + 6662 108 29 6799 1a8f mm/page_owner.o 1025 8 8 1041 411 mm/page_ext.o Although, roughly, 8 KB code is added in total, page_alloc.o increase by diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst index 03f294a638bd..d3028554b1e9 100644 --- a/Documentation/vm/slub.rst +++ b/Documentation/vm/slub.rst @@ -181,7 +181,7 @@ SLUB Debug output Here is a sample of slub debug output:: ==================================================================== - BUG kmalloc-8: Redzone overwritten + BUG kmalloc-8: Right Redzone overwritten -------------------------------------------------------------------- INFO: 0xc90f6d28-0xc90f6d2b. First byte 0x00 instead of 0xcc @@ -189,10 +189,10 @@ Here is a sample of slub debug output:: INFO: Object 0xc90f6d20 @offset=3360 fp=0xc90f6d58 INFO: Allocated in get_modalias+0x61/0xf5 age=53 cpu=1 pid=554 - Bytes b4 0xc90f6d10: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ - Object 0xc90f6d20: 31 30 31 39 2e 30 30 35 1019.005 - Redzone 0xc90f6d28: 00 cc cc cc . - Padding 0xc90f6d50: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ + Bytes b4 (0xc90f6d10): 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ + Object (0xc90f6d20): 31 30 31 39 2e 30 30 35 1019.005 + Redzone (0xc90f6d28): 00 cc cc cc . + Padding (0xc90f6d50): 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ [<c010523d>] dump_trace+0x63/0x1eb [<c01053df>] show_trace_log_lvl+0x1a/0x2f diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst index 0ed23e59abe5..216db1d67d04 100644 --- a/Documentation/vm/transhuge.rst +++ b/Documentation/vm/transhuge.rst @@ -53,11 +53,6 @@ prevent the page from being split by anyone. of handling GUP on hugetlbfs will also work fine on transparent hugepage backed mappings. -In case you can't handle compound pages if they're returned by -follow_page, the FOLL_SPLIT bit can be specified as a parameter to -follow_page, so that it will split the hugepages before returning -them. - Graceful fallback ================= diff --git a/Documentation/watchdog/pcwd-watchdog.rst b/Documentation/watchdog/pcwd-watchdog.rst index 405e2a370082..151505c856f6 100644 --- a/Documentation/watchdog/pcwd-watchdog.rst +++ b/Documentation/watchdog/pcwd-watchdog.rst @@ -47,7 +47,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> WDIOC_GETSTATUS This returns the status of the card, with the bits of WDIOF_* bitwise-anded into the value. (The comments - are in linux/pcwd.h) + are in include/uapi/linux/watchdog.h) WDIOC_GETBOOTSTATUS This returns the status of the card that was reported diff --git a/Documentation/x86/amd-memory-encryption.rst b/Documentation/x86/amd-memory-encryption.rst index c48d452d0718..a1940ebe7be5 100644 --- a/Documentation/x86/amd-memory-encryption.rst +++ b/Documentation/x86/amd-memory-encryption.rst @@ -53,7 +53,7 @@ CPUID function 0x8000001f reports information related to SME:: system physical addresses, not guest physical addresses) -If support for SME is present, MSR 0xc00100010 (MSR_K8_SYSCFG) can be used to +If support for SME is present, MSR 0xc00100010 (MSR_AMD64_SYSCFG) can be used to determine if SME is enabled and/or to enable memory encryption:: 0xc0010010: @@ -79,7 +79,7 @@ The state of SME in the Linux kernel can be documented as follows: The CPU supports SME (determined through CPUID instruction). - Enabled: - Supported and bit 23 of MSR_K8_SYSCFG is set. + Supported and bit 23 of MSR_AMD64_SYSCFG is set. - Active: Supported, Enabled and the Linux kernel is actively applying @@ -89,7 +89,7 @@ The state of SME in the Linux kernel can be documented as follows: SME can also be enabled and activated in the BIOS. If SME is enabled and activated in the BIOS, then all memory accesses will be encrypted and it will not be necessary to activate the Linux memory encryption support. If the BIOS -merely enables SME (sets bit 23 of the MSR_K8_SYSCFG), then Linux can activate +merely enables SME (sets bit 23 of the MSR_AMD64_SYSCFG), then Linux can activate memory encryption by default (CONFIG_AMD_MEM_ENCRYPT_ACTIVE_BY_DEFAULT=y) or by supplying mem_encrypt=on on the kernel command line. However, if BIOS does not enable SME, then Linux will not be able to activate memory encryption, even diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst index eaee1368b4fd..dd0ac96ff9ef 100644 --- a/Documentation/x86/sgx.rst +++ b/Documentation/x86/sgx.rst @@ -209,3 +209,44 @@ An application may be loaded into a container enclave which is specially configured with a library OS and run-time which permits the application to run. The enclave run-time and library OS work together to execute the application when a thread enters the enclave. + +Impact of Potential Kernel SGX Bugs +=================================== + +EPC leaks +--------- + +When EPC page leaks happen, a WARNING like this is shown in dmesg: + +"EREMOVE returned ... and an EPC page was leaked. SGX may become unusable..." + +This is effectively a kernel use-after-free of an EPC page, and due +to the way SGX works, the bug is detected at freeing. Rather than +adding the page back to the pool of available EPC pages, the kernel +intentionally leaks the page to avoid additional errors in the future. + +When this happens, the kernel will likely soon leak more EPC pages, and +SGX will likely become unusable because the memory available to SGX is +limited. However, while this may be fatal to SGX, the rest of the kernel +is unlikely to be impacted and should continue to work. + +As a result, when this happpens, user should stop running any new +SGX workloads, (or just any new workloads), and migrate all valuable +workloads. Although a machine reboot can recover all EPC memory, the bug +should be reported to Linux developers. + + +Virtual EPC +=========== + +The implementation has also a virtual EPC driver to support SGX enclaves +in guests. Unlike the SGX driver, an EPC page allocated by the virtual +EPC driver doesn't have a specific enclave associated with it. This is +because KVM doesn't track how a guest uses EPC pages. + +As a result, the SGX core page reclaimer doesn't support reclaiming EPC +pages allocated to KVM guests through the virtual EPC driver. If the +user wants to deploy SGX applications both on the host and in guests +on the same machine, the user should reserve enough EPC (by taking out +total virtual EPC size of all SGX VMs from the physical EPC size) for +host SGX applications so they can run with acceptable performance. diff --git a/Documentation/x86/x86_64/5level-paging.rst b/Documentation/x86/x86_64/5level-paging.rst index 44856417e6a5..b792bbdc0b01 100644 --- a/Documentation/x86/x86_64/5level-paging.rst +++ b/Documentation/x86/x86_64/5level-paging.rst @@ -6,9 +6,9 @@ Overview ======== -Original x86-64 was limited by 4-level paing to 256 TiB of virtual address +Original x86-64 was limited by 4-level paging to 256 TiB of virtual address space and 64 TiB of physical address space. We are already bumping into -this limit: some vendors offers servers with 64 TiB of memory today. +this limit: some vendors offer servers with 64 TiB of memory today. To overcome the limitation upcoming hardware will introduce support for 5-level paging. It is a straight-forward extension of the current page |
