diff options
Diffstat (limited to 'Documentation')
540 files changed, 18065 insertions, 10568 deletions
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1 index 140d85b4ae92..992dfb183ed0 100644 --- a/Documentation/ABI/stable/sysfs-bus-w1 +++ b/Documentation/ABI/stable/sysfs-bus-w1 @@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component. control systems are attached/generate presence for as short as 100 ms - hence the tens-to-hundreds milliseconds scan intervals are required. - see Documentation/w1/w1.generic for detailed information. + see Documentation/w1/w1-generic.rst for detailed information. Users: any user space application which wants to know bus scanning interval diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 index 26579ee868c9..3e1c1fa8d54d 100644 --- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 @@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio Date: May 2012 Contact: Markus Franke <franm@hrz.tu-chemnitz.de> Description: read/write the contents of the two PIO's of the DS28E04-100 - see Documentation/w1/slaves/w1_ds28e04 for detailed information + see Documentation/w1/slaves/w1_ds28e04.rst for detailed information Users: any user space application which wants to communicate with DS28E04-100 @@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom Date: May 2012 Contact: Markus Franke <franm@hrz.tu-chemnitz.de> Description: read/write the contents of the EEPROM memory of the DS28E04-100 - see Documentation/w1/slaves/w1_ds28e04 for detailed information + see Documentation/w1/slaves/w1_ds28e04.rst for detailed information Users: any user space application which wants to communicate with DS28E04-100 diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 index e928def14f28..534e63731a49 100644 --- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 @@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq Date: Apr 2015 Contact: Matt Campbell <mattrcampbell@gmail.com> Description: Support for the DS28EA00 chain sequence function - see Documentation/w1/slaves/w1_therm for detailed information + see Documentation/w1/slaves/w1_therm.rst for detailed information Users: any user space application which wants to communicate with DS28EA00 diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip new file mode 100644 index 000000000000..a7c63e6c4bc3 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-hisi-zip @@ -0,0 +1,50 @@ +What: /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of compression cores related debug registers. + Only available for PF. + +What: /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of decompression cores related debug registers. + Only available for PF. + +What: /sys/kernel/debug/hisi_zip/<bdf>/clear_enable +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Compression/decompression core debug registers read clear + control. 1 means enable register read clear, otherwise 0. + Writing to this file has no functional effect, only enable or + disable counters clear after reading of these registers. + Only available for PF. + +What: /sys/kernel/debug/hisi_zip/<bdf>/current_qm +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: One ZIP controller has one PF and multiple VFs, each function + has a QM. Select the QM which below qm refers to. + Only available for PF. + +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/qm_regs +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: Dump of QM related debug registers. + Available for PF and VF in host. VF in guest currently only + has one debug register. + +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: One QM may contain multiple queues. Select specific queue to + show its debug registers in above qm_regs. + Only available for PF. + +What: /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable +Date: Nov 2018 +Contact: linux-crypto@vger.kernel.org +Description: QM debug registers(qm_regs) read clear control. 1 means enable + register read clear, otherwise 0. + Writing to this file has no functional effect, only enable or + disable counters clear after reading of these registers. + Only available for PF. diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet new file mode 100644 index 000000000000..67b1717794d8 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-moxtet @@ -0,0 +1,23 @@ +What: /sys/kernel/debug/moxtet/input +Date: March 2019 +KernelVersion: 5.3 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Read input from the shift registers, in hexadecimal. + Returns N+1 bytes, where N is the number of Moxtet connected + modules. The first byte is from the CPU board itself. + Example: 101214 + 10: CPU board with SD card + 12: 2 = PCIe module, 1 = IRQ not active + 14: 4 = Peridot module, 1 = IRQ not active + +What: /sys/kernel/debug/moxtet/output +Date: March 2019 +KernelVersion: 5.3 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (RW) Read last written value to the shift registers, in + hexadecimal, or write values to the shift registers, also + in hexadecimal. + Example: 0102 + 01: 01 was last written, or is to be written, to the + first module's shift register + 02: the same for second module diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 index da9822309f07..0e66ae9b0071 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 @@ -13,4 +13,4 @@ Description: error on writing If DFSDM input is SPI Slave: Reading returns value previously set. - Writing value before starting conversions.
\ No newline at end of file + Writing value before starting conversions. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 index 161c147d3c40..b7259234ad70 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 @@ -91,29 +91,6 @@ Description: When counting down the counter start from preset value and fire event when reach 0. -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -KernelVersion: 4.12 -Contact: benjamin.gaignard@st.com -Description: - Reading returns the list possible quadrature modes. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode -KernelVersion: 4.12 -Contact: benjamin.gaignard@st.com -Description: - Configure the device counter quadrature modes: - channel_A: - Encoder A input servers as the count input and B as - the UP/DOWN direction control input. - - channel_B: - Encoder B input serves as the count input and A as - the UP/DOWN direction control input. - - quadrature: - Encoder A and B inputs are mixed to get direction - and count with a scale of 0.25. - What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available KernelVersion: 4.12 Contact: benjamin.gaignard@st.com diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc index f54ae244f3f1..456cb62b384c 100644 --- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc @@ -12,7 +12,8 @@ Description: (RW) Configure MSC operating mode: - "single", for contiguous buffer mode (high-order alloc); - "multi", for multiblock mode; - "ExI", for DCI handler mode; - - "debug", for debug mode. + - "debug", for debug mode; + - any of the currently loaded buffer sinks. If operating mode changes, existing buffer is deallocated, provided there are no active users and tracing is not enabled, otherwise the write will fail. diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices new file mode 100644 index 000000000000..355958527fa3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices @@ -0,0 +1,17 @@ +What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description +Date: March 2019 +KernelVersion: 5.3 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Moxtet module description. Format: string + +What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id +Date: March 2019 +KernelVersion: 5.3 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Moxtet module ID. Format: %x + +What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name +Date: March 2019 +KernelVersion: 5.3 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Moxtet module name. Format: string diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic index 6ef682603179..6ef682603179 100644 --- a/Documentation/ABI/testing/sysfs-class-mic.txt +++ b/Documentation/ABI/testing/sysfs-class-mic diff --git a/Documentation/ABI/testing/sysfs-class-wakeup b/Documentation/ABI/testing/sysfs-class-wakeup new file mode 100644 index 000000000000..754aab8b6dcd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-wakeup @@ -0,0 +1,76 @@ +What: /sys/class/wakeup/ +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + The /sys/class/wakeup/ directory contains pointers to all + wakeup sources in the kernel at that moment in time. + +What: /sys/class/wakeup/.../name +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the name of the wakeup source. + +What: /sys/class/wakeup/.../active_count +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the number of times the wakeup source was + activated. + +What: /sys/class/wakeup/.../event_count +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the number of signaled wakeup events + associated with the wakeup source. + +What: /sys/class/wakeup/.../wakeup_count +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the number of times the wakeup source might + abort suspend. + +What: /sys/class/wakeup/.../expire_count +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the number of times the wakeup source's + timeout has expired. + +What: /sys/class/wakeup/.../active_time_ms +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the amount of time the wakeup source has + been continuously active, in milliseconds. If the wakeup + source is not active, this file contains '0'. + +What: /sys/class/wakeup/.../total_time_ms +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the total amount of time this wakeup source + has been active, in milliseconds. + +What: /sys/class/wakeup/.../max_time_ms +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the maximum amount of time this wakeup + source has been continuously active, in milliseconds. + +What: /sys/class/wakeup/.../last_change_ms +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + This file contains the monotonic clock time when the wakeup + source was touched last time, in milliseconds. + +What: /sys/class/wakeup/.../prevent_suspend_time_ms +Date: June 2019 +Contact: Tri Vo <trong@android.com> +Description: + The file contains the total amount of time this wakeup source + has been preventing autosleep, in milliseconds. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu new file mode 100644 index 000000000000..ae9af984471a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu @@ -0,0 +1,128 @@ + Intel Stratix10 Remote System Update (RSU) device attributes + +What: /sys/devices/platform/stratix10-rsu.0/current_image +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the address in flash of currently running image. + +What: /sys/devices/platform/stratix10-rsu.0/fail_image +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the address in flash of failed image. + +What: /sys/devices/platform/stratix10-rsu.0/state +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the state of RSU system. + The state field has two parts: major error code in + upper 16 bits and minor error code in lower 16 bits. + + b[15:0] + Currently used only when major error is 0xF006 + (CPU watchdog timeout), in which case the minor + error code is the value reported by CPU to + firmware through the RSU notify command before + the watchdog timeout occurs. + + b[31:16] + 0xF001 bitstream error + 0xF002 hardware access failure + 0xF003 bitstream corruption + 0xF004 internal error + 0xF005 device error + 0xF006 CPU watchdog timeout + 0xF007 internal unknown error + +What: /sys/devices/platform/stratix10-rsu.0/version +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the version number of RSU firmware. 19.3 or late + version includes information about the firmware which + reported the error. + + pre 19.3: + b[31:0] + 0x0 version number + + 19.3 or late: + b[15:0] + 0x1 version number + b[31:16] + 0x0 no error + 0x0DCF Decision CMF error + 0x0ACF Application CMF error + +What: /sys/devices/platform/stratix10-rsu.0/error_location +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the error offset inside the image that failed. + +What: /sys/devices/platform/stratix10-rsu.0/error_details +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) error code. + +What: /sys/devices/platform/stratix10-rsu.0/retry_counter +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) the current image's retry counter, which is used by + user to know how many times the images is still allowed + to reload itself before giving up and starting RSU + fail-over flow. + +What: /sys/devices/platform/stratix10-rsu.0/reboot_image +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (WO) the address in flash of image to be loaded on next + reboot command. + +What: /sys/devices/platform/stratix10-rsu.0/notify +Date: August 2019 +KernelVersion: 5.4 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (WO) client to notify firmware with different actions. + + b[15:0] + inform firmware the current software execution + stage. + 0 the first stage bootloader didn't run or + didn't reach the point of launching second + stage bootloader. + 1 failed in second bootloader or didn't get + to the point of launching the operating + system. + 2 both first and second stage bootloader ran + and the operating system launch was + attempted. + + b[16] + 1 firmware to reset current image retry + counter. + 0 no action. + + b[17] + 1 firmware to clear RSU log + 0 no action. + + b[18] + this is negative logic + 1 no action + 0 firmware record the notify code defined + in b[15:0]. diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power index 80a00f7b6667..1763e64dd152 100644 --- a/Documentation/ABI/testing/sysfs-devices-power +++ b/Documentation/ABI/testing/sysfs-devices-power @@ -260,3 +260,12 @@ Description: This attribute has no effect on system-wide suspend/resume and hibernation. + +What: /sys/devices/.../power/runtime_status +Date: April 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/runtime_status attribute contains + the current runtime PM status of the device, which may be + "suspended", "suspending", "resuming", "active", "error" (fatal + error), or "unsupported" (runtime PM is disabled). diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc index 6d9cc253f2b2..ba3a3fac0ee1 100644 --- a/Documentation/ABI/testing/sysfs-devices-soc +++ b/Documentation/ABI/testing/sysfs-devices-soc @@ -26,6 +26,13 @@ Description: Read-only attribute common to all SoCs. Contains SoC family name (e.g. DB8500). +What: /sys/devices/socX/serial_number +Date: January 2019 +contact: Bjorn Andersson <bjorn.andersson@linaro.org> +Description: + Read-only attribute supported by most SoCs. Contains the SoC's + serial number, if available. + What: /sys/devices/socX/soc_id Date: January 2012 contact: Lee Jones <lee.jones@linaro.org> diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs index f433fc6db3c6..782df74042ed 100644 --- a/Documentation/ABI/testing/sysfs-driver-habanalabs +++ b/Documentation/ABI/testing/sysfs-driver-habanalabs @@ -57,6 +57,7 @@ KernelVersion: 5.1 Contact: oded.gabbay@gmail.com Description: Allows the user to set the maximum clock frequency for MME, TPC and IC when the power management profile is set to "automatic". + This property is valid only for the Goya ASIC family What: /sys/class/habanalabs/hl<n>/ic_clk Date: Jan 2019 @@ -127,8 +128,8 @@ Description: Power management profile. Values are "auto", "manual". In "auto" the max clock frequency to a low value when there are no user processes that are opened on the device's file. In "manual" mode, the user sets the maximum clock frequency by writing to - ic_clk, mme_clk and tpc_clk - + ic_clk, mme_clk and tpc_clk. This property is valid only for + the Goya ASIC family What: /sys/class/habanalabs/hl<n>/preboot_btl_ver Date: Jan 2019 @@ -186,11 +187,4 @@ What: /sys/class/habanalabs/hl<n>/uboot_ver Date: Jan 2019 KernelVersion: 5.1 Contact: oded.gabbay@gmail.com -Description: Version of the u-boot running on the device's CPU - -What: /sys/class/habanalabs/hl<n>/write_open_cnt -Date: Jan 2019 -KernelVersion: 5.1 -Contact: oded.gabbay@gmail.com -Description: Displays the total number of user processes that are currently - opened on the device's file +Description: Version of the u-boot running on the device's CPU
\ No newline at end of file diff --git a/Documentation/ABI/testing/sysfs-firmware-efi b/Documentation/ABI/testing/sysfs-firmware-efi index e794eac32a90..5e4d0b27cdfe 100644 --- a/Documentation/ABI/testing/sysfs-firmware-efi +++ b/Documentation/ABI/testing/sysfs-firmware-efi @@ -28,3 +28,11 @@ Description: Displays the physical addresses of all EFI Configuration versions are always printed first, i.e. ACPI20 comes before ACPI. Users: dmidecode + +What: /sys/firmware/efi/tables/rci2 +Date: July 2019 +Contact: Narendra K <Narendra.K@dell.com>, linux-bugs@dell.com +Description: Displays the content of the Runtime Configuration Interface + Table version 2 on Dell EMC PowerEdge systems in binary format +Users: It is used by Dell EMC OpenManage Server Administrator tool to + populate BIOS setup page. diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm new file mode 100644 index 000000000000..15595fab88d1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm @@ -0,0 +1,37 @@ +What: /sys/firmware/turris-mox-rwtm/board_version +Date: August 2019 +KernelVersion: 5.4 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Board version burned into eFuses of this Turris Mox board. + Format: %i + +What: /sys/firmware/turris-mox-rwtm/mac_address* +Date: August 2019 +KernelVersion: 5.4 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) MAC addresses burned into eFuses of this Turris Mox board. + Format: %pM + +What: /sys/firmware/turris-mox-rwtm/pubkey +Date: August 2019 +KernelVersion: 5.4 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) ECDSA public key (in pubkey hex compressed form) computed + as pair to the ECDSA private key burned into eFuses of this + Turris Mox Board. + Format: string + +What: /sys/firmware/turris-mox-rwtm/ram_size +Date: August 2019 +KernelVersion: 5.4 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) RAM size in MiB of this Turris Mox board as was detected + during manufacturing and burned into eFuses. Can be 512 or 1024. + Format: %i + +What: /sys/firmware/turris-mox-rwtm/serial_number +Date: August 2019 +KernelVersion: 5.4 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (R) Serial number burned into eFuses of this Turris Mox device. + Format: %016X diff --git a/Documentation/ABI/testing/sysfs-kernel-btf b/Documentation/ABI/testing/sysfs-kernel-btf new file mode 100644 index 000000000000..2c9744b2cd59 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-btf @@ -0,0 +1,17 @@ +What: /sys/kernel/btf +Date: Aug 2019 +KernelVersion: 5.5 +Contact: bpf@vger.kernel.org +Description: + Contains BTF type information and related data for kernel and + kernel modules. + +What: /sys/kernel/btf/vmlinux +Date: Aug 2019 +KernelVersion: 5.5 +Contact: bpf@vger.kernel.org +Description: + Read-only binary attribute exposing kernel's own BTF type + information with description of all internal kernel types. See + Documentation/bpf/btf.rst for detailed description of format + itself. diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme index 8fa4febfa4b2..72634d3ae4f4 100644 --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme @@ -21,3 +21,88 @@ Contact: Wu Hao <hao.wu@intel.com> Description: Read-only. It returns Bitstream (static FPGA region) meta data, which includes the synthesis date, seed and other information of this static FPGA region. + +What: /sys/bus/platform/devices/dfl-fme.0/cache_size +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It returns cache size of this FPGA device. + +What: /sys/bus/platform/devices/dfl-fme.0/fabric_version +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It returns fabric version of this FPGA device. + Userspace applications need this information to select + best data channels per different fabric design. + +What: /sys/bus/platform/devices/dfl-fme.0/socket_id +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It returns socket_id to indicate which socket + this FPGA belongs to, only valid for integrated solution. + User only needs this information, in case standard numa node + can't provide correct information. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie0_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-Write. Read this file for errors detected on pcie0 link. + Write this file to clear errors logged in pcie0_errors. Write + fails with -EINVAL if input parsing fails or input error code + doesn't match. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie1_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-Write. Read this file for errors detected on pcie1 link. + Write this file to clear errors logged in pcie1_errors. Write + fails with -EINVAL if input parsing fails or input error code + doesn't match. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/nonfatal_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It returns non-fatal errors detected. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/catfatal_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It returns catastrophic and fatal errors detected. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/inject_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-Write. Read this file to check errors injected. Write this + file to inject errors for testing purpose. Write fails with + -EINVAL if input parsing fails or input inject error code isn't + supported. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/fme_errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-Write. Read this file to get errors detected on FME. + Write this file to clear errors logged in fme_errors. Write + fials with -EINVAL if input parsing fails or input error code + doesn't match. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/first_error +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the first error detected by + hardware. + +What: /sys/bus/platform/devices/dfl-fme.0/errors/next_error +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the second error detected by + hardware. diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-port b/Documentation/ABI/testing/sysfs-platform-dfl-port index 6a92dda517b0..65658267fcc0 100644 --- a/Documentation/ABI/testing/sysfs-platform-dfl-port +++ b/Documentation/ABI/testing/sysfs-platform-dfl-port @@ -14,3 +14,88 @@ Description: Read-only. User can program different PR bitstreams to FPGA Accelerator Function Unit (AFU) for different functions. It returns uuid which could be used to identify which PR bitstream is programmed in this AFU. + +What: /sys/bus/platform/devices/dfl-port.0/power_state +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. It reports the APx (AFU Power) state, different APx + means different throttling level. When reading this file, it + returns "0" - Normal / "1" - AP1 / "2" - AP2 / "6" - AP6. + +What: /sys/bus/platform/devices/dfl-port.0/ap1_event +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-write. Read this file for AP1 (AFU Power State 1) event. + It's used to indicate transient AP1 state. Write 1 to this + file to clear AP1 event. + +What: /sys/bus/platform/devices/dfl-port.0/ap2_event +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-write. Read this file for AP2 (AFU Power State 2) event. + It's used to indicate transient AP2 state. Write 1 to this + file to clear AP2 event. + +What: /sys/bus/platform/devices/dfl-port.0/ltr +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-write. Read or set AFU latency tolerance reporting value. + Set ltr to 1 if the AFU can tolerate latency >= 40us or set it + to 0 if it is latency sensitive. + +What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcmd +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Write-only. User writes command to this interface to set + userclock to AFU. + +What: /sys/bus/platform/devices/dfl-port.0/userclk_freqsts +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the status of issued command + to userclck_freqcmd. + +What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrcmd +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Write-only. User writes command to this interface to set + userclock counter. + +What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrsts +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the status of issued command + to userclck_freqcntrcmd. + +What: /sys/bus/platform/devices/dfl-port.0/errors/errors +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-Write. Read this file to get errors detected on port and + Accelerated Function Unit (AFU). Write error code to this file + to clear errors. Write fails with -EINVAL if input parsing + fails or input error code doesn't match. Write fails with + -EBUSY or -ETIMEDOUT if error can't be cleared as hardware + in low power state (-EBUSY) or not respoding (-ETIMEDOUT). + +What: /sys/bus/platform/devices/dfl-port.0/errors/first_error +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the first error detected by + hardware. + +What: /sys/bus/platform/devices/dfl-port.0/errors/first_malformed_req +Date: August 2019 +KernelVersion: 5.4 +Contact: Wu Hao <hao.wu@intel.com> +Description: Read-only. Read this file to get the first malformed request + captured by hardware. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 3c5130355011..6f87b9dd384b 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -301,3 +301,109 @@ Description: Using this sysfs file will override any values that were set using the kernel command line for disk offset. + +What: /sys/power/suspend_stats +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats directory contains suspend related + statistics. + +What: /sys/power/suspend_stats/success +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/success file contains the number + of times entering system sleep state succeeded. + +What: /sys/power/suspend_stats/fail +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/fail file contains the number + of times entering system sleep state failed. + +What: /sys/power/suspend_stats/failed_freeze +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_freeze file contains the + number of times freezing processes failed. + +What: /sys/power/suspend_stats/failed_prepare +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_prepare file contains the + number of times preparing all non-sysdev devices for + a system PM transition failed. + +What: /sys/power/suspend_stats/failed_resume +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_resume file contains the + number of times executing "resume" callbacks of + non-sysdev devices failed. + +What: /sys/power/suspend_stats/failed_resume_early +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_resume_early file contains + the number of times executing "early resume" callbacks + of devices failed. + +What: /sys/power/suspend_stats/failed_resume_noirq +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_resume_noirq file contains + the number of times executing "noirq resume" callbacks + of devices failed. + +What: /sys/power/suspend_stats/failed_suspend +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_suspend file contains + the number of times executing "suspend" callbacks + of all non-sysdev devices failed. + +What: /sys/power/suspend_stats/failed_suspend_late +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_suspend_late file contains + the number of times executing "late suspend" callbacks + of all devices failed. + +What: /sys/power/suspend_stats/failed_suspend_noirq +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/failed_suspend_noirq file contains + the number of times executing "noirq suspend" callbacks + of all devices failed. + +What: /sys/power/suspend_stats/last_failed_dev +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/last_failed_dev file contains + the last device for which a suspend/resume callback failed. + +What: /sys/power/suspend_stats/last_failed_errno +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/last_failed_errno file contains + the errno of the last failed attempt at entering + system sleep state. + +What: /sys/power/suspend_stats/last_failed_step +Date: July 2019 +Contact: Kalesh Singh <kaleshsingh96@gmail.com> +Description: + The /sys/power/suspend_stats/last_failed_step file contains + the last failed step in the suspend/resume path. diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst index f4c6121868c3..6768305e4c26 100644 --- a/Documentation/PCI/index.rst +++ b/Documentation/PCI/index.rst @@ -9,7 +9,7 @@ Linux PCI Bus Subsystem :numbered: pci - picebus-howto + pciebus-howto pci-iov-howto msi-howto acpi-info diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index e5d450df06b4..13beee23cb04 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -421,7 +421,6 @@ That is, the recovery API only requires that: - drivers/net/ixgbe - drivers/net/cxgb3 - drivers/net/s2io.c - - drivers/net/qlge The End ------- diff --git a/Documentation/PCI/picebus-howto.rst b/Documentation/PCI/pciebus-howto.rst index f882ff62c51f..f882ff62c51f 100644 --- a/Documentation/PCI/picebus-howto.rst +++ b/Documentation/PCI/pciebus-howto.rst diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html index 5a9238a2883c..467251f7fef6 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.html +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -2129,6 +2129,8 @@ Some of the relevant points of interest are as follows: <li> <a href="#Hotplug CPU">Hotplug CPU</a>. <li> <a href="#Scheduler and RCU">Scheduler and RCU</a>. <li> <a href="#Tracing and RCU">Tracing and RCU</a>. +<li> <a href="#Accesses to User Memory and RCU"> +Accesses to User Memory and RCU</a>. <li> <a href="#Energy Efficiency">Energy Efficiency</a>. <li> <a href="#Scheduling-Clock Interrupts and RCU"> Scheduling-Clock Interrupts and RCU</a>. @@ -2512,7 +2514,7 @@ disabled across the entire RCU read-side critical section. <p> It is possible to use tracing on RCU code, but tracing itself uses RCU. -For this reason, <tt>rcu_dereference_raw_notrace()</tt> +For this reason, <tt>rcu_dereference_raw_check()</tt> is provided for use by tracing, which avoids the destructive recursion that could otherwise ensue. This API is also used by virtualization in some architectures, @@ -2521,6 +2523,75 @@ cannot be used. The tracing folks both located the requirement and provided the needed fix, so this surprise requirement was relatively painless. +<h3><a name="Accesses to User Memory and RCU"> +Accesses to User Memory and RCU</a></h3> + +<p> +The kernel needs to access user-space memory, for example, to access +data referenced by system-call parameters. +The <tt>get_user()</tt> macro does this job. + +<p> +However, user-space memory might well be paged out, which means +that <tt>get_user()</tt> might well page-fault and thus block while +waiting for the resulting I/O to complete. +It would be a very bad thing for the compiler to reorder +a <tt>get_user()</tt> invocation into an RCU read-side critical +section. +For example, suppose that the source code looked like this: + +<blockquote> +<pre> + 1 rcu_read_lock(); + 2 p = rcu_dereference(gp); + 3 v = p->value; + 4 rcu_read_unlock(); + 5 get_user(user_v, user_p); + 6 do_something_with(v, user_v); +</pre> +</blockquote> + +<p> +The compiler must not be permitted to transform this source code into +the following: + +<blockquote> +<pre> + 1 rcu_read_lock(); + 2 p = rcu_dereference(gp); + 3 get_user(user_v, user_p); // BUG: POSSIBLE PAGE FAULT!!! + 4 v = p->value; + 5 rcu_read_unlock(); + 6 do_something_with(v, user_v); +</pre> +</blockquote> + +<p> +If the compiler did make this transformation in a +<tt>CONFIG_PREEMPT=n</tt> kernel build, and if <tt>get_user()</tt> did +page fault, the result would be a quiescent state in the middle +of an RCU read-side critical section. +This misplaced quiescent state could result in line 4 being +a use-after-free access, which could be bad for your kernel's +actuarial statistics. +Similar examples can be constructed with the call to <tt>get_user()</tt> +preceding the <tt>rcu_read_lock()</tt>. + +<p> +Unfortunately, <tt>get_user()</tt> doesn't have any particular +ordering properties, and in some architectures the underlying <tt>asm</tt> +isn't even marked <tt>volatile</tt>. +And even if it was marked <tt>volatile</tt>, the above access to +<tt>p->value</tt> is not volatile, so the compiler would not have any +reason to keep those two accesses in order. + +<p> +Therefore, the Linux-kernel definitions of <tt>rcu_read_lock()</tt> +and <tt>rcu_read_unlock()</tt> must act as compiler barriers, +at least for outermost instances of <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> within a nested set of RCU read-side critical +sections. + <h3><a name="Energy Efficiency">Energy Efficiency</a></h3> <p> diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 13e88fc00f01..f48f4621ccbc 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -57,6 +57,12 @@ o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that CONFIG_PREEMPT_RCU case, you might see stall-warning messages. + You can use the rcutree.kthread_prio kernel boot parameter to + increase the scheduling priority of RCU's kthreads, which can + help avoid this problem. However, please note that doing this + can increase your system's context-switch rate and thus degrade + performance. + o A periodic interrupt whose handler takes longer than the time interval between successive pairs of interrupts. This can prevent RCU's kthreads and softirq handlers from running. diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst new file mode 100644 index 000000000000..18c2865bd322 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst @@ -0,0 +1,98 @@ +=================================== +cfag12864b LCD Driver Documentation +=================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda Sandonis +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + 4. USERSPACE PROGRAMMING + +1. Driver Information +--------------------- + +This driver supports a cfag12864b LCD. + + +2. Device Information +--------------------- + +:Manufacturer: Crystalfontz +:Device Name: Crystalfontz 12864b LCD Series +:Device Code: cfag12864b +:Webpage: http://www.crystalfontz.com +:Device Webpage: http://www.crystalfontz.com/products/12864b/ +:Type: LCD (Liquid Crystal Display) +:Width: 128 +:Height: 64 +:Colors: 2 (B/N) +:Controller: ks0108 +:Controllers: 2 +:Pages: 8 each controller +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte + + +3. Wiring +--------- + +The cfag12864b LCD Series don't have official wiring. + +The common wiring is done to the parallel port as shown:: + + Parallel Port cfag12864b + + Name Pin# Pin# Name + + Strobe ( 1)------------------------------(17) Enable + Data 0 ( 2)------------------------------( 4) Data 0 + Data 1 ( 3)------------------------------( 5) Data 1 + Data 2 ( 4)------------------------------( 6) Data 2 + Data 3 ( 5)------------------------------( 7) Data 3 + Data 4 ( 6)------------------------------( 8) Data 4 + Data 5 ( 7)------------------------------( 9) Data 5 + Data 6 ( 8)------------------------------(10) Data 6 + Data 7 ( 9)------------------------------(11) Data 7 + (10) [+5v]---( 1) Vdd + (11) [GND]---( 2) Ground + (12) [+5v]---(14) Reset + (13) [GND]---(15) Read / Write + Line (14)------------------------------(13) Controller Select 1 + (15) + Init (16)------------------------------(12) Controller Select 2 + Select (17)------------------------------(16) Data / Instruction + Ground (18)---[GND] [+5v]---(19) LED + + Ground (19)---[GND] + Ground (20)---[GND] E A Values: + Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm + Ground (22)---[GND] | - P1 = Preset = 10 Kohm + Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm + Ground (24)---[GND] | | + Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED - + + +4. Userspace Programming +------------------------ + +The cfag12864bfb describes a framebuffer device (/dev/fbX). + +It has a size of 1024 bytes = 1 Kbyte. +Each bit represents one pixel. If the bit is high, the pixel will +turn on. If the pixel is low, the pixel will turn off. + +You can use the framebuffer as a file: fopen, fwrite, fclose... +Although the LCD won't get updated until the next refresh time arrives. + +Also, you can mmap the framebuffer: open & mmap, munmap & close... +which is the best option for most uses. + +Check samples/auxdisplay/cfag12864b-example.c +for a real working userspace complete program with usage examples. diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst new file mode 100644 index 000000000000..e466f0595248 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/index.rst @@ -0,0 +1,16 @@ +========================= +Auxiliary Display Support +========================= + +.. toctree:: + :maxdepth: 1 + + ks0108.rst + cfag12864b.rst + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst new file mode 100644 index 000000000000..c0b7faf73136 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/ks0108.rst @@ -0,0 +1,50 @@ +========================================== +ks0108 LCD Controller Driver Documentation +========================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda Sandonis +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + + +1. Driver Information +--------------------- + +This driver supports the ks0108 LCD controller. + + +2. Device Information +--------------------- + +:Manufacturer: Samsung +:Device Name: KS0108 LCD Controller +:Device Code: ks0108 +:Webpage: - +:Device Webpage: - +:Type: LCD Controller (Liquid Crystal Display Controller) +:Width: 64 +:Height: 64 +:Colors: 2 (B/N) +:Pages: 8 +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 8 * 64 * 1 = 512 bytes + + +3. Wiring +--------- + +The driver supports data parallel port wiring. + +If you aren't building LCD related hardware, you should check +your LCD specific wiring information in the same folder. + +For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst index 1d7d962933be..36d43ae7dc13 100644 --- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst +++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst @@ -130,12 +130,6 @@ Proportional weight policy files dev weight 8:16 300 -- blkio.leaf_weight[_device] - - Equivalents of blkio.weight[_device] for the purpose of - deciding how much weight tasks in the given cgroup has while - competing with the cgroup's child cgroups. For details, - please refer to Documentation/block/cfq-iosched.txt. - - blkio.time - disk time allocated to cgroup per device in milliseconds. First two fields specify the major and minor number of the device and diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 3b29005aa981..0fa8c0e615c2 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -951,6 +951,13 @@ controller implements weight and absolute bandwidth limit models for normal scheduling policy and absolute bandwidth allocation model for realtime scheduling policy. +In all the above models, cycles distribution is defined only on a temporal +base and it does not account for the frequency at which tasks are executed. +The (optional) utilization clamping support allows to hint the schedutil +cpufreq governor about the minimum desired frequency which should always be +provided by a CPU, as well as the maximum desired frequency, which should not +be exceeded by a CPU. + WARNING: cgroup2 doesn't yet support control of realtime processes and the cpu controller can only be enabled when all RT processes are in the root cgroup. Be aware that system management software may already @@ -1016,6 +1023,33 @@ All time durations are in microseconds. Shows pressure stall information for CPU. See Documentation/accounting/psi.rst for details. + cpu.uclamp.min + A read-write single value file which exists on non-root cgroups. + The default is "0", i.e. no utilization boosting. + + The requested minimum utilization (protection) as a percentage + rational number, e.g. 12.34 for 12.34%. + + This interface allows reading and setting minimum utilization clamp + values similar to the sched_setattr(2). This minimum utilization + value is used to clamp the task specific minimum utilization clamp. + + The requested minimum utilization (protection) is always capped by + the current value for the maximum utilization (limit), i.e. + `cpu.uclamp.max`. + + cpu.uclamp.max + A read-write single value file which exists on non-root cgroups. + The default is "max". i.e. no utilization capping + + The requested maximum utilization (limit) as a percentage rational + number, e.g. 98.76 for 98.76%. + + This interface allows reading and setting maximum utilization clamp + values similar to the sched_setattr(2). This maximum utilization + value is used to clamp the task specific maximum utilization clamp. + + Memory ------ @@ -1435,6 +1469,103 @@ IO Interface Files 8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353 dbytes=0 dios=0 8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252 dbytes=50331648 dios=3021 + io.cost.qos + A read-write nested-keyed file with exists only on the root + cgroup. + + This file configures the Quality of Service of the IO cost + model based controller (CONFIG_BLK_CGROUP_IOCOST) which + currently implements "io.weight" proportional control. Lines + are keyed by $MAJ:$MIN device numbers and not ordered. The + line for a given device is populated on the first write for + the device on "io.cost.qos" or "io.cost.model". The following + nested keys are defined. + + ====== ===================================== + enable Weight-based control enable + ctrl "auto" or "user" + rpct Read latency percentile [0, 100] + rlat Read latency threshold + wpct Write latency percentile [0, 100] + wlat Write latency threshold + min Minimum scaling percentage [1, 10000] + max Maximum scaling percentage [1, 10000] + ====== ===================================== + + The controller is disabled by default and can be enabled by + setting "enable" to 1. "rpct" and "wpct" parameters default + to zero and the controller uses internal device saturation + state to adjust the overall IO rate between "min" and "max". + + When a better control quality is needed, latency QoS + parameters can be configured. For example:: + + 8:16 enable=1 ctrl=auto rpct=95.00 rlat=75000 wpct=95.00 wlat=150000 min=50.00 max=150.0 + + shows that on sdb, the controller is enabled, will consider + the device saturated if the 95th percentile of read completion + latencies is above 75ms or write 150ms, and adjust the overall + IO issue rate between 50% and 150% accordingly. + + The lower the saturation point, the better the latency QoS at + the cost of aggregate bandwidth. The narrower the allowed + adjustment range between "min" and "max", the more conformant + to the cost model the IO behavior. Note that the IO issue + base rate may be far off from 100% and setting "min" and "max" + blindly can lead to a significant loss of device capacity or + control quality. "min" and "max" are useful for regulating + devices which show wide temporary behavior changes - e.g. a + ssd which accepts writes at the line speed for a while and + then completely stalls for multiple seconds. + + When "ctrl" is "auto", the parameters are controlled by the + kernel and may change automatically. Setting "ctrl" to "user" + or setting any of the percentile and latency parameters puts + it into "user" mode and disables the automatic changes. The + automatic mode can be restored by setting "ctrl" to "auto". + + io.cost.model + A read-write nested-keyed file with exists only on the root + cgroup. + + This file configures the cost model of the IO cost model based + controller (CONFIG_BLK_CGROUP_IOCOST) which currently + implements "io.weight" proportional control. Lines are keyed + by $MAJ:$MIN device numbers and not ordered. The line for a + given device is populated on the first write for the device on + "io.cost.qos" or "io.cost.model". The following nested keys + are defined. + + ===== ================================ + ctrl "auto" or "user" + model The cost model in use - "linear" + ===== ================================ + + When "ctrl" is "auto", the kernel may change all parameters + dynamically. When "ctrl" is set to "user" or any other + parameters are written to, "ctrl" become "user" and the + automatic changes are disabled. + + When "model" is "linear", the following model parameters are + defined. + + ============= ======================================== + [r|w]bps The maximum sequential IO throughput + [r|w]seqiops The maximum 4k sequential IOs per second + [r|w]randiops The maximum 4k random IOs per second + ============= ======================================== + + From the above, the builtin linear model determines the base + costs of a sequential and random IO and the cost coefficient + for the IO size. While simple, this model can cover most + common device classes acceptably. + + The IO cost model isn't expected to be accurate in absolute + sense and is scaled to the device behavior dynamically. + + If needed, tools/cgroup/iocost_coef_gen.py can be used to + generate device-specific coefficients. + io.weight A read-write flat-keyed file which exists on non-root cgroups. The default is "default 100". diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst index 75865da2ce14..b02d6dd6c070 100644 --- a/Documentation/filesystems/cifs/AUTHORS +++ b/Documentation/admin-guide/cifs/authors.rst @@ -1,5 +1,10 @@ +======= +Authors +======= + Original Author -=============== +--------------- + Steve French (sfrench@samba.org) The author wishes to express his appreciation and thanks to: @@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client) for proving years ago that very good smb/cifs clients could be done on Unix-like -operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John +operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John Newbigin and others for their work on the Linux smbfs module. Thanks to the other members of the Storage Network Industry Association CIFS Technical Workgroup for their work specifying this highly complex protocol and finally @@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement. Patch Contributors ------------------ -Zwane Mwaikambo -Andi Kleen -Amrut Joshi -Shobhit Dayal -Sergey Vlasov -Richard Hughes -Yury Umanets -Mark Hamzy (for some of the early cifs IPv6 work) -Domen Puncer -Jesper Juhl (in particular for lots of whitespace/formatting cleanup) -Vince Negri and Dave Stahl (for finding an important caching bug) -Adrian Bunk (kcalloc cleanups) -Miklos Szeredi -Kazeon team for various fixes especially for 2.4 version. -Asser Ferno (Change Notify support) -Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup -Gunter Kukkukk (testing and suggestions for support of old servers) -Igor Mammedov (DFS support) -Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code) -Scott Lovenberg -Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features) -Aurelien Aptel (for DFS SMB3 work and some key bug fixes) -Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding) -Shirish Pargaonkar (for many ACL patches over the years) -Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security) -Paulo Alcantara -Long Li (some great work on RDMA, SMB Direct) + +- Zwane Mwaikambo +- Andi Kleen +- Amrut Joshi +- Shobhit Dayal +- Sergey Vlasov +- Richard Hughes +- Yury Umanets +- Mark Hamzy (for some of the early cifs IPv6 work) +- Domen Puncer +- Jesper Juhl (in particular for lots of whitespace/formatting cleanup) +- Vince Negri and Dave Stahl (for finding an important caching bug) +- Adrian Bunk (kcalloc cleanups) +- Miklos Szeredi +- Kazeon team for various fixes especially for 2.4 version. +- Asser Ferno (Change Notify support) +- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup +- Gunter Kukkukk (testing and suggestions for support of old servers) +- Igor Mammedov (DFS support) +- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code) +- Scott Lovenberg +- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features) +- Aurelien Aptel (for DFS SMB3 work and some key bug fixes) +- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding) +- Shirish Pargaonkar (for many ACL patches over the years) +- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security) +- Paulo Alcantara +- Long Li (some great work on RDMA, SMB Direct) Test case and Bug Report contributors diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst index 1df7f4910eb2..71f2ecb62299 100644 --- a/Documentation/filesystems/cifs/CHANGES +++ b/Documentation/admin-guide/cifs/changes.rst @@ -1,3 +1,7 @@ +======= +Changes +======= + See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary information (that may be easier to read than parsing the output of "git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst new file mode 100644 index 000000000000..fad5268635f5 --- /dev/null +++ b/Documentation/admin-guide/cifs/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +CIFS +==== + +.. toctree:: + :maxdepth: 2 + + introduction + usage + todo + changes + authors + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst index 1be3d21c286e..0b98f672d36f 100644 --- a/Documentation/filesystems/cifs/cifs.txt +++ b/Documentation/admin-guide/cifs/introduction.rst @@ -1,3 +1,7 @@ +============ +Introduction +============ + This is the client VFS module for the SMB3 NAS protocol as well as for older dialects such as the Common Internet File System (CIFS) protocol which was the successor to the Server Message Block @@ -33,7 +37,9 @@ tools (including smbinfo and setcifsacl) that can be obtained from https://git.samba.org/?p=cifs-utils.git + or + git://git.samba.org/cifs-utils.git mount.cifs should be installed in the directory with the other mount helpers. @@ -41,5 +47,7 @@ For more information on the module see the project wiki page at https://wiki.samba.org/index.php/LinuxCIFS + and + https://wiki.samba.org/index.php/LinuxCIFS_utils diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst index 9267f3fb131f..084c25f92dcb 100644 --- a/Documentation/filesystems/cifs/TODO +++ b/Documentation/admin-guide/cifs/todo.rst @@ -1,3 +1,7 @@ +==== +TODO +==== + Version 2.14 December 21, 2018 A Partial List of Missing Features @@ -8,53 +12,60 @@ for visible, important contributions to this module. Here is a partial list of the known problems and missing features: a) SMB3 (and SMB3.1.1) missing optional features: + - multichannel (started), integration with RDMA - directory leases (improved metadata caching), started (root dir only) - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl currently the only two server side copy mechanisms supported) -b) improved sparse file support +b) improved sparse file support (fiemap and SEEK_HOLE are implemented + but additional features would be supportable by the protocol). c) Directory entry caching relies on a 1 second timer, rather than -using Directory Leases, currently only the root file handle is cached longer + using Directory Leases, currently only the root file handle is cached longer d) quota support (needs minor kernel change since quota calls -to make it to network filesystems or deviceless filesystems) + to make it to network filesystems or deviceless filesystems) -e) Additional use cases where we use "compoounding" (e.g. open/query/close -and open/setinfo/close) to reduce the number of roundtrips, and also -open to reduce redundant opens (using deferred close and reference counts more). +e) Additional use cases can be optimized to use "compounding" (e.g. + open/query/close and open/setinfo/close) to reduce the number of + roundtrips to the server and improve performance. Various cases + (stat, statfs, create, unlink, mkdir) already have been improved by + using compounding but more can be done. In addition we could + significantly reduce redundant opens by using deferred close (with + handle caching leases) and better using reference counters on file + handles. f) Finish inotify support so kde and gnome file list windows -will autorefresh (partially complete by Asser). Needs minor kernel -vfs change to support removing D_NOTIFY on a file. + will autorefresh (partially complete by Asser). Needs minor kernel + vfs change to support removing D_NOTIFY on a file. g) Add GUI tool to configure /proc/fs/cifs settings and for display of -the CIFS statistics (started) + the CIFS statistics (started) h) implement support for security and trusted categories of xattrs -(requires minor protocol extension) to enable better support for SELINUX + (requires minor protocol extension) to enable better support for SELINUX i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol feature (may be especially useful for virtualization). j) Create UID mapping facility so server UIDs can be mapped on a per -mount or a per server basis to client UIDs or nobody if no mapping -exists. Also better integration with winbind for resolving SID owners + mount or a per server basis to client UIDs or nobody if no mapping + exists. Also better integration with winbind for resolving SID owners k) Add tools to take advantage of more smb3 specific ioctls and features -(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server -is in progress, and a passthrough query_info call is already implemented -in cifs.ko to allow smb3 info levels queries to be sent from userspace) + (passthrough ioctl/fsctl is now implemented in cifs.ko to allow + sending various SMB3 fsctls and query info and set info calls + directly from user space) Add tools to make setting various non-POSIX + metadata attributes easier from tools (e.g. extending what was done + in smb-info tool). l) encrypted file support m) improved stats gathering tools (perhaps integration with nfsometer?) -to extend and make easier to use what is currently in /proc/fs/cifs/Stats + to extend and make easier to use what is currently in /proc/fs/cifs/Stats -n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed -file attribute via chflags) and improve user space tools for managing and -viewing them. +n) Add support for claims based ACLs ("DAC") o) mount helper GUI (to simplify the various configuration options on mount) @@ -65,55 +76,58 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space different servers, and the server we are connected to has gone down. q) Allow mount.cifs to be more verbose in reporting errors with dialect -or unsupported feature errors. + or unsupported feature errors. r) updating cifs documentation, and user guide. s) Addressing bugs found by running a broader set of xfstests in standard -file system xfstest suite. + file system xfstest suite. t) split cifs and smb3 support into separate modules so legacy (and less -secure) CIFS dialect can be disabled in environments that don't need it -and simplify the code. + secure) CIFS dialect can be disabled in environments that don't need it + and simplify the code. v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added -so far). + so far). w) Add support for additional strong encryption types, and additional spnego -authentication mechanisms (see MS-SMB2) + authentication mechanisms (see MS-SMB2) + +x) Finish support for SMB3.1.1 compression + +Known Bugs +========== -KNOWN BUGS -==================================== See http://bugzilla.samba.org - search on product "CifsVFS" for current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS) 1) existing symbolic links (Windows reparse points) are recognized but -can not be created remotely. They are implemented for Samba and those that -support the CIFS Unix extensions, although earlier versions of Samba -overly restrict the pathnames. + can not be created remotely. They are implemented for Samba and those that + support the CIFS Unix extensions, although earlier versions of Samba + overly restrict the pathnames. 2) follow_link and readdir code does not follow dfs junctions -but recognizes them + but recognizes them Misc testing to do ================== 1) check out max path names and max path name components against various server -types. Try nested symlinks (8 deep). Return max path name in stat -f information + types. Try nested symlinks (8 deep). Return max path name in stat -f information 2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test -cifs/smb3 better + cifs/smb3 better -3) Additional performance testing and optimization using iozone and similar - -there are some easy changes that can be done to parallelize sequential writes, -and when signing is disabled to request larger read sizes (larger than -negotiated size) and send larger write sizes to modern servers. +3) Additional performance testing and optimization using iozone and similar - + there are some easy changes that can be done to parallelize sequential writes, + and when signing is disabled to request larger read sizes (larger than + negotiated size) and send larger write sizes to modern servers. 4) More exhaustively test against less common servers 5) Continue to extend the smb3 "buildbot" which does automated xfstesting -against Windows, Samba and Azure currently - to add additional tests and -to allow the buildbot to execute the tests faster. The URL for the -buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com + against Windows, Samba and Azure currently - to add additional tests and + to allow the buildbot to execute the tests faster. The URL for the + buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com 6) Address various coverity warnings (most are not bugs per-se, but -the more warnings are addressed, the easier it is to spot real -problems that static analyzers will point out in the future). + the more warnings are addressed, the easier it is to spot real + problems that static analyzers will point out in the future). diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst index 4a804619cff2..d3fb67b8a976 100644 --- a/Documentation/filesystems/cifs/README +++ b/Documentation/admin-guide/cifs/usage.rst @@ -1,53 +1,61 @@ +===== +Usage +===== + This module supports the SMB3 family of advanced network protocols (as well as older dialects, originally called "CIFS" or SMB1). The CIFS VFS module for Linux supports many advanced network filesystem features such as hierarchical DFS like namespace, hardlinks, locking and more. -It was designed to comply with the SNIA CIFS Technical Reference (which -supersedes the 1992 X/Open SMB Standard) as well as to perform best practice -practical interoperability with Windows 2000, Windows XP, Samba and equivalent +It was designed to comply with the SNIA CIFS Technical Reference (which +supersedes the 1992 X/Open SMB Standard) as well as to perform best practice +practical interoperability with Windows 2000, Windows XP, Samba and equivalent servers. This code was developed in participation with the Protocol Freedom Information Foundation. CIFS and now SMB3 has now become a defacto standard for interoperating between Macs and Windows and major NAS appliances. Please see - MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) - http://protocolfreedom.org/ and - http://samba.org/samba/PFIF/ +MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) +http://protocolfreedom.org/ and +http://samba.org/samba/PFIF/ for more details. For questions or bug reports please contact: + smfrench@gmail.com See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils -Build instructions: +Build instructions ================== + For Linux: + 1) Download the kernel (e.g. from http://www.kernel.org) -and change directory into the top of the kernel directory tree -(e.g. /usr/src/linux-2.5.73) + and change directory into the top of the kernel directory tree + (e.g. /usr/src/linux-2.5.73) 2) make menuconfig (or make xconfig) 3) select cifs from within the network filesystem choices 4) save and exit 5) make -Installation instructions: +Installation instructions ========================= + If you have built the CIFS vfs as module (successfully) simply -type "make modules_install" (or if you prefer, manually copy the file to +type ``make modules_install`` (or if you prefer, manually copy the file to the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko). If you have built the CIFS vfs into the kernel itself, follow the instructions for your distribution on how to install a new kernel (usually you -would simply type "make install"). +would simply type ``make install``). If you do not have the utility mount.cifs (in the Samba 4.x source tree and on the CIFS VFS web site) copy it to the same directory in which mount helpers reside (usually /sbin). Although the helper software is not -required, mount.cifs is recommended. Most distros include a "cifs-utils" +required, mount.cifs is recommended. Most distros include a ``cifs-utils`` package that includes this utility so it is recommended to install this. Note that running the Winbind pam/nss module (logon service) on all of your @@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org If cifs is built as a module, then the size and number of network buffers and maximum number of simultaneous requests to one server can be configured. -Changing these from their defaults is not recommended. By executing modinfo +Changing these from their defaults is not recommended. By executing modinfo:: + modinfo kernel/fs/cifs/cifs.ko + on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made at module initialization time (by running insmod cifs.ko) can be seen. Recommendations =============== + To improve security the SMB2.1 dialect or later (usually will get SMB3) is now the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0" on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is @@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection and encrypted shares and stronger signing and authentication algorithms. There are additional mount options that may be helpful for SMB3 to get improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1): - "mfsymlinks" and "cifsacl" and "idsfromsid" + + ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid`` Allowing User Mounts ==================== + To permit users to mount and unmount over directories they own is possible with the cifs vfs. A way to enable such mounting is to mark the mount.cifs -utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to +utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to umount shares they mount requires + 1) mount.cifs version 1.4 or later 2) an entry for the share in /etc/fstab indicating that a user may -unmount it e.g. -//server/usersharename /mnt/username cifs user 0 0 + unmount it e.g.:: + + //server/usersharename /mnt/username cifs user 0 0 -Note that when the mount.cifs utility is run suid (allowing user mounts), -in order to reduce risks, the "nosuid" mount flag is passed in on mount to +Note that when the mount.cifs utility is run suid (allowing user mounts), +in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to disallow execution of an suid program mounted on the remote target. When mount is executed as root, nosuid is not passed in by default, and execution of suid programs on the remote target would be enabled -by default. This can be changed, as with nfs and other filesystems, -by simply specifying "nosuid" among the mount options. For user mounts -though to be able to pass the suid flag to mount requires rebuilding +by default. This can be changed, as with nfs and other filesystems, +by simply specifying ``nosuid`` among the mount options. For user mounts +though to be able to pass the suid flag to mount requires rebuilding mount.cifs with the following flag: CIFS_ALLOW_USR_SUID There is a corresponding manual page for cifs mounting in the Samba 3.0 and -later source tree in docs/manpages/mount.cifs.8 +later source tree in docs/manpages/mount.cifs.8 Allowing User Unmounts ====================== + To permit users to ummount directories that they have user mounted (see above), -the utility umount.cifs may be used. It may be invoked directly, or if +the utility umount.cifs may be used. It may be invoked directly, or if umount.cifs is placed in /sbin, umount can invoke the cifs umount helper (at least for most versions of the umount utility) for umount of cifs mounts, unless umount is invoked with -i (which will avoid invoking a umount helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked -as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions +as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions allow adding entries to a file to the /etc/permissions file to achieve the equivalent suid effect). For this utility to succeed the target path must be a cifs mount, and the uid of the current user must match the uid of the user who mounted the resource. -Also note that the customary way of allowing user mounts and unmounts is +Also note that the customary way of allowing user mounts and unmounts is (instead of using mount.cifs and unmount.cifs as suid) to add a line to the file /etc/fstab for each //server/share you wish to mount, but this can become unwieldy when potential mount targets include many or unpredictable UNC names. -Samba Considerations +Samba Considerations ==================== + Most current servers support SMB2.1 and SMB3 which are more secure, but there are useful protocol extensions for the older less secure CIFS dialect, so to get the maximum benefit if mounting using the older dialect (CIFS/SMB1), we recommend using a server that supports the SNIA CIFS Unix Extensions standard (e.g. almost any version of Samba ie version 2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers. -Note that uid, gid and file permissions will display default values if you do -not have a server that supports the Unix extensions for CIFS (such as Samba -2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add -the line: +Note that uid, gid and file permissions will display default values if you do +not have a server that supports the Unix extensions for CIFS (such as Samba +2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add +the line:: unix extensions = yes - -to your smb.conf file on the server. Note that the following smb.conf settings -are also useful (on the Samba server) when the majority of clients are Unix or -Linux: + +to your smb.conf file on the server. Note that the following smb.conf settings +are also useful (on the Samba server) when the majority of clients are Unix or +Linux:: case sensitive = yes - delete readonly = yes + delete readonly = yes ea support = yes Note that server ea support is required for supporting xattrs from the Linux -cifs client, and that EA support is present in later versions of Samba (e.g. +cifs client, and that EA support is present in later versions of Samba (e.g. 3.0.6 and later (also EA support works in all versions of Windows, at least to shares on NTFS filesystems). Extended Attribute (xattr) support is an optional feature of most Linux filesystems which may require enabling via make menuconfig. Client support for extended attributes (user xattr) can be -disabled on a per-mount basis by specifying "nouser_xattr" on mount. +disabled on a per-mount basis by specifying ``nouser_xattr`` on mount. The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers -version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and +version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and then POSIX support in the CIFS configuration options when building the cifs module. POSIX ACL support can be disabled on a per mount basic by specifying -"noacl" on mount. - -Some administrators may want to change Samba's smb.conf "map archive" and -"create mask" parameters from the default. Unless the create mask is changed +``noacl`` on mount. + +Some administrators may want to change Samba's smb.conf ``map archive`` and +``create mask`` parameters from the default. Unless the create mask is changed newly created files can end up with an unnecessarily restrictive default mode, which may not be what you want, although if the CIFS Unix extensions are enabled on the server and client, subsequent setattr calls (e.g. chmod) can -fix the mode. Note that creating special devices (mknod) remotely -may require specifying a mkdev function to Samba if you are not using +fix the mode. Note that creating special devices (mknod) remotely +may require specifying a mkdev function to Samba if you are not using Samba 3.0.6 or later. For more information on these see the manual pages -("man smb.conf") on the Samba server system. Note that the cifs vfs, -unlike the smbfs vfs, does not read the smb.conf on the client system -(the few optional settings are passed in on mount via -o parameters instead). +(``man smb.conf``) on the Samba server system. Note that the cifs vfs, +unlike the smbfs vfs, does not read the smb.conf on the client system +(the few optional settings are passed in on mount via -o parameters instead). Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete -open files (required for strict POSIX compliance). Windows Servers already +open files (required for strict POSIX compliance). Windows Servers already supported this feature. Samba server does not allow symlinks that refer to files outside of the share, so in Samba versions prior to 3.0.6, most symlinks to -files with absolute paths (ie beginning with slash) such as: +files with absolute paths (ie beginning with slash) such as:: + ln -s /mnt/foo bar -would be forbidden. Samba 3.0.6 server or later includes the ability to create -such symlinks safely by converting unsafe symlinks (ie symlinks to server + +would be forbidden. Samba 3.0.6 server or later includes the ability to create +such symlinks safely by converting unsafe symlinks (ie symlinks to server files that are outside of the share) to a samba specific format on the server that is ignored by local server applications and non-cifs clients and that will not be traversed by the Samba server). This is opaque to the Linux client application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or later, but only for remote clients using the CIFS Unix extensions, and will be invisbile to Windows clients and typically will not affect local -applications running on the same server as Samba. +applications running on the same server as Samba. -Use instructions: +Use instructions ================ -Once the CIFS VFS support is built into the kernel or installed as a module + +Once the CIFS VFS support is built into the kernel or installed as a module (cifs.ko), you can use mount syntax like the following to access Samba or -Mac or Windows servers: +Mac or Windows servers:: mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword Before -o the option -v may be specified to make the mount.cifs -mount helper display the mount steps more verbosely. +mount helper display the mount steps more verbosely. After -o the following commonly used cifs vfs specific options -are supported: +are supported:: username=<username> password=<password> domain=<domain name> - + Other cifs mount options are described below. Use of TCP names (in addition to ip addresses) is available if the mount helper (mount.cifs) is installed. If you do not trust the server to which are mounted, or if you do not have cifs signing enabled (and the physical network is insecure), consider use -of the standard mount options "noexec" and "nosuid" to reduce the risk of +of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of running an altered binary on your local system (downloaded from a hostile server or altered by a hostile router). Although mounting using format corresponding to the CIFS URL specification is not possible in mount.cifs yet, it is possible to use an alternate format for the server and sharename (which is somewhat similar to NFS style mount -syntax) instead of the more widely used UNC format (i.e. \\server\share): +syntax) instead of the more widely used UNC format (i.e. \\server\share):: + mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd When using the mount helper mount.cifs, passwords may be specified via alternate -mechanisms, instead of specifying it after -o using the normal "pass=" syntax +mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax on the command line: 1) By including it in a credential file. Specify credentials=filename as one -of the mount options. Credential files contain two lines - username=someuser - password=your_password +of the mount options. Credential files contain two lines:: + + username=someuser + password=your_password + 2) By specifying the password in the PASSWD environment variable (similarly -the user name can be taken from the USER environment variable). + the user name can be taken from the USER environment variable). 3) By specifying the password in a file by name via PASSWD_FILE 4) By specifying the password in a file by file descriptor via PASSWD_FD @@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry Restrictions ============ -Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC -1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a + +Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC +1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a problem as most servers support this. Valid filenames differ between Windows and Linux. Windows typically restricts -filenames which contain certain reserved characters (e.g.the character : +filenames which contain certain reserved characters (e.g.the character : which is used to delimit the beginning of a stream name by Windows), while Linux allows a slightly wider set of valid characters in filenames. Windows servers can remap such characters when an explicit mapping is specified in -the Server's registry. Samba starting with version 3.10 will allow such +the Server's registry. Samba starting with version 3.10 will allow such filenames (ie those which contain valid Linux characters, which normally would be forbidden for Windows/CIFS semantics) as long as the server is configured for Unix Extensions (and the client has not disabled /proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option -"mapposix" can be used on CIFS (vers=1.0) to force the mapping of +``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of illegal Windows/NTFS/SMB characters to a remap range (this mount parm -is the default for SMB3). This remap ("mapposix") range is also +is the default for SMB3). This remap (``mapposix``) range is also compatible with Mac (and "Services for Mac" on some older Windows). CIFS VFS Mount Options ====================== A partial list of the supported mount options follows: - username The user name to use when trying to establish + + username + The user name to use when trying to establish the CIFS session. - password The user password. If the mount helper is + password + The user password. If the mount helper is installed, the user will be prompted for password if not supplied. - ip The ip address of the target server - unc The target server Universal Network Name (export) to - mount. - domain Set the SMB/CIFS workgroup name prepended to the + ip + The ip address of the target server + unc + The target server Universal Network Name (export) to + mount. + domain + Set the SMB/CIFS workgroup name prepended to the username during CIFS session establishment - forceuid Set the default uid for inodes to the uid + forceuid + Set the default uid for inodes to the uid passed in on mount. For mounts to servers which do support the CIFS Unix extensions, such as a properly configured Samba server, the server provides @@ -276,32 +307,39 @@ A partial list of the supported mount options follows: extensions, the default uid (and gid) returned on lookup of existing files will be the uid (gid) of the person who executed the mount (root, except when mount.cifs - is configured setuid for user mounts) unless the "uid=" + is configured setuid for user mounts) unless the ``uid=`` (gid) mount option is specified. Also note that permission checks (authorization checks) on accesses to a file occur at the server, but there are cases in which an administrator may want to restrict at the client as well. For those servers which do not report a uid/gid owner (such as Windows), permissions can also be checked at the - client, and a crude form of client side permission checking - can be enabled by specifying file_mode and dir_mode on + client, and a crude form of client side permission checking + can be enabled by specifying file_mode and dir_mode on the client. (default) - forcegid (similar to above but for the groupid instead of uid) (default) - noforceuid Fill in file owner information (uid) by requesting it from + forcegid + (similar to above but for the groupid instead of uid) (default) + noforceuid + Fill in file owner information (uid) by requesting it from the server if possible. With this option, the value given in the uid= option (on mount) will only be used if the server can not support returning uids on inodes. - noforcegid (similar to above but for the group owner, gid, instead of uid) - uid Set the default uid for inodes, and indicate to the + noforcegid + (similar to above but for the group owner, gid, instead of uid) + uid + Set the default uid for inodes, and indicate to the cifs kernel driver which local user mounted. If the server supports the unix extensions the default uid is not used to fill in the owner fields of inodes (files) - unless the "forceuid" parameter is specified. - gid Set the default gid for inodes (similar to above). - file_mode If CIFS Unix extensions are not supported by the server + unless the ``forceuid`` parameter is specified. + gid + Set the default gid for inodes (similar to above). + file_mode + If CIFS Unix extensions are not supported by the server this overrides the default mode for file inodes. - fsc Enable local disk caching using FS-Cache (off by default). This - option could be useful to improve performance on a slow link, + fsc + Enable local disk caching using FS-Cache (off by default). This + option could be useful to improve performance on a slow link, heavily loaded server and/or network where reading from the disk is faster than reading from the server (over the network). This could also impact scalability positively as the @@ -310,18 +348,22 @@ A partial list of the supported mount options follows: type workloads. So, you need to consider carefully your workload/scenario before using this option. Currently, local disk caching is functional for CIFS files opened as read-only. - dir_mode If CIFS Unix extensions are not supported by the server + dir_mode + If CIFS Unix extensions are not supported by the server this overrides the default mode for directory inodes. - port attempt to contact the server on this tcp port, before + port + attempt to contact the server on this tcp port, before trying the usual ports (port 445, then 139). - iocharset Codepage used to convert local path names to and from + iocharset + Codepage used to convert local path names to and from Unicode. Unicode is used by default for network path names if the server supports it. If iocharset is not specified then the nls_default specified during the local client kernel build will be used. If server does not support Unicode, this parameter is unused. - rsize default read size (usually 16K). The client currently + rsize + default read size (usually 16K). The client currently can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize defaults to 16K and may be changed (from 8K to the maximum kmalloc size allowed by your kernel) at module install time @@ -333,10 +375,12 @@ A partial list of the supported mount options follows: newer servers (e.g. Samba 3.0.26 or later) do. rsize can be set from a minimum of 2048 to a maximum of 130048 (127K or CIFSMaxBufSize, whichever is smaller) - wsize default write size (default 57344) + wsize + default write size (default 57344) maximum wsize currently allowed by CIFS is 57344 (fourteen 4096 byte pages) - actimeo=n attribute cache timeout in seconds (default 1 second). + actimeo=n + attribute cache timeout in seconds (default 1 second). After this timeout, the cifs client requests fresh attribute information from the server. This option allows to tune the attribute cache timeout to suit the workload needs. Shorter @@ -345,49 +389,67 @@ A partial list of the supported mount options follows: of calls to the server at the expense of less stricter cache coherency checks (i.e. incorrect attribute cache for a short period of time). - rw mount the network share read-write (note that the + rw + mount the network share read-write (note that the server may still consider the share read-only) - ro mount network share read-only - version used to distinguish different versions of the + ro + mount network share read-only + version + used to distinguish different versions of the mount helper utility (not typically needed) - sep if first mount option (after the -o), overrides + sep + if first mount option (after the -o), overrides the comma as the separator between the mount - parms. e.g. + parms. e.g.:: + -o user=myname,password=mypassword,domain=mydom - could be passed instead with period as the separator by + + could be passed instead with period as the separator by:: + -o sep=.user=myname.password=mypassword.domain=mydom + this might be useful when comma is contained within username or password or domain. This option is less important when the cifs mount helper cifs.mount (version 1.1 or later) is used. - nosuid Do not allow remote executables with the suid bit + nosuid + Do not allow remote executables with the suid bit program to be executed. This is only meaningful for mounts to servers such as Samba which support the CIFS Unix Extensions. If you do not trust the servers in your network (your mount targets) it is recommended that you specify this option for greater security. - exec Permit execution of binaries on the mount. - noexec Do not permit execution of binaries on the mount. - dev Recognize block devices on the remote mount. - nodev Do not recognize devices on the remote mount. - suid Allow remote files on this mountpoint with suid enabled to + exec + Permit execution of binaries on the mount. + noexec + Do not permit execution of binaries on the mount. + dev + Recognize block devices on the remote mount. + nodev + Do not recognize devices on the remote mount. + suid + Allow remote files on this mountpoint with suid enabled to be executed (default for mounts when executed as root, nosuid is default for user mounts). - credentials Although ignored by the cifs kernel component, it is used by + credentials + Although ignored by the cifs kernel component, it is used by the mount helper, mount.cifs. When mount.cifs is installed it - opens and reads the credential file specified in order + opens and reads the credential file specified in order to obtain the userid and password arguments which are passed to the cifs vfs. - guest Although ignored by the kernel component, the mount.cifs + guest + Although ignored by the kernel component, the mount.cifs mount helper will not prompt the user for a password if guest is specified on the mount options. If no password is specified a null password will be used. - perm Client does permission checks (vfs_permission check of uid + perm + Client does permission checks (vfs_permission check of uid and gid of the file against the mode and desired operation), Note that this is in addition to the normal ACL check on the - target machine done by the server software. + target machine done by the server software. Client permission checking is enabled by default. - noperm Client does not do permission checks. This can expose + noperm + Client does not do permission checks. This can expose files on this mount to access by other users on the local client system. It is typically only needed when the server supports the CIFS Unix Extensions but the UIDs/GIDs on the @@ -399,7 +461,8 @@ A partial list of the supported mount options follows: Note that this does not affect the normal ACL check on the target machine done by the server software (of the server ACL against the user name provided at mount time). - serverino Use server's inode numbers instead of generating automatically + serverino + Use server's inode numbers instead of generating automatically incrementing inode numbers on the client. Although this will make it easier to spot hardlinked files (as they will have the same inode numbers) and inode numbers may be persistent, @@ -412,14 +475,16 @@ A partial list of the supported mount options follows: or the CIFS Unix Extensions equivalent and for those this mount option will have no effect. Exporting cifs mounts under nfsd requires this mount option on the cifs mount. - This is now the default if server supports the + This is now the default if server supports the required network operation. - noserverino Client generates inode numbers (rather than using the actual one + noserverino + Client generates inode numbers (rather than using the actual one from the server). These inode numbers will vary after unmount or reboot which can confuse some applications, but not all server filesystems support unique inode numbers. - setuids If the CIFS Unix extensions are negotiated with the server + setuids + If the CIFS Unix extensions are negotiated with the server the client will attempt to set the effective uid and gid of the local process on newly created files, directories, and devices (create, mkdir, mknod). If the CIFS Unix Extensions @@ -427,9 +492,10 @@ A partial list of the supported mount options follows: instead of using the default uid and gid specified on the mount, cache the new file's uid and gid locally which means that the uid for the file can change when the inode is - reloaded (or the user remounts the share). - nosetuids The client will not attempt to set the uid and gid on - on newly created files, directories, and devices (create, + reloaded (or the user remounts the share). + nosetuids + The client will not attempt to set the uid and gid on + on newly created files, directories, and devices (create, mkdir, mknod) which will result in the server setting the uid and gid to the default (usually the server uid of the user who mounted the share). Letting the server (rather than @@ -437,38 +503,49 @@ A partial list of the supported mount options follows: Unix Extensions are not negotiated then the uid and gid for new files will appear to be the uid (gid) of the mounter or the uid (gid) parameter specified on the mount. - netbiosname When mounting to servers via port 139, specifies the RFC1001 - source name to use to represent the client netbios machine + netbiosname + When mounting to servers via port 139, specifies the RFC1001 + source name to use to represent the client netbios machine name when doing the RFC1001 netbios session initialize. - direct Do not do inode data caching on files opened on this mount. + direct + Do not do inode data caching on files opened on this mount. This precludes mmapping files on this mount. In some cases with fast networks and little or no caching benefits on the client (e.g. when the application is doing large sequential - reads bigger than page size without rereading the same data) + reads bigger than page size without rereading the same data) this can provide better performance than the default - behavior which caches reads (readahead) and writes - (writebehind) through the local Linux client pagecache + behavior which caches reads (readahead) and writes + (writebehind) through the local Linux client pagecache if oplock (caching token) is granted and held. Note that direct allows write operations larger than page size to be sent to the server. - strictcache Use for switching on strict cache mode. In this mode the + strictcache + Use for switching on strict cache mode. In this mode the client read from the cache all the time it has Oplock Level II, otherwise - read from the server. All written data are stored in the cache, but if the client doesn't have Exclusive Oplock, it writes the data to the server. - rwpidforward Forward pid of a process who opened a file to any read or write + rwpidforward + Forward pid of a process who opened a file to any read or write operation on that file. This prevent applications like WINE from failing on read and write if we use mandatory brlock style. - acl Allow setfacl and getfacl to manage posix ACLs if server + acl + Allow setfacl and getfacl to manage posix ACLs if server supports them. (default) - noacl Do not allow setfacl and getfacl calls on this mount - user_xattr Allow getting and setting user xattrs (those attributes whose - name begins with "user." or "os2.") as OS/2 EAs (extended + noacl + Do not allow setfacl and getfacl calls on this mount + user_xattr + Allow getting and setting user xattrs (those attributes whose + name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended attributes) to the server. This allows support of the setfattr and getfattr utilities. (default) - nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs - mapchars Translate six of the seven reserved characters (not backslash) + nouser_xattr + Do not allow getfattr/setfattr to get/set/list xattrs + mapchars + Translate six of the seven reserved characters (not backslash):: + *?<>|: + to the remap range (above 0xF000), which also allows the CIFS client to recognize files created with such characters by Windows's POSIX emulation. This can @@ -477,39 +554,47 @@ A partial list of the supported mount options follows: whose names contain any of these seven characters). This has no effect if the server does not support Unicode on the wire. - nomapchars Do not translate any of these seven characters (default). - nocase Request case insensitive path name matching (case + nomapchars + Do not translate any of these seven characters (default). + nocase + Request case insensitive path name matching (case sensitive is the default if the server supports it). - (mount option "ignorecase" is identical to "nocase") - posixpaths If CIFS Unix extensions are supported, attempt to + (mount option ``ignorecase`` is identical to ``nocase``) + posixpaths + If CIFS Unix extensions are supported, attempt to negotiate posix path name support which allows certain characters forbidden in typical CIFS filenames, without requiring remapping. (default) - noposixpaths If CIFS Unix extensions are supported, do not request + noposixpaths + If CIFS Unix extensions are supported, do not request posix path name support (this may cause servers to reject creatingfile with certain reserved characters). - nounix Disable the CIFS Unix Extensions for this mount (tree + nounix + Disable the CIFS Unix Extensions for this mount (tree connection). This is rarely needed, but it may be useful in order to turn off multiple settings all at once (ie posix acls, posix locks, posix paths, symlink support and retrieving uids/gids/mode from the server) or to work around a bug in server which implement the Unix Extensions. - nobrl Do not send byte range lock requests to the server. + nobrl + Do not send byte range lock requests to the server. This is necessary for certain applications that break with cifs style mandatory byte range locks (and most cifs servers do not yet support requesting advisory byte range locks). - forcemandatorylock Even if the server supports posix (advisory) byte range + forcemandatorylock + Even if the server supports posix (advisory) byte range locking, send only mandatory lock requests. For some (presumably rare) applications, originally coded for DOS/Windows, which require Windows style mandatory byte range locking, they may be able to take advantage of this option, forcing the cifs client to only send mandatory locks even if the cifs server would support posix advisory locks. - "forcemand" is accepted as a shorter form of this mount + ``forcemand`` is accepted as a shorter form of this mount option. - nostrictsync If this mount option is set, when an application does an + nostrictsync + If this mount option is set, when an application does an fsync call then the cifs client does not send an SMB Flush to the server (to force the server to write all dirty data for this file immediately to disk), although cifs still sends @@ -522,41 +607,50 @@ A partial list of the supported mount options follows: crash. If this mount option is not set, by default cifs will send an SMB flush request (and wait for a response) on every fsync call. - nodfs Disable DFS (global name space support) even if the + nodfs + Disable DFS (global name space support) even if the server claims to support it. This can help work around a problem with parsing of DFS paths with Samba server versions 3.0.24 and 3.0.25. - remount remount the share (often used to change from ro to rw mounts - or vice versa) - cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for - the file. (EXPERIMENTAL) - servern Specify the server 's netbios name (RFC1001 name) to use - when attempting to setup a session to the server. + remount + remount the share (often used to change from ro to rw mounts + or vice versa) + cifsacl + Report mode bits (e.g. on stat) based on the Windows ACL for + the file. (EXPERIMENTAL) + servern + Specify the server 's netbios name (RFC1001 name) to use + when attempting to setup a session to the server. This is needed for mounting to some older servers (such as OS/2 or Windows 98 and Windows ME) since they do not support a default server name. A server name can be up to 15 characters long and is usually uppercased. - sfu When the CIFS Unix Extensions are not negotiated, attempt to + sfu + When the CIFS Unix Extensions are not negotiated, attempt to create device files and fifos in a format compatible with Services for Unix (SFU). In addition retrieve bits 10-12 of the mode via the SETFILEBITS extended attribute (as SFU does). In the future the bottom 9 bits of the mode also will be emulated using queries of the security descriptor (ACL). - mfsymlinks Enable support for Minshall+French symlinks + mfsymlinks + Enable support for Minshall+French symlinks (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks) This option is ignored when specified together with the 'sfu' option. Minshall+French symlinks are used even if the server supports the CIFS Unix Extensions. - sign Must use packet signing (helps avoid unwanted data modification + sign + Must use packet signing (helps avoid unwanted data modification by intermediate systems in the route). Note that signing does not work with lanman or plaintext authentication. - seal Must seal (encrypt) all data on this mounted share before + seal + Must seal (encrypt) all data on this mounted share before sending on the network. Requires support for Unix Extensions. Note that this differs from the sign mount option in that it causes encryption of data sent over this mounted share but other shares mounted to the same server are unaffected. - locallease This option is rarely needed. Fcntl F_SETLEASE is + locallease + This option is rarely needed. Fcntl F_SETLEASE is used by some applications such as Samba and NFSv4 server to check to see whether a file is cacheable. CIFS has no way to explicitly request a lease, but can check whether a file @@ -569,51 +663,73 @@ A partial list of the supported mount options follows: will allow the cifs client to check for leases (only) locally for files which are not oplocked instead of denying leases in that case. (EXPERIMENTAL) - sec Security mode. Allowed values are: - none attempt to connection as a null user (no name) - krb5 Use Kerberos version 5 authentication - krb5i Use Kerberos authentication and packet signing - ntlm Use NTLM password hashing (default) - ntlmi Use NTLM password hashing with signing (if + sec + Security mode. Allowed values are: + + none + attempt to connection as a null user (no name) + krb5 + Use Kerberos version 5 authentication + krb5i + Use Kerberos authentication and packet signing + ntlm + Use NTLM password hashing (default) + ntlmi + Use NTLM password hashing with signing (if /proc/fs/cifs/PacketSigningEnabled on or if - server requires signing also can be the default) - ntlmv2 Use NTLMv2 password hashing - ntlmv2i Use NTLMv2 password hashing with packet signing - lanman (if configured in kernel config) use older + server requires signing also can be the default) + ntlmv2 + Use NTLMv2 password hashing + ntlmv2i + Use NTLMv2 password hashing with packet signing + lanman + (if configured in kernel config) use older lanman hash -hard Retry file operations if server is not responding -soft Limit retries to unresponsive servers (usually only + hard + Retry file operations if server is not responding + soft + Limit retries to unresponsive servers (usually only one retry) before returning an error. (default) The mount.cifs mount helper also accepts a few mount options before -o including: +=============== =============================================================== -S take password from stdin (equivalent to setting the environment - variable "PASSWD_FD=0" + variable ``PASSWD_FD=0`` -V print mount.cifs version -? display simple usage information +=============== =============================================================== With most 2.6 kernel versions of modutils, the version of the cifs kernel module can be displayed via modinfo. Misc /proc/fs/cifs Flags and Debug Info ======================================= + Informational pseudo-files: + +======================= ======================================================= DebugData Displays information about active CIFS sessions and shares, features enabled as well as the cifs.ko version. Stats Lists summary resource usage information as well as per share statistics. +======================= ======================================================= Configuration pseudo-files: + +======================= ======================================================= SecurityFlags Flags which control security negotiation and also packet signing. Authentication (may/must) flags (e.g. for NTLM and/or NTLMv2) may be combined with the signing flags. Specifying two different password - hashing mechanisms (as "must use") on the other hand - does not make much sense. Default flags are - 0x07007 - (NTLM, NTLMv2 and packet signing allowed). The maximum + hashing mechanisms (as "must use") on the other hand + does not make much sense. Default flags are:: + + 0x07007 + + (NTLM, NTLMv2 and packet signing allowed). The maximum allowable flags if you want to allow mounts to servers using weaker password hashes is 0x37037 (lanman, plaintext, ntlm, ntlmv2, signing allowed). Some @@ -626,21 +742,21 @@ SecurityFlags Flags which control security negotiation and laintext passwords using the older lanman dialect form of the session setup SMB. (e.g. for authentication using plain text passwords, set the SecurityFlags - to 0x30030): - - may use packet signing 0x00001 - must use packet signing 0x01001 - may use NTLM (most common password hash) 0x00002 - must use NTLM 0x02002 - may use NTLMv2 0x00004 - must use NTLMv2 0x04004 - may use Kerberos security 0x00008 - must use Kerberos 0x08008 - may use lanman (weak) password hash 0x00010 - must use lanman password hash 0x10010 - may use plaintext passwords 0x00020 - must use plaintext passwords 0x20020 - (reserved for future packet encryption) 0x00040 + to 0x30030):: + + may use packet signing 0x00001 + must use packet signing 0x01001 + may use NTLM (most common password hash) 0x00002 + must use NTLM 0x02002 + may use NTLMv2 0x00004 + must use NTLMv2 0x04004 + may use Kerberos security 0x00008 + must use Kerberos 0x08008 + may use lanman (weak) password hash 0x00010 + must use lanman password hash 0x10010 + may use plaintext passwords 0x00020 + must use plaintext passwords 0x20020 + (reserved for future packet encryption) 0x00040 cifsFYI If set to non-zero value, additional debug information will be logged to the system error log. This field @@ -650,14 +766,19 @@ cifsFYI If set to non-zero value, additional debug information Some debugging statements are not compiled into the cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the kernel configuration. cifsFYI may be set to one or - nore of the following flags (7 sets them all): - - log cifs informational messages 0x01 - log return codes from cifs entry points 0x02 - log slow responses (ie which take longer than 1 second) - CONFIG_CIFS_STATS2 must be enabled in .config 0x04 - - + nore of the following flags (7 sets them all):: + + +-----------------------------------------------+------+ + | log cifs informational messages | 0x01 | + +-----------------------------------------------+------+ + | log return codes from cifs entry points | 0x02 | + +-----------------------------------------------+------+ + | log slow responses | 0x04 | + | (ie which take longer than 1 second) | | + | | | + | CONFIG_CIFS_STATS2 must be enabled in .config | | + +-----------------------------------------------+------+ + traceSMB If set to one, debug information is logged to the system error log with the start of smb requests and responses (default 0) @@ -671,24 +792,25 @@ LinuxExtensionsEnabled If set to one then the client will attempt to as support symbolic links. If you use servers such as Samba that support the CIFS Unix extensions but do not want to use symbolic link - support and want to map the uid and gid fields - to values supplied at mount (rather than the + 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) +======================= ======================================================= -These experimental features and tracing can be enabled by changing flags in -/proc/fs/cifs (after the cifs module has been installed or built into the -kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable -tracing to the kernel message log type: +These experimental features and tracing can be enabled by changing flags in +/proc/fs/cifs (after the cifs module has been installed or built into the +kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable +tracing to the kernel message log type:: echo 7 > /proc/fs/cifs/cifsFYI - + cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel logging of various informational messages. 2 enables logging of non-zero SMB return codes while 4 enables logging of requests that take longer -than one second to complete (except for byte range lock requests). +than one second to complete (except for byte range lock requests). Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration (.config). Setting it to seven enables all three. Finally, tracing -the start of smb requests and responses can be enabled via: +the start of smb requests and responses can be enabled via:: echo 1 > /proc/fs/cifs/traceSMB @@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc. Also recorded is the total bytes read and bytes written to the server for that share. Note that due to client caching effects this can be less than the number of bytes read and written by the application running on the client. -Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be +Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be useful if comparing performance of two different scenarios. - -Also note that "cat /proc/fs/cifs/DebugData" will display information about + +Also note that ``cat /proc/fs/cifs/DebugData`` will display information about the active sessions and the shares that are mounted. Enabling Kerberos (extended security) works but requires version 1.2 or later @@ -725,19 +847,23 @@ space to ease network configuration and improve reliability. To use cifs Kerberos and DFS support, the Linux keyutils package should be installed and something like the following lines should be added to the -/etc/request-key.conf file: +/etc/request-key.conf file:: -create cifs.spnego * * /usr/local/sbin/cifs.upcall %k -create dns_resolver * * /usr/local/sbin/cifs.upcall %k + create cifs.spnego * * /usr/local/sbin/cifs.upcall %k + create dns_resolver * * /usr/local/sbin/cifs.upcall %k CIFS kernel module parameters ============================= These module parameters can be specified or modified either during the time of -module loading or during the runtime by using the interface +module loading or during the runtime by using the interface:: + /proc/module/cifs/parameters/<param> -i.e. echo "value" > /sys/module/cifs/parameters/<param> +i.e.:: -1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default. - [Y/y/1]. To disable use any of [N/n/0]. + echo "value" > /sys/module/cifs/parameters/<param> +================= ========================================================== +1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default. + [Y/y/1]. To disable use any of [N/n/0]. +================= ========================================================== diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl index 322a9c833f23..322a9c833f23 100755 --- a/Documentation/filesystems/cifs/winucase_convert.pl +++ b/Documentation/admin-guide/cifs/winucase_convert.pl diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index e56e00655153..1c5d2281efc9 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -1647,8 +1647,17 @@ 0 = /dev/comedi0 First comedi device 1 = /dev/comedi1 Second comedi device ... + 47 = /dev/comedi47 48th comedi device - See http://stm.lbl.gov/comedi. + Minors 48 to 255 are reserved for comedi subdevices with + pathnames of the form "/dev/comediX_subdY", where "X" is the + minor number of the associated comedi device and "Y" is the + subdevice number. These subdevice minors are assigned + dynamically, so there is no fixed mapping from subdevice + pathnames to minor numbers. + + See http://www.comedi.org/ for information about the Comedi + project. 98 block User-mode virtual block device 0 = /dev/ubda First user-mode block device diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 25f3b2532198..e05e581af5cf 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -41,10 +41,11 @@ Related CVEs The following CVE entries describe Spectre variants: - ============= ======================= ================= + ============= ======================= ========================== CVE-2017-5753 Bounds check bypass Spectre variant 1 CVE-2017-5715 Branch target injection Spectre variant 2 - ============= ======================= ================= + CVE-2019-1125 Spectre v1 swapgs Spectre variant 1 (swapgs) + ============= ======================= ========================== Problem ------- @@ -78,6 +79,13 @@ There are some extensions of Spectre variant 1 attacks for reading data over the network, see :ref:`[12] <spec_ref12>`. However such attacks are difficult, low bandwidth, fragile, and are considered low risk. +Note that, despite "Bounds Check Bypass" name, Spectre variant 1 is not +only about user-controlled array bounds checks. It can affect any +conditional checks. The kernel entry code interrupt, exception, and NMI +handlers all have conditional swapgs checks. Those may be problematic +in the context of Spectre v1, as kernel code can speculatively run with +a user GS. + Spectre variant 2 (Branch Target Injection) ------------------------------------------- @@ -132,6 +140,9 @@ not cover all possible attack vectors. 1. A user process attacking the kernel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Spectre variant 1 +~~~~~~~~~~~~~~~~~ + The attacker passes a parameter to the kernel via a register or via a known address in memory during a syscall. Such parameter may be used later by the kernel as an index to an array or to derive @@ -144,7 +155,40 @@ not cover all possible attack vectors. potentially be influenced for Spectre attacks, new "nospec" accessor macros are used to prevent speculative loading of data. - Spectre variant 2 attacker can :ref:`poison <poison_btb>` the branch +Spectre variant 1 (swapgs) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + An attacker can train the branch predictor to speculatively skip the + swapgs path for an interrupt or exception. If they initialize + the GS register to a user-space value, if the swapgs is speculatively + skipped, subsequent GS-related percpu accesses in the speculation + window will be done with the attacker-controlled GS value. This + could cause privileged memory to be accessed and leaked. + + For example: + + :: + + if (coming from user space) + swapgs + mov %gs:<percpu_offset>, %reg + mov (%reg), %reg1 + + When coming from user space, the CPU can speculatively skip the + swapgs, and then do a speculative percpu load using the user GS + value. So the user can speculatively force a read of any kernel + value. If a gadget exists which uses the percpu value as an address + in another load/store, then the contents of the kernel value may + become visible via an L1 side channel attack. + + A similar attack exists when coming from kernel space. The CPU can + speculatively do the swapgs, causing the user GS to get used for the + rest of the speculative window. + +Spectre variant 2 +~~~~~~~~~~~~~~~~~ + + A spectre variant 2 attacker can :ref:`poison <poison_btb>` the branch target buffer (BTB) before issuing syscall to launch an attack. After entering the kernel, the kernel could use the poisoned branch target buffer on indirect jump and jump to gadget code in speculative @@ -280,11 +324,18 @@ The sysfs file showing Spectre variant 1 mitigation status is: The possible values in this file are: - ======================================= ================================= - 'Mitigation: __user pointer sanitation' Protection in kernel on a case by - case base with explicit pointer - sanitation. - ======================================= ================================= + .. list-table:: + + * - 'Not affected' + - The processor is not vulnerable. + * - 'Vulnerable: __user pointer sanitization and usercopy barriers only; no swapgs barriers' + - The swapgs protections are disabled; otherwise it has + protection in the kernel on a case by case base with explicit + pointer sanitation and usercopy LFENCE barriers. + * - 'Mitigation: usercopy/swapgs barriers and __user pointer sanitization' + - Protection in the kernel on a case by case base with explicit + pointer sanitation, usercopy LFENCE barriers, and swapgs LFENCE + barriers. However, the protections are put in place on a case by case basis, and there is no guarantee that all possible attack vectors for Spectre @@ -366,12 +417,27 @@ Turning on mitigation for Spectre variant 1 and Spectre variant 2 1. Kernel mitigation ^^^^^^^^^^^^^^^^^^^^ +Spectre variant 1 +~~~~~~~~~~~~~~~~~ + For the Spectre variant 1, vulnerable kernel code (as determined by code audit or scanning tools) is annotated on a case by case basis to use nospec accessor macros for bounds clipping :ref:`[2] <spec_ref2>` to avoid any usable disclosure gadgets. However, it may not cover all attack vectors for Spectre variant 1. + Copy-from-user code has an LFENCE barrier to prevent the access_ok() + check from being mis-speculated. The barrier is done by the + barrier_nospec() macro. + + For the swapgs variant of Spectre variant 1, LFENCE barriers are + added to interrupt, exception and NMI entry where needed. These + barriers are done by the FENCE_SWAPGS_KERNEL_ENTRY and + FENCE_SWAPGS_USER_ENTRY macros. + +Spectre variant 2 +~~~~~~~~~~~~~~~~~ + For Spectre variant 2 mitigation, the compiler turns indirect calls or jumps in the kernel into equivalent return trampolines (retpolines) :ref:`[3] <spec_ref3>` :ref:`[9] <spec_ref9>` to go to the target @@ -473,6 +539,12 @@ Mitigation control on the kernel command line Spectre variant 2 mitigation can be disabled or force enabled at the kernel command line. + nospectre_v1 + + [X86,PPC] Disable mitigations for Spectre Variant 1 + (bounds check bypass). With this option data leaks are + possible in the system. + nospectre_v2 [X86] Disable all mitigations for the Spectre variant 2 diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 33feab2f4084..34cc20ee7f3a 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -77,7 +77,10 @@ configure specific aspects of kernel behavior to your liking. blockdev/index ext4 binderfs + cifs/index xfs + jfs + ufs pm/index thunderbolt LSM/index @@ -98,6 +101,7 @@ configure specific aspects of kernel behavior to your liking. iostats kernel-per-CPU-kthreads laptops/index + auxdisplay/index lcd-panel-cgram ldm lockup-watchdogs @@ -105,6 +109,7 @@ configure specific aspects of kernel behavior to your liking. pnp rtc svga + wimax/index video-output .. only:: subproject and html diff --git a/Documentation/filesystems/jfs.txt b/Documentation/admin-guide/jfs.rst index 41fd757997b3..9e12d936bc90 100644 --- a/Documentation/filesystems/jfs.txt +++ b/Documentation/admin-guide/jfs.rst @@ -1,45 +1,59 @@ +=========================================== IBM's Journaled File System (JFS) for Linux +=========================================== JFS Homepage: http://jfs.sourceforge.net/ The following mount options are supported: + (*) == default -iocharset=name Character set to use for converting from Unicode to +iocharset=name + Character set to use for converting from Unicode to ASCII. The default is to do no conversion. Use iocharset=utf8 for UTF-8 translations. This requires CONFIG_NLS_UTF8 to be set in the kernel .config file. iocharset=none specifies the default behavior explicitly. -resize=value Resize the volume to <value> blocks. JFS only supports +resize=value + Resize the volume to <value> blocks. JFS only supports growing a volume, not shrinking it. This option is only valid during a remount, when the volume is mounted read-write. The resize keyword with no value will grow the volume to the full size of the partition. -nointegrity Do not write to the journal. The primary use of this option +nointegrity + Do not write to the journal. The primary use of this option is to allow for higher performance when restoring a volume from backup media. The integrity of the volume is not guaranteed if the system abnormally abends. -integrity(*) Commit metadata changes to the journal. Use this option to +integrity(*) + Commit metadata changes to the journal. Use this option to remount a volume where the nointegrity option was previously specified in order to restore normal behavior. -errors=continue Keep going on a filesystem error. -errors=remount-ro(*) Remount the filesystem read-only on an error. -errors=panic Panic and halt the machine if an error occurs. +errors=continue + Keep going on a filesystem error. +errors=remount-ro(*) + Remount the filesystem read-only on an error. +errors=panic + Panic and halt the machine if an error occurs. -uid=value Override on-disk uid with specified value -gid=value Override on-disk gid with specified value -umask=value Override on-disk umask with specified octal value. For - directories, the execute bit will be set if the corresponding +uid=value + Override on-disk uid with specified value +gid=value + Override on-disk gid with specified value +umask=value + Override on-disk umask with specified octal value. For + directories, the execute bit will be set if the corresponding read bit is set. -discard=minlen This enables/disables the use of discard/TRIM commands. -discard The discard/TRIM commands are sent to the underlying -nodiscard(*) block device when blocks are freed. This is useful for SSD - devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl +discard=minlen, discard/nodiscard(*) + This enables/disables the use of discard/TRIM commands. + The discard/TRIM commands are sent to the underlying + block device when blocks are freed. This is useful for SSD + devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl command is also available together with the nodiscard option. The value of minlen specifies the minimum blockcount, when a TRIM command to the block device is considered useful. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 7ccd158b3894..782e9072407b 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1044,6 +1044,10 @@ specified address. The serial port must already be setup and configured. Options are not yet supported. + sbi + Use RISC-V SBI (Supervisor Binary Interface) for early + console. + smh Use ARM semihosting calls for early console. s3c2410,<addr> @@ -1090,6 +1094,12 @@ the framebuffer, pass the 'ram' option so that it is mapped with the correct attributes. + linflex,<addr> + Use early console provided by Freescale LinFlex UART + serial driver for NXP S32V234 SoCs. A valid base + address must be provided, and the serial port must + already be setup and configured. + earlyprintk= [X86,SH,ARM,M68k,S390] earlyprintk=vga earlyprintk=sclp @@ -1197,12 +1207,6 @@ See comment before function elanfreq_setup() in arch/x86/kernel/cpu/cpufreq/elanfreq.c. - elevator= [IOSCHED] - Format: { "mq-deadline" | "kyber" | "bfq" } - See Documentation/block/deadline-iosched.rst, - Documentation/block/kyber-iosched.rst and - Documentation/block/bfq-iosched.rst for details. - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] Specifies physical address of start of kernel core image elf header and optionally the size. Generally @@ -1732,6 +1736,11 @@ Note that using this option lowers the security provided by tboot because it makes the system vulnerable to DMA attacks. + nobounce [Default off] + Disable bounce buffer for unstrusted devices such as + the Thunderbolt devices. This will treat the untrusted + devices as the trusted ones, hence might expose security + risks of DMA attacks. intel_idle.max_cstate= [KNL,HW,ACPI,X86] 0 disables intel_idle and fall back on acpi_idle. @@ -1811,7 +1820,7 @@ synchronously. iommu.passthrough= - [ARM64] Configure DMA to bypass the IOMMU by default. + [ARM64, X86] Configure DMA to bypass the IOMMU by default. Format: { "0" | "1" } 0 - Use IOMMU translation for DMA. 1 - Bypass the IOMMU for DMA. @@ -2373,7 +2382,7 @@ machvec= [IA-64] Force the use of a particular machine-vector (machvec) in a generic kernel. - Example: machvec=hpzx1_swiotlb + Example: machvec=hpzx1 machtype= [Loongson] Share the same kernel image file between different yeeloong laptop. @@ -2604,7 +2613,7 @@ expose users to several CPU vulnerabilities. Equivalent to: nopti [X86,PPC] kpti=0 [ARM64] - nospectre_v1 [PPC] + nospectre_v1 [X86,PPC] nobp=0 [S390] nospectre_v2 [X86,PPC,S390,ARM64] spectre_v2_user=off [X86] @@ -2965,9 +2974,9 @@ nosmt=force: Force disable SMT, cannot be undone via the sysfs control file. - nospectre_v1 [PPC] Disable mitigations for Spectre Variant 1 (bounds - check bypass). With this option data leaks are possible - in the system. + nospectre_v1 [X86,PPC] Disable mitigations for Spectre Variant 1 + (bounds check bypass). With this option data leaks are + possible in the system. nospectre_v2 [X86,PPC_FSL_BOOK3E,ARM64] Disable all mitigations for the Spectre variant 2 (indirect branch prediction) @@ -3837,12 +3846,13 @@ RCU_BOOST is not set, valid values are 0-99 and the default is zero (non-realtime operation). - rcutree.rcu_nocb_leader_stride= [KNL] - Set the number of NOCB kthread groups, which - defaults to the square root of the number of - CPUs. Larger numbers reduces the wakeup overhead - on the per-CPU grace-period kthreads, but increases - that same overhead on each group's leader. + rcutree.rcu_nocb_gp_stride= [KNL] + Set the number of NOCB callback kthreads in + each group, which defaults to the square root + of the number of CPUs. Larger numbers reduce + the wakeup overhead on the global grace-period + kthread, but increases that same overhead on + each group's NOCB grace-period kthread. rcutree.qhimark= [KNL] Set threshold of queued RCU callbacks beyond which @@ -4047,6 +4057,10 @@ rcutorture.verbose= [KNL] Enable additional printk() statements. + rcupdate.rcu_cpu_stall_ftrace_dump= [KNL] + Dump ftrace buffer after reporting RCU CPU + stall warning. + rcupdate.rcu_cpu_stall_suppress= [KNL] Suppress RCU CPU stall warning messages. @@ -4090,6 +4104,13 @@ Run specified binary instead of /init from the ramdisk, used for early userspace startup. See initrd. + rdrand= [X86] + force - Override the decision by the kernel to hide the + advertisement of RDRAND support (this affects + certain AMD processors because of buggy BIOS + support, specifically around the suspend/resume + path). + rdt= [HW,X86,RDT] Turn on/off individual RDT features. List is: cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, l2cdp, diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 4f18456dd3b1..baeeba8762ae 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -274,9 +274,7 @@ To reduce its OS jitter, do any of the following: (based on an earlier one from Gilad Ben-Yossef) that reduces or even eliminates vmstat overhead for some workloads at https://lkml.org/lkml/2013/9/4/379. - e. Boot with "elevator=noop" to avoid workqueue use by - the block layer. - f. If running on high-end powerpc servers, build with + e. If running on high-end powerpc servers, build with CONFIG_PPC_RTAS_DAEMON=n. This prevents the RTAS daemon from running on each CPU every second or so. (This will require editing Kconfig files and will defeat @@ -284,12 +282,12 @@ To reduce its OS jitter, do any of the following: due to the rtas_event_scan() function. WARNING: Please check your CPU specifications to make sure that this is safe on your particular system. - g. If running on Cell Processor, build your kernel with + f. If running on Cell Processor, build your kernel with CBE_CPUFREQ_SPU_GOVERNOR=n to avoid OS jitter from spu_gov_work(). WARNING: Please check your CPU specifications to make sure that this is safe on your particular system. - h. If running on PowerMAC, build your kernel with + g. If running on PowerMAC, build your kernel with CONFIG_PMAC_RACKMETER=n to disable the CPU-meter, avoiding OS jitter from rackmeter_do_timer(). diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index adea0bf2acc5..822907dcc845 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -49,6 +49,7 @@ detailed description): - Fan control and monitoring: fan speed, fan enable/disable - WAN enable and disable - UWB enable and disable + - LCD Shadow (PrivacyGuard) enable and disable A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1409,6 +1410,28 @@ Sysfs notes Documentation/driver-api/rfkill.rst for details. +LCD Shadow control +------------------ + +procfs: /proc/acpi/ibm/lcdshadow + +Some newer T480s and T490s ThinkPads provide a feature called +PrivacyGuard. By turning this feature on, the usable vertical and +horizontal viewing angles of the LCD can be limited (as if some privacy +screen was applied manually in front of the display). + +procfs notes +^^^^^^^^^^^^ + +The available commands are:: + + echo '0' >/proc/acpi/ibm/lcdshadow + echo '1' >/proc/acpi/ibm/lcdshadow + +The first command ensures the best viewing angle and the latter one turns +on the feature, restricting the viewing angles. + + EXPERIMENTAL: UWB ----------------- diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst new file mode 100644 index 000000000000..517a205abad6 --- /dev/null +++ b/Documentation/admin-guide/perf/imx-ddr.rst @@ -0,0 +1,52 @@ +===================================================== +Freescale i.MX8 DDR Performance Monitoring Unit (PMU) +===================================================== + +There are no performance counters inside the DRAM controller, so performance +signals are brought out to the edge of the controller where a set of 4 x 32 bit +counters is implemented. This is controlled by the CSV modes programed in counter +control register which causes a large number of PERF signals to be generated. + +Selection of the value for each counter is done via the config registers. There +is one register for each counter. Counter 0 is special in that it always counts +“time” and when expired causes a lock on itself and the other counters and an +interrupt is raised. If any other counter overflows, it continues counting, and +no interrupt is raised. + +The "format" directory describes format of the config (event ID) and config1 +(AXI filtering) fields of the perf_event_attr structure, see /sys/bus/event_source/ +devices/imx8_ddr0/format/. The "events" directory describes the events types +hardware supported that can be used with perf tool, see /sys/bus/event_source/ +devices/imx8_ddr0/events/. + e.g.:: + perf stat -a -e imx8_ddr0/cycles/ cmd + perf stat -a -e imx8_ddr0/read/,imx8_ddr0/write/ cmd + +AXI filtering is only used by CSV modes 0x41 (axid-read) and 0x42 (axid-write) +to count reading or writing matches filter setting. Filter setting is various +from different DRAM controller implementations, which is distinguished by quirks +in the driver. + +* With DDR_CAP_AXI_ID_FILTER quirk. + Filter is defined with two configuration parts: + --AXI_ID defines AxID matching value. + --AXI_MASKING defines which bits of AxID are meaningful for the matching. + 0：corresponding bit is masked. + 1: corresponding bit is not masked, i.e. used to do the matching. + + AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter. + When non-masked bits are matching corresponding AXI_ID bits then counter is + incremented. Perf counter is incremented if + AxID && AXI_MASKING == AXI_ID && AXI_MASKING + + This filter doesn't support filter different AXI ID for axid-read and axid-write + event at the same time as this filter is shared between counters. + e.g.:: + perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + + NOTE: axi_mask is inverted in userspace(i.e. set bits are bits to mask), and + it will be reverted in driver automatically. so that the user can just specify + axi_id to monitor a specific id, rather than having to specify axi_mask. + e.g.:: + perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index a7d44e71019d..287b98708a40 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -39,7 +39,6 @@ Table : Subdirectories in /proc/sys/net 802 E802 protocol ax25 AX25 ethernet Ethernet protocol rose X.25 PLP layer ipv4 IP version 4 x25 X.25 protocol - ipx IPX token-ring IBM token ring bridge Bridging decnet DEC net ipv6 IP version 6 tipc TIPC ========= =================== = ========== ================== @@ -401,33 +400,7 @@ interface. (network) that the route leads to, the router (may be directly connected), the route flags, and the device the route is using. - -5. IPX ------- - -The IPX protocol has no tunable values in proc/sys/net. - -The IPX protocol does, however, provide proc/net/ipx. This lists each IPX -socket giving the local and remote addresses in Novell format (that is -network:node:port). In accordance with the strange Novell tradition, -everything but the port is in hex. Not_Connected is displayed for sockets that -are not tied to a specific remote address. The Tx and Rx queue sizes indicate -the number of bytes pending for transmission and reception. The state -indicates the state the socket is in and the uid is the owning uid of the -socket. - -The /proc/net/ipx_interface file lists all IPX interfaces. For each interface -it gives the network number, the node number, and indicates if the network is -the primary network. It also indicates which device it is bound to (or -Internal for internal networks) and the Frame Type if appropriate. Linux -supports 802.3, 802.2, 802.2 SNAP and DIX (Blue Book) ethernet framing for -IPX. - -The /proc/net/ipx_route table holds a list of IPX routes. For each route it -gives the destination network, the router node (or Directly) and the network -address of the router (or Connected) for internal networks. - -6. TIPC +5. TIPC ------- tipc_rmem diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 7b9035c01a2e..72b2cfb066f4 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -171,22 +171,20 @@ It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) -``reboot(b)`` is good when you're unable to shut down. But you should also -``sync(s)`` and ``umount(u)`` first. +``reboot(b)`` is good when you're unable to shut down, it is an equivalent +of pressing the "reset" button. ``crash(c)`` can be used to manually trigger a crashdump when the system is hung. Note that this just triggers a crash if there is no dump mechanism available. -``sync(s)`` is great when your system is locked up, it allows you to sync your -disks and will certainly lessen the chance of data loss and fscking. Note -that the sync hasn't taken place until you see the "OK" and "Done" appear -on the screen. (If the kernel is really in strife, you may not ever get the -OK or Done message...) +``sync(s)`` is handy before yanking removable medium or after using a rescue +shell that provides no graceful shutdown -- it will ensure your data is +safely written to the disk. Note that the sync hasn't taken place until you see +the "OK" and "Done" appear on the screen. -``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally -``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved -me many a fsck. Again, the unmount (remount read-only) hasn't taken place until -you see the "OK" and "Done" message appear on the screen. +``umount(u)`` can be used to mark filesystems as properly unmounted. From the +running system's point of view, they will be remounted read-only. The remount +isn't complete until you see the "OK" and "Done" message appear on the screen. The loglevels ``0``-``9`` are useful when your console is being flooded with kernel messages you do not want to see. Selecting ``0`` will prevent all but diff --git a/Documentation/filesystems/ufs.txt b/Documentation/admin-guide/ufs.rst index 7a602adeca2b..55d15297f8d7 100644 --- a/Documentation/filesystems/ufs.txt +++ b/Documentation/admin-guide/ufs.rst @@ -1,37 +1,45 @@ -USING UFS +========= +Using UFS ========= mount -t ufs -o ufstype=type_of_ufs device dir -UFS OPTIONS +UFS Options =========== ufstype=type_of_ufs UFS is a file system widely used in different operating systems. The problem are differences among implementations. Features of some implementations are undocumented, so its hard to recognize - type of ufs automatically. That's why user must specify type of + type of ufs automatically. That's why user must specify type of ufs manually by mount option ufstype. Possible values are: - old old format of ufs + old + old format of ufs default value, supported as read-only - 44bsd used in FreeBSD, NetBSD, OpenBSD + 44bsd + used in FreeBSD, NetBSD, OpenBSD supported as read-write - ufs2 used in FreeBSD 5.x + ufs2 + used in FreeBSD 5.x supported as read-write - 5xbsd synonym for ufs2 + 5xbsd + synonym for ufs2 - sun used in SunOS (Solaris) + sun + used in SunOS (Solaris) supported as read-write - sunx86 used in SunOS for Intel (Solarisx86) + sunx86 + used in SunOS for Intel (Solarisx86) supported as read-write - hp used in HP-UX + hp + used in HP-UX supported as read-only nextstep @@ -47,14 +55,14 @@ ufstype=type_of_ufs supported as read-only -POSSIBLE PROBLEMS -================= +Possible Problems +----------------- See next section, if you have any. -BUG REPORTS -=========== +Bug Reports +----------- Any ufs bug report you can send to daniel.pirkl@email.cz or to dushistov@mail.ru (do not send partition tables bug reports). diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst index 7dffd8919cb0..194388c0c351 100644 --- a/Documentation/wimax/README.i2400m +++ b/Documentation/admin-guide/wimax/i2400m.rst @@ -1,18 +1,23 @@ +.. include:: <isonum.txt> - Driver for the Intel Wireless Wimax Connection 2400m +==================================================== +Driver for the Intel Wireless Wimax Connection 2400m +==================================================== - (C) 2008 Intel Corporation < linux-wimax@intel.com > +:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com > This provides a driver for the Intel Wireless WiMAX Connection 2400m and a basic Linux kernel WiMAX stack. 1. Requirements +=============== * Linux installation with Linux kernel 2.6.22 or newer (if building from a separate tree) * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel Wireless WiMAX/WiFi Link 5x50 series. * build tools: + + Linux kernel development package for the target kernel; to build against your currently running kernel, you need to have the kernel development package corresponding to the running @@ -22,8 +27,10 @@ + GNU C Compiler, make 2. Compilation and installation +=============================== 2.1. Compilation of the drivers included in the kernel +------------------------------------------------------ Configure the kernel; to enable the WiMAX drivers select Drivers > Networking Drivers > WiMAX device support. Enable all of them as @@ -36,37 +43,39 @@ Compile and install your kernel as usual. 2.2. Compilation of the drivers distributed as an standalone module +------------------------------------------------------------------- - To compile + To compile:: -$ cd source/directory -$ make + $ cd source/directory + $ make Once built you can load and unload using the provided load.sh script; load.sh will load the modules, load.sh u will unload them. To install in the default kernel directories (and enable auto loading - when the device is plugged): + when the device is plugged):: -$ make install -$ depmod -a + $ make install + $ depmod -a If your kernel development files are located in a non standard directory or if you want to build for a kernel that is not the - currently running one, set KDIR to the right location: + currently running one, set KDIR to the right location:: -$ make KDIR=/path/to/kernel/dev/tree + $ make KDIR=/path/to/kernel/dev/tree For more information, please contact linux-wimax@intel.com. 3. Installing the firmware +-------------------------- The firmware can be obtained from http://linuxwimax.org or might have been supplied with your hardware. - It has to be installed in the target system: - * -$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf + It has to be installed in the target system:: + + $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf * NOTE: if your firmware came in an .rpm or .deb file, just install it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg @@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf with other types. 4. Design +========= This package contains two major parts: a WiMAX kernel stack and a driver for the Intel i2400m. @@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf API calls should be replaced with the target OS's. 5. Usage +======== To load the driver, follow the instructions in the install section; once the driver is loaded, plug in the device (unless it is permanently plugged in). The driver will enumerate the device, upload the firmware and output messages in the kernel log (dmesg, /var/log/messages or - /var/log/kern.log) such as: + /var/log/kern.log) such as:: -... -i2400m_usb 5-4:1.0: firmware interface version 8.0.0 -i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready + ... + i2400m_usb 5-4:1.0: firmware interface version 8.0.0 + i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready At this point the device is ready to work. @@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready on how to scan, connect and disconnect. 5.1. Module parameters +---------------------- Module parameters can be set at kernel or module load time or by - echoing values: + echoing values:: -$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME + $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME To make changes permanent, for example, for the i2400m module, you can - also create a file named /etc/modprobe.d/i2400m containing: + also create a file named /etc/modprobe.d/i2400m containing:: -options i2400m idle_mode_disabled=1 + options i2400m idle_mode_disabled=1 - To find which parameters are supported by a module, run: + To find which parameters are supported by a module, run:: -$ modinfo path/to/module.ko + $ modinfo path/to/module.ko During kernel bootup (if the driver is linked in the kernel), specify - the following to the kernel command line: + the following to the kernel command line:: -i2400m.PARAMETER=VALUE + i2400m.PARAMETER=VALUE 5.1.1. i2400m: idle_mode_disabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The i2400m module supports a parameter to disable idle mode. This parameter, once set, will take effect only when the device is reinitialized by the driver (eg: following a reset or a reconnect). 5.2. Debug operations: debugfs entries +-------------------------------------- The driver will register debugfs entries that allow the user to tweak debug settings. There are three main container directories where entries are placed, which correspond to the three blocks a i2400m WiMAX driver has: + * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack controls * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic @@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE /sys/kernel/debug, those paths will change. 5.2.1. Increasing debug output +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The files named *dl_* indicate knobs for controlling the debug output - of different submodules: - * -# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb -/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx -/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx -/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill -/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev -/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw -/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs -/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver -/sys/kernel/debug/wimax:wmx0/i2400m/dl_control -/sys/kernel/debug/wimax:wmx0/wimax_dl_stack -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg -/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table -/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs + of different submodules:: + + # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb + /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx + /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx + /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill + /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev + /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw + /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs + /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver + /sys/kernel/debug/wimax:wmx0/i2400m/dl_control + /sys/kernel/debug/wimax:wmx0/wimax_dl_stack + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg + /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs By reading the file you can obtain the current value of said debug level; by writing to it, you can set it. To increase the debug level of, for example, the i2400m's generic TX - engine, just write: + engine, just write:: -$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx + $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx Increasing numbers yield increasing debug information; for details of what is printed and the available levels, check the source. The code uses 0 for disabled and increasing values until 8. 5.2.2. RX and TX statistics +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The i2400m/rx_stats and i2400m/tx_stats provide statistics about the - data reception/delivery from the device: + data reception/delivery from the device:: -$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats -45 1 3 34 3104 48 480 + $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats + 45 1 3 34 3104 48 480 + + The numbers reported are: - The numbers reported are * packets/RX-buffer: total, min, max * RX-buffers: total RX buffers received, accumulated RX buffer size in bytes, min size received, max size received @@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats Thus, to find the average buffer size received, divide accumulated RX-buffer / total RX-buffers. - To clear the statistics back to 0, write anything to the rx_stats file: + To clear the statistics back to 0, write anything to the rx_stats file:: -$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats + $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats Likewise for TX. @@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats to the host. See drivers/net/wimax/i2400m/tx.c. 5.2.3. Tracing messages received from user space +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To echo messages received from user space into the trace pipe that the i2400m driver creates, set the debug file i2400m/trace_msg_from_user to - 1: - * -$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user + 1:: + + $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user 5.2.4. Performing a device reset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By writing a 0, a 1 or a 2 to the file /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without @@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user (bus specific) reset on the device. 5.2.5. Asking the device to enter power saving mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the device will attempt to enter power saving mode. 6. Troubleshooting +================== -6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed' +6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed`` +---------------------------------------------------------------------- If upon connecting the device, the following is output in the kernel - log: + log:: -i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2 + i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2 This means that the driver cannot locate the firmware file named /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst new file mode 100644 index 000000000000..fdf7c1f99ff5 --- /dev/null +++ b/Documentation/admin-guide/wimax/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +WiMAX subsystem +=============== + +.. toctree:: + :maxdepth: 2 + + wimax + + i2400m + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst index b78c4378084e..817ee8ba2732 100644 --- a/Documentation/wimax/README.wimax +++ b/Documentation/admin-guide/wimax/wimax.rst @@ -1,12 +1,16 @@ +.. include:: <isonum.txt> - Linux kernel WiMAX stack +======================== +Linux kernel WiMAX stack +======================== - (C) 2008 Intel Corporation < linux-wimax@intel.com > +:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com > This provides a basic Linux kernel WiMAX stack to provide a common control API for WiMAX devices, usable from kernel and user space. 1. Design +========= The WiMAX stack is designed to provide for common WiMAX control services to current and future WiMAX devices from any vendor. @@ -31,6 +35,7 @@ include/linux/wimax.h. 2. Usage +======== For usage in a driver (registration, API, etc) please refer to the instructions in the header file include/linux/wimax.h. @@ -40,6 +45,7 @@ control. 2.1. Obtaining debug information: debugfs entries +------------------------------------------------- The WiMAX stack is compiled, by default, with debug messages that can be used to diagnose issues. By default, said messages are disabled. @@ -52,20 +58,22 @@ create more subentries below it. 2.1.1. Increasing debug output +------------------------------ The files named *dl_* indicate knobs for controlling the debug output - of different submodules of the WiMAX stack: - * -# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* -/sys/kernel/debug/wimax:wmx0/wimax_dl_stack -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg -/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table -/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs -/sys/kernel/debug/wimax:wmx0/.... # other driver specific files - - NOTE: Of course, if debugfs is mounted in a directory other than + of different submodules of the WiMAX stack:: + + # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* + /sys/kernel/debug/wimax:wmx0/wimax_dl_stack + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg + /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs + /sys/kernel/debug/wimax:wmx0/.... # other driver specific files + + NOTE: + Of course, if debugfs is mounted in a directory other than /sys/kernel/debug, those paths will change. By reading the file you can obtain the current value of said debug @@ -74,7 +82,7 @@ To increase the debug level of, for example, the id-table submodule, just write: -$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table Increasing numbers yield increasing debug information; for details of what is printed and the available levels, check the source. The code diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index e76665a8f2f2..fb5b39f73059 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -337,11 +337,12 @@ None at present. Removed Sysctls =============== +============================= ======= Name Removed - ---- ------- +============================= ======= fs.xfs.xfsbufd_centisec v4.0 fs.xfs.age_buffer_centisecs v4.0 - +============================= ======= Error handling ============== diff --git a/Documentation/arm/sa1100/adsbitsy.rst b/Documentation/arm/sa1100/adsbitsy.rst deleted file mode 100644 index c179cb26b682..000000000000 --- a/Documentation/arm/sa1100/adsbitsy.rst +++ /dev/null @@ -1,51 +0,0 @@ -=============================== -ADS Bitsy Single Board Computer -=============================== - -(It is different from Bitsy(iPAQ) of Compaq) - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The Linux support for this product has been provided by -Woojung Huh <whuh@applieddata.net> - -Use 'make adsbitsy_config' before any 'make config'. -This will set up defaults for ADS Bitsy support. - -The kernel zImage is linked to be loaded and executed at 0xc0400000. - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- SA1100 serial port -- pcmcia, compact flash -- touchscreen(ucb1200) -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console - -To do -===== - -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. - You should be careful to use flash on board. - Its partition is different from GraphicsClient Plus and GraphicsMaster - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arm/sa1100/assabet.rst index 3e704831c311..a761e128fb08 100644 --- a/Documentation/arm/sa1100/assabet.rst +++ b/Documentation/arm/sa1100/assabet.rst @@ -14,7 +14,7 @@ Building the kernel To build the kernel with current defaults:: - make assabet_config + make assabet_defconfig make oldconfig make zImage diff --git a/Documentation/arm/sa1100/brutus.rst b/Documentation/arm/sa1100/brutus.rst deleted file mode 100644 index e1a23bee6d44..000000000000 --- a/Documentation/arm/sa1100/brutus.rst +++ /dev/null @@ -1,69 +0,0 @@ -====== -Brutus -====== - -Brutus is an evaluation platform for the SA1100 manufactured by Intel. -For more details, see: - -http://developer.intel.com - -To compile for Brutus, you must issue the following commands:: - - make brutus_config - make config - [accept all the defaults] - make zImage - -The resulting kernel will end up in linux/arch/arm/boot/zImage. This file -must be loaded at 0xc0008000 in Brutus's memory and execution started at -0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon -entry. - -But prior to execute the kernel, a ramdisk image must also be loaded in -memory. Use memory address 0xd8000000 for this. Note that the file -containing the (compressed) ramdisk image must not exceed 4 MB. - -Typically, you'll need angelboot to load the kernel. -The following angelboot.opt file should be used:: - - base 0xc0008000 - entry 0xc0008000 - r0 0x00000000 - r1 0x00000010 - device /dev/ttyS0 - options "9600 8N1" - baud 115200 - otherfile ramdisk_img.gz - otherbase 0xd8000000 - -Then load the kernel and ramdisk with:: - - angelboot -f angelboot.opt zImage - -The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your -host PC) is used by angel to load the kernel and ramdisk image. The serial -console is provided through the second Brutus serial port. To access it, -you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow -control. - -Currently supported -=================== - - - RS232 serial ports - - audio output - - LCD screen - - keyboard - -The actual Brutus support may not be complete without extra patches. -If such patches exist, they should be found from -ftp.netwinder.org/users/n/nico. - -A full PCMCIA support is still missing, although it's possible to hack -some drivers in order to drive already inserted cards at boot time with -little modifications. - -Any contribution is welcome. - -Please send patches to nico@fluxnic.net - -Have Fun ! diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst deleted file mode 100644 index 81043d0c6d64..000000000000 --- a/Documentation/arm/sa1100/freebird.rst +++ /dev/null @@ -1,25 +0,0 @@ -======== -Freebird -======== - -Freebird-1.1 is produced by Legend(C), Inc. -`http://web.archive.org/web/*/http://www.legend.com.cn` -and software/linux maintained by Coventive(C), Inc. -(http://www.coventive.com) - -Based on the Nicolas's strongarm kernel tree. - -Maintainer: - -Chester Kuo - - <chester@coventive.com> - - <chester@linux.org.tw> - -Author: - -- Tim wu <timwu@coventive.com> -- CIH <cih@coventive.com> -- Eric Peng <ericpeng@coventive.com> -- Jeff Lee <jeff_lee@coventive.com> -- Allen Cheng -- Tony Liu <tonyliu@coventive.com> diff --git a/Documentation/arm/sa1100/graphicsclient.rst b/Documentation/arm/sa1100/graphicsclient.rst deleted file mode 100644 index a73d61c3ce91..000000000000 --- a/Documentation/arm/sa1100/graphicsclient.rst +++ /dev/null @@ -1,102 +0,0 @@ -============================================= -ADS GraphicsClient Plus Single Board Computer -============================================= - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The original Linux support for this product has been provided by -Nicolas Pitre <nico@fluxnic.net>. Continued development work by -Woojung Huh <whuh@applieddata.net> - -It's currently possible to mount a root filesystem via NFS providing a -complete Linux environment. Otherwise a ramdisk image may be used. The -board supports MTD/JFFS, so you could also mount something on there. - -Use 'make graphicsclient_config' before any 'make config'. This will set up -defaults for GraphicsClient Plus support. - -The kernel zImage is linked to be loaded and executed at 0xc0200000. -Also the following registers should have the specified values upon entry:: - - r0 = 0 - r1 = 29 (this is the GraphicsClient architecture number) - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. -Angel is not available for the GraphicsClient Plus AFAIK. - -There is a board known as just the GraphicsClient that ADS used to -produce but has end of lifed. This code will not work on the older -board with the ADS bootloader, but should still work with Angel, -as outlined below. In any case, if you're planning on deploying -something en masse, you should probably get the newer board. - -If using Angel on the older boards, here is a typical angel.opt option file -if the kernel is loaded through the Angel Debug Monitor:: - - base 0xc0200000 - entry 0xc0200000 - r0 0x00000000 - r1 0x0000001d - device /dev/ttyS1 - options "38400 8N1" - baud 115200 - #otherfile ramdisk.gz - #otherbase 0xc0800000 - exec minicom - -Then the kernel (and ramdisk if otherfile/otherbase lines above are -uncommented) would be loaded with:: - - angelboot -f angelboot.opt zImage - -Here it is assumed that the board is connected to ttyS1 on your PC -and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow -control by default. - -If any other bootloader is used, ensure it accomplish the same, especially -for r0/r1 register values before jumping into the kernel. - - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation - and example user space code. ps/2 keybd is multiplexed through this driver - -To do -===== - -- UCB1200 audio with new ucb_generic layer -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. mtd0 is where - the ADS boot ROM and zImage is stored. It's been marked as - read-only to keep you from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/graphicsmaster.rst b/Documentation/arm/sa1100/graphicsmaster.rst deleted file mode 100644 index e39892514f0c..000000000000 --- a/Documentation/arm/sa1100/graphicsmaster.rst +++ /dev/null @@ -1,60 +0,0 @@ -======================================== -ADS GraphicsMaster Single Board Computer -======================================== - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The original Linux support for this product has been provided by -Nicolas Pitre <nico@fluxnic.net>. Continued development work by -Woojung Huh <whuh@applieddata.net> - -Use 'make graphicsmaster_config' before any 'make config'. -This will set up defaults for GraphicsMaster support. - -The kernel zImage is linked to be loaded and executed at 0xc0400000. - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia, compact flash -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation - and example user space code. ps/2 keybd is multiplexed through this driver - -To do -===== - -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. mtd0 is where - the zImage is stored. It's been marked as read-only to keep you - from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/huw_webpanel.rst b/Documentation/arm/sa1100/huw_webpanel.rst deleted file mode 100644 index 1dc7ccb165f0..000000000000 --- a/Documentation/arm/sa1100/huw_webpanel.rst +++ /dev/null @@ -1,21 +0,0 @@ -======================= -Hoeft & Wessel Webpanel -======================= - -The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG - -If you want more information, please visit -http://www.hoeft-wessel.de - -To build the kernel:: - - make huw_webpanel_config - make oldconfig - [accept all defaults] - make zImage - -Mostly of the work is done by: -Roman Jordan jor@hoeft-wessel.de -Christoph Schulz schu@hoeft-wessel.de - -2000/12/18/ diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst index 68c2a280a745..c9aed43280ff 100644 --- a/Documentation/arm/sa1100/index.rst +++ b/Documentation/arm/sa1100/index.rst @@ -7,19 +7,7 @@ Intel StrongARM 1100 .. toctree:: :maxdepth: 1 - adsbitsy assabet - brutus cerf - freebird - graphicsclient - graphicsmaster - huw_webpanel - itsy lart - nanoengine - pangolin - pleb serial_uart - tifon - yopy diff --git a/Documentation/arm/sa1100/itsy.rst b/Documentation/arm/sa1100/itsy.rst deleted file mode 100644 index f49896ba3ef1..000000000000 --- a/Documentation/arm/sa1100/itsy.rst +++ /dev/null @@ -1,47 +0,0 @@ -==== -Itsy -==== - -Itsy is a research project done by the Western Research Lab, and Systems -Research Center in Palo Alto, CA. The Itsy project is one of several -research projects at Compaq that are related to pocket computing. - -For more information, see: - - http://www.hpl.hp.com/downloads/crl/itsy/ - -Notes on initial 2.4 Itsy support (8/27/2000) : - -The port was done on an Itsy version 1.5 machine with a daughtercard with -64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for -serial console (to see what you're doing). No other devices have been -enabled. - -To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support. -Disable Flash and LCD support. and then do a make zImage. -Finally, you will need to cd to arch/arm/boot/tools and execute a make there -to build the params-itsy program used to boot the kernel. - -In order to install the port of 2.4 to the itsy, You will need to set the -configuration parameters in the monitor as follows:: - - Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 - -Make sure the start-routine address is set to 0x00060000. - -Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the -flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 -("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000 -("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on -handhelds.org. - -The serial connection we established was at: - -8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the -params-itsy program, and in the kernel itself. This can be changed, but -not easily. The monitor parameters are easily changed, the params program -setup is assembly outl's, and the kernel is a configuration item specific to -the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.) - - -This should get you a properly booting 2.4 kernel on the itsy. diff --git a/Documentation/arm/sa1100/nanoengine.rst b/Documentation/arm/sa1100/nanoengine.rst deleted file mode 100644 index 47f1a14cf98a..000000000000 --- a/Documentation/arm/sa1100/nanoengine.rst +++ /dev/null @@ -1,11 +0,0 @@ -========== -nanoEngine -========== - -"nanoEngine" is a SA1110 based single board computer from -Bright Star Engineering Inc. See www.brightstareng.com/arm -for more info. -(Ref: Stuart Adams <sja@brightstareng.com>) - -Also visit Larry Doolittle's "Linux for the nanoEngine" site: -http://www.brightstareng.com/arm/nanoeng.htm diff --git a/Documentation/arm/sa1100/pangolin.rst b/Documentation/arm/sa1100/pangolin.rst deleted file mode 100644 index f0c5c1618553..000000000000 --- a/Documentation/arm/sa1100/pangolin.rst +++ /dev/null @@ -1,29 +0,0 @@ -======== -Pangolin -======== - -Pangolin is a StrongARM 1110-based evaluation platform produced -by Dialogue Technology (http://www.dialogue.com.tw/). -It has EISA slots for ease of configuration with SDRAM/Flash -memory card, USB/Serial/Audio card, Compact Flash card, -PCMCIA/IDE card and TFT-LCD card. - -To compile for Pangolin, you must issue the following commands:: - - make pangolin_config - make oldconfig - make zImage - -Supported peripherals -===================== - -- SA1110 serial port (UART1/UART2/UART3) -- flash memory access -- compact flash driver -- UDA1341 sound driver -- SA1100 LCD controller for 800x600 16bpp TFT-LCD -- MQ-200 driver for 800x600 16bpp TFT-LCD -- Penmount(touch panel) driver -- PCMCIA driver -- SMC91C94 LAN driver -- IDE driver (experimental) diff --git a/Documentation/arm/sa1100/pleb.rst b/Documentation/arm/sa1100/pleb.rst deleted file mode 100644 index d5b732967aa3..000000000000 --- a/Documentation/arm/sa1100/pleb.rst +++ /dev/null @@ -1,13 +0,0 @@ -==== -PLEB -==== - -The PLEB project was started as a student initiative at the School of -Computer Science and Engineering, University of New South Wales to make a -pocket computer capable of running the Linux Kernel. - -PLEB support has yet to be fully integrated. - -For more information, see: - - http://www.cse.unsw.edu.au diff --git a/Documentation/arm/sa1100/tifon.rst b/Documentation/arm/sa1100/tifon.rst deleted file mode 100644 index c26e910b9ea7..000000000000 --- a/Documentation/arm/sa1100/tifon.rst +++ /dev/null @@ -1,7 +0,0 @@ -===== -Tifon -===== - -More info has to come... - -Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se> diff --git a/Documentation/arm/sa1100/yopy.rst b/Documentation/arm/sa1100/yopy.rst deleted file mode 100644 index 5b35a5f61a44..000000000000 --- a/Documentation/arm/sa1100/yopy.rst +++ /dev/null @@ -1,5 +0,0 @@ -==== -Yopy -==== - -See http://www.yopydeveloper.org for more. diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst index 5b8a7f9398d8..ccb951a0bedb 100644 --- a/Documentation/arm/samsung-s3c24xx/index.rst +++ b/Documentation/arm/samsung-s3c24xx/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -========================== +========================== Samsung S3C24XX SoC Family ========================== diff --git a/Documentation/arm/sh-mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore deleted file mode 100644 index c928dbf3cc88..000000000000 --- a/Documentation/arm/sh-mobile/.gitignore +++ /dev/null @@ -1 +0,0 @@ -vrl4 diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst index 96b696ba4e6c..5c0c69dc58aa 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -16,6 +16,7 @@ ARM64 Architecture pointer-authentication silicon-errata sve + tagged-address-abi tagged-pointers .. only:: subproject and html diff --git a/Documentation/arm64/kasan-offsets.sh b/Documentation/arm64/kasan-offsets.sh new file mode 100644 index 000000000000..2b7a021db363 --- /dev/null +++ b/Documentation/arm64/kasan-offsets.sh @@ -0,0 +1,27 @@ +#!/bin/sh + +# Print out the KASAN_SHADOW_OFFSETS required to place the KASAN SHADOW +# start address at the mid-point of the kernel VA space + +print_kasan_offset () { + printf "%02d\t" $1 + printf "0x%08x00000000\n" $(( (0xffffffff & (-1 << ($1 - 1 - 32))) \ + + (1 << ($1 - 32 - $2)) \ + - (1 << (64 - 32 - $2)) )) +} + +echo KASAN_SHADOW_SCALE_SHIFT = 3 +printf "VABITS\tKASAN_SHADOW_OFFSET\n" +print_kasan_offset 48 3 +print_kasan_offset 47 3 +print_kasan_offset 42 3 +print_kasan_offset 39 3 +print_kasan_offset 36 3 +echo +echo KASAN_SHADOW_SCALE_SHIFT = 4 +printf "VABITS\tKASAN_SHADOW_OFFSET\n" +print_kasan_offset 48 4 +print_kasan_offset 47 4 +print_kasan_offset 42 4 +print_kasan_offset 39 4 +print_kasan_offset 36 4 diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst index 464b880fc4b7..b040909e45f8 100644 --- a/Documentation/arm64/memory.rst +++ b/Documentation/arm64/memory.rst @@ -14,6 +14,10 @@ with the 4KB page configuration, allowing 39-bit (512GB) or 48-bit 64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB) virtual address, are used but the memory layout is the same. +ARMv8.2 adds optional support for Large Virtual Address space. This is +only available when running with a 64KB page size and expands the +number of descriptors in the first level of translation. + User addresses have bits 63:48 set to 0 while the kernel addresses have the same bits set to 1. TTBRx selection is given by bit 63 of the virtual address. The swapper_pg_dir contains only kernel (global) @@ -22,40 +26,43 @@ The swapper_pg_dir address is written to TTBR1 and never written to TTBR0. -AArch64 Linux memory layout with 4KB pages + 3 levels:: - - Start End Size Use - ----------------------------------------------------------------------- - 0000000000000000 0000007fffffffff 512GB user - ffffff8000000000 ffffffffffffffff 512GB kernel - - -AArch64 Linux memory layout with 4KB pages + 4 levels:: +AArch64 Linux memory layout with 4KB pages + 4 levels (48-bit):: Start End Size Use ----------------------------------------------------------------------- 0000000000000000 0000ffffffffffff 256TB user - ffff000000000000 ffffffffffffffff 256TB kernel - - -AArch64 Linux memory layout with 64KB pages + 2 levels:: + ffff000000000000 ffff7fffffffffff 128TB kernel logical memory map + ffff800000000000 ffff9fffffffffff 32TB kasan shadow region + ffffa00000000000 ffffa00007ffffff 128MB bpf jit region + ffffa00008000000 ffffa0000fffffff 128MB modules + ffffa00010000000 fffffdffbffeffff ~93TB vmalloc + fffffdffbfff0000 fffffdfffe5f8fff ~998MB [guard region] + fffffdfffe5f9000 fffffdfffe9fffff 4124KB fixed mappings + fffffdfffea00000 fffffdfffebfffff 2MB [guard region] + fffffdfffec00000 fffffdffffbfffff 16MB PCI I/O space + fffffdffffc00000 fffffdffffdfffff 2MB [guard region] + fffffdffffe00000 ffffffffffdfffff 2TB vmemmap + ffffffffffe00000 ffffffffffffffff 2MB [guard region] + + +AArch64 Linux memory layout with 64KB pages + 3 levels (52-bit with HW support):: Start End Size Use ----------------------------------------------------------------------- - 0000000000000000 000003ffffffffff 4TB user - fffffc0000000000 ffffffffffffffff 4TB kernel - - -AArch64 Linux memory layout with 64KB pages + 3 levels:: - - Start End Size Use - ----------------------------------------------------------------------- - 0000000000000000 0000ffffffffffff 256TB user - ffff000000000000 ffffffffffffffff 256TB kernel - - -For details of the virtual kernel memory layout please see the kernel -booting log. + 0000000000000000 000fffffffffffff 4PB user + fff0000000000000 fff7ffffffffffff 2PB kernel logical memory map + fff8000000000000 fffd9fffffffffff 1440TB [gap] + fffda00000000000 ffff9fffffffffff 512TB kasan shadow region + ffffa00000000000 ffffa00007ffffff 128MB bpf jit region + ffffa00008000000 ffffa0000fffffff 128MB modules + ffffa00010000000 fffff81ffffeffff ~88TB vmalloc + fffff81fffff0000 fffffc1ffe58ffff ~3TB [guard region] + fffffc1ffe590000 fffffc1ffe9fffff 4544KB fixed mappings + fffffc1ffea00000 fffffc1ffebfffff 2MB [guard region] + fffffc1ffec00000 fffffc1fffbfffff 16MB PCI I/O space + fffffc1fffc00000 fffffc1fffdfffff 2MB [guard region] + fffffc1fffe00000 ffffffffffdfffff 3968GB vmemmap + ffffffffffe00000 ffffffffffffffff 2MB [guard region] Translation table lookup with 4KB pages:: @@ -83,7 +90,8 @@ Translation table lookup with 64KB pages:: | | | | [15:0] in-page offset | | | +----------> [28:16] L3 index | | +--------------------------> [41:29] L2 index - | +-------------------------------> [47:42] L1 index + | +-------------------------------> [47:42] L1 index (48-bit) + | [51:42] L1 index (52-bit) +-------------------------------------------------> [63] TTBR0/1 @@ -96,3 +104,62 @@ ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs. When using KVM with the Virtualization Host Extensions, no additional mappings are created, since the host kernel runs directly in EL2. + +52-bit VA support in the kernel +------------------------------- +If the ARMv8.2-LVA optional feature is present, and we are running +with a 64KB page size; then it is possible to use 52-bits of address +space for both userspace and kernel addresses. However, any kernel +binary that supports 52-bit must also be able to fall back to 48-bit +at early boot time if the hardware feature is not present. + +This fallback mechanism necessitates the kernel .text to be in the +higher addresses such that they are invariant to 48/52-bit VAs. Due +to the kasan shadow being a fraction of the entire kernel VA space, +the end of the kasan shadow must also be in the higher half of the +kernel VA space for both 48/52-bit. (Switching from 48-bit to 52-bit, +the end of the kasan shadow is invariant and dependent on ~0UL, +whilst the start address will "grow" towards the lower addresses). + +In order to optimise phys_to_virt and virt_to_phys, the PAGE_OFFSET +is kept constant at 0xFFF0000000000000 (corresponding to 52-bit), +this obviates the need for an extra variable read. The physvirt +offset and vmemmap offsets are computed at early boot to enable +this logic. + +As a single binary will need to support both 48-bit and 52-bit VA +spaces, the VMEMMAP must be sized large enough for 52-bit VAs and +also must be sized large enought to accommodate a fixed PAGE_OFFSET. + +Most code in the kernel should not need to consider the VA_BITS, for +code that does need to know the VA size the variables are +defined as follows: + +VA_BITS constant the *maximum* VA space size + +VA_BITS_MIN constant the *minimum* VA space size + +vabits_actual variable the *actual* VA space size + + +Maximum and minimum sizes can be useful to ensure that buffers are +sized large enough or that addresses are positioned close enough for +the "worst" case. + +52-bit userspace VAs +-------------------- +To maintain compatibility with software that relies on the ARMv8.0 +VA space maximum size of 48-bits, the kernel will, by default, +return virtual addresses to userspace from a 48-bit range. + +Software can "opt-in" to receiving VAs from a 52-bit space by +specifying an mmap hint parameter that is larger than 48-bit. +For example: + maybe_high_address = mmap(~0UL, size, prot, flags,...); + +It is also possible to build a debug kernel that returns addresses +from a 52-bit space by enabling the following kernel config options: + CONFIG_EXPERT=y && CONFIG_ARM64_FORCE_52BIT=y + +Note that this option is only intended for debugging applications +and should not be used in production. diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 3e57d09246e6..17ea3fecddaa 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -115,6 +115,8 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | Hisilicon | Hip0{6,7} | #161010701 | N/A | +----------------+-----------------+-----------------+-----------------------------+ +| Hisilicon | Hip0{6,7} | #161010803 | N/A | ++----------------+-----------------+-----------------+-----------------------------+ | Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 | +----------------+-----------------+-----------------+-----------------------------+ | Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A | diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst new file mode 100644 index 000000000000..d4a85d535bf9 --- /dev/null +++ b/Documentation/arm64/tagged-address-abi.rst @@ -0,0 +1,156 @@ +========================== +AArch64 TAGGED ADDRESS ABI +========================== + +Authors: Vincenzo Frascino <vincenzo.frascino@arm.com> + Catalin Marinas <catalin.marinas@arm.com> + +Date: 21 August 2019 + +This document describes the usage and semantics of the Tagged Address +ABI on AArch64 Linux. + +1. Introduction +--------------- + +On AArch64 the ``TCR_EL1.TBI0`` bit is set by default, allowing +userspace (EL0) to perform memory accesses through 64-bit pointers with +a non-zero top byte. This document describes the relaxation of the +syscall ABI that allows userspace to pass certain tagged pointers to +kernel syscalls. + +2. AArch64 Tagged Address ABI +----------------------------- + +From the kernel syscall interface perspective and for the purposes of +this document, a "valid tagged pointer" is a pointer with a potentially +non-zero top-byte that references an address in the user process address +space obtained in one of the following ways: + +- ``mmap()`` syscall where either: + + - flags have the ``MAP_ANONYMOUS`` bit set or + - the file descriptor refers to a regular file (including those + returned by ``memfd_create()``) or ``/dev/zero`` + +- ``brk()`` syscall (i.e. the heap area between the initial location of + the program break at process creation and its current location). + +- any memory mapped by the kernel in the address space of the process + 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 +how the user addresses are used by the kernel: + +1. User addresses not accessed by the kernel but used for address space + management (e.g. ``mmap()``, ``mprotect()``, ``madvise()``). The use + of valid tagged pointers in this context is always allowed. + +2. User addresses accessed by the kernel (e.g. ``write()``). This ABI + relaxation is disabled by default and the application thread needs to + explicitly enable it via ``prctl()`` as follows: + + - ``PR_SET_TAGGED_ADDR_CTRL``: enable or disable the AArch64 Tagged + Address ABI for the calling thread. + + The ``(unsigned int) arg2`` argument is a bit mask describing the + control mode used: + + - ``PR_TAGGED_ADDR_ENABLE``: enable AArch64 Tagged Address ABI. + Default status is disabled. + + Arguments ``arg3``, ``arg4``, and ``arg5`` must be 0. + + - ``PR_GET_TAGGED_ADDR_CTRL``: get the status of the AArch64 Tagged + Address ABI for the calling thread. + + Arguments ``arg2``, ``arg3``, ``arg4``, and ``arg5`` must be 0. + + The ABI properties described above are thread-scoped, inherited on + clone() and fork() and cleared on exec(). + + Calling ``prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)`` + returns ``-EINVAL`` if the AArch64 Tagged Address ABI is globally + disabled by ``sysctl abi.tagged_addr_disabled=1``. The default + ``sysctl abi.tagged_addr_disabled`` configuration is 0. + +When the AArch64 Tagged Address ABI is enabled for a thread, the +following behaviours are guaranteed: + +- All syscalls except the cases mentioned in section 3 can accept any + valid tagged pointer. + +- The syscall behaviour is undefined for invalid tagged pointers: it may + result in an error code being returned, a (fatal) signal being raised, + or other modes of failure. + +- The syscall behaviour for a valid tagged pointer is the same as for + the corresponding untagged pointer. + + +A definition of the meaning of tagged pointers on AArch64 can be found +in Documentation/arm64/tagged-pointers.rst. + +3. AArch64 Tagged Address ABI Exceptions +----------------------------------------- + +The following system call parameters must be untagged regardless of the +ABI relaxation: + +- ``prctl()`` other than pointers to user data either passed directly or + indirectly as arguments to be accessed by the kernel. + +- ``ioctl()`` other than pointers to user data either passed directly or + indirectly as arguments to be accessed by the kernel. + +- ``shmat()`` and ``shmdt()``. + +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. + +4. Example of correct usage +--------------------------- +.. code-block:: c + + #include <stdlib.h> + #include <string.h> + #include <unistd.h> + #include <sys/mman.h> + #include <sys/prctl.h> + + #define PR_SET_TAGGED_ADDR_CTRL 55 + #define PR_TAGGED_ADDR_ENABLE (1UL << 0) + + #define TAG_SHIFT 56 + + int main(void) + { + int tbi_enabled = 0; + unsigned long tag = 0; + char *ptr; + + /* check/enable the tagged address ABI */ + if (!prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)) + tbi_enabled = 1; + + /* memory allocation */ + ptr = mmap(NULL, sysconf(_SC_PAGE_SIZE), PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); + if (ptr == MAP_FAILED) + return 1; + + /* set a non-zero tag if the ABI is available */ + if (tbi_enabled) + tag = rand() & 0xff; + ptr = (char *)((unsigned long)ptr | (tag << TAG_SHIFT)); + + /* memory access to a tagged address */ + strcpy(ptr, "tagged pointer\n"); + + /* syscall with a tagged pointer */ + write(1, ptr, strlen(ptr)); + + return 0; + } diff --git a/Documentation/arm64/tagged-pointers.rst b/Documentation/arm64/tagged-pointers.rst index 2acdec3ebbeb..eab4323609b9 100644 --- a/Documentation/arm64/tagged-pointers.rst +++ b/Documentation/arm64/tagged-pointers.rst @@ -20,7 +20,9 @@ Passing tagged addresses to the kernel -------------------------------------- All interpretation of userspace memory addresses by the kernel assumes -an address tag of 0x00. +an address tag of 0x00, unless the application enables the AArch64 +Tagged Address ABI explicitly +(Documentation/arm64/tagged-address-abi.rst). This includes, but is not limited to, addresses found in: @@ -33,13 +35,15 @@ This includes, but is not limited to, addresses found in: - the frame pointer (x29) and frame records, e.g. when interpreting them to generate a backtrace or call graph. -Using non-zero address tags in any of these locations may result in an -error code being returned, a (fatal) signal being raised, or other modes -of failure. +Using non-zero address tags in any of these locations when the +userspace application did not enable the AArch64 Tagged Address ABI may +result in an error code being returned, a (fatal) signal being raised, +or other modes of failure. -For these reasons, passing non-zero address tags to the kernel via -system calls is forbidden, and using a non-zero address tag for sp is -strongly discouraged. +For these reasons, when the AArch64 Tagged Address ABI is disabled, +passing non-zero address tags to the kernel via system calls is +forbidden, and using a non-zero address tag for sp is strongly +discouraged. Programs maintaining a frame pointer and frame records that use non-zero address tags may suffer impaired or inaccurate debug and profiling @@ -59,6 +63,9 @@ be preserved. The architecture prevents the use of a tagged PC, so the upper byte will be set to a sign-extension of bit 55 on exception return. +This behaviour is maintained when the AArch64 Tagged Address ABI is +enabled. + Other considerations -------------------- diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b deleted file mode 100644 index 12fd51b8de75..000000000000 --- a/Documentation/auxdisplay/cfag12864b +++ /dev/null @@ -1,105 +0,0 @@ - =================================== - cfag12864b LCD Driver Documentation - =================================== - -License: GPLv2 -Author & Maintainer: Miguel Ojeda Sandonis -Date: 2006-10-27 - - - --------- -0. INDEX --------- - - 1. DRIVER INFORMATION - 2. DEVICE INFORMATION - 3. WIRING - 4. USERSPACE PROGRAMMING - - ---------------------- -1. DRIVER INFORMATION ---------------------- - -This driver supports a cfag12864b LCD. - - ---------------------- -2. DEVICE INFORMATION ---------------------- - -Manufacturer: Crystalfontz -Device Name: Crystalfontz 12864b LCD Series -Device Code: cfag12864b -Webpage: http://www.crystalfontz.com -Device Webpage: http://www.crystalfontz.com/products/12864b/ -Type: LCD (Liquid Crystal Display) -Width: 128 -Height: 64 -Colors: 2 (B/N) -Controller: ks0108 -Controllers: 2 -Pages: 8 each controller -Addresses: 64 each page -Data size: 1 byte each address -Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte - - ---------- -3. WIRING ---------- - -The cfag12864b LCD Series don't have official wiring. - -The common wiring is done to the parallel port as shown: - -Parallel Port cfag12864b - - Name Pin# Pin# Name - -Strobe ( 1)------------------------------(17) Enable -Data 0 ( 2)------------------------------( 4) Data 0 -Data 1 ( 3)------------------------------( 5) Data 1 -Data 2 ( 4)------------------------------( 6) Data 2 -Data 3 ( 5)------------------------------( 7) Data 3 -Data 4 ( 6)------------------------------( 8) Data 4 -Data 5 ( 7)------------------------------( 9) Data 5 -Data 6 ( 8)------------------------------(10) Data 6 -Data 7 ( 9)------------------------------(11) Data 7 - (10) [+5v]---( 1) Vdd - (11) [GND]---( 2) Ground - (12) [+5v]---(14) Reset - (13) [GND]---(15) Read / Write - Line (14)------------------------------(13) Controller Select 1 - (15) - Init (16)------------------------------(12) Controller Select 2 -Select (17)------------------------------(16) Data / Instruction -Ground (18)---[GND] [+5v]---(19) LED + -Ground (19)---[GND] -Ground (20)---[GND] E A Values: -Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm -Ground (22)---[GND] | - P1 = Preset = 10 Kohm -Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm -Ground (24)---[GND] | | -Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED - - - ------------------------- -4. USERSPACE PROGRAMMING ------------------------- - -The cfag12864bfb describes a framebuffer device (/dev/fbX). - -It has a size of 1024 bytes = 1 Kbyte. -Each bit represents one pixel. If the bit is high, the pixel will -turn on. If the pixel is low, the pixel will turn off. - -You can use the framebuffer as a file: fopen, fwrite, fclose... -Although the LCD won't get updated until the next refresh time arrives. - -Also, you can mmap the framebuffer: open & mmap, munmap & close... -which is the best option for most uses. - -Check samples/auxdisplay/cfag12864b-example.c -for a real working userspace complete program with usage examples. diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108 deleted file mode 100644 index 8ddda0c8ceef..000000000000 --- a/Documentation/auxdisplay/ks0108 +++ /dev/null @@ -1,55 +0,0 @@ - ========================================== - ks0108 LCD Controller Driver Documentation - ========================================== - -License: GPLv2 -Author & Maintainer: Miguel Ojeda Sandonis -Date: 2006-10-27 - - - --------- -0. INDEX --------- - - 1. DRIVER INFORMATION - 2. DEVICE INFORMATION - 3. WIRING - - ---------------------- -1. DRIVER INFORMATION ---------------------- - -This driver supports the ks0108 LCD controller. - - ---------------------- -2. DEVICE INFORMATION ---------------------- - -Manufacturer: Samsung -Device Name: KS0108 LCD Controller -Device Code: ks0108 -Webpage: - -Device Webpage: - -Type: LCD Controller (Liquid Crystal Display Controller) -Width: 64 -Height: 64 -Colors: 2 (B/N) -Pages: 8 -Addresses: 64 each page -Data size: 1 byte each address -Memory size: 8 * 64 * 1 = 512 bytes - - ---------- -3. WIRING ---------- - -The driver supports data parallel port wiring. - -If you aren't building LCD related hardware, you should check -your LCD specific wiring information in the same folder. - -For example, check Documentation/auxdisplay/cfag12864b. diff --git a/Documentation/block/null_blk.rst b/Documentation/block/null_blk.rst index 31451d80783c..edbbab2f12f8 100644 --- a/Documentation/block/null_blk.rst +++ b/Documentation/block/null_blk.rst @@ -1,19 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + ======================== Null block device driver ======================== -1. Overview -=========== +Overview +======== -The null block device (/dev/nullb*) is used for benchmarking the various +The null block device (``/dev/nullb*``) is used for benchmarking the various block-layer implementations. It emulates a block device of X gigabytes in size. -The following instances are possible: - - Single-queue block-layer - - - Request-based. - - Single submission queue per device. - - Implements IO scheduling algorithms (CFQ, Deadline, noop). +It does not execute any read/write operation, just mark them as complete in +the request queue. The following instances are possible: Multi-queue block-layer @@ -27,15 +24,15 @@ The following instances are possible: All of them have a completion queue for each core in the system. -2. Module parameters applicable for all instances -================================================= +Module parameters +================= queue_mode=[0-2]: Default: 2-Multi-queue Selects which block-layer the module should instantiate with. = ============ 0 Bio-based - 1 Single-queue + 1 Single-queue (deprecated) 2 Multi-queue = ============ @@ -67,7 +64,7 @@ irqmode=[0-2]: Default: 1-Soft-irq completion_nsec=[ns]: Default: 10,000ns Combined with irqmode=2 (timer). The time each completion event must wait. -submit_queues=[1..nr_cpus]: +submit_queues=[1..nr_cpus]: Default: 1 The number of submission queues attached to the device driver. If unset, it defaults to 1. For multi-queue, it is ignored when use_per_node_hctx module parameter is 1. @@ -75,9 +72,11 @@ submit_queues=[1..nr_cpus]: hw_queue_depth=[0..qdepth]: Default: 64 The hardware queue depth of the device. -III: Multi-queue specific parameters +Multi-queue specific parameters +------------------------------- use_per_node_hctx=[0/1]: Default: 0 + Number of hardware context queues. = ===================================================================== 0 The number of submit queues are set to the value of the submit_queues @@ -87,6 +86,7 @@ use_per_node_hctx=[0/1]: Default: 0 = ===================================================================== no_sched=[0/1]: Default: 0 + Enable/disable the io scheduler. = ====================================== 0 nullb* use default blk-mq io scheduler @@ -94,6 +94,7 @@ no_sched=[0/1]: Default: 0 = ====================================== blocking=[0/1]: Default: 0 + Blocking behavior of the request queue. = =============================================================== 0 Register as a non-blocking blk-mq driver device. @@ -103,6 +104,7 @@ blocking=[0/1]: Default: 0 = =============================================================== shared_tags=[0/1]: Default: 0 + Sharing tags between devices. = ================================================================ 0 Tag set is not shared. @@ -111,6 +113,7 @@ shared_tags=[0/1]: Default: 0 = ================================================================ zoned=[0/1]: Default: 0 + Device is a random-access or a zoned block device. = ====================================================================== 0 Block device is exposed as a random-access block device. diff --git a/Documentation/block/switching-sched.rst b/Documentation/block/switching-sched.rst index 42042417380e..520f6b857544 100644 --- a/Documentation/block/switching-sched.rst +++ b/Documentation/block/switching-sched.rst @@ -2,10 +2,6 @@ Switching Scheduler =================== -To choose IO schedulers at boot time, use the argument 'elevator=deadline'. -'noop' and 'cfq' (the default) are also available. IO schedulers are assigned -globally at boot time only presently. - Each io queue has a set of io scheduler tunables associated with it. These tunables control how the io scheduler works. You can find these entries in:: diff --git a/Documentation/bpf/prog_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst index ed343abe541e..a78bf036cadd 100644 --- a/Documentation/bpf/prog_flow_dissector.rst +++ b/Documentation/bpf/prog_flow_dissector.rst @@ -26,6 +26,7 @@ The inputs are: * ``nhoff`` - initial offset of the networking header * ``thoff`` - initial offset of the transport header, initialized to nhoff * ``n_proto`` - L3 protocol type, parsed out of L2 header + * ``flags`` - optional flags Flow dissector BPF program should fill out the rest of the ``struct bpf_flow_keys`` fields. Input arguments ``nhoff/thoff/n_proto`` should be @@ -101,6 +102,23 @@ can be called for both cases and would have to be written carefully to handle both cases. +Flags +===== + +``flow_keys->flags`` might contain optional input flags that work as follows: + +* ``BPF_FLOW_DISSECTOR_F_PARSE_1ST_FRAG`` - tells BPF flow dissector to + continue parsing first fragment; the default expected behavior is that + flow dissector returns as soon as it finds out that the packet is fragmented; + used by ``eth_get_headlen`` to estimate length of all headers for GRO. +* ``BPF_FLOW_DISSECTOR_F_STOP_AT_FLOW_LABEL`` - tells BPF flow dissector to + stop parsing as soon as it reaches IPv6 flow label; used by + ``___skb_get_hash`` and ``__skb_get_hash_symmetric`` to get flow hash. +* ``BPF_FLOW_DISSECTOR_F_STOP_AT_ENCAP`` - tells BPF flow dissector to stop + parsing as soon as it reaches encapsulated headers; used by routing + infrastructure. + + Reference Implementation ======================== diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index da0ed972d224..fa16a0538dcb 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -25,6 +25,7 @@ Core utilities librs genalloc errseq + packing printk-formats circular-buffers generic-radix-tree @@ -48,7 +49,7 @@ Interfaces for kernel debugging debug-objects tracepoint -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst index f830c98645f1..d8c341fe383e 100644 --- a/Documentation/packing.txt +++ b/Documentation/core-api/packing.rst @@ -30,6 +30,7 @@ The solution ------------ This API deals with 2 basic operations: + - Packing a CPU-usable number into a memory buffer (with hardware constraints/quirks) - Unpacking a memory buffer (which has hardware constraints/quirks) @@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit. 1. Normally (no quirks), we would do it like this: -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 -7 6 5 4 -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -3 2 1 0 +:: + + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the LSByte (0) of the u64 sits at memory offset 7. @@ -63,10 +66,12 @@ comments as "logical" notation. 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this: -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 -7 6 5 4 -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 -3 2 1 0 +:: + + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but inverts bit offsets inside a byte. @@ -74,10 +79,12 @@ inverts bit offsets inside a byte. 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this: -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 -4 5 6 7 -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 -0 1 2 3 +:: + + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every byte from each 4-byte word is placed at its mirrored position compared to @@ -86,18 +93,22 @@ the boundary of that word. 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it like this: -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 -4 5 6 7 -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 -0 1 2 3 +:: + + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this: -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -3 2 1 0 -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 -7 6 5 4 +:: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 In this case the 8 byte memory region is interpreted as follows: first 4 bytes correspond to the least significant 4-byte word, next 4 bytes to @@ -107,28 +118,34 @@ the more significant 4-byte word. 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like this: -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 -3 2 1 0 -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 -7 6 5 4 +:: + + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like this: -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 -0 1 2 3 -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 -4 5 6 7 +:: + + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT are set, it looks like this: -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 -0 1 2 3 -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 -4 5 6 7 +:: + + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 We always think of our offsets as if there were no quirk, and we translate diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index c6224d039bcb..ecbebf4ca8e7 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -13,10 +13,10 @@ Integer types If variable is of Type, use printk format specifier: ------------------------------------------------------------ - char %hhd or %hhx - unsigned char %hhu or %hhx - short int %hd or %hx - unsigned short int %hu or %hx + char %d or %x + unsigned char %u or %x + short int %d or %x + unsigned short int %u or %x int %d or %x unsigned int %u or %x long %ld or %lx @@ -25,10 +25,10 @@ Integer types unsigned long long %llu or %llx size_t %zu or %zx ssize_t %zd or %zx - s8 %hhd or %hhx - u8 %hhu or %hhx - s16 %hd or %hx - u16 %hu or %hx + s8 %d or %x + u8 %u or %x + s16 %d or %x + u16 %u or %x s32 %d or %x u32 %u or %x s64 %lld or %llx diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt index 55193e680250..ed577d9c154b 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.txt @@ -57,19 +57,11 @@ transition notifiers. 2.1 CPUFreq policy notifiers ---------------------------- -These are notified when a new policy is intended to be set. Each -CPUFreq policy notifier is called twice for a policy transition: +These are notified when a new policy is created or removed. -1.) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if - they see a need for this - may it be thermal considerations or - hardware limitations. - -2.) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy - - if two hardware drivers failed to agree on a new policy before this - stage, the incompatible hardware shall be shut down, and the user - informed of this. - -The phase is specified in the second argument to the notifier. +The phase is specified in the second argument to the notifier. The phase is +CPUFREQ_CREATE_POLICY when the policy is first created and it is +CPUFREQ_REMOVE_POLICY when the policy is removed. The third argument, a void *pointer, points to a struct cpufreq_policy consisting of several values, including min, max (the lower and upper diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst index 236c674d6897..3baa23c2cd08 100644 --- a/Documentation/crypto/crypto_engine.rst +++ b/Documentation/crypto/crypto_engine.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 + Crypto Engine ============= diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 6b0dfd5c17ba..5138a2f6232a 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -19,7 +19,9 @@ quiet_cmd_mk_schema = SCHEMA $@ DT_DOCS = $(shell \ cd $(srctree)/$(src) && \ - find * \( -name '*.yaml' ! -name $(DT_TMP_SCHEMA) \) \ + find * \( -name '*.yaml' ! \ + -name $(DT_TMP_SCHEMA) ! \ + -name '*.example.dt.yaml' \) \ ) DT_SCHEMA_FILES ?= $(addprefix $(src)/,$(DT_DOCS)) diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 325c6fd3566d..99015cef8bb1 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -91,13 +91,11 @@ properties: - description: Boards with the Amlogic Meson GXL S905X SoC items: - enum: - - amediatech,x96-max - amlogic,p212 - hwacom,amazetv - khadas,vim - libretech,cc - nexbox,a95x - - seirobotics,sei510 - const: amlogic,s905x - const: amlogic,meson-gxl @@ -129,16 +127,33 @@ properties: - const: amlogic,a113d - const: amlogic,meson-axg - - description: Boards with the Amlogic Meson G12A S905D2 SoC + - description: Boards with the Amlogic Meson G12A S905D2/X2/Y2 SoC items: - enum: + - amediatech,x96-max - amlogic,u200 + - seirobotics,sei510 - const: amlogic,g12a + - description: Boards with the Amlogic Meson G12B A311D SoC + items: + - enum: + - khadas,vim3 + - const: amlogic,a311d + - const: amlogic,g12b + - description: Boards with the Amlogic Meson G12B S922X SoC items: - enum: - hardkernel,odroid-n2 + - khadas,vim3 + - const: amlogic,s922x - const: amlogic,g12b + - description: Boards with the Amlogic Meson SM1 S905X3/D3/Y3 SoC + items: + - enum: + - seirobotics,sei610 + - khadas,vim3l + - const: amlogic,sm1 ... diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt index 317a2fc3667a..083dbf96ee00 100644 --- a/Documentation/devicetree/bindings/arm/arm,scmi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -73,6 +73,16 @@ Required properties: as used by the firmware. Refer to platform details for your implementation for the IDs to use. +Reset signal bindings for the reset domains based on SCMI Message Protocol +------------------------------------------------------------ + +This binding for the SCMI reset domain providers uses the generic reset +signal binding[5]. + +Required properties: + - #reset-cells : Should be 1. Contains the reset domain ID value used + by SCMI commands. + SRAM and Shared Memory for SCMI ------------------------------- @@ -93,6 +103,7 @@ Required sub-node properties: [2] Documentation/devicetree/bindings/power/power_domain.txt [3] Documentation/devicetree/bindings/thermal/thermal.txt [4] Documentation/devicetree/bindings/sram/sram.txt +[5] Documentation/devicetree/bindings/reset/reset.txt Example: @@ -152,6 +163,11 @@ firmware { reg = <0x15>; #thermal-sensor-cells = <1>; }; + + scmi_reset: protocol@16 { + reg = <0x16>; + #reset-cells = <1>; + }; }; }; @@ -166,6 +182,7 @@ hdlcd@7ff60000 { reg = <0 0x7ff60000 0 0x1000>; clocks = <&scmi_clk 4>; power-domains = <&scmi_devpd 1>; + resets = <&scmi_reset 10>; }; thermal-zones { diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index aa40b074b864..727e0ffc702b 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -175,6 +175,7 @@ properties: - amlogic,meson8-smp - amlogic,meson8b-smp - arm,realview-smp + - aspeed,ast2600-smp - brcm,bcm11351-cpu-method - brcm,bcm23550 - brcm,bcm2836-smp diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt index a575e42f7fec..c149fadc6f47 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -136,7 +136,9 @@ Required properties: OCOTP bindings based on SCU Message Protocol ------------------------------------------------------------ Required properties: -- compatible: Should be "fsl,imx8qxp-scu-ocotp" +- compatible: Should be one of: + "fsl,imx8qm-scu-ocotp", + "fsl,imx8qxp-scu-ocotp". - #address-cells: Must be 1. Contains byte index - #size-cells: Must be 1. Contains byte length diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 7294ac36f4c0..1b4b4e6573b5 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -161,6 +161,20 @@ properties: items: - enum: - fsl,imx6ul-14x14-evk # i.MX6 UltraLite 14x14 EVK Board + - kontron,imx6ul-n6310-som # Kontron N6310 SOM + - const: fsl,imx6ul + + - description: Kontron N6310 S Board + items: + - const: kontron,imx6ul-n6310-s + - const: kontron,imx6ul-n6310-som + - const: fsl,imx6ul + + - description: Kontron N6310 S 43 Board + items: + - const: kontron,imx6ul-n6310-s-43 + - const: kontron,imx6ul-n6310-s + - const: kontron,imx6ul-n6310-som - const: fsl,imx6ul - description: i.MX6ULL based Boards @@ -188,6 +202,7 @@ properties: - fsl,imx7d-sdb # i.MX7 SabreSD Board - novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board - tq,imx7d-mba7 # i.MX7D TQ MBa7 with TQMa7D SoM + - zii,imx7d-rmu2 # ZII RMU2 Board - zii,imx7d-rpu2 # ZII RPU2 Board - const: fsl,imx7d @@ -214,16 +229,26 @@ properties: - fsl,imx8mm-evk # i.MX8MM EVK Board - const: fsl,imx8mm + - description: i.MX8MN based Boards + items: + - enum: + - fsl,imx8mn-ddr4-evk # i.MX8MN DDR4 EVK Board + - const: fsl,imx8mn + - description: i.MX8MQ based Boards items: - enum: + - boundary,imx8mq-nitrogen8m # i.MX8MQ NITROGEN Board - fsl,imx8mq-evk # i.MX8MQ EVK Board - purism,librem5-devkit # Purism Librem5 devkit + - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse + - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk - const: fsl,imx8mq - description: i.MX8QXP based Boards items: - enum: + - einfochips,imx8qxp-ai_ml # i.MX8QXP AI_ML Board - fsl,imx8qxp-mek # i.MX8QXP MEK Board - const: fsl,imx8qxp @@ -283,6 +308,7 @@ properties: - description: LS1046A based Boards items: - enum: + - fsl,ls1046a-frwy - fsl,ls1046a-qds - fsl,ls1046a-rdb - const: fsl,ls1046a diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index a4ad2eb926f9..4043c5046441 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -48,6 +48,10 @@ properties: - const: mediatek,mt6765 - items: - enum: + - mediatek,mt6779-evb + - const: mediatek,mt6779 + - items: + - enum: - mediatek,mt6795-evb - const: mediatek,mt6795 - items: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt index f5518f26a914..30cb645c0e54 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt @@ -9,8 +9,6 @@ Required Properties: - "mediatek,mt7622-sgmiisys", "syscon" - "mediatek,mt7629-sgmiisys", "syscon" - #clock-cells: Must be 1 -- mediatek,physpeed: Should be one of "auto", "1000" or "2500" to match up - the capability of the target PHY. The SGMIISYS controller uses the common clk binding from Documentation/devicetree/bindings/clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 54ef6b6b9189..e39d8f02e33c 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -45,6 +45,7 @@ description: | mtp sbc hk01 + qrd The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor> where the minor number may be omitted when it's zero, i.e. v1.0 is the same @@ -116,6 +117,13 @@ properties: - const: qcom,msm8916 - items: + - enum: + - longcheer,l8150 + - samsung,a3u-eur + - samsung,a5u-eur + - const: qcom,msm8916 + + - items: - const: qcom,msm8996-mtp - items: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 34865042f4e4..c82c5e57d44c 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -128,6 +128,21 @@ properties: - const: google,veyron - const: rockchip,rk3288 + - description: Google Fievel (AOPEN Chromebox Mini) + items: + - const: google,veyron-fievel-rev8 + - const: google,veyron-fievel-rev7 + - const: google,veyron-fievel-rev6 + - const: google,veyron-fievel-rev5 + - const: google,veyron-fievel-rev4 + - const: google,veyron-fievel-rev3 + - const: google,veyron-fievel-rev2 + - const: google,veyron-fievel-rev1 + - const: google,veyron-fievel-rev0 + - const: google,veyron-fievel + - const: google,veyron + - const: rockchip,rk3288 + - description: Google Gru (dev-board) items: - const: google,gru-rev15 @@ -311,6 +326,21 @@ properties: - const: google,veyron - const: rockchip,rk3288 + - description: Google Tiger (AOpen Chromebase Mini) + items: + - const: google,veyron-tiger-rev8 + - const: google,veyron-tiger-rev7 + - const: google,veyron-tiger-rev6 + - const: google,veyron-tiger-rev5 + - const: google,veyron-tiger-rev4 + - const: google,veyron-tiger-rev3 + - const: google,veyron-tiger-rev2 + - const: google,veyron-tiger-rev1 + - const: google,veyron-tiger-rev0 + - const: google,veyron-tiger + - const: google,veyron + - const: rockchip,rk3288 + - description: Haoyu MarsBoard RK3066 items: - const: haoyu,marsboard-rk3066 @@ -329,6 +359,16 @@ properties: - khadas,edge-v - const: rockchip,rk3399 + - description: Mecer Xtreme Mini S6 + items: + - const: mecer,xms6 + - const: rockchip,rk3229 + + - description: Leez RK3399 P710 + items: + - const: leez,p710 + - const: rockchip,rk3399 + - description: mqmaker MiQi items: - const: mqmaker,miqi @@ -424,11 +464,6 @@ properties: - rockchip,rk3288-evb-rk808 - const: rockchip,rk3288 - - description: Rockchip RK3288 Fennec - items: - - const: rockchip,rk3288-fennec - - const: rockchip,rk3288 - - description: Rockchip RK3328 Evaluation board items: - const: rockchip,rk3328-evb diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 000a00d12d6a..972b1e9ee804 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -353,6 +353,12 @@ properties: - const: licheepi,licheepi-zero - const: allwinner,sun8i-v3s + - description: Lichee Zero Plus (with S3, without eMMC/SPI Flash) + items: + - const: sipeed,lichee-zero-plus + - const: sochip,s3 + - const: allwinner,sun8i-v3 + - description: Linksprite PCDuino items: - const: linksprite,a10-pcduino @@ -568,6 +574,11 @@ properties: - const: olimex,a64-olinuxino - const: allwinner,sun50i-a64 + - description: Olimex A64-OlinuXino (with eMMC) + items: + - const: olimex,a64-olinuxino-emmc + - const: allwinner,sun50i-a64 + - description: Olimex A64 Teres-I items: - const: olimex,a64-teres-i @@ -671,6 +682,11 @@ properties: - const: sinlinx,sina33 - const: allwinner,sun8i-a33 + - description: Tanix TX6 + items: + - const: oranth,tanix-tx6 + - const: allwinner,sun50i-h6 + - description: TBS A711 Tablet items: - const: tbs-biometrics,a711 diff --git a/Documentation/devicetree/bindings/bus/imx-weim.txt b/Documentation/devicetree/bindings/bus/imx-weim.txt index dda7d6d66479..1b1d1c5c21ea 100644 --- a/Documentation/devicetree/bindings/bus/imx-weim.txt +++ b/Documentation/devicetree/bindings/bus/imx-weim.txt @@ -44,6 +44,10 @@ Optional properties: what bootloader sets up in IOMUXC_GPR1[11:0] will be used. + - fsl,burst-clk-enable For "fsl,imx50-weim" and "fsl,imx6q-weim" type of + devices, the presence of this property indicates that + the weim bus should operate in Burst Clock Mode. + Timing property for child nodes. It is mandatory, not optional. - fsl,weim-cs-timing: The timing array, contains timing values for the diff --git a/Documentation/devicetree/bindings/bus/moxtet.txt b/Documentation/devicetree/bindings/bus/moxtet.txt new file mode 100644 index 000000000000..fb50fc865336 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/moxtet.txt @@ -0,0 +1,46 @@ +Turris Mox module status and configuration bus (over SPI) + +Required properties: + - compatible : Should be "cznic,moxtet" + - #address-cells : Has to be 1 + - #size-cells : Has to be 0 + - spi-cpol : Required inverted clock polarity + - spi-cpha : Required shifted clock phase + - interrupts : Must contain reference to the shared interrupt line + - interrupt-controller : Required + - #interrupt-cells : Has to be 1 + +For other required and optional properties of SPI slave nodes please refer to +../spi/spi-bus.txt. + +Required properties of subnodes: + - reg : Should be position on the Moxtet bus (how many Moxtet + modules are between this module and CPU module, so + either 0 or a positive integer) + +The driver finds the devices connected to the bus by itself, but it may be +needed to reference some of them from other parts of the device tree. In that +case the devices can be defined as subnodes of the moxtet node. + +Example: + + moxtet@1 { + compatible = "cznic,moxtet"; + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + spi-max-frequency = <10000000>; + spi-cpol; + spi-cpha; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gpiosb>; + interrupts = <5 IRQ_TYPE_EDGE_FALLING>; + + moxtet_sfp: gpio@0 { + compatible = "cznic,moxtet-gpio"; + gpio-controller; + #gpio-cells = <2>; + reg = <0>; + } + }; diff --git a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt index 0f777749f4f1..b3957d10d241 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt @@ -22,6 +22,7 @@ Required Properties: components. - resets : phandle of the internal reset line - #clock-cells : should be 1. +- #reset-cells : should be 1 on the g12a (and following) soc family 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 diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt index 6eaa52092313..7ccecd5c02c1 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt @@ -11,6 +11,7 @@ Required Properties: "amlogic,axg-clkc" for AXG SoC. "amlogic,g12a-clkc" for G12A SoC. "amlogic,g12b-clkc" for G12B SoC. + "amlogic,sm1-clkc" for SM1 SoC. - clocks : list of clock phandle, one for each entry clock-names. - clock-names : should contain the following: * "xtal": the platform xtal diff --git a/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml new file mode 100644 index 000000000000..622f3658bd9f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/clock/imx8mn-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8M Nano Clock Control Module Binding + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +description: | + NXP i.MX8M Nano clock control module is an integrated clock controller, which + generates and supplies to all modules. + +properties: + compatible: + const: fsl,imx8mn-ccm + + reg: + maxItems: 1 + + clocks: + items: + - description: 32k osc + - description: 24m osc + - description: ext1 clock input + - description: ext2 clock input + - description: ext3 clock input + - description: ext4 clock input + + clock-names: + items: + - const: osc_32k + - const: osc_24m + - const: clk_ext1 + - const: clk_ext2 + - const: clk_ext3 + - const: clk_ext4 + + '#clock-cells': + const: 1 + description: | + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx8mn-clock.h + for the full list of i.MX8M Nano clock IDs. + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +examples: + # Clock Control Module node: + - | + clk: clock-controller@30380000 { + compatible = "fsl,imx8mn-ccm"; + reg = <0x0 0x30380000 0x0 0x10000>; + #clock-cells = <1>; + clocks = <&osc_32k>, <&osc_24m>, <&clk_ext1>, + <&clk_ext2>, <&clk_ext3>, <&clk_ext4>; + clock-names = "osc_32k", "osc_24m", "clk_ext1", + "clk_ext2", "clk_ext3", "clk_ext4"; + }; + + # Required external clocks for Clock Control Module node: + - | + osc_32k: clock-osc-32k { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <32768>; + clock-output-names = "osc_32k"; + }; + + osc_24m: clock-osc-24m { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <24000000>; + clock-output-names = "osc_24m"; + }; + + clk_ext1: clock-ext1 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <133000000>; + clock-output-names = "clk_ext1"; + }; + + clk_ext2: clock-ext2 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <133000000>; + clock-output-names = "clk_ext2"; + }; + + clk_ext3: clock-ext3 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <133000000>; + clock-output-names = "clk_ext3"; + }; + + clk_ext4: clock-ext4 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency= <133000000>; + clock-output-names = "clk_ext4"; + }; + +... diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt index cef556d4e5ee..d357987181ee 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.txt +++ b/Documentation/devicetree/bindings/connector/usb-connector.txt @@ -17,6 +17,20 @@ Optional properties: - self-powered: Set this property if the usb device that has its own power source. +Optional properties for usb-b-connector: +- id-gpios: an input gpio for USB ID pin. +- vbus-gpios: an input gpio for USB VBUS pin, used to detect presence of + VBUS 5V. + see gpio/gpio.txt. +- vbus-supply: a phandle to the regulator for USB VBUS if needed when host + mode or dual role mode is supported. + Particularly, if use an output GPIO to control a VBUS regulator, should + model it as a regulator. + see regulator/fixed-regulator.yaml +- pinctrl-names : a pinctrl state named "default" is optional +- pinctrl-0 : pin control group + see pinctrl/pinctrl-bindings.txt + Optional properties for usb-c-connector: - power-role: should be one of "source", "sink" or "dual"(DRP) if typec connector has power support. diff --git a/Documentation/devicetree/bindings/arm/topology.txt b/Documentation/devicetree/bindings/cpu/cpu-topology.txt index b0d80c0fb265..99918189403c 100644 --- a/Documentation/devicetree/bindings/arm/topology.txt +++ b/Documentation/devicetree/bindings/cpu/cpu-topology.txt @@ -1,21 +1,19 @@ =========================================== -ARM topology binding description +CPU topology binding description =========================================== =========================================== 1 - Introduction =========================================== -In an ARM system, the hierarchy of CPUs is defined through three entities that +In a SMP system, the hierarchy of CPUs is defined through three entities that are used to describe the layout of physical CPUs in the system: +- socket - cluster - core - thread -The cpu nodes (bindings defined in [1]) represent the devices that -correspond to physical CPUs and are to be mapped to the hierarchy levels. - The bottom hierarchy level sits at core or thread level depending on whether symmetric multi-threading (SMT) is supported or not. @@ -24,33 +22,31 @@ threads existing in the system and map to the hierarchy level "thread" above. In systems where SMT is not supported "cpu" nodes represent all cores present in the system and map to the hierarchy level "core" above. -ARM topology bindings allow one to associate cpu nodes with hierarchical groups +CPU topology bindings allow one to associate cpu nodes with hierarchical groups corresponding to the system hierarchy; syntactically they are defined as device tree nodes. -The remainder of this document provides the topology bindings for ARM, based -on the Devicetree Specification, available from: +Currently, only ARM/RISC-V intend to use this cpu topology binding but it may be +used for any other architecture as well. -https://www.devicetree.org/specifications/ +The cpu nodes, as per bindings defined in [4], represent the devices that +correspond to physical CPUs and are to be mapped to the hierarchy levels. -If not stated otherwise, whenever a reference to a cpu node phandle is made its -value must point to a cpu node compliant with the cpu node bindings as -documented in [1]. A topology description containing phandles to cpu nodes that are not compliant -with bindings standardized in [1] is therefore considered invalid. +with bindings standardized in [4] is therefore considered invalid. =========================================== 2 - cpu-map node =========================================== -The ARM CPU topology is defined within the cpu-map node, which is a direct +The ARM/RISC-V CPU topology is defined within the cpu-map node, which is a direct child of the cpus node and provides a container where the actual topology nodes are listed. - cpu-map node - Usage: Optional - On ARM SMP systems provide CPUs topology to the OS. - ARM uniprocessor systems do not require a topology + Usage: Optional - On SMP systems provide CPUs topology to the OS. + Uniprocessor systems do not require a topology description and therefore should not define a cpu-map node. @@ -63,21 +59,23 @@ nodes are listed. The cpu-map node's child nodes can be: - - one or more cluster nodes + - one or more cluster nodes or + - one or more socket nodes in a multi-socket system Any other configuration is considered invalid. -The cpu-map node can only contain three types of child nodes: +The cpu-map node can only contain 4 types of child nodes: +- socket node - cluster node - core node - thread node whose bindings are described in paragraph 3. -The nodes describing the CPU topology (cluster/core/thread) can only -be defined within the cpu-map node and every core/thread in the system -must be defined within the topology. Any other configuration is +The nodes describing the CPU topology (socket/cluster/core/thread) can +only be defined within the cpu-map node and every core/thread in the +system must be defined within the topology. Any other configuration is invalid and therefore must be ignored. =========================================== @@ -85,26 +83,44 @@ invalid and therefore must be ignored. =========================================== cpu-map child nodes must follow a naming convention where the node name -must be "clusterN", "coreN", "threadN" depending on the node type (ie -cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which -are siblings within a single common parent node must be given a unique and +must be "socketN", "clusterN", "coreN", "threadN" depending on the node type +(ie socket/cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes +which are siblings within a single common parent node must be given a unique and sequential N value, starting from 0). cpu-map child nodes which do not share a common parent node can have the same name (ie same number N as other cpu-map child nodes at different device tree levels) since name uniqueness will be guaranteed by the device tree hierarchy. =========================================== -3 - cluster/core/thread node bindings +3 - socket/cluster/core/thread node bindings =========================================== -Bindings for cluster/cpu/thread nodes are defined as follows: +Bindings for socket/cluster/cpu/thread nodes are defined as follows: + +- socket node + + Description: must be declared within a cpu-map node, one node + per physical socket in the system. A system can + contain single or multiple physical socket. + The association of sockets and NUMA nodes is beyond + the scope of this bindings, please refer [2] for + NUMA bindings. + + This node is optional for a single socket system. + + The socket node name must be "socketN" as described in 2.1 above. + A socket node can not be a leaf node. + + A socket node's child nodes must be one or more cluster nodes. + + Any other configuration is considered invalid. - cluster node Description: must be declared within a cpu-map node, one node per cluster. A system can contain several layers of - clustering and cluster nodes can be contained in parent - cluster nodes. + clustering within a single physical socket and cluster + nodes can be contained in parent cluster nodes. The cluster node name must be "clusterN" as described in 2.1 above. A cluster node can not be a leaf node. @@ -164,90 +180,93 @@ Bindings for cluster/cpu/thread nodes are defined as follows: 4 - Example dts =========================================== -Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters): +Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters in a single +physical socket): cpus { #size-cells = <0>; #address-cells = <2>; cpu-map { - cluster0 { + socket0 { cluster0 { - core0 { - thread0 { - cpu = <&CPU0>; + cluster0 { + core0 { + thread0 { + cpu = <&CPU0>; + }; + thread1 { + cpu = <&CPU1>; + }; }; - thread1 { - cpu = <&CPU1>; - }; - }; - core1 { - thread0 { - cpu = <&CPU2>; - }; - thread1 { - cpu = <&CPU3>; + core1 { + thread0 { + cpu = <&CPU2>; + }; + thread1 { + cpu = <&CPU3>; + }; }; }; - }; - cluster1 { - core0 { - thread0 { - cpu = <&CPU4>; - }; - thread1 { - cpu = <&CPU5>; + cluster1 { + core0 { + thread0 { + cpu = <&CPU4>; + }; + thread1 { + cpu = <&CPU5>; + }; }; - }; - core1 { - thread0 { - cpu = <&CPU6>; - }; - thread1 { - cpu = <&CPU7>; - }; - }; - }; - }; - - cluster1 { - cluster0 { - core0 { - thread0 { - cpu = <&CPU8>; - }; - thread1 { - cpu = <&CPU9>; - }; - }; - core1 { - thread0 { - cpu = <&CPU10>; - }; - thread1 { - cpu = <&CPU11>; + core1 { + thread0 { + cpu = <&CPU6>; + }; + thread1 { + cpu = <&CPU7>; + }; }; }; }; cluster1 { - core0 { - thread0 { - cpu = <&CPU12>; + cluster0 { + core0 { + thread0 { + cpu = <&CPU8>; + }; + thread1 { + cpu = <&CPU9>; + }; }; - thread1 { - cpu = <&CPU13>; + core1 { + thread0 { + cpu = <&CPU10>; + }; + thread1 { + cpu = <&CPU11>; + }; }; }; - core1 { - thread0 { - cpu = <&CPU14>; + + cluster1 { + core0 { + thread0 { + cpu = <&CPU12>; + }; + thread1 { + cpu = <&CPU13>; + }; }; - thread1 { - cpu = <&CPU15>; + core1 { + thread0 { + cpu = <&CPU14>; + }; + thread1 { + cpu = <&CPU15>; + }; }; }; }; @@ -470,6 +489,65 @@ cpus { }; }; +Example 3: HiFive Unleashed (RISC-V 64 bit, 4 core system) + +{ + #address-cells = <2>; + #size-cells = <2>; + compatible = "sifive,fu540g", "sifive,fu500"; + model = "sifive,hifive-unleashed-a00"; + + ... + cpus { + #address-cells = <1>; + #size-cells = <0>; + cpu-map { + socket0 { + cluster0 { + core0 { + cpu = <&CPU1>; + }; + core1 { + cpu = <&CPU2>; + }; + core2 { + cpu0 = <&CPU2>; + }; + core3 { + cpu0 = <&CPU3>; + }; + }; + }; + }; + + CPU1: cpu@1 { + device_type = "cpu"; + compatible = "sifive,rocket0", "riscv"; + reg = <0x1>; + } + + CPU2: cpu@2 { + device_type = "cpu"; + compatible = "sifive,rocket0", "riscv"; + reg = <0x2>; + } + CPU3: cpu@3 { + device_type = "cpu"; + compatible = "sifive,rocket0", "riscv"; + reg = <0x3>; + } + CPU4: cpu@4 { + device_type = "cpu"; + compatible = "sifive,rocket0", "riscv"; + reg = <0x4>; + } + } +}; =============================================================================== [1] ARM Linux kernel documentation Documentation/devicetree/bindings/arm/cpus.yaml +[2] Devicetree NUMA binding description + Documentation/devicetree/bindings/numa.txt +[3] RISC-V Linux kernel documentation + Documentation/devicetree/bindings/riscv/cpus.txt +[4] https://www.devicetree.org/specifications/ diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml new file mode 100644 index 000000000000..15abc0f9429f --- /dev/null +++ b/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/allwinner,sun4i-a10-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 DMA Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + "#dma-cells": + const: 2 + description: + The first cell is either 0 or 1, the former to use the normal + DMA, 1 for dedicated DMA. The second cell is the request line + number. + + compatible: + const: allwinner,sun4i-a10-dma + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - "#dma-cells" + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + dma: dma-controller@1c02000 { + compatible = "allwinner,sun4i-a10-dma"; + reg = <0x01c02000 0x1000>; + interrupts = <27>; + clocks = <&ahb_gates 6>; + #dma-cells = <2>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml new file mode 100644 index 000000000000..4cb9d6b93138 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/allwinner,sun50i-a64-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A64 DMA Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + "#dma-cells": + const: 1 + description: The cell is the request line number. + + compatible: + enum: + - allwinner,sun50i-a64-dma + - allwinner,sun50i-h6-dma + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + items: + - const: bus + - const: mbus + + resets: + maxItems: 1 + +required: + - "#dma-cells" + - compatible + - reg + - interrupts + - clocks + - resets + - dma-channels + +if: + properties: + compatible: + const: allwinner,sun50i-h6-dma + +then: + properties: + clocks: + maxItems: 2 + + required: + - clock-names + +else: + properties: + clocks: + maxItems: 1 + +# FIXME: We should set it, but it would report all the generic +# properties as additional properties. +# additionalProperties: false + +examples: + - | + dma: dma-controller@1c02000 { + compatible = "allwinner,sun50i-a64-dma"; + reg = <0x01c02000 0x1000>; + interrupts = <0 50 4>; + clocks = <&ccu 30>; + dma-channels = <8>; + dma-requests = <27>; + resets = <&ccu 7>; + #dma-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml new file mode 100644 index 000000000000..740b7f9b535b --- /dev/null +++ b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/allwinner,sun6i-a31-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 DMA Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + "#dma-cells": + const: 1 + description: The cell is the request line number. + + compatible: + oneOf: + - const: allwinner,sun6i-a31-dma + - const: allwinner,sun8i-a23-dma + - const: allwinner,sun8i-a83t-dma + - const: allwinner,sun8i-h3-dma + - const: allwinner,sun8i-v3s-dma + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - "#dma-cells" + - compatible + - reg + - interrupts + - clocks + - resets + +additionalProperties: false + +examples: + - | + dma: dma-controller@1c02000 { + compatible = "allwinner,sun6i-a31-dma"; + reg = <0x01c02000 0x1000>; + interrupts = <0 50 4>; + clocks = <&ahb1_gates 6>; + resets = <&ahb1_rst 6>; + #dma-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/dma-common.yaml b/Documentation/devicetree/bindings/dma/dma-common.yaml new file mode 100644 index 000000000000..ed0a49a6f020 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/dma-common.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/dma-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DMA Engine Generic Binding + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +description: + Generic binding to provide a way for a driver using DMA Engine to + retrieve the DMA request or channel information that goes from a + hardware device to a DMA controller. + +select: false + +properties: + "#dma-cells": + minimum: 1 + # Should be enough + maximum: 255 + description: + Used to provide DMA controller specific information. + + dma-channel-mask: + $ref: /schemas/types.yaml#definitions/uint32 + description: + Bitmask of available DMA channels in ascending order that are + not reserved by firmware and are available to the + kernel. i.e. first channel corresponds to LSB. + + dma-channels: + $ref: /schemas/types.yaml#definitions/uint32 + description: + Number of DMA channels supported by the controller. + + dma-requests: + $ref: /schemas/types.yaml#definitions/uint32 + description: + Number of DMA request signals supported by the controller. + +required: + - "#dma-cells" diff --git a/Documentation/devicetree/bindings/dma/dma-controller.yaml b/Documentation/devicetree/bindings/dma/dma-controller.yaml new file mode 100644 index 000000000000..c39f6de76670 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/dma-controller.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/dma-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DMA Controller Generic Binding + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +allOf: + - $ref: "dma-common.yaml#" + +# Everything else is described in the common file +properties: + $nodename: + pattern: "^dma-controller(@.*)?$" + +examples: + - | + dma: dma-controller@48000000 { + compatible = "ti,omap-sdma"; + reg = <0x48000000 0x1000>; + interrupts = <0 12 0x4 + 0 13 0x4 + 0 14 0x4 + 0 15 0x4>; + #dma-cells = <1>; + dma-channels = <32>; + dma-requests = <127>; + dma-channel-mask = <0xfffe>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/dma-router.yaml b/Documentation/devicetree/bindings/dma/dma-router.yaml new file mode 100644 index 000000000000..5b5f07393135 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/dma-router.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/dma-router.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DMA Router Generic Binding + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +allOf: + - $ref: "dma-common.yaml#" + +description: + DMA routers are transparent IP blocks used to route DMA request + lines from devices to the DMA controller. Some SoCs (like TI DRA7x) + have more peripherals integrated with DMA requests than what the DMA + controller can handle directly. + +properties: + $nodename: + pattern: "^dma-router(@.*)?$" + + dma-masters: + $ref: /schemas/types.yaml#definitions/phandle-array + description: + Array of phandles to the DMA controllers the router can direct + the signal to. + + dma-requests: + description: + Number of incoming request lines the router can handle. + +required: + - "#dma-cells" + - dma-masters + +examples: + - | + sdma_xbar: dma-router@4a002b78 { + compatible = "ti,dra7-dma-crossbar"; + reg = <0x4a002b78 0xfc>; + #dma-cells = <1>; + dma-requests = <205>; + ti,dma-safe-map = <0>; + dma-masters = <&sdma>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/dma.txt b/Documentation/devicetree/bindings/dma/dma.txt index eeb4e4d1771e..90a67a016a48 100644 --- a/Documentation/devicetree/bindings/dma/dma.txt +++ b/Documentation/devicetree/bindings/dma/dma.txt @@ -1,113 +1 @@ -* Generic DMA Controller and DMA request bindings - -Generic binding to provide a way for a driver using DMA Engine to retrieve the -DMA request or channel information that goes from a hardware device to a DMA -controller. - - -* DMA controller - -Required property: -- #dma-cells: Must be at least 1. Used to provide DMA controller - specific information. See DMA client binding below for - more details. - -Optional properties: -- dma-channels: Number of DMA channels supported by the controller. -- dma-requests: Number of DMA request signals supported by the - controller. -- dma-channel-mask: Bitmask of available DMA channels in ascending order - that are not reserved by firmware and are available to - the kernel. i.e. first channel corresponds to LSB. - -Example: - - dma: dma@48000000 { - compatible = "ti,omap-sdma"; - reg = <0x48000000 0x1000>; - interrupts = <0 12 0x4 - 0 13 0x4 - 0 14 0x4 - 0 15 0x4>; - #dma-cells = <1>; - dma-channels = <32>; - dma-requests = <127>; - dma-channel-mask = <0xfffe> - }; - -* DMA router - -DMA routers are transparent IP blocks used to route DMA request lines from -devices to the DMA controller. Some SoCs (like TI DRA7x) have more peripherals -integrated with DMA requests than what the DMA controller can handle directly. - -Required property: -- dma-masters: phandle of the DMA controller or list of phandles for - the DMA controllers the router can direct the signal to. -- #dma-cells: Must be at least 1. Used to provide DMA router specific - information. See DMA client binding below for more - details. - -Optional properties: -- dma-requests: Number of incoming request lines the router can handle. -- In the node pointed by the dma-masters: - - dma-requests: The router driver might need to look for this in order - to configure the routing. - -Example: - sdma_xbar: dma-router@4a002b78 { - compatible = "ti,dra7-dma-crossbar"; - reg = <0x4a002b78 0xfc>; - #dma-cells = <1>; - dma-requests = <205>; - ti,dma-safe-map = <0>; - dma-masters = <&sdma>; - }; - -* DMA client - -Client drivers should specify the DMA property using a phandle to the controller -followed by DMA controller specific data. - -Required property: -- dmas: List of one or more DMA specifiers, each consisting of - - A phandle pointing to DMA controller node - - A number of integer cells, as determined by the - #dma-cells property in the node referenced by phandle - containing DMA controller specific information. This - typically contains a DMA request line number or a - channel number, but can contain any data that is - required for configuring a channel. -- dma-names: Contains one identifier string for each DMA specifier in - the dmas property. The specific strings that can be used - are defined in the binding of the DMA client device. - Multiple DMA specifiers can be used to represent - alternatives and in this case the dma-names for those - DMA specifiers must be identical (see examples). - -Examples: - -1. A device with one DMA read channel, one DMA write channel: - - i2c1: i2c@1 { - ... - dmas = <&dma 2 /* read channel */ - &dma 3>; /* write channel */ - dma-names = "rx", "tx"; - ... - }; - -2. A single read-write channel with three alternative DMA controllers: - - dmas = <&dma1 5 - &dma2 7 - &dma3 2>; - dma-names = "rx-tx", "rx-tx", "rx-tx"; - -3. A device with three channels, one of which has two alternatives: - - dmas = <&dma1 2 /* read channel */ - &dma1 3 /* write channel */ - &dma2 0 /* error read */ - &dma3 0>; /* alternative error read */ - dma-names = "rx", "tx", "error", "error"; +This file has been moved to dma-controller.yaml. diff --git a/Documentation/devicetree/bindings/dma/nbpfaxi.txt b/Documentation/devicetree/bindings/dma/renesas,nbpfaxi.txt index d2e1e62e346a..d2e1e62e346a 100644 --- a/Documentation/devicetree/bindings/dma/nbpfaxi.txt +++ b/Documentation/devicetree/bindings/dma/renesas,nbpfaxi.txt diff --git a/Documentation/devicetree/bindings/dma/shdma.txt b/Documentation/devicetree/bindings/dma/renesas,shdma.txt index a91920a49433..a91920a49433 100644 --- a/Documentation/devicetree/bindings/dma/shdma.txt +++ b/Documentation/devicetree/bindings/dma/renesas,shdma.txt diff --git a/Documentation/devicetree/bindings/dma/sun4i-dma.txt b/Documentation/devicetree/bindings/dma/sun4i-dma.txt deleted file mode 100644 index 8ad556aca70b..000000000000 --- a/Documentation/devicetree/bindings/dma/sun4i-dma.txt +++ /dev/null @@ -1,45 +0,0 @@ -Allwinner A10 DMA Controller - -This driver follows the generic DMA bindings defined in dma.txt. - -Required properties: - -- compatible: Must be "allwinner,sun4i-a10-dma" -- reg: Should contain the registers base address and length -- interrupts: Should contain a reference to the interrupt used by this device -- clocks: Should contain a reference to the parent AHB clock -- #dma-cells : Should be 2, first cell denoting normal or dedicated dma, - second cell holding the request line number. - -Example: - dma: dma-controller@1c02000 { - compatible = "allwinner,sun4i-a10-dma"; - reg = <0x01c02000 0x1000>; - interrupts = <27>; - clocks = <&ahb_gates 6>; - #dma-cells = <2>; - }; - -Clients: - -DMA clients connected to the Allwinner A10 DMA controller must use the -format described in the dma.txt file, using a three-cell specifier for -each channel: a phandle plus two integer cells. -The three cells in order are: - -1. A phandle pointing to the DMA controller. -2. Whether it is using normal (0) or dedicated (1) channels -3. The port ID as specified in the datasheet - -Example: - spi2: spi@1c17000 { - compatible = "allwinner,sun4i-a10-spi"; - reg = <0x01c17000 0x1000>; - interrupts = <0 12 4>; - clocks = <&ahb_gates 22>, <&spi2_clk>; - clock-names = "ahb", "mod"; - dmas = <&dma 1 29>, <&dma 1 28>; - dma-names = "rx", "tx"; - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt deleted file mode 100644 index cae31f4e77ba..000000000000 --- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt +++ /dev/null @@ -1,81 +0,0 @@ -Allwinner A31 DMA Controller - -This driver follows the generic DMA bindings defined in dma.txt. - -Required properties: - -- compatible: Must be one of - "allwinner,sun6i-a31-dma" - "allwinner,sun8i-a23-dma" - "allwinner,sun8i-a83t-dma" - "allwinner,sun8i-h3-dma" - "allwinner,sun8i-v3s-dma" -- reg: Should contain the registers base address and length -- interrupts: Should contain a reference to the interrupt used by this device -- clocks: Should contain a reference to the parent AHB clock -- resets: Should contain a reference to the reset controller asserting - this device in reset -- #dma-cells : Should be 1, a single cell holding a line request number - -Example: - dma: dma-controller@1c02000 { - compatible = "allwinner,sun6i-a31-dma"; - reg = <0x01c02000 0x1000>; - interrupts = <0 50 4>; - clocks = <&ahb1_gates 6>; - resets = <&ahb1_rst 6>; - #dma-cells = <1>; - }; - ------------------------------------------------------------------------------- -For A64 and H6 DMA controller: - -Required properties: -- compatible: Must be one of - "allwinner,sun50i-a64-dma" - "allwinner,sun50i-h6-dma" -- dma-channels: Number of DMA channels supported by the controller. - Refer to Documentation/devicetree/bindings/dma/dma.txt -- clocks: In addition to parent AHB clock, it should also contain mbus - clock (H6 only) -- clock-names: Should contain "bus" and "mbus" (H6 only) -- all properties above, i.e. reg, interrupts, clocks, resets and #dma-cells - -Optional properties: -- dma-requests: Number of DMA request signals supported by the controller. - Refer to Documentation/devicetree/bindings/dma/dma.txt - -Example: - dma: dma-controller@1c02000 { - compatible = "allwinner,sun50i-a64-dma"; - reg = <0x01c02000 0x1000>; - interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&ccu CLK_BUS_DMA>; - dma-channels = <8>; - dma-requests = <27>; - resets = <&ccu RST_BUS_DMA>; - #dma-cells = <1>; - }; ------------------------------------------------------------------------------- - -Clients: - -DMA clients connected to the A31 DMA controller must use the format -described in the dma.txt file, using a two-cell specifier for each -channel: a phandle plus one integer cells. -The two cells in order are: - -1. A phandle pointing to the DMA controller. -2. The port ID as specified in the datasheet - -Example: -spi2: spi@1c6a000 { - compatible = "allwinner,sun6i-a31-spi"; - reg = <0x01c6a000 0x1000>; - interrupts = <0 67 4>; - clocks = <&ahb1_gates 22>, <&spi2_clk>; - clock-names = "ahb", "mod"; - dmas = <&dma 25>, <&dma 25>; - dma-names = "rx", "tx"; - resets = <&ahb1_rst 22>; -}; diff --git a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml new file mode 100644 index 000000000000..3248595dc93c --- /dev/null +++ b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dsp/fsl,dsp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8 DSP core + +maintainers: + - Daniel Baluta <daniel.baluta@nxp.com> + +description: | + Some boards from i.MX8 family contain a DSP core used for + advanced pre- and post- audio processing. + +properties: + compatible: + enum: + - fsl,imx8qxp-dsp + + reg: + description: Should contain register location and length + + clocks: + items: + - description: ipg clock + - description: ocram clock + - description: core clock + + clock-names: + items: + - const: ipg + - const: ocram + - const: core + + power-domains: + description: + List of phandle and PM domain specifier as documented in + Documentation/devicetree/bindings/power/power_domain.txt + maxItems: 4 + + mboxes: + description: + List of <&phandle type channel> - 2 channels for TXDB, 2 channels for RXDB + (see mailbox/fsl,mu.txt) + maxItems: 4 + + mbox-names: + items: + - const: txdb0 + - const: txdb1 + - const: rxdb0 + - const: rxdb1 + + memory-region: + description: + phandle to a node describing reserved memory (System RAM memory) + used by DSP (see bindings/reserved-memory/reserved-memory.txt) + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - power-domains + - mboxes + - mbox-names + - memory-region + +examples: + - | + #include <dt-bindings/firmware/imx/rsrc.h> + #include <dt-bindings/clock/imx8-clock.h> + dsp@596e8000 { + compatible = "fsl,imx8qxp-dsp"; + reg = <0x596e8000 0x88000>; + clocks = <&adma_lpcg IMX_ADMA_LPCG_DSP_IPG_CLK>, + <&adma_lpcg IMX_ADMA_LPCG_OCRAM_IPG_CLK>, + <&adma_lpcg IMX_ADMA_LPCG_DSP_CORE_CLK>; + clock-names = "ipg", "ocram", "core"; + power-domains = <&pd IMX_SC_R_MU_13A>, + <&pd IMX_SC_R_MU_13B>, + <&pd IMX_SC_R_DSP>, + <&pd IMX_SC_R_DSP_RAM>; + mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1"; + mboxes = <&lsio_mu13 2 0>, <&lsio_mu13 2 1>, <&lsio_mu13 3 0>, <&lsio_mu13 3 1>; + }; diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index b3bde97dc199..42577dd113dd 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt @@ -3,6 +3,7 @@ EEPROMs (SPI) compatible with Atmel at25. Required properties: - compatible : Should be "<vendor>,<type>", and generic value "atmel,at25". Example "<vendor>,<type>" values: + "anvo,anv32e61w" "microchip,25lc040" "st,m95m02" "st,m95256" diff --git a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt index 7f3d94ae81ff..208daaff0be4 100644 --- a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt +++ b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt @@ -72,5 +72,5 @@ codec: wm8280@0 { 1 2 1 /* MICDET2 MICBIAS2 GPIO=high */ >; - wlf,gpsw = <0>; + wlf,gpsw = <ARIZONA_GPSW_OPEN>; }; diff --git a/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt b/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt index d592c21245f2..624bd76f468e 100644 --- a/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt +++ b/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt @@ -5,7 +5,9 @@ controlled using I2C and enables USB data, stereo and mono audio, video, microphone, and UART data to use a common connector port. Required properties: - - compatible : Must be "fcs,fsa9480" + - compatible : Must be one of + "fcs,fsa9480" + "fcs,fsa880" - reg : Specifies i2c slave address. Must be 0x25. - interrupts : Should contain one entry specifying interrupt signal of interrupt parent to which interrupt pin of the chip is connected. diff --git a/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt b/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt deleted file mode 100644 index b1f9474f36d5..000000000000 --- a/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt +++ /dev/null @@ -1,71 +0,0 @@ -* Arcx Anybus-S controller - -This chip communicates with the SoC over a parallel bus. It is -expected that its Device Tree node is specified as the child of a node -corresponding to the parallel bus used for communication. - -Required properties: --------------------- - - - compatible : The following chip-specific string: - "arcx,anybus-controller" - - - reg : three areas: - index 0: bus memory area where the cpld registers are located. - index 1: bus memory area of the first host's dual-port ram. - index 2: bus memory area of the second host's dual-port ram. - - - reset-gpios : the GPIO pin connected to the reset line of the controller. - - - interrupts : two interrupts: - index 0: interrupt connected to the first host - index 1: interrupt connected to the second host - Generic interrupt client node bindings are described in - interrupt-controller/interrupts.txt - -Optional: use of subnodes -------------------------- - -The card connected to a host may need additional properties. These can be -specified in subnodes to the controller node. - -The subnodes are identified by the standard 'reg' property. Which information -exactly can be specified depends on the bindings for the function driver -for the subnode. - -Required controller node properties when using subnodes: -- #address-cells: should be one. -- #size-cells: should be zero. - -Required subnode properties: -- reg: Must contain the host index of the card this subnode describes: - <0> for the first host on the controller - <1> for the second host on the controller - Note that only a single card can be plugged into a host, so the host - index uniquely describes the card location. - -Example of usage: ------------------ - -This example places the bridge on top of the i.MX WEIM parallel bus, see: -Documentation/devicetree/bindings/bus/imx-weim.txt - -&weim { - controller@0,0 { - compatible = "arcx,anybus-controller"; - reg = <0 0 0x100>, <0 0x400000 0x800>, <1 0x400000 0x800>; - reset-gpios = <&gpio5 2 GPIO_ACTIVE_HIGH>; - interrupt-parent = <&gpio1>; - interrupts = <1 IRQ_TYPE_LEVEL_LOW>, <5 IRQ_TYPE_LEVEL_LOW>; - /* fsl,weim-cs-timing is a i.MX WEIM bus specific property */ - fsl,weim-cs-timing = <0x024400b1 0x00001010 0x20081100 - 0x00000000 0xa0000240 0x00000000>; - /* optional subnode for a card plugged into the first host */ - #address-cells = <1>; - #size-cells = <0>; - card@0 { - reg = <0>; - /* card specific properties go here */ - }; - }; -}; diff --git a/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt b/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt new file mode 100644 index 000000000000..338169dea7bb --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt @@ -0,0 +1,19 @@ +Turris Mox rWTM firmware driver + +Required properties: + - compatible : Should be "cznic,turris-mox-rwtm" + - mboxes : Must contain a reference to associated mailbox + +This device tree node should be used on Turris Mox, or potentially another A3700 +compatible device running the Mox's rWTM firmware in the secure processor (for +example it is possible to flash this firmware into EspressoBin). + +Example: + + firmware { + turris-mox-rwtm { + compatible = "cznic,turris-mox-rwtm"; + mboxes = <&rwtm 0>; + status = "okay"; + }; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 41f133a4e2fa..3f29ea04b5fe 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -9,14 +9,16 @@ Required properties: - compatible: must contain one of the following: * "qcom,scm-apq8064" * "qcom,scm-apq8084" + * "qcom,scm-ipq4019" * "qcom,scm-msm8660" * "qcom,scm-msm8916" * "qcom,scm-msm8960" * "qcom,scm-msm8974" * "qcom,scm-msm8996" * "qcom,scm-msm8998" - * "qcom,scm-ipq4019" + * "qcom,scm-sc7180" * "qcom,scm-sdm845" + * "qcom,scm-sm8150" and: * "qcom,scm" - clocks: Specifies clocks needed by the SCM interface, if any: diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt index 817a8d4bf903..5dd0ff0f7b4e 100644 --- a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt +++ b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt @@ -3,10 +3,7 @@ Altera FPGA To SDRAM Bridge Driver Required properties: - compatible : Should contain "altr,socfpga-fpga2sdram-bridge" -Optional properties: -- bridge-enable : 0 if driver should disable bridge at startup - 1 if driver should enable bridge at startup - Default is to leave bridge in current state. +See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: fpga_bridge3: fpga-bridge@ffc25080 { diff --git a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt index f8e288c71b2d..8b26fbcff3c6 100644 --- a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt +++ b/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt @@ -10,10 +10,7 @@ Required properties: - compatible : Should contain "altr,freeze-bridge-controller" - regs : base address and size for freeze bridge module -Optional properties: -- bridge-enable : 0 if driver should disable bridge at startup - 1 if driver should enable bridge at startup - Default is to leave bridge in current state. +See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: freeze-controller@100000450 { diff --git a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt index 6406f9337eeb..68cce3945b10 100644 --- a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt +++ b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt @@ -9,10 +9,7 @@ Required properties: - resets : Phandle and reset specifier for this bridge's reset - clocks : Clocks used by this module. -Optional properties: -- bridge-enable : 0 if driver should disable bridge at startup. - 1 if driver should enable bridge at startup. - Default is to leave bridge in its current state. +See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: fpga_bridge0: fpga-bridge@ff400000 { diff --git a/Documentation/devicetree/bindings/fpga/fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/fpga-bridge.txt new file mode 100644 index 000000000000..72e06917288a --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/fpga-bridge.txt @@ -0,0 +1,13 @@ +FPGA Bridge Device Tree Binding + +Optional properties: +- bridge-enable : 0 if driver should disable bridge at startup + 1 if driver should enable bridge at startup + Default is to leave bridge in current state. + +Example: + fpga_bridge3: fpga-bridge@ffc25080 { + compatible = "altr,socfpga-fpga2sdram-bridge"; + reg = <0xffc25080 0x4>; + bridge-enable = <0>; + }; diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt index 8dcfba926bc7..4284d293fa61 100644 --- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt +++ b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt @@ -18,12 +18,8 @@ Required properties: - clocks : input clock to IP - clock-names : should contain "aclk" -Optional properties: -- bridge-enable : 0 if driver should disable bridge at startup - 1 if driver should enable bridge at startup - Default is to leave bridge in current state. - -See Documentation/devicetree/bindings/fpga/fpga-region.txt for generic bindings. +See Documentation/devicetree/bindings/fpga/fpga-region.txt and +Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: fpga-bridge@100000450 { diff --git a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt index 7e9b586770b0..b2033fc3a71a 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt @@ -2,7 +2,8 @@ Aspeed GPIO controller Device Tree Bindings ------------------------------------------- Required properties: -- compatible : Either "aspeed,ast2400-gpio" or "aspeed,ast2500-gpio" +- compatible : Either "aspeed,ast2400-gpio", "aspeed,ast2500-gpio", + or "aspeed,ast2600-gpio". - #gpio-cells : Should be two - First cell is the GPIO line number @@ -17,7 +18,9 @@ Required properties: Optional properties: -- clocks : A phandle to the clock to use for debounce timings +- clocks : A phandle to the clock to use for debounce timings +- ngpios : Number of GPIOs controlled by this controller. Should be set + when there are multiple GPIO controllers on a SoC (ast2600). The gpio and interrupt properties are further described in their respective bindings documentation: diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt index bc6b4b62df83..cd91d61eac31 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt @@ -6,6 +6,7 @@ Required Properties: 66AK2E SoCs "ti,k2g-gpio", "ti,keystone-gpio": for 66AK2G "ti,am654-gpio", "ti,keystone-gpio": for TI K3 AM654 + "ti,j721e-gpio", "ti,keystone-gpio": for J721E SoCs - reg: Physical base address of the controller and the size of memory mapped registers. diff --git a/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt b/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt new file mode 100644 index 000000000000..410759de9f09 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt @@ -0,0 +1,18 @@ +Turris Mox Moxtet GPIO expander via Moxtet bus + +Required properties: + - compatible : Should be "cznic,moxtet-gpio". + - gpio-controller : Marks the device node as a GPIO controller. + - #gpio-cells : Should be two. For consumer use see gpio.txt. + +Other properties are required for a Moxtet bus device, please refer to +Documentation/devicetree/bindings/bus/moxtet.txt. + +Example: + + moxtet_sfp: gpio@0 { + compatible = "cznic,moxtet-gpio"; + gpio-controller; + #gpio-cells = <2>; + reg = <0>; + } diff --git a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt index 69d46162d0f5..cd28e932bf50 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt @@ -4,7 +4,7 @@ Required properties: - compatible : Should be "fsl,<soc>-gpio" The following <soc>s are known to be supported: mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq, - ls1021a, ls1043a, ls2080a. + ls1021a, ls1043a, ls2080a, ls1028a, ls1088a. - reg : Address and length of the register set for the device - interrupts : Should be the port interrupt shared by all 32 pins. - #gpio-cells : Should be two. The first cell is the pin number and @@ -37,3 +37,17 @@ gpio0: gpio@2300000 { interrupt-controller; #interrupt-cells = <2>; }; + + +Example of gpio-controller node for a ls1028a/ls1088a SoC: + +gpio1: gpio@2300000 { + compatible = "fsl,ls1028a-gpio", "fsl,ls1088a-gpio", "fsl,qoriq-gpio"; + reg = <0x0 0x2300000 0x0 0x10000>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + little-endian; +}; diff --git a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt new file mode 100644 index 000000000000..d4d83916c09d --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt @@ -0,0 +1,45 @@ +Aspeed SGPIO controller Device Tree Bindings +-------------------------------------------- + +This SGPIO controller is for ASPEED AST2500 SoC, it supports up to 80 full +featured Serial GPIOs. Each of the Serial GPIO pins can be programmed to +support the following options: +- Support interrupt option for each input port and various interrupt + sensitivity option (level-high, level-low, edge-high, edge-low) +- Support reset tolerance option for each output port +- Directly connected to APB bus and its shift clock is from APB bus clock + divided by a programmable value. +- Co-work with external signal-chained TTL components (74LV165/74LV595) + +Required properties: + +- compatible : Should be one of + "aspeed,ast2400-sgpio", "aspeed,ast2500-sgpio" +- #gpio-cells : Should be 2, see gpio.txt +- reg : Address and length of the register set for the device +- gpio-controller : Marks the device node as a GPIO controller +- interrupts : Interrupt specifier, see interrupt-controller/interrupts.txt +- interrupt-controller : Mark the GPIO controller as an interrupt-controller +- ngpios : number of GPIO lines, see gpio.txt + (should be multiple of 8, up to 80 pins) +- clocks : A phandle to the APB clock for SGPM clock division +- bus-frequency : SGPM CLK frequency + +The sgpio and interrupt properties are further described in their respective +bindings documentation: + +- Documentation/devicetree/bindings/gpio/gpio.txt +- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + + Example: + sgpio: sgpio@1e780200 { + #gpio-cells = <2>; + compatible = "aspeed,ast2500-sgpio"; + gpio-controller; + interrupts = <40>; + reg = <0x1e780200 0x0100>; + clocks = <&syscon ASPEED_CLK_APB>; + interrupt-controller; + ngpios = <8>; + bus-frequency = <12000000>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/as370.txt b/Documentation/devicetree/bindings/hwmon/as370.txt new file mode 100644 index 000000000000..d102fe765124 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/as370.txt @@ -0,0 +1,11 @@ +Bindings for Synaptics AS370 PVT sensors + +Required properties: +- compatible : "syna,as370-hwmon" +- reg : address and length of the register set. + +Example: + hwmon@ea0810 { + compatible = "syna,as370-hwmon"; + reg = <0xea0810 0xc>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt b/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt index f68a0a68fc52..1036f65fb778 100644 --- a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt +++ b/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt @@ -1,8 +1,10 @@ -Device-tree bindings for IBM Common Form Factor Power Supply Version 1 ----------------------------------------------------------------------- +Device-tree bindings for IBM Common Form Factor Power Supply Versions 1 and 2 +----------------------------------------------------------------------------- Required properties: - - compatible = "ibm,cffps1"; + - compatible : Must be one of the following: + "ibm,cffps1" + "ibm,cffps2" - reg = < I2C bus address >; : Address of the power supply on the I2C bus. diff --git a/Documentation/devicetree/bindings/hwmon/lm75.txt b/Documentation/devicetree/bindings/hwmon/lm75.txt index 586b5ed70be7..273616702c51 100644 --- a/Documentation/devicetree/bindings/hwmon/lm75.txt +++ b/Documentation/devicetree/bindings/hwmon/lm75.txt @@ -15,6 +15,7 @@ Required properties: "maxim,max31725", "maxim,max31726", "maxim,mcp980x", + "nxp,pct2075", "st,stds75", "st,stlm75", "microchip,tcn75", diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt index 2907dab56298..8b444b94e92f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt @@ -42,7 +42,7 @@ Optional properties: This means that no unrelated I2C transactions are allowed on the parent I2C adapter for the complete multiplexed I2C transaction. The properties of mux-locked and parent-locked multiplexers are discussed - in more detail in Documentation/i2c/i2c-topology. + in more detail in Documentation/i2c/i2c-topology.rst. For each i2c child node, an I2C child bus will be created. They will be numbered based on their order in the device tree. diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml index 001f2b7abad0..c779000515d6 100644 --- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -26,6 +26,9 @@ properties: - items: - const: allwinner,sun50i-a64-i2c - const: allwinner,sun6i-a31-i2c + - items: + - const: allwinner,sun50i-h6-i2c + - const: allwinner,sun6i-a31-i2c - const: marvell,mv64xxx-i2c - const: marvell,mv78230-i2c diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml new file mode 100644 index 000000000000..676ec42e1438 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 Analog Devices Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/iio/adc/adi,ad7192.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD7192 ADC device driver + +maintainers: + - Michael Hennerich <michael.hennerich@analog.com> + +description: | + Bindings for the Analog Devices AD7192 ADC device. Datasheet can be + found here: + https://www.analog.com/media/en/technical-documentation/data-sheets/AD7192.pdf + +properties: + compatible: + enum: + - adi,ad7190 + - adi,ad7192 + - adi,ad7193 + - adi,ad7195 + + reg: + maxItems: 1 + + spi-cpol: true + + spi-cpha: true + + clocks: + maxItems: 1 + description: phandle to the master clock (mclk) + + clock-names: + items: + - const: mclk + + interrupts: + maxItems: 1 + + dvdd-supply: + description: DVdd voltage supply + items: + - const: dvdd + + avdd-supply: + description: AVdd voltage supply + items: + - const: avdd + + adi,rejection-60-Hz-enable: + description: | + This bit enables a notch at 60 Hz when the first notch of the sinc + filter is at 50 Hz. When REJ60 is set, a filter notch is placed at + 60 Hz when the sinc filter first notch is at 50 Hz. This allows + simultaneous 50 Hz/ 60 Hz rejection. + type: boolean + + adi,refin2-pins-enable: + description: | + External reference applied between the P1/REFIN2(+) and P0/REFIN2(−) pins. + type: boolean + + adi,buffer-enable: + description: | + Enables the buffer on the analog inputs. If cleared, the analog inputs + are unbuffered, lowering the power consumption of the device. If this + bit is set, the analog inputs are buffered, allowing the user to place + source impedances on the front end without contributing gain errors to + the system. + type: boolean + + adi,burnout-currents-enable: + description: | + When this bit is set to 1, the 500 nA current sources in the signal + path are enabled. When BURN = 0, the burnout currents are disabled. + The burnout currents can be enabled only when the buffer is active + and when chop is disabled. + type: boolean + + bipolar: + description: see Documentation/devicetree/bindings/iio/adc/adc.txt + type: boolean + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - dvdd-supply + - avdd-supply + - spi-cpol + - spi-cpha + +examples: + - | + spi0 { + adc@0 { + compatible = "adi,ad7192"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + spi-cpha; + clocks = <&ad7192_mclk>; + clock-names = "mclk"; + #interrupt-cells = <2>; + interrupts = <25 0x2>; + interrupt-parent = <&gpio>; + dvdd-supply = <&dvdd>; + avdd-supply = <&avdd>; + + adi,refin2-pins-enable; + adi,rejection-60-Hz-enable; + adi,buffer-enable; + adi,burnout-currents-enable; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt deleted file mode 100644 index d8652460198e..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt +++ /dev/null @@ -1,66 +0,0 @@ -Analog Devices AD7606 Simultaneous Sampling ADC - -Required properties for the AD7606: - -- compatible: Must be one of - * "adi,ad7605-4" - * "adi,ad7606-8" - * "adi,ad7606-6" - * "adi,ad7606-4" - * "adi,ad7616" -- reg: SPI chip select number for the device -- spi-max-frequency: Max SPI frequency to use - see: Documentation/devicetree/bindings/spi/spi-bus.txt -- spi-cpha: See Documentation/devicetree/bindings/spi/spi-bus.txt -- avcc-supply: phandle to the Avcc power supply -- interrupts: IRQ line for the ADC - see: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt -- adi,conversion-start-gpios: must be the device tree identifier of the CONVST pin. - This logic input is used to initiate conversions on the analog - input channels. As the line is active high, it should be marked - GPIO_ACTIVE_HIGH. - -Optional properties: - -- reset-gpios: must be the device tree identifier of the RESET pin. If specified, - it will be asserted during driver probe. As the line is active high, - it should be marked GPIO_ACTIVE_HIGH. -- standby-gpios: must be the device tree identifier of the STBY pin. This pin is used - to place the AD7606 into one of two power-down modes, Standby mode or - Shutdown mode. As the line is active low, it should be marked - GPIO_ACTIVE_LOW. -- adi,first-data-gpios: must be the device tree identifier of the FRSTDATA pin. - The FRSTDATA output indicates when the first channel, V1, is - being read back on either the parallel, byte or serial interface. - As the line is active high, it should be marked GPIO_ACTIVE_HIGH. -- adi,range-gpios: must be the device tree identifier of the RANGE pin. The polarity on - this pin determines the input range of the analog input channels. If - this pin is tied to a logic high, the analog input range is ±10V for - all channels. If this pin is tied to a logic low, the analog input range - is ±5V for all channels. As the line is active high, it should be marked - GPIO_ACTIVE_HIGH. -- adi,oversampling-ratio-gpios: must be the device tree identifier of the over-sampling - mode pins. As the line is active high, it should be marked - GPIO_ACTIVE_HIGH. - -Example: - - adc@0 { - compatible = "adi,ad7606-8"; - reg = <0>; - spi-max-frequency = <1000000>; - spi-cpol; - - avcc-supply = <&adc_vref>; - - interrupts = <25 IRQ_TYPE_EDGE_FALLING>; - interrupt-parent = <&gpio>; - - adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; - reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; - adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH - &gpio 23 GPIO_ACTIVE_HIGH - &gpio 26 GPIO_ACTIVE_HIGH>; - standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml new file mode 100644 index 000000000000..cc544fdc38be --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/adi,ad7606.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD7606 Simultaneous Sampling ADC + +maintainers: + - Beniamin Bia <beniamin.bia@analog.com> + - Stefan Popa <stefan.popa@analog.com> + +description: | + Analog Devices AD7606 Simultaneous Sampling ADC + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606_7606-6_7606-4.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/AD7606B.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/AD7616.pdf + +properties: + compatible: + enum: + - adi,ad7605-4 + - adi,ad7606-8 + - adi,ad7606-6 + - adi,ad7606-4 + - adi,ad7606b + - adi,ad7616 + + reg: + maxItems: 1 + + spi-cpha: true + + avcc-supply: + description: + Phandle to the Avcc power supply + maxItems: 1 + + interrupts: + maxItems: 1 + + adi,conversion-start-gpios: + description: + Must be the device tree identifier of the CONVST pin. + This logic input is used to initiate conversions on the analog + input channels. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. + maxItems: 1 + + reset-gpios: + description: + Must be the device tree identifier of the RESET pin. If specified, + it will be asserted during driver probe. As the line is active high, + it should be marked GPIO_ACTIVE_HIGH. + maxItems: 1 + + standby-gpios: + description: + Must be the device tree identifier of the STBY pin. This pin is used + to place the AD7606 into one of two power-down modes, Standby mode or + Shutdown mode. As the line is active low, it should be marked + GPIO_ACTIVE_LOW. + maxItems: 1 + + adi,first-data-gpios: + description: + Must be the device tree identifier of the FRSTDATA pin. + The FRSTDATA output indicates when the first channel, V1, is + being read back on either the parallel, byte or serial interface. + As the line is active high, it should be marked GPIO_ACTIVE_HIGH. + maxItems: 1 + + adi,range-gpios: + description: + Must be the device tree identifier of the RANGE pin. The polarity on + this pin determines the input range of the analog input channels. If + this pin is tied to a logic high, the analog input range is ±10V for + all channels. If this pin is tied to a logic low, the analog input range + is ±5V for all channels. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. + maxItems: 1 + + adi,oversampling-ratio-gpios: + description: + Must be the device tree identifier of the over-sampling + mode pins. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. + maxItems: 1 + + adi,sw-mode: + description: + Software mode of operation, so far available only for ad7616 and ad7606b. + It is enabled when all three oversampling mode pins are connected to + high level. The device is configured by the corresponding registers. If the + adi,oversampling-ratio-gpios property is defined, then the driver will set the + oversampling gpios to high. Otherwise, it is assumed that the pins are hardwired + to VDD. + type: boolean + +required: + - compatible + - reg + - spi-cpha + - avcc-supply + - interrupts + - adi,conversion-start-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "adi,ad7606-8"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + spi-cpha; + + avcc-supply = <&adc_vref>; + + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; + + adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; + adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; + adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH + &gpio 23 GPIO_ACTIVE_HIGH + &gpio 26 GPIO_ACTIVE_HIGH>; + standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>; + adi,sw-mode; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/ads1015.txt b/Documentation/devicetree/bindings/iio/adc/ads1015.txt index 918a507d1159..918a507d1159 100644 --- a/Documentation/devicetree/bindings/hwmon/ads1015.txt +++ b/Documentation/devicetree/bindings/iio/adc/ads1015.txt diff --git a/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml new file mode 100644 index 000000000000..d74962c0f5ae --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/allwinner,sun8i-a33-ths.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A33 Thermal Sensor Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#io-channel-cells": + const: 0 + + "#thermal-sensor-cells": + const: 0 + + compatible: + const: allwinner,sun8i-a33-ths + + reg: + maxItems: 1 + +required: + - "#io-channel-cells" + - "#thermal-sensor-cells" + - compatible + - reg + +additionalProperties: false + +examples: + - | + ths: ths@1c25000 { + compatible = "allwinner,sun8i-a33-ths"; + reg = <0x01c25000 0x100>; + #thermal-sensor-cells = <0>; + #io-channel-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 93a0bd2efc05..4c0da8c74bb2 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -47,6 +47,12 @@ Required properties: Optional properties: - A pinctrl state named "default" for each ADC channel may be defined to set inX ADC pins in mode of operation for analog input on external pin. +- booster-supply: Phandle to the embedded booster regulator that can be used + to supply ADC analog input switches on stm32h7 and stm32mp1. +- vdd-supply: Phandle to the vdd input voltage. It can be used to supply ADC + analog input switches on stm32mp1. +- st,syscfg: Phandle to system configuration controller. It can be used to + control the analog circuitry on stm32mp1. Contents of a stm32 adc child node: ----------------------------------- diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt deleted file mode 100644 index c52ea2126eaa..000000000000 --- a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt +++ /dev/null @@ -1,26 +0,0 @@ -* Plantower PMS7003 particulate matter sensor - -Required properties: -- compatible: must one of: - "plantower,pms1003" - "plantower,pms3003" - "plantower,pms5003" - "plantower,pms6003" - "plantower,pms7003" - "plantower,pmsa003" -- vcc-supply: phandle to the regulator that provides power to the sensor - -Optional properties: -- plantower,set-gpios: phandle to the GPIO connected to the SET line -- reset-gpios: phandle to the GPIO connected to the RESET line - -Refer to serial/slave-device.txt for generic serial attached device bindings. - -Example: - -&uart0 { - air-pollution-sensor { - compatible = "plantower,pms7003"; - vcc-supply = <®_vcc5v0>; - }; -}; diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml new file mode 100644 index 000000000000..a551d3101f93 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/chemical/plantower,pms7003.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Plantower PMS7003 air pollution sensor + +maintainers: + - Tomasz Duszynski <tduszyns@gmail.com> + +description: | + Air pollution sensor capable of measuring mass concentration of dust + particles. + +properties: + compatible: + enum: + - plantower,pms1003 + - plantower,pms3003 + - plantower,pms5003 + - plantower,pms6003 + - plantower,pms7003 + - plantower,pmsa003 + + vcc-supply: + description: regulator that provides power to the sensor + maxItems: 1 + + plantower,set-gpios: + description: GPIO connected to the SET line + maxItems: 1 + + reset-gpios: + description: GPIO connected to the RESET line + maxItems: 1 + +required: + - compatible + - vcc-supply + +examples: + - | + serial { + air-pollution-sensor { + compatible = "plantower,pms7003"; + vcc-supply = <®_vcc5v0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml new file mode 100644 index 000000000000..0c53009ba7d6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/imu/adi,adis16460.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADIS16460 and similar IMUs + +maintainers: + - Dragos Bogdan <dragos.bogdan@analog.com> + +description: | + Analog Devices ADIS16460 and similar IMUs + https://www.analog.com/media/en/technical-documentation/data-sheets/ADIS16460.pdf + +properties: + compatible: + enum: + - adi,adis16460 + + reg: + maxItems: 1 + + spi-cpha: true + + spi-cpol: true + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + imu@0 { + compatible = "adi,adis16460"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpol; + spi-cpha; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt index efec9ece034a..6d0c050d89fe 100644 --- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -11,6 +11,9 @@ Required properties: "st,asm330lhh" "st,lsm6dsox" "st,lsm6dsr" + "st,lsm6ds3tr-c" + "st,ism330dhcx" + "st,lsm9ds1-imu" - reg: i2c address of the sensor / spi cs line Optional properties: diff --git a/Documentation/devicetree/bindings/iio/light/noa1305.yaml b/Documentation/devicetree/bindings/iio/light/noa1305.yaml new file mode 100644 index 000000000000..17e7f140b69b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/noa1305.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/noa1305.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ON Semiconductor NOA1305 Ambient Light Sensor + +maintainers: + - Martyn Welch <martyn.welch@collabora.com> + +description: | + Ambient sensing with an i2c interface. + + https://www.onsemi.com/pub/Collateral/NOA1305-D.PDF + +properties: + compatible: + enum: + - onnn,noa1305 + + reg: + maxItems: 1 + + vin-supply: + description: Regulator that provides power to the sensor + +required: + - compatible + - reg + +examples: + - | + i2c { + + #address-cells = <1>; + #size-cells = <0>; + + light@39 { + compatible = "onnn,noa1305"; + reg = <0x39>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/light/isl29501.txt b/Documentation/devicetree/bindings/iio/light/renesas,isl29501.txt index 46957997fee3..46957997fee3 100644 --- a/Documentation/devicetree/bindings/iio/light/isl29501.txt +++ b/Documentation/devicetree/bindings/iio/light/renesas,isl29501.txt diff --git a/Documentation/devicetree/bindings/iio/light/stk33xx.yaml b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml new file mode 100644 index 000000000000..aae8a6d627c9 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/stk33xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: | + Sensortek STK33xx I2C Ambient Light and Proximity sensor + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +description: | + Ambient light and proximity sensor over an i2c interface. + +properties: + compatible: + enum: + - sensortek,stk3310 + - sensortek,stk3311 + - sensortek,stk3335 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + + #address-cells = <1>; + #size-cells = <0>; + + stk3310@48 { + compatible = "sensortek,stk3310"; + reg = <0x48>; + interrupt-parent = <&gpio1>; + interrupts = <5 IRQ_TYPE_LEVEL_LOW>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt new file mode 100644 index 000000000000..c3344ab509a3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt @@ -0,0 +1,203 @@ +For discussion. Unclear are: +* is the definition of +/- values practical or counterintuitive? +* are the definitions unambiguous and easy to follow? +* are the examples correct? +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)? + +==== + + +Mounting matrix + +The mounting matrix is a device tree property used to orient any device +that produce three-dimensional data in relation to the world where it is +deployed. + +The purpose of the mounting matrix is to translate the sensor frame of +reference into the device frame of reference using a translation matrix as +defined in linear algebra. + +The typical usecase is that where a component has an internal representation +of the (x,y,z) triplets, such as different registers to read these coordinates, +and thus implying that the component should be mounted in a certain orientation +relative to some specific device frame of reference. + +For example a device with some kind of screen, where the user is supposed to +interact with the environment using an accelerometer, gyroscope or magnetometer +mounted on the same chassis as this screen, will likely take the screen as +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the +screen and (z) being depth, the axis perpendicular to the screen. + +For a screen you probably want (x) coordinates to go from negative on the left +to positive on the right, (y) from negative on the bottom to positive on top +and (z) depth to be negative under the screen and positive in front of it, +toward the face of the user. + +A sensor can be mounted in any angle along the axes relative to the frame of +reference. This means that the sensor may be flipped upside-down, left-right, +or tilted at any angle relative to the frame of reference. + +Another frame of reference is how the device with its sensor relates to the +external world, the environment where the device is deployed. Usually the data +from the sensor is used to figure out how the device is oriented with respect +to this world. When using the mounting matrix, the sensor and device orientation +becomes identical and we can focus on the data as it relates to the surrounding +world. + +Device-to-world examples for some three-dimensional sensor types: + +- Accelerometers have their world frame of reference toward the center of + gravity, usually to the core of the planet. A reading of the (x,y,z) values + from the sensor will give a projection of the gravity vector through the + device relative to the center of the planet, i.e. relative to its surface at + this point. Up and down in the world relative to the device frame of + reference can thus be determined. and users would likely expect a value of + 9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device + is held with its screen flat on the planets surface and 0 on the other axes, + as the gravity vector is projected 1:1 onto the sensors (z)-axis. + + If you tilt the device, the g vector virtually coming out of the display + is projected onto the (x,y) plane of the display panel. + + Example: + + ^ z: +g ^ z: > 0 + ! /! + ! x=y=0 / ! x: > 0 + +--------+ +--------+ + ! ! ! ! + +--------+ +--------+ + ! / + ! / + v v + center of center of + gravity gravity + + + If the device is tilted to the left, you get a positive x value. If you point + its top towards surface, you get a negative y axis. + + (---------) + ! ! y: -g + ! ! ^ + ! ! ! + ! ! + ! ! x: +g <- z: +g -> x: -g + ! 1 2 3 ! + ! 4 5 6 ! ! + ! 7 8 9 ! v + ! * 0 # ! y: +g + (---------) + + +- Magnetometers (compasses) have their world frame of reference relative to the + geomagnetic field. The system orientation vis-a-vis the world is defined with + respect to the local earth geomagnetic reference frame where (y) is in the + ground plane and positive towards magnetic North, (x) is in the ground plane, + perpendicular to the North axis and positive towards the East and (z) is + perpendicular to the ground plane and positive upwards. + + + ^^^ North: y > 0 + + (---------) + ! ! + ! ! + ! ! + ! ! > + ! ! > North: x > 0 + ! 1 2 3 ! > + ! 4 5 6 ! + ! 7 8 9 ! + ! * 0 # ! + (---------) + + Since the geomagnetic field is not uniform this definition fails if we come + closer to the poles. + + Sensors and driver can not and should not take care of this because there + are complex calculations and empirical data to be taken care of. We leave + this up to user space. + + The definition we take: + + If the device is placed at the equator and the top is pointing north, the + display is readable by a person standing upright on the earth surface, this + defines a positive y value. + + +- Gyroscopes detects the movement relative the device itself. The angular + velocity is defined as orthogonal to the plane of rotation, so if you put the + device on a flat surface and spin it around the z axis (such as rotating a + device with a screen lying flat on a table), you should get a negative value + along the (z) axis if rotated clockwise, and a positive value if rotated + counter-clockwise according to the right-hand rule. + + + (---------) y > 0 + ! ! v---\ + ! ! + ! ! + ! ! <--\ + ! ! ! z > 0 + ! 1 2 3 ! --/ + ! 4 5 6 ! + ! 7 8 9 ! + ! * 0 # ! + (---------) + + +So unless the sensor is ideally mounted, we need a means to indicate the +relative orientation of any given sensor of this type with respect to the +frame of reference. + +To achieve this, use the device tree property "mount-matrix" for the sensor. + +This supplies a 3x3 rotation matrix in the strict linear algebraic sense, +to orient the senor axes relative to a desired point of reference. This means +the resulting values from the sensor, after scaling to proper units, should be +multiplied by this matrix to give the proper vectors values in three-dimensional +space, relative to the device or world point of reference. + +For more information, consult: +https://en.wikipedia.org/wiki/Rotation_matrix + +The mounting matrix has the layout: + + (mxx, myx, mzx) + (mxy, myy, mzy) + (mxz, myz, mzz) + +Values are intended to be multiplied as: + + x' = mxx * x + myx * y + mzx * z + y' = mxy * x + myy * y + mzy * z + z' = mxz * x + myz * y + mzz * z + +It is represented as an array of strings containing the real values for +producing the transformation matrix. + +Examples: + +Identity matrix (nothing happens to the coordinates, which means the device was +mechanically mounted in an ideal way and we need no transformation): + +mount-matrix = "1", "0", "0", + "0", "1", "0", + "0", "0", "1"; + +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we +compensate by performing a -30 degrees rotation around the X axis: + +mount-matrix = "1", "0", "0", + "0", "0.866", "0.5", + "0", "-0.5", "0.866"; + +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted +upside-down: + +mount-matrix = "0.998", "0.054", "0", + "-0.054", "0.998", "0", + "0", "0", "1"; + +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation diff --git a/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml new file mode 100644 index 000000000000..5082f919df2a --- /dev/null +++ b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/potentiometer/max5432.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX5432-MAX5435 Digital Potentiometers + +maintainers: + - Martin Kaiser <martin@kaiser.cx> + +description: | + Maxim Integrated MAX5432-MAX5435 Digital Potentiometers connected via I2C + + Datasheet: + https://datasheets.maximintegrated.com/en/ds/MAX5432-MAX5435.pdf + +properties: + compatible: + enum: + - maxim,max5432 + - maxim,max5433 + - maxim,max5434 + - maxim,max5435 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + max5434@28 { + compatible = "maxim,max5434"; + reg = <0x28>; + }; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt b/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt new file mode 100644 index 000000000000..c07d89812b73 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt @@ -0,0 +1,45 @@ +Qualcomm QCS404 Network-On-Chip interconnect driver binding +----------------------------------------------------------- + +Required properties : +- compatible : shall contain only one of the following: + "qcom,qcs404-bimc" + "qcom,qcs404-pcnoc" + "qcom,qcs404-snoc" +- #interconnect-cells : should contain 1 + +reg : specifies the physical base address and size of registers +clocks : list of phandles and specifiers to all interconnect bus clocks +clock-names : clock names should include both "bus" and "bus_a" + +Example: + +soc { + ... + bimc: interconnect@400000 { + reg = <0x00400000 0x80000>; + compatible = "qcom,qcs404-bimc"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_BIMC_CLK>, + <&rpmcc RPM_SMD_BIMC_A_CLK>; + }; + + pnoc: interconnect@500000 { + reg = <0x00500000 0x15080>; + compatible = "qcom,qcs404-pcnoc"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_PNOC_CLK>, + <&rpmcc RPM_SMD_PNOC_A_CLK>; + }; + + snoc: interconnect@580000 { + reg = <0x00580000 0x23080>; + compatible = "qcom,qcs404-snoc"; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_SNOC_CLK>, + <&rpmcc RPM_SMD_SNOC_A_CLK>; + }; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt index 7d531d5fff29..684bb1cd75ec 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt @@ -16,6 +16,7 @@ Required properties: "amlogic,meson-gxl-gpio-intc" for GXL SoCs (S905X, S912) "amlogic,meson-axg-gpio-intc" for AXG SoCs (A113D, A113X) "amlogic,meson-g12a-gpio-intc" for G12A SoCs (S905D2, S905X2, S905Y2) + "amlogic,meson-sm1-gpio-intc" for SM1 SoCs (S905D3, S905X3, S905Y3) - reg : Specifies base physical address and size of the registers. - interrupt-controller : Identifies the node as an interrupt controller. - #interrupt-cells : Specifies the number of cells needed to encode an diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml index c34df35a25fc..1fe147daca4c 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml @@ -44,11 +44,13 @@ properties: be at least 4. The 1st cell is the interrupt type; 0 for SPI interrupts, 1 for PPI - interrupts. Other values are reserved for future use. + interrupts, 2 for interrupts in the Extended SPI range, 3 for the + Extended PPI range. Other values are reserved for future use. The 2nd cell contains the interrupt number for the interrupt type. SPI interrupts are in the range [0-987]. PPI interrupts are in the - range [0-15]. + range [0-15]. Extented SPI interrupts are in the range [0-1023]. + Extended PPI interrupts are in the range [0-127]. The 3rd cell is the flags, encoded as follows: bits[3:0] trigger type and level flags. diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt index 0e312fea2a5d..84ced3f4179b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt @@ -15,6 +15,7 @@ Required properties: "mediatek,mt7629-sysirq", "mediatek,mt6577-sysirq": for MT7629 "mediatek,mt6795-sysirq", "mediatek,mt6577-sysirq": for MT6795 "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq": for MT6797 + "mediatek,mt6779-sysirq", "mediatek,mt6577-sysirq": for MT6779 "mediatek,mt6765-sysirq", "mediatek,mt6577-sysirq": for MT6765 "mediatek,mt6755-sysirq", "mediatek,mt6577-sysirq": for MT6755 "mediatek,mt6592-sysirq", "mediatek,mt6577-sysirq": for MT6592 diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt index 09fc02b99845..a5c1db95b3ec 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt @@ -1,20 +1,30 @@ * ARC-HS Interrupt Distribution Unit - This optional 2nd level interrupt controller can be used in SMP configurations for - dynamic IRQ routing, load balancing of common/external IRQs towards core intc. + This optional 2nd level interrupt controller can be used in SMP configurations + for dynamic IRQ routing, load balancing of common/external IRQs towards core + intc. Properties: - compatible: "snps,archs-idu-intc" - interrupt-controller: This is an interrupt controller. -- #interrupt-cells: Must be <1>. - - Value of the cell specifies the "common" IRQ from peripheral to IDU. Number N - of the particular interrupt line of IDU corresponds to the line N+24 of the - core interrupt controller. - - intc accessed via the special ARC AUX register interface, hence "reg" property - is not specified. +- #interrupt-cells: Must be <1> or <2>. + + Value of the first cell specifies the "common" IRQ from peripheral to IDU. + Number N of the particular interrupt line of IDU corresponds to the line N+24 + of the core interrupt controller. + + The (optional) second cell specifies any of the following flags: + - bits[3:0] trigger type and level flags + 1 = low-to-high edge triggered + 2 = NOT SUPPORTED (high-to-low edge triggered) + 4 = active high level-sensitive <<< DEFAULT + 8 = NOT SUPPORTED (active low level-sensitive) + When no second cell is specified, the interrupt is assumed to be level + sensitive. + + The interrupt controller is accessed via the special ARC AUX register + interface, hence "reg" property is not specified. Example: core_intc: core-interrupt-controller { diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt index 6922db598def..ce59a505f5a4 100644 --- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt +++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt @@ -11,10 +11,23 @@ ARM Short-Descriptor translation table format for address translation. | m4u (Multimedia Memory Management Unit) | + +--------+ + | | + gals0-rx gals1-rx (Global Async Local Sync rx) + | | + | | + gals0-tx gals1-tx (Global Async Local Sync tx) + | | Some SoCs may have GALS. + +--------+ + | SMI Common(Smart Multimedia Interface Common) | +----------------+------- | | + | gals-rx There may be GALS in some larbs. + | | + | | + | gals-tx | | SMI larb0 SMI larb1 ... SoCs have several SMI local arbiter(larb). (display) (vdec) @@ -36,6 +49,10 @@ each local arbiter. like display, video decode, and camera. And there are different ports in each larb. Take a example, There are many ports like MC, PP, VLD in the video decode local arbiter, all these ports are according to the video HW. + In some SoCs, there may be a GALS(Global Async Local Sync) module between +smi-common and m4u, and additional GALS module between smi-larb and +smi-common. GALS can been seen as a "asynchronous fifo" which could help +synchronize for the modules in different clock frequency. Required properties: - compatible : must be one of the following string: @@ -44,18 +61,25 @@ Required properties: "mediatek,mt7623-m4u", "mediatek,mt2701-m4u" for mt7623 which uses generation one m4u HW. "mediatek,mt8173-m4u" for mt8173 which uses generation two m4u HW. + "mediatek,mt8183-m4u" for mt8183 which uses generation two m4u HW. - reg : m4u register base and size. - interrupts : the interrupt of m4u. - clocks : must contain one entry for each clock-names. -- clock-names : must be "bclk", It is the block clock of m4u. +- clock-names : Only 1 optional clock: + - "bclk": the block clock of m4u. + Here is the list which require this "bclk": + - mt2701, mt2712, mt7623 and mt8173. + Note that m4u use the EMI clock which always has been enabled before kernel + if there is no this "bclk". - mediatek,larbs : List of phandle to the local arbiters in the current Socs. Refer to bindings/memory-controllers/mediatek,smi-larb.txt. It must sort according to the local arbiter index, like larb0, larb1, larb2... - iommu-cells : must be 1. This is the mtk_m4u_id according to the HW. Specifies the mtk_m4u_id as defined in dt-binding/memory/mt2701-larb-port.h for mt2701, mt7623 - dt-binding/memory/mt2712-larb-port.h for mt2712, and - dt-binding/memory/mt8173-larb-port.h for mt8173. + dt-binding/memory/mt2712-larb-port.h for mt2712, + dt-binding/memory/mt8173-larb-port.h for mt8173, and + dt-binding/memory/mt8183-larb-port.h for mt8183. Example: iommu: iommu@10205000 { diff --git a/Documentation/devicetree/bindings/leds/ams,as3645a.txt b/Documentation/devicetree/bindings/leds/ams,as3645a.txt index fdc40e354a64..4af2987b25e9 100644 --- a/Documentation/devicetree/bindings/leds/ams,as3645a.txt +++ b/Documentation/devicetree/bindings/leds/ams,as3645a.txt @@ -39,7 +39,9 @@ ams,input-max-microamp: Maximum flash controller input current. The Optional properties of the flash child node =========================================== -label : The label of the flash LED. +function : See Documentation/devicetree/bindings/leds/common.txt. +color : See Documentation/devicetree/bindings/leds/common.txt. +label : See Documentation/devicetree/bindings/leds/common.txt (deprecated). Required properties of the indicator child node (1) @@ -52,28 +54,32 @@ led-max-microamp: Maximum indicator current. The allowed values are Optional properties of the indicator child node =============================================== -label : The label of the indicator LED. +function : See Documentation/devicetree/bindings/leds/common.txt. +color : See Documentation/devicetree/bindings/leds/common.txt. +label : See Documentation/devicetree/bindings/leds/common.txt (deprecated). Example ======= +#include <dt-bindings/leds/common.h> + as3645a@30 { - #address-cells: 1 - #size-cells: 0 + #address-cells = <1>; + #size-cells = <0>; reg = <0x30>; compatible = "ams,as3645a"; - flash@0 { + led@0 { reg = <0x0>; flash-timeout-us = <150000>; flash-max-microamp = <320000>; led-max-microamp = <60000>; ams,input-max-microamp = <1750000>; - label = "as3645a:flash"; + function = LED_FUNCTION_FLASH; }; - indicator@1 { + led@1 { reg = <0x1>; led-max-microamp = <10000>; - label = "as3645a:indicator"; + function = LED_FUNCTION_INDICATOR; }; }; diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt index 70876ac11367..9fa6f9795d50 100644 --- a/Documentation/devicetree/bindings/leds/common.txt +++ b/Documentation/devicetree/bindings/leds/common.txt @@ -10,14 +10,30 @@ can influence the way of the LED device initialization, the LED components have to be tightly coupled with the LED device binding. They are represented by child nodes of the parent LED device binding. + Optional properties for child nodes: - led-sources : List of device current outputs the LED is connected to. The outputs are identified by the numbers that must be defined in the LED device binding documentation. + +- function: LED functon. Use one of the LED_FUNCTION_* prefixed definitions + from the header include/dt-bindings/leds/common.h. + If there is no matching LED_FUNCTION available, add a new one. + +- color : Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions + from the header include/dt-bindings/leds/common.h. + If there is no matching LED_COLOR_ID available, add a new one. + +- function-enumerator: Integer to be used when more than one instance + of the same function is needed, differing only with + an ordinal number. + - label : The label for this LED. If omitted, the label is taken from the node name (excluding the unit address). It has to uniquely identify a device, i.e. no other LED class device can be assigned the same - label. + label. This property is deprecated - use 'function' and 'color' + properties instead. function-enumerator has no effect when this + property is present. - default-state : The initial state of the LED. Valid values are "on", "off", and "keep". If the LED is already on or off and the default-state property is @@ -99,29 +115,59 @@ Required properties for trigger source: * Examples -gpio-leds { +#include <dt-bindings/leds/common.h> + +led-controller@0 { compatible = "gpio-leds"; - system-status { - label = "Status"; + led0 { + function = LED_FUNCTION_STATUS; linux,default-trigger = "heartbeat"; gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>; }; - usb { + led1 { + function = LED_FUNCTION_USB; gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>; trigger-sources = <&ohci_port1>, <&ehci_port1>; }; }; -max77693-led { +led-controller@0 { compatible = "maxim,max77693-led"; - camera-flash { - label = "Flash"; + led { + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; led-sources = <0>, <1>; led-max-microamp = <50000>; flash-max-microamp = <320000>; flash-max-timeout-us = <500000>; }; }; + +led-controller@30 { + compatible = "panasonic,an30259a"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + led@1 { + reg = <1>; + linux,default-trigger = "heartbeat"; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <1>; + }; + + led@2 { + reg = <2>; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <2>; + }; + + led@3 { + reg = <3>; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <3>; + }; +}; diff --git a/Documentation/devicetree/bindings/leds/leds-aat1290.txt b/Documentation/devicetree/bindings/leds/leds-aat1290.txt index 85c0c58617f6..62ed17ec075b 100644 --- a/Documentation/devicetree/bindings/leds/leds-aat1290.txt +++ b/Documentation/devicetree/bindings/leds/leds-aat1290.txt @@ -32,15 +32,18 @@ Required properties of the LED child node: formula: T = 8.82 * 10^9 * Ct. Optional properties of the LED child node: -- label : see Documentation/devicetree/bindings/leds/common.txt +- function : see Documentation/devicetree/bindings/leds/common.txt +- color : see Documentation/devicetree/bindings/leds/common.txt +- label : see Documentation/devicetree/bindings/leds/common.txt (deprecated) Example (by Ct = 220nF, Rset = 160kohm and exynos4412-trats2 board with a switch that allows for routing strobe signal either from the host or from the camera sensor): #include "exynos4412.dtsi" +#include <dt-bindings/leds/common.h> -aat1290 { +led-controller { compatible = "skyworks,aat1290"; flen-gpios = <&gpj1 1 GPIO_ACTIVE_HIGH>; enset-gpios = <&gpj1 2 GPIO_ACTIVE_HIGH>; @@ -50,8 +53,9 @@ aat1290 { pinctrl-1 = <&camera_flash_host>; pinctrl-2 = <&camera_flash_isp>; - camera_flash: flash-led { - label = "aat1290-flash"; + camera_flash: led { + function = LED_FUNCTION_FLASH; + color = <LED_COLOR_ID_WHITE>; led-max-microamp = <520833>; flash-max-microamp = <1012500>; flash-max-timeout-us = <1940000>; diff --git a/Documentation/devicetree/bindings/leds/leds-an30259a.txt b/Documentation/devicetree/bindings/leds/leds-an30259a.txt index 6ffb861083c0..cbd833906b2b 100644 --- a/Documentation/devicetree/bindings/leds/leds-an30259a.txt +++ b/Documentation/devicetree/bindings/leds/leds-an30259a.txt @@ -15,10 +15,19 @@ Required sub-node properties: - reg: Pin that the LED is connected to. Must be 1, 2, or 3. Optional sub-node properties: - - label: see Documentation/devicetree/bindings/leds/common.txt - - linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt + - function : + see Documentation/devicetree/bindings/leds/common.txt + - color : + see Documentation/devicetree/bindings/leds/common.txt + - label : + see Documentation/devicetree/bindings/leds/common.txt (deprecated) + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt Example: + +#include <dt-bindings/leds/common.h> + led-controller@30 { compatible = "panasonic,an30259a"; reg = <0x30>; @@ -28,16 +37,19 @@ led-controller@30 { led@1 { reg = <1>; linux,default-trigger = "heartbeat"; - label = "red:indicator"; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_RED>; }; led@2 { reg = <2>; - label = "green:indicator"; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_GREEN>; }; led@3 { reg = <3>; - label = "blue:indicator"; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_BLUE>; }; }; diff --git a/Documentation/devicetree/bindings/leds/leds-cr0014114.txt b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt index 4255b19ad25c..f8de7516a39b 100644 --- a/Documentation/devicetree/bindings/leds/leds-cr0014114.txt +++ b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt @@ -11,14 +11,20 @@ Property rules described in Documentation/devicetree/bindings/spi/spi-bus.txt apply. In particular, "reg" and "spi-max-frequency" properties must be given. LED sub-node properties: -- label : +- function : + see Documentation/devicetree/bindings/leds/common.txt +- color : see Documentation/devicetree/bindings/leds/common.txt +- label : + see Documentation/devicetree/bindings/leds/common.txt (deprecated) - linux,default-trigger : (optional) see Documentation/devicetree/bindings/leds/common.txt Example ------- +#include <dt-bindings/leds/common.h> + led-controller@0 { compatible = "crane,cr0014114"; reg = <0>; @@ -28,27 +34,33 @@ led-controller@0 { led@0 { reg = <0>; - label = "red:coin"; + function = "coin"; + color = <LED_COLOR_ID_RED>; }; led@1 { reg = <1>; - label = "green:coin"; + function = "coin"; + color = <LED_COLOR_ID_GREEN>; }; led@2 { reg = <2>; - label = "blue:coin"; + function = "coin"; + color = <LED_COLOR_ID_BLUE>; }; led@3 { reg = <3>; - label = "red:bill"; + function = "bill"; + color = <LED_COLOR_ID_RED>; }; led@4 { reg = <4>; - label = "green:bill"; + function = "bill"; + color = <LED_COLOR_ID_GREEN>; }; led@5 { reg = <5>; - label = "blue:bill"; + function = "bill"; + color = <LED_COLOR_ID_BLUE>; }; ... }; diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.txt b/Documentation/devicetree/bindings/leds/leds-gpio.txt index a48dda268f81..d21281b63d38 100644 --- a/Documentation/devicetree/bindings/leds/leds-gpio.txt +++ b/Documentation/devicetree/bindings/leds/leds-gpio.txt @@ -10,8 +10,12 @@ LED sub-node properties: - gpios : Should specify the LED's GPIO, see "gpios property" in Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs should be indicated using flags in the GPIO specifier. -- label : (optional) +- function : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- color : (optional) see Documentation/devicetree/bindings/leds/common.txt +- label : (optional) + see Documentation/devicetree/bindings/leds/common.txt (deprecated) - linux,default-trigger : (optional) see Documentation/devicetree/bindings/leds/common.txt - default-state: (optional) The initial state of the LED. @@ -27,30 +31,34 @@ LED sub-node properties: Examples: #include <dt-bindings/gpio/gpio.h> +#include <dt-bindings/leds/common.h> leds { compatible = "gpio-leds"; - hdd { - label = "Disk Activity"; + led0 { gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>; linux,default-trigger = "disk-activity"; + function = LED_FUNCTION_DISK; }; - fault { + led1 { gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>; /* Keep LED on if BIOS detected hardware fault */ default-state = "keep"; + function = LED_FUNCTION_FAULT; }; }; run-control { compatible = "gpio-leds"; - red { + led0 { gpios = <&mpc8572 6 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_RED>; default-state = "off"; }; - green { + led1 { gpios = <&mpc8572 7 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_GREEN>; default-state = "on"; }; }; @@ -58,9 +66,10 @@ run-control { leds { compatible = "gpio-leds"; - charger-led { + led0 { gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; linux,default-trigger = "max8903-charger-charging"; retain-state-suspended; + function = LED_FUNCTION_CHARGE; }; }; diff --git a/Documentation/devicetree/bindings/leds/leds-lm3532.txt b/Documentation/devicetree/bindings/leds/leds-lm3532.txt index c087f85ddddc..53793213dd52 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3532.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt @@ -62,6 +62,9 @@ Optional LED child properties: - label : see Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : see Documentation/devicetree/bindings/leds/common.txt + - led-max-microamp : Defines the full scale current value for each control + bank. The range is from 5000uA-29800uA in increments + of 800uA. Example: led-controller@38 { @@ -85,6 +88,7 @@ led-controller@38 { reg = <0>; led-sources = <2>; ti,led-mode = <1>; + led-max-microamp = <21800>; label = ":backlight"; linux,default-trigger = "backlight"; }; diff --git a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt index a88b2c41e75b..095dafb6ec7f 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt @@ -22,9 +22,14 @@ Required properties for flash LED child nodes: - led-max-microamp : Range from 2.4mA - 376mA Optional child properties: - - label : see Documentation/devicetree/bindings/leds/common.txt + - function : see Documentation/devicetree/bindings/leds/common.txt + - color : see Documentation/devicetree/bindings/leds/common.txt + - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated) Example: + +#include <dt-bindings/leds/common.h> + led-controller@64 { compatible = "ti,lm36010"; #address-cells = <1>; @@ -33,7 +38,8 @@ led-controller@64 { led@0 { reg = <1>; - label = "white:torch"; + function = LED_FUNCTION_TORCH; + color = <LED_COLOR_ID_WHITE>; led-max-microamp = <376000>; flash-max-microamp = <1500000>; flash-max-timeout-us = <1600000>; diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt index 08b352840bd7..4c2d923f8758 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -26,12 +26,16 @@ Required child properties: 3 - Will enable the LED3 sync (LM36923 only) Optional child properties: - - label : see Documentation/devicetree/bindings/leds/common.txt + - function : see Documentation/devicetree/bindings/leds/common.txt + - color : see Documentation/devicetree/bindings/leds/common.txt + - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated) - linux,default-trigger : see Documentation/devicetree/bindings/leds/common.txt Example: +#include <dt-bindings/leds/common.h> + led-controller@36 { compatible = "ti,lm3692x"; reg = <0x36>; @@ -43,7 +47,8 @@ led-controller@36 { led@0 { reg = <0>; - label = "white:backlight_cluster"; + function = LED_FUNCTION_BACKLIGHT; + color = <LED_COLOR_ID_WHITE>; linux,default-trigger = "backlight"; }; } diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index 5f0e892ad759..9863220db4ba 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -20,12 +20,16 @@ Required child properties: - reg : 0 Optional child properties: - - label : see Documentation/devicetree/bindings/leds/common.txt + - function : see Documentation/devicetree/bindings/leds/common.txt + - color : see Documentation/devicetree/bindings/leds/common.txt + - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated) - linux,default-trigger : see Documentation/devicetree/bindings/leds/common.txt Example: +#include <dt-bindings/leds/common.h> + led-controller@2d { compatible = "ti,lp8860"; #address-cells = <1>; @@ -36,7 +40,8 @@ led-controller@2d { led@0 { reg = <0>; - label = "white:backlight"; + function = LED_FUNCTION_BACKLIGHT; + color = <LED_COLOR_ID_WHITE>; linux,default-trigger = "backlight"; }; } diff --git a/Documentation/devicetree/bindings/leds/leds-lt3593.txt b/Documentation/devicetree/bindings/leds/leds-lt3593.txt index 6b2cabc36c0c..24eccdaa6322 100644 --- a/Documentation/devicetree/bindings/leds/leds-lt3593.txt +++ b/Documentation/devicetree/bindings/leds/leds-lt3593.txt @@ -9,8 +9,10 @@ The hardware supports only one LED. The properties of this LED are configured in a sub-node in the device node. Optional sub-node properties: -- label: A label for the LED. If none is given, the LED will be - named "lt3595::". +- function: See Documentation/devicetree/bindings/leds/common.txt +- color: See Documentation/devicetree/bindings/leds/common.txt +- label: A label for the LED. If none is given, the LED will be + named "lt3595::" (deprecated) - linux,default-trigger: The default trigger for the LED. See Documentation/devicetree/bindings/leds/common.txt - default-state: The initial state of the LED. @@ -21,12 +23,15 @@ be handled by its own device node. Example: +#include <dt-bindings/leds/common.h> + led-controller { compatible = "lltc,lt3593"; lltc,ctrl-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; led { - label = "white:backlight"; + function = LED_FUNCTION_BACKLIGHT; + color = <LED_COLOR_ID_WHITE>; default-state = "on"; }; }; diff --git a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt index dddf84f9c7ea..df2b4e1c492b 100644 --- a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt +++ b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt @@ -14,7 +14,9 @@ Required child properties: - reg: Port this LED is connected to. Optional child properties: -- label: See Documentation/devicetree/bindings/leds/common.txt. +- function: See Documentation/devicetree/bindings/leds/common.txt. +- color: See Documentation/devicetree/bindings/leds/common.txt. +- label: See Documentation/devicetree/bindings/leds/common.txt (deprecated). Examples: @@ -25,17 +27,17 @@ led-controller@200 { reg = <0x200>; led@0 { - label = "red"; + color = <LED_COLOR_ID_RED>; reg = <0x0>; }; led@1 { - label = "green"; + color = <LED_COLOR_ID_GREEN>; reg = <0x1>; }; led@2 { - label = "blue"; + color = <LED_COLOR_ID_BLUE>; reg = <0x2>; }; }; diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml new file mode 100644 index 000000000000..27f38eed389e --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/allwinner,sun4i-a10-csi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 CMOS Sensor Interface (CSI) Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +description: |- + The Allwinner A10 and later has a CMOS Sensor Interface to retrieve + frames from a parallel or BT656 sensor. + +properties: + compatible: + const: allwinner,sun7i-a20-csi0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: The CSI interface clock + - description: The CSI module clock + - description: The CSI ISP clock + - description: The CSI DRAM clock + + clock-names: + items: + - const: bus + - const: mod + - const: isp + - const: ram + + resets: + maxItems: 1 + + # See ./video-interfaces.txt for details + port: + type: object + additionalProperties: false + + properties: + endpoint: + type: object + + properties: + bus-width: + enum: [8, 16] + + data-active: true + hsync-active: true + pclk-sample: true + remote-endpoint: true + vsync-active: true + + required: + - bus-width + - data-active + - hsync-active + - pclk-sample + - remote-endpoint + - vsync-active + + required: + - endpoint + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun7i-a20-ccu.h> + #include <dt-bindings/reset/sun4i-a10-ccu.h> + + csi0: csi@1c09000 { + compatible = "allwinner,sun7i-a20-csi0"; + reg = <0x01c09000 0x1000>; + interrupts = <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_AHB_CSI0>, <&ccu CLK_CSI0>, + <&ccu CLK_CSI_SCLK>, <&ccu CLK_DRAM_CSI0>; + clock-names = "bus", "mod", "isp", "ram"; + resets = <&ccu RST_CSI0>; + + port { + csi_from_ov5640: endpoint { + remote-endpoint = <&ov5640_to_csi>; + bus-width = <8>; + hsync-active = <1>; /* Active high */ + vsync-active = <0>; /* Active low */ + data-active = <1>; /* Active high */ + pclk-sample = <1>; /* Rising */ + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml new file mode 100644 index 000000000000..98c1bdde9a86 --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/allwinner,sun4i-a10-ir.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Infrared Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +allOf: + - $ref: "rc.yaml#" + +properties: + compatible: + oneOf: + - const: allwinner,sun4i-a10-ir + - const: allwinner,sun5i-a13-ir + - items: + - const: allwinner,sun8i-a83t-ir + - const: allwinner,sun6i-a31-ir + - const: allwinner,sun6i-a31-ir + - items: + - const: allwinner,sun50i-a64-ir + - const: allwinner,sun6i-a31-ir + - items: + - const: allwinner,sun50i-h6-ir + - const: allwinner,sun6i-a31-ir + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: apb + - const: ir + + resets: + maxItems: 1 + + clock-frequency: + default: 8000000 + description: + IR Receiver clock frequency, in Hertz. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +# FIXME: We should set it, but it would report all the generic +# properties as additional properties. +# additionalProperties: false + +examples: + - | + ir0: ir@1c21800 { + compatible = "allwinner,sun4i-a10-ir"; + clocks = <&apb0_gates 6>, <&ir0_clk>; + clock-names = "apb", "ir"; + clock-frequency = <3000000>; + resets = <&apb0_rst 1>; + interrupts = <0 5 1>; + reg = <0x01C21800 0x40>; + linux,rc-map-name = "rc-rc6-mce"; + }; + +... diff --git a/Documentation/devicetree/bindings/media/amlogic,vdec.txt b/Documentation/devicetree/bindings/media/amlogic,vdec.txt index aabdd01bcf32..9b6aace86ca7 100644 --- a/Documentation/devicetree/bindings/media/amlogic,vdec.txt +++ b/Documentation/devicetree/bindings/media/amlogic,vdec.txt @@ -26,6 +26,7 @@ Required properties: - GXBB (S905) : "amlogic,gxbb-vdec" - GXL (S905X, S905D) : "amlogic,gxl-vdec" - GXM (S912) : "amlogic,gxm-vdec" + followed by the common "amlogic,gx-vdec" - reg: base address and size of he following memory-mapped regions : - dos - esparser @@ -47,8 +48,8 @@ Required properties: Example: -vdec: video-decoder@c8820000 { - compatible = "amlogic,gxbb-vdec"; +vdec: video-codec@c8820000 { + compatible = "amlogic,gxbb-vdec", "amlogic,gx-vdec"; reg = <0x0 0xc8820000 0x0 0x10000>, <0x0 0xc110a580 0x0 0xe4>; reg-names = "dos", "esparser"; diff --git a/Documentation/devicetree/bindings/media/cdns,csi2tx.txt b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt index 459c6e332f52..751b9edf1247 100644 --- a/Documentation/devicetree/bindings/media/cdns,csi2tx.txt +++ b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt @@ -5,7 +5,8 @@ The Cadence MIPI-CSI2 TX controller is a CSI-2 bridge supporting up to 4 CSI lanes in output, and up to 4 different pixel streams in input. Required properties: - - compatible: must be set to "cdns,csi2tx" + - compatible: must be set to "cdns,csi2tx" or "cdns,csi2tx-1.3" + for version 1.3 of the controller, "cdns,csi2tx-2.1" for v2.1 - reg: base address and size of the memory mapped region - clocks: phandles to the clocks driving the controller - clock-names: must contain: diff --git a/Documentation/devicetree/bindings/media/imx7-csi.txt b/Documentation/devicetree/bindings/media/imx7-csi.txt index 443aef07356e..d80ceefa0c00 100644 --- a/Documentation/devicetree/bindings/media/imx7-csi.txt +++ b/Documentation/devicetree/bindings/media/imx7-csi.txt @@ -9,7 +9,7 @@ to connect directly to external CMOS image sensors. Required properties: -- compatible : "fsl,imx7-csi"; +- compatible : "fsl,imx7-csi" or "fsl,imx6ul-csi"; - reg : base address and length of the register set for the device; - interrupts : should contain CSI interrupt; - clocks : list of clock specifiers, see diff --git a/Documentation/devicetree/bindings/media/meson-ao-cec.txt b/Documentation/devicetree/bindings/media/meson-ao-cec.txt index c67fc41d4aa2..ad92ee41c0dd 100644 --- a/Documentation/devicetree/bindings/media/meson-ao-cec.txt +++ b/Documentation/devicetree/bindings/media/meson-ao-cec.txt @@ -5,10 +5,12 @@ to handle communication between HDMI connected devices over the CEC bus. Required properties: - compatible : value should be following depending on the SoC : - For GXBB, GXL, GXM and G12A (AO_CEC_A module) : + For GXBB, GXL, GXM, G12A and SM1 (AO_CEC_A module) : "amlogic,meson-gx-ao-cec" For G12A (AO_CEC_B module) : "amlogic,meson-g12a-ao-cec" + For SM1 (AO_CEC_B module) : + "amlogic,meson-sm1-ao-cec" - reg : Physical base address of the IP registers and length of memory mapped region. @@ -16,9 +18,9 @@ Required properties: - interrupts : AO-CEC interrupt number to the CPU. - clocks : from common clock binding: handle to AO-CEC clock. - clock-names : from common clock binding, must contain : - For GXBB, GXL, GXM and G12A (AO_CEC_A module) : + For GXBB, GXL, GXM, G12A and SM1 (AO_CEC_A module) : - "core" - For G12A (AO_CEC_B module) : + For G12A, SM1 (AO_CEC_B module) : - "oscin" corresponding to entry in the clocks property. - hdmi-phandle: phandle to the HDMI controller diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt index 7302e949e662..602169b8aa19 100644 --- a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt +++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt @@ -35,6 +35,7 @@ Optional properties: - resets : Must contain an entry for each entry in reset-names. - reset-names : Must include the following entries: - mc +- iommus: Must contain phandle to the IOMMU device node. Example: @@ -59,4 +60,5 @@ video-codec@6001a000 { clocks = <&tegra_car TEGRA20_CLK_VDE>; reset-names = "vde", "mc"; resets = <&tegra_car 61>, <&mc TEGRA20_MC_RESET_VDE>; + iommus = <&mc TEGRA_SWGROUP_VDE>; }; diff --git a/Documentation/devicetree/bindings/media/rc.txt b/Documentation/devicetree/bindings/media/rc.txt index d3e7a012bfda..be629f7fa77e 100644 --- a/Documentation/devicetree/bindings/media/rc.txt +++ b/Documentation/devicetree/bindings/media/rc.txt @@ -1,117 +1 @@ -The following properties are common to the infrared remote controllers: - -- linux,rc-map-name: string, specifies the scancode/key mapping table - defined in-kernel for the remote controller. Support values are: - * "rc-adstech-dvb-t-pci" - * "rc-alink-dtu-m" - * "rc-anysee" - * "rc-apac-viewcomp" - * "rc-asus-pc39" - * "rc-asus-ps3-100" - * "rc-ati-tv-wonder-hd-600" - * "rc-ati-x10" - * "rc-avermedia-a16d" - * "rc-avermedia-cardbus" - * "rc-avermedia-dvbt" - * "rc-avermedia-m135a" - * "rc-avermedia-m733a-rm-k6" - * "rc-avermedia-rm-ks" - * "rc-avermedia" - * "rc-avertv-303" - * "rc-azurewave-ad-tu700" - * "rc-behold-columbus" - * "rc-behold" - * "rc-budget-ci-old" - * "rc-cec" - * "rc-cinergy-1400" - * "rc-cinergy" - * "rc-delock-61959" - * "rc-dib0700-nec" - * "rc-dib0700-rc5" - * "rc-digitalnow-tinytwin" - * "rc-digittrade" - * "rc-dm1105-nec" - * "rc-dntv-live-dvbt-pro" - * "rc-dntv-live-dvb-t" - * "rc-dtt200u" - * "rc-dvbsky" - * "rc-empty" - * "rc-em-terratec" - * "rc-encore-enltv2" - * "rc-encore-enltv-fm53" - * "rc-encore-enltv" - * "rc-evga-indtube" - * "rc-eztv" - * "rc-flydvb" - * "rc-flyvideo" - * "rc-fusionhdtv-mce" - * "rc-gadmei-rm008z" - * "rc-geekbox" - * "rc-genius-tvgo-a11mce" - * "rc-gotview7135" - * "rc-hauppauge" - * "rc-imon-mce" - * "rc-imon-pad" - * "rc-iodata-bctv7e" - * "rc-it913x-v1" - * "rc-it913x-v2" - * "rc-kaiomy" - * "rc-kworld-315u" - * "rc-kworld-pc150u" - * "rc-kworld-plus-tv-analog" - * "rc-leadtek-y04g0051" - * "rc-lirc" - * "rc-lme2510" - * "rc-manli" - * "rc-medion-x10" - * "rc-medion-x10-digitainer" - * "rc-medion-x10-or2x" - * "rc-msi-digivox-ii" - * "rc-msi-digivox-iii" - * "rc-msi-tvanywhere-plus" - * "rc-msi-tvanywhere" - * "rc-nebula" - * "rc-nec-terratec-cinergy-xs" - * "rc-norwood" - * "rc-npgtech" - * "rc-pctv-sedna" - * "rc-pinnacle-color" - * "rc-pinnacle-grey" - * "rc-pinnacle-pctv-hd" - * "rc-pixelview-new" - * "rc-pixelview" - * "rc-pixelview-002t" - * "rc-pixelview-mk12" - * "rc-powercolor-real-angel" - * "rc-proteus-2309" - * "rc-purpletv" - * "rc-pv951" - * "rc-hauppauge" - * "rc-rc5-tv" - * "rc-rc6-mce" - * "rc-real-audio-220-32-keys" - * "rc-reddo" - * "rc-snapstream-firefly" - * "rc-streamzap" - * "rc-tbs-nec" - * "rc-technisat-ts35" - * "rc-technisat-usb2" - * "rc-terratec-cinergy-c-pci" - * "rc-terratec-cinergy-s2-hd" - * "rc-terratec-cinergy-xs" - * "rc-terratec-slim" - * "rc-terratec-slim-2" - * "rc-tevii-nec" - * "rc-tivo" - * "rc-total-media-in-hand" - * "rc-total-media-in-hand-02" - * "rc-trekstor" - * "rc-tt-1500" - * "rc-twinhan-dtv-cab-ci" - * "rc-twinhan1027" - * "rc-videomate-k100" - * "rc-videomate-s350" - * "rc-videomate-tv-pvr" - * "rc-winfast" - * "rc-winfast-usbii-deluxe" - * "rc-su3000" +This file has been moved to rc.yaml. diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml new file mode 100644 index 000000000000..3d5c154fd230 --- /dev/null +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/rc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Infrared Remote Controller Device Tree Bindings + +maintainers: + - Mauro Carvalho Chehab <mchehab@kernel.org> + - Sean Young <sean@mess.org> + +properties: + $nodename: + pattern: "^ir(@[a-f0-9]+)?$" + + linux,rc-map-name: + description: + Specifies the scancode/key mapping table defined in-kernel for + the remote controller. + allOf: + - $ref: '/schemas/types.yaml#/definitions/string' + - enum: + - rc-adstech-dvb-t-pci + - rc-alink-dtu-m + - rc-anysee + - rc-apac-viewcomp + - rc-astrometa-t2hybrid + - rc-asus-pc39 + - rc-asus-ps3-100 + - rc-ati-tv-wonder-hd-600 + - rc-ati-x10 + - rc-avermedia + - rc-avermedia-a16d + - rc-avermedia-cardbus + - rc-avermedia-dvbt + - rc-avermedia-m135a + - rc-avermedia-m733a-rm-k6 + - rc-avermedia-rm-ks + - rc-avertv-303 + - rc-azurewave-ad-tu700 + - rc-behold + - rc-behold-columbus + - rc-budget-ci-old + - rc-cec + - rc-cinergy + - rc-cinergy-1400 + - rc-d680-dmb + - rc-delock-61959 + - rc-dib0700-nec + - rc-dib0700-rc5 + - rc-digitalnow-tinytwin + - rc-digittrade + - rc-dm1105-nec + - rc-dntv-live-dvb-t + - rc-dntv-live-dvbt-pro + - rc-dtt200u + - rc-dvbsky + - rc-dvico-mce + - rc-dvico-portable + - rc-em-terratec + - rc-empty + - rc-encore-enltv + - rc-encore-enltv-fm53 + - rc-encore-enltv2 + - rc-evga-indtube + - rc-eztv + - rc-flydvb + - rc-flyvideo + - rc-fusionhdtv-mce + - rc-gadmei-rm008z + - rc-geekbox + - rc-genius-tvgo-a11mce + - rc-gotview7135 + - rc-hauppauge + - rc-hauppauge + - rc-hisi-poplar + - rc-hisi-tv-demo + - rc-imon-mce + - rc-imon-pad + - rc-imon-rsc + - rc-iodata-bctv7e + - rc-it913x-v1 + - rc-it913x-v2 + - rc-kaiomy + - rc-kworld-315u + - rc-kworld-pc150u + - rc-kworld-plus-tv-analog + - rc-leadtek-y04g0051 + - rc-lme2510 + - rc-manli + - rc-medion-x10 + - rc-medion-x10-digitainer + - rc-medion-x10-or2x + - rc-msi-digivox-ii + - rc-msi-digivox-iii + - rc-msi-tvanywhere + - rc-msi-tvanywhere-plus + - rc-nebula + - rc-nec-terratec-cinergy-xs + - rc-norwood + - rc-npgtech + - rc-pctv-sedna + - rc-pinnacle-color + - rc-pinnacle-grey + - rc-pinnacle-pctv-hd + - rc-pixelview + - rc-pixelview-002t + - rc-pixelview-mk12 + - rc-pixelview-new + - rc-powercolor-real-angel + - rc-proteus-2309 + - rc-purpletv + - rc-pv951 + - rc-rc5-tv + - rc-rc6-mce + - rc-real-audio-220-32-keys + - rc-reddo + - rc-snapstream-firefly + - rc-streamzap + - rc-su3000 + - rc-tango + - rc-tbs-nec + - rc-technisat-ts35 + - rc-technisat-usb2 + - rc-terratec-cinergy-c-pci + - rc-terratec-cinergy-s2-hd + - rc-terratec-cinergy-xs + - rc-terratec-slim + - rc-terratec-slim-2 + - rc-tevii-nec + - rc-tivo + - rc-total-media-in-hand + - rc-total-media-in-hand-02 + - rc-trekstor + - rc-tt-1500 + - rc-twinhan-dtv-cab-ci + - rc-twinhan1027 + - rc-videomate-k100 + - rc-videomate-s350 + - rc-videomate-tv-pvr + - rc-winfast + - rc-winfast-usbii-deluxe + - rc-xbox-dvd + - rc-zx-irdec diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,csi2.txt index 331409259752..331409259752 100644 --- a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt +++ b/Documentation/devicetree/bindings/media/renesas,csi2.txt diff --git a/Documentation/devicetree/bindings/media/rcar_imr.txt b/Documentation/devicetree/bindings/media/renesas,imr.txt index b0614153ed36..b0614153ed36 100644 --- a/Documentation/devicetree/bindings/media/rcar_imr.txt +++ b/Documentation/devicetree/bindings/media/renesas,imr.txt diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/renesas,vin.txt index aa217b096279..aa217b096279 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/renesas,vin.txt diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.txt b/Documentation/devicetree/bindings/media/rockchip-vpu.txt index 35dc464ad7c8..339252d9c515 100644 --- a/Documentation/devicetree/bindings/media/rockchip-vpu.txt +++ b/Documentation/devicetree/bindings/media/rockchip-vpu.txt @@ -1,14 +1,17 @@ device-tree bindings for rockchip VPU codec Rockchip (Video Processing Unit) present in various Rockchip platforms, -such as RK3288 and RK3399. +such as RK3288, RK3328 and RK3399. Required properties: - compatible: value should be one of the following "rockchip,rk3288-vpu"; + "rockchip,rk3328-vpu"; "rockchip,rk3399-vpu"; - interrupts: encoding and decoding interrupt specifiers -- interrupt-names: should be "vepu" and "vdpu" +- interrupt-names: should be + "vepu", "vdpu" on RK3288 and RK3399, + "vdpu" on RK3328. - clocks: phandle to VPU aclk, hclk clocks - clock-names: should be "aclk" and "hclk" - power-domains: phandle to power domain node @@ -27,3 +30,14 @@ SoC-specific DT entry: power-domains = <&power RK3288_PD_VIDEO>; iommus = <&vpu_mmu>; }; + + vpu: video-codec@ff350000 { + compatible = "rockchip,rk3328-vpu"; + reg = <0x0 0xff350000 0x0 0x800>; + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "vdpu"; + clocks = <&cru ACLK_VPU>, <&cru HCLK_VPU>; + clock-names = "aclk", "hclk"; + power-domains = <&power RK3328_PD_VPU>; + iommus = <&vpu_mmu>; + }; diff --git a/Documentation/devicetree/bindings/media/sunxi-ir.txt b/Documentation/devicetree/bindings/media/sunxi-ir.txt deleted file mode 100644 index 278098987edb..000000000000 --- a/Documentation/devicetree/bindings/media/sunxi-ir.txt +++ /dev/null @@ -1,28 +0,0 @@ -Device-Tree bindings for SUNXI IR controller found in sunXi SoC family - -Required properties: -- compatible : "allwinner,sun4i-a10-ir" or "allwinner,sun5i-a13-ir" -- clocks : list of clock specifiers, corresponding to - entries in clock-names property; -- clock-names : should contain "apb" and "ir" entries; -- interrupts : should contain IR IRQ number; -- reg : should contain IO map address for IR. - -Optional properties: -- linux,rc-map-name: see rc.txt file in the same directory. -- resets : phandle + reset specifier pair -- clock-frequency : IR Receiver clock frequency, in Hertz. Defaults to 8 MHz - if missing. - -Example: - -ir0: ir@1c21800 { - compatible = "allwinner,sun4i-a10-ir"; - clocks = <&apb0_gates 6>, <&ir0_clk>; - clock-names = "apb", "ir"; - clock-frequency = <3000000>; - resets = <&apb0_rst 1>; - interrupts = <0 5 1>; - reg = <0x01C21800 0x40>; - linux,rc-map-name = "rc-rc6-mce"; -}; diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt index e937ddd871a6..b478ade4da65 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt @@ -2,9 +2,10 @@ SMI (Smart Multimedia Interface) Common The hardware block diagram please check bindings/iommu/mediatek,iommu.txt -Mediatek SMI have two generations of HW architecture, mt2712 and mt8173 use -the second generation of SMI HW while mt2701 uses the first generation HW of -SMI. +Mediatek SMI have two generations of HW architecture, here is the list +which generation the SoCs use: +generation 1: mt2701 and mt7623. +generation 2: mt2712, mt8173 and mt8183. There's slight differences between the two SMI, for generation 2, the register which control the iommu port is at each larb's register base. But @@ -19,6 +20,7 @@ Required properties: "mediatek,mt2712-smi-common" "mediatek,mt7623-smi-common", "mediatek,mt2701-smi-common" "mediatek,mt8173-smi-common" + "mediatek,mt8183-smi-common" - reg : the register and size of the SMI block. - power-domains : a phandle to the power domain of this local arbiter. - clocks : Must contain an entry for each entry in clock-names. @@ -30,6 +32,10 @@ Required properties: They may be the same if both source clocks are the same. - "async" : asynchronous clock, it help transform the smi clock into the emi clock domain, this clock is only needed by generation 1 smi HW. + and these 2 option clocks for generation 2 smi HW: + - "gals0": the path0 clock of GALS(Global Async Local Sync). + - "gals1": the path1 clock of GALS(Global Async Local Sync). + Here is the list which has this GALS: mt8183. Example: smi_common: smi@14022000 { diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt index 94eddcae77ab..4b369b3e1a69 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt @@ -8,6 +8,7 @@ Required properties: "mediatek,mt2712-smi-larb" "mediatek,mt7623-smi-larb", "mediatek,mt2701-smi-larb" "mediatek,mt8173-smi-larb" + "mediatek,mt8183-smi-larb" - reg : the register and size of this local arbiter. - mediatek,smi : a phandle to the smi_common node. - power-domains : a phandle to the power domain of this local arbiter. @@ -16,6 +17,9 @@ Required properties: - "apb" : Advanced Peripheral Bus clock, It's the clock for setting the register. - "smi" : It's the clock for transfer data and command. + and this optional clock name: + - "gals": the clock for GALS(Global Async Local Sync). + Here is the list which has this GALS: mt8183. Required property for mt2701, mt2712 and mt7623: - mediatek,larb-id :the hardware id of this larb. diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt b/Documentation/devicetree/bindings/memory-controllers/renesas,dbsc.txt index 9f78e6c82740..9f78e6c82740 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,dbsc.txt diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml new file mode 100644 index 000000000000..4b1a09acb98b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/allwinner,sun4i-a10-ts.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Resistive Touchscreen Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#thermal-sensor-cells": + const: 0 + + compatible: + enum: + - allwinner,sun4i-a10-ts + - allwinner,sun5i-a13-ts + - allwinner,sun6i-a31-ts + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + allwinner,ts-attached: + $ref: /schemas/types.yaml#/definitions/flag + description: A touchscreen is attached to the controller + + allwinner,tp-sensitive-adjust: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - minimum: 0 + maximum: 15 + default: 15 + description: Sensitivity of pen down detection + + allwinner,filter-type: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - minimum: 0 + maximum: 3 + default: 1 + description: | + Select median and averaging filter. Sample used for median / + averaging filter: + 0: 4/2 + 1: 5/3 + 2: 8/4 + 3: 16/8 + +required: + - "#thermal-sensor-cells" + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + rtp: rtp@1c25000 { + compatible = "allwinner,sun4i-a10-ts"; + reg = <0x01c25000 0x100>; + interrupts = <29>; + allwinner,ts-attached; + #thermal-sensor-cells = <0>; + /* sensitive/noisy touch panel */ + allwinner,tp-sensitive-adjust = <0>; + allwinner,filter-type = <3>; + }; + +... diff --git a/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt b/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt deleted file mode 100644 index 86dd8191b04c..000000000000 --- a/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt +++ /dev/null @@ -1,59 +0,0 @@ -Allwinner SoCs' GPADC Device Tree bindings ------------------------------------------- -The Allwinner SoCs all have an ADC that can also act as a thermal sensor -and sometimes as a touchscreen controller. - -Required properties: - - compatible: "allwinner,sun8i-a33-ths", - - reg: mmio address range of the chip, - - #thermal-sensor-cells: shall be 0, - - #io-channel-cells: shall be 0, - -Example: - ths: ths@1c25000 { - compatible = "allwinner,sun8i-a33-ths"; - reg = <0x01c25000 0x100>; - #thermal-sensor-cells = <0>; - #io-channel-cells = <0>; - }; - -sun4i, sun5i and sun6i SoCs are also supported via the older binding: - -sun4i resistive touchscreen controller --------------------------------------- - -Required properties: - - compatible: "allwinner,sun4i-a10-ts", "allwinner,sun5i-a13-ts" or - "allwinner,sun6i-a31-ts" - - reg: mmio address range of the chip - - interrupts: interrupt to which the chip is connected - - #thermal-sensor-cells: shall be 0 - -Optional properties: - - allwinner,ts-attached : boolean indicating that an actual touchscreen - is attached to the controller - - allwinner,tp-sensitive-adjust : integer (4 bits) - adjust sensitivity of pen down detection - between 0 (least sensitive) and 15 - (defaults to 15) - - allwinner,filter-type : integer (2 bits) - select median and averaging filter - samples used for median / averaging filter - 0: 4/2 - 1: 5/3 - 2: 8/4 - 3: 16/8 - (defaults to 1) - -Example: - - rtp: rtp@1c25000 { - compatible = "allwinner,sun4i-a10-ts"; - reg = <0x01c25000 0x100>; - interrupts = <29>; - allwinner,ts-attached; - #thermal-sensor-cells = <0>; - /* sensitive/noisy touch panel */ - allwinner,tp-sensitive-adjust = <0>; - allwinner,filter-type = <3>; - }; diff --git a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml index df0280edef97..d2d4308596b8 100644 --- a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml @@ -30,16 +30,22 @@ properties: - const: allwinner,sun8i-a83t-mmc - const: allwinner,sun7i-a20-mmc - items: - - const: allwinner,sun50i-h6-emmc + - const: allwinner,sun8i-r40-emmc - const: allwinner,sun50i-a64-emmc - items: - - const: allwinner,sun50i-h6-mmc + - const: allwinner,sun8i-r40-mmc - const: allwinner,sun50i-a64-mmc - items: - - const: allwinner,sun8i-r40-emmc + - const: allwinner,sun50i-h5-emmc - const: allwinner,sun50i-a64-emmc - items: - - const: allwinner,sun8i-r40-mmc + - const: allwinner,sun50i-h5-mmc + - const: allwinner,sun50i-a64-mmc + - items: + - const: allwinner,sun50i-h6-emmc + - const: allwinner,sun50i-a64-emmc + - items: + - const: allwinner,sun50i-h6-mmc - const: allwinner,sun50i-a64-mmc reg: diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt index 1edbb049cccb..7ca0aa7ccc0b 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt @@ -17,6 +17,8 @@ Required Properties: For this device it is strongly suggested to include arasan,soc-ctl-syscon. - "ti,am654-sdhci-5.1", "arasan,sdhci-5.1": TI AM654 MMC PHY Note: This binding has been deprecated and moved to [5]. + - "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1": Intel LGM eMMC PHY + For this device it is strongly suggested to include arasan,soc-ctl-syscon. [5] Documentation/devicetree/bindings/mmc/sdhci-am654.txt @@ -80,3 +82,18 @@ Example: phy-names = "phy_arasan"; #clock-cells = <0>; }; + + emmc: sdhci@ec700000 { + compatible = "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1"; + reg = <0xec700000 0x300>; + interrupt-parent = <&ioapic1>; + interrupts = <44 1>; + clocks = <&cgu0 LGM_CLK_EMMC5>, <&cgu0 LGM_CLK_NGI>, + <&cgu0 LGM_GCLK_EMMC>; + clock-names = "clk_xin", "clk_ahb", "gate"; + clock-output-names = "emmc_cardclock"; + #clock-cells = <0>; + phys = <&emmc_phy>; + phy-names = "phy_arasan"; + arasan,soc-ctl-syscon = <&sysconf>; + }; diff --git a/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml b/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml new file mode 100644 index 000000000000..200de9396036 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright 2019 IBM Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/aspeed,sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED SD/SDIO/MMC Controller + +maintainers: + - Andrew Jeffery <andrew@aj.id.au> + - Ryan Chen <ryanchen.aspeed@gmail.com> + +description: |+ + The ASPEED SD/SDIO/eMMC controller exposes two slots implementing the SDIO + Host Specification v2.00, with 1 or 4 bit data buses, or an 8 bit data bus if + only a single slot is enabled. + + The two slots are supported by a common configuration area. As the SDHCIs for + the slots are dependent on the common configuration area, they are described + as child nodes. + +properties: + compatible: + enum: + - aspeed,ast2400-sd-controller + - aspeed,ast2500-sd-controller + - aspeed,ast2600-sd-controller + reg: + maxItems: 1 + description: Common configuration registers + "#address-cells": + const: 1 + "#size-cells": + const: 1 + ranges: true + clocks: + maxItems: 1 + description: The SD/SDIO controller clock gate + +patternProperties: + "^sdhci@[0-9a-f]+$": + type: object + allOf: + - $ref: mmc-controller.yaml + properties: + compatible: + enum: + - aspeed,ast2400-sdhci + - aspeed,ast2500-sdhci + - aspeed,ast2600-sdhci + reg: + maxItems: 1 + description: The SDHCI registers + clocks: + maxItems: 1 + description: The SD bus clock + interrupts: + maxItems: 1 + description: The SD interrupt shared between both slots + sdhci,auto-cmd12: + type: boolean + description: Specifies that controller should use auto CMD12 + required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - ranges + - clocks + +examples: + - | + #include <dt-bindings/clock/aspeed-clock.h> + sdc@1e740000 { + compatible = "aspeed,ast2500-sd-controller"; + reg = <0x1e740000 0x100>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x1e740000 0x20000>; + clocks = <&syscon ASPEED_CLK_GATE_SDCLK>; + + sdhci0: sdhci@100 { + compatible = "aspeed,ast2500-sdhci"; + reg = <0x100 0x100>; + interrupts = <26>; + sdhci,auto-cmd12; + clocks = <&syscon ASPEED_CLK_SDIO>; + }; + + sdhci1: sdhci@200 { + compatible = "aspeed,ast2500-sdhci"; + reg = <0x200 0x100>; + interrupts = <26>; + sdhci,auto-cmd12; + clocks = <&syscon ASPEED_CLK_SDIO>; + }; + }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt index fa90d253dc7e..09d87cc1182a 100644 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt @@ -6,10 +6,12 @@ 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 Rasperry PI. +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. diff --git a/Documentation/devicetree/bindings/net/adi,adin.yaml b/Documentation/devicetree/bindings/net/adi,adin.yaml new file mode 100644 index 000000000000..69375cb28e92 --- /dev/null +++ b/Documentation/devicetree/bindings/net/adi,adin.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0+ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/adi,adin.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADIN1200/ADIN1300 PHY + +maintainers: + - Alexandru Ardelean <alexandru.ardelean@analog.com> + +description: | + Bindings for Analog Devices Industrial Ethernet PHYs + +allOf: + - $ref: ethernet-phy.yaml# + +properties: + adi,rx-internal-delay-ps: + description: | + RGMII RX Clock Delay used only when PHY operates in RGMII mode with + internal delay (phy-mode is 'rgmii-id' or 'rgmii-rxid') in pico-seconds. + enum: [ 1600, 1800, 2000, 2200, 2400 ] + default: 2000 + + adi,tx-internal-delay-ps: + description: | + RGMII TX Clock Delay used only when PHY operates in RGMII mode with + internal delay (phy-mode is 'rgmii-id' or 'rgmii-txid') in pico-seconds. + enum: [ 1600, 1800, 2000, 2200, 2400 ] + default: 2000 + + adi,fifo-depth-bits: + description: | + When operating in RMII mode, this option configures the FIFO depth. + enum: [ 4, 8, 12, 16, 20, 24 ] + default: 8 + + adi,disable-energy-detect: + description: | + Disables Energy Detect Powerdown Mode (default disabled, i.e energy detect + is enabled if this property is unspecified) + type: boolean + +examples: + - | + ethernet { + #address-cells = <1>; + #size-cells = <0>; + + phy-mode = "rgmii-id"; + + ethernet-phy@0 { + reg = <0>; + + adi,rx-internal-delay-ps = <1800>; + adi,tx-internal-delay-ps = <2200>; + }; + }; + - | + ethernet { + #address-cells = <1>; + #size-cells = <0>; + + phy-mode = "rmii"; + + ethernet-phy@1 { + reg = <1>; + + adi,fifo-depth-bits = <16>; + adi,disable-energy-detect; + }; + }; diff --git a/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml index 06b1cc8bea14..ef446ae166f3 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml @@ -17,6 +17,9 @@ properties: compatible: const: allwinner,sun7i-a20-gmac + reg: + maxItems: 1 + interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml new file mode 100644 index 000000000000..ae91aa9d8616 --- /dev/null +++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 BayLibre, SAS +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/amlogic,meson-dwmac.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic Meson DWMAC Ethernet controller + +maintainers: + - Neil Armstrong <narmstrong@baylibre.com> + - Martin Blumenstingl <martin.blumenstingl@googlemail.com> + +# We need a select here so we don't match all nodes with 'snps,dwmac' +select: + properties: + compatible: + contains: + enum: + - amlogic,meson6-dwmac + - amlogic,meson8b-dwmac + - amlogic,meson8m2-dwmac + - amlogic,meson-gxbb-dwmac + - amlogic,meson-axg-dwmac + required: + - compatible + +allOf: + - $ref: "snps,dwmac.yaml#" + - if: + properties: + compatible: + contains: + enum: + - amlogic,meson8b-dwmac + - amlogic,meson8m2-dwmac + - amlogic,meson-gxbb-dwmac + - amlogic,meson-axg-dwmac + + then: + properties: + clocks: + items: + - description: GMAC main clock + - description: First parent clock of the internal mux + - description: Second parent clock of the internal mux + + clock-names: + minItems: 3 + maxItems: 3 + items: + - const: stmmaceth + - const: clkin0 + - const: clkin1 + + amlogic,tx-delay-ns: + $ref: /schemas/types.yaml#definitions/uint32 + description: + The internal RGMII TX clock delay (provided by this driver) in + nanoseconds. Allowed values are 0ns, 2ns, 4ns, 6ns. + When phy-mode is set to "rgmii" then the TX delay should be + explicitly configured. When not configured a fallback of 2ns is + used. When the phy-mode is set to either "rgmii-id" or "rgmii-txid" + the TX clock delay is already provided by the PHY. In that case + this property should be set to 0ns (which disables the TX clock + delay in the MAC to prevent the clock from going off because both + PHY and MAC are adding a delay). + Any configuration is ignored when the phy-mode is set to "rmii". + +properties: + compatible: + additionalItems: true + maxItems: 3 + items: + - enum: + - amlogic,meson6-dwmac + - amlogic,meson8b-dwmac + - amlogic,meson8m2-dwmac + - amlogic,meson-gxbb-dwmac + - amlogic,meson-axg-dwmac + contains: + enum: + - snps,dwmac-3.70a + - snps,dwmac + + reg: + items: + - description: + The first register range should be the one of the DWMAC controller + - description: + The second range is is for the Amlogic specific configuration + (for example the PRG_ETHERNET register range on Meson8b and newer) + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - phy-mode + +examples: + - | + ethmac: ethernet@c9410000 { + compatible = "amlogic,meson-gxbb-dwmac", "snps,dwmac"; + reg = <0xc9410000 0x10000>, <0xc8834540 0x8>; + interrupts = <8>; + interrupt-names = "macirq"; + clocks = <&clk_eth>, <&clkc_fclk_div2>, <&clk_mpll2>; + clock-names = "stmmaceth", "clkin0", "clkin1"; + phy-mode = "rgmii"; + }; diff --git a/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml b/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml new file mode 100644 index 000000000000..71808e78a495 --- /dev/null +++ b/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/aspeed,ast2600-mdio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED AST2600 MDIO Controller + +maintainers: + - Andrew Jeffery <andrew@aj.id.au> + +description: |+ + The ASPEED AST2600 MDIO controller is the third iteration of ASPEED's MDIO + bus register interface, this time also separating out the controller from the + MAC. + +allOf: + - $ref: "mdio.yaml#" + +properties: + compatible: + const: aspeed,ast2600-mdio + reg: + maxItems: 1 + description: The register range of the MDIO controller instance + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + +examples: + - | + mdio0: mdio@1e650000 { + compatible = "aspeed,ast2600-mdio"; + reg = <0x1e650000 0x8>; + #address-cells = <1>; + #size-cells = <0>; + + ethphy0: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt index c26f4e11037c..4fa00e2eafcf 100644 --- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt @@ -13,6 +13,7 @@ Required properties: * "brcm,bcm20702a1" * "brcm,bcm4330-bt" * "brcm,bcm43438-bt" + * "brcm,bcm4345c5" Optional properties: diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt index bc77477c6878..94c0f8bf4deb 100644 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt @@ -32,6 +32,15 @@ Optional properties: ack_gpr is the gpr register offset of CAN stop acknowledge. ack_bit is the bit offset of CAN stop acknowledge. +- fsl,clk-source: Select the clock source to the CAN Protocol Engine (PE). + It's SoC Implementation dependent. Refer to RM for detailed + definition. If this property is not set in device tree node + then driver selects clock source 1 by default. + 0: clock source 0 (oscillator clock) + 1: clock source 1 (peripheral clock) + +- wakeup-source: enable CAN remote wakeup + Example: can@1c000 { @@ -40,4 +49,5 @@ Example: interrupts = <48 0x2>; interrupt-parent = <&mpic>; clock-frequency = <200000000>; // filled in by bootloader + fsl,clk-source = <0>; // select clock source 0 for PE }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index b463e1268ac4..19e4a7d91511 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -5,6 +5,7 @@ Required properties: - compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. "renesas,can-r8a7744" if CAN controller is a part of R8A7744 SoC. "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. + "renesas,can-r8a77470" if CAN controller is a part of R8A77470 SoC. "renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC. "renesas,can-r8a774c0" if CAN controller is a part of R8A774C0 SoC. "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. @@ -17,6 +18,8 @@ Required properties: "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-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. "renesas,rcar-gen1-can" for a generic R-Car Gen1 compatible device. "renesas,rcar-gen2-can" for a generic R-Car Gen2 or RZ/G1 compatible device. @@ -33,7 +36,8 @@ Required properties: - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". -Required properties for R8A7795, R8A7796 and R8A77965: +Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, 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/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt index 32f051f6d338..a901cd9be29e 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt @@ -4,6 +4,7 @@ Renesas R-Car CAN FD controller Device Tree Bindings Required properties: - compatible: Must contain one or more of the following: - "renesas,rcar-gen3-canfd" for R-Car Gen3 and RZ/G2 compatible controllers. + - "renesas,r8a774a1-canfd" for R8A774A1 (RZ/G2M) compatible controller. - "renesas,r8a774c0-canfd" for R8A774C0 (RZ/G2E) compatible controller. - "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller. - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller. @@ -11,6 +12,7 @@ Required properties: - "renesas,r8a77970-canfd" for R8A77970 (R-Car V3M) compatible controller. - "renesas,r8a77980-canfd" for R8A77980 (R-Car V3H) compatible controller. - "renesas,r8a77990-canfd" for R8A77990 (R-Car E3) compatible controller. + - "renesas,r8a77995-canfd" for R8A77995 (R-Car D3) compatible controller. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the @@ -29,13 +31,12 @@ The name of the child nodes are "channel0" and "channel1" respectively. Each child node supports the "status" property only, which is used to enable/disable the respective channel. -Required properties for "renesas,r8a774c0-canfd", "renesas,r8a7795-canfd", -"renesas,r8a7796-canfd", "renesas,r8a77965-canfd", and "renesas,r8a77990-canfd" -compatible: -In R8A774C0, R8A7795, R8A7796, R8A77965, and R8A77990 SoCs, canfd clock 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 using the below properties: +Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, R8A77965, +R8A77990, and R8A77995: +In the denoted SoCs, canfd clock 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 using the below +properties: - assigned-clocks: phandle of canfd clock. - assigned-clock-rates: maximum frequency of this clock. diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt new file mode 100644 index 000000000000..27e1b4cebfbd --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -0,0 +1,40 @@ +Texas Instruments TCAN4x5x CAN Controller +================================================ + +This file provides device node information for the TCAN4x5x interface contains. + +Required properties: + - compatible: "ti,tcan4x5x" + - reg: 0 + - #address-cells: 1 + - #size-cells: 0 + - spi-max-frequency: Maximum frequency of the SPI bus the chip can + operate at should be less than or equal to 18 MHz. + - device-wake-gpios: Wake up GPIO to wake up the TCAN device. + - interrupt-parent: the phandle to the interrupt controller which provides + the interrupt. + - interrupts: interrupt specification for data-ready. + +See Documentation/devicetree/bindings/net/can/m_can.txt for additional +required property details. + +Optional properties: + - reset-gpios: Hardwired output GPIO. If not defined then software + reset. + - device-state-gpios: Input GPIO that indicates if the device is in + a sleep state or if the device is active. + +Example: +tcan4x5x: tcan4x5x@0 { + compatible = "ti,tcan4x5x"; + reg = <0>; + #address-cells = <1>; + #size-cells = <1>; + spi-max-frequency = <10000000>; + bosch,mram-cfg = <0x0 0 0 32 0 0 1 1>; + interrupt-parent = <&gpio1>; + interrupts = <14 GPIO_ACTIVE_LOW>; + device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; + device-wake-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio1 27 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/net/dsa/ksz.txt b/Documentation/devicetree/bindings/net/dsa/ksz.txt index 4ac21cef370e..95e91e84151c 100644 --- a/Documentation/devicetree/bindings/net/dsa/ksz.txt +++ b/Documentation/devicetree/bindings/net/dsa/ksz.txt @@ -5,6 +5,9 @@ Required properties: - compatible: For external switch chips, compatible string must be exactly one of the following: + - "microchip,ksz8765" + - "microchip,ksz8794" + - "microchip,ksz8795" - "microchip,ksz9477" - "microchip,ksz9897" - "microchip,ksz9896" @@ -12,6 +15,7 @@ Required properties: - "microchip,ksz8565" - "microchip,ksz9893" - "microchip,ksz9563" + - "microchip,ksz8563" Optional properties: diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt index 6f9538974bb9..30c11fea491b 100644 --- a/Documentation/devicetree/bindings/net/dsa/marvell.txt +++ b/Documentation/devicetree/bindings/net/dsa/marvell.txt @@ -22,7 +22,7 @@ which is at a different MDIO base address in different switch families. - "marvell,mv88e6190" : Switch has base address 0x00. Use with models: 6190, 6190X, 6191, 6290, 6390, 6390X - "marvell,mv88e6250" : Switch has base address 0x08 or 0x18. Use with model: - 6250 + 6220, 6250 Required properties: - compatible : Should be one of "marvell,mv88e6085", diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt index 47aa205ee0bd..c5ed5d25f642 100644 --- a/Documentation/devicetree/bindings/net/dsa/mt7530.txt +++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt @@ -35,6 +35,42 @@ Required properties for the child nodes within ports container: - phy-mode: String, must be either "trgmii" or "rgmii" for port labeled "cpu". +Port 5 of the switch is muxed between: +1. GMAC5: GMAC5 can interface with another external MAC or PHY. +2. PHY of port 0 or port 4: PHY interfaces with an external MAC like 2nd GMAC + of the SOC. Used in many setups where port 0/4 becomes the WAN port. + Note: On a MT7621 SOC with integrated switch: 2nd GMAC can only connected to + GMAC5 when the gpios for RGMII2 (GPIO 22-33) are not used and not + connected to external component! + +Port 5 modes/configurations: +1. Port 5 is disabled and isolated: An external phy can interface to the 2nd + GMAC of the SOC. + In the case of a build-in MT7530 switch, port 5 shares the RGMII bus with 2nd + GMAC and an optional external phy. Mind the GPIO/pinctl settings of the SOC! +2. Port 5 is muxed to PHY of port 0/4: Port 0/4 interfaces with 2nd GMAC. + It is a simple MAC to PHY interface, port 5 needs to be setup for xMII mode + and RGMII delay. +3. Port 5 is muxed to GMAC5 and can interface to an external phy. + Port 5 becomes an extra switch port. + Only works on platform where external phy TX<->RX lines are swapped. + Like in the Ubiquiti ER-X-SFP. +4. Port 5 is muxed to GMAC5 and interfaces with the 2nd GAMC as 2nd CPU port. + Currently a 2nd CPU port is not supported by DSA code. + +Depending on how the external PHY is wired: +1. normal: The PHY can only connect to 2nd GMAC but not to the switch +2. swapped: RGMII TX, RX are swapped; external phy interface with the switch as + a ethernet port. But can't interface to the 2nd GMAC. + +Based on the DT the port 5 mode is configured. + +Driver tries to lookup the phy-handle of the 2nd GMAC of the master device. +When phy-handle matches PHY of port 0 or 4 then port 5 set-up as mode 2. +phy-mode must be set, see also example 2 below! + * mt7621: phy-mode = "rgmii-txid"; + * mt7623: phy-mode = "rgmii"; + See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional required, optional properties and how the integrated switch subnodes must be specified. @@ -94,3 +130,181 @@ Example: }; }; }; + +Example 2: MT7621: Port 4 is WAN port: 2nd GMAC -> Port 5 -> PHY port 4. + +ð { + gmac0: mac@0 { + compatible = "mediatek,eth-mac"; + reg = <0>; + phy-mode = "rgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + + gmac1: mac@1 { + compatible = "mediatek,eth-mac"; + reg = <1>; + phy-mode = "rgmii-txid"; + phy-handle = <&phy4>; + }; + + mdio: mdio-bus { + #address-cells = <1>; + #size-cells = <0>; + + /* Internal phy */ + phy4: ethernet-phy@4 { + reg = <4>; + }; + + mt7530: switch@1f { + compatible = "mediatek,mt7621"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x1f>; + pinctrl-names = "default"; + mediatek,mcm; + + resets = <&rstctrl 2>; + reset-names = "mcm"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan0"; + }; + + port@1 { + reg = <1>; + label = "lan1"; + }; + + port@2 { + reg = <2>; + label = "lan2"; + }; + + port@3 { + reg = <3>; + label = "lan3"; + }; + +/* Commented out. Port 4 is handled by 2nd GMAC. + port@4 { + reg = <4>; + label = "lan4"; + }; +*/ + + cpu_port0: port@6 { + reg = <6>; + label = "cpu"; + ethernet = <&gmac0>; + phy-mode = "rgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + }; + }; + }; +}; + +Example 3: MT7621: Port 5 is connected to external PHY: Port 5 -> external PHY. + +ð { + gmac0: mac@0 { + compatible = "mediatek,eth-mac"; + reg = <0>; + phy-mode = "rgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + + mdio: mdio-bus { + #address-cells = <1>; + #size-cells = <0>; + + /* External phy */ + ephy5: ethernet-phy@7 { + reg = <7>; + }; + + mt7530: switch@1f { + compatible = "mediatek,mt7621"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x1f>; + pinctrl-names = "default"; + mediatek,mcm; + + resets = <&rstctrl 2>; + reset-names = "mcm"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan0"; + }; + + port@1 { + reg = <1>; + label = "lan1"; + }; + + port@2 { + reg = <2>; + label = "lan2"; + }; + + port@3 { + reg = <3>; + label = "lan3"; + }; + + port@4 { + reg = <4>; + label = "lan4"; + }; + + port@5 { + reg = <5>; + label = "lan5"; + phy-mode = "rgmii"; + phy-handle = <&ephy5>; + }; + + cpu_port0: port@6 { + reg = <6>; + label = "cpu"; + ethernet = <&gmac0>; + phy-mode = "rgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/fsl-enetc.txt b/Documentation/devicetree/bindings/net/fsl-enetc.txt index 25fc687419db..b7034ccbc1bd 100644 --- a/Documentation/devicetree/bindings/net/fsl-enetc.txt +++ b/Documentation/devicetree/bindings/net/fsl-enetc.txt @@ -11,7 +11,9 @@ Required properties: to parent node bindings. - compatible : Should be "fsl,enetc". -1) The ENETC external port is connected to a MDIO configurable phy: +1. The ENETC external port is connected to a MDIO configurable phy + +1.1. Using the local ENETC Port MDIO interface In this case, the ENETC node should include a "mdio" sub-node that in turn should contain the "ethernet-phy" node describing the @@ -47,8 +49,42 @@ Example: }; }; -2) The ENETC port is an internal port or has a fixed-link external -connection: +1.2. Using the central MDIO PCIe endpoint device + +In this case, the mdio node should be defined as another PCIe +endpoint node, at the same level with the ENETC port nodes. + +Required properties: + +- reg : Specifies PCIe Device Number and Function + Number of the ENETC endpoint device, according + to parent node bindings. +- compatible : Should be "fsl,enetc-mdio". + +The remaining required mdio bus properties are standard, their bindings +already defined in Documentation/devicetree/bindings/net/mdio.txt. + +Example: + + ethernet@0,0 { + compatible = "fsl,enetc"; + reg = <0x000000 0 0 0 0>; + phy-handle = <&sgmii_phy0>; + phy-connection-type = "sgmii"; + }; + + mdio@0,3 { + compatible = "fsl,enetc-mdio"; + reg = <0x000300 0 0 0 0>; + #address-cells = <1>; + #size-cells = <0>; + sgmii_phy0: ethernet-phy@2 { + reg = <0x2>; + }; + }; + +2. The ENETC port is an internal port or has a fixed-link external +connection In this case, the ENETC port node defines a fixed link connection, as specified by Documentation/devicetree/bindings/net/fixed-link.txt. diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index 2d41fb96ce0a..5b88fae0307d 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -7,18 +7,6 @@ Required properties: - phy-mode : See ethernet.txt file in the same directory Optional properties: -- phy-reset-gpios : Should specify the gpio for phy reset -- phy-reset-duration : Reset duration in milliseconds. Should present - only if property "phy-reset-gpios" is available. Missing the property - will have the duration be 1 millisecond. Numbers greater than 1000 are - invalid and 1 millisecond will be used instead. -- phy-reset-active-high : If present then the reset sequence using the GPIO - specified in the "phy-reset-gpios" property is reversed (H=reset state, - L=operation state). -- phy-reset-post-delay : Post reset delay in milliseconds. If present then - a delay of phy-reset-post-delay milliseconds will be observed after the - phy-reset-gpios has been toggled. Can be omitted thus no delay is - observed. Delay is in range of 1ms to 1000ms. Other delays are invalid. - phy-supply : regulator that powers the Ethernet PHY. - phy-handle : phandle to the PHY device connected to this device. - fixed-link : Assume a fixed link. See fixed-link.txt in the same directory. @@ -47,11 +35,27 @@ Optional properties: For imx6sx, "int0" handles all 3 queues and ENET_MII. "pps" is for the pulse per second interrupt associated with 1588 precision time protocol(PTP). - Optional subnodes: - mdio : specifies the mdio bus in the FEC, used as a container for phy nodes according to phy.txt in the same directory +Deprecated optional properties: + To avoid these, create a phy node according to phy.txt in the same + directory, and point the fec's "phy-handle" property to it. Then use + the phy's reset binding, again described by phy.txt. +- phy-reset-gpios : Should specify the gpio for phy reset +- phy-reset-duration : Reset duration in milliseconds. Should present + only if property "phy-reset-gpios" is available. Missing the property + will have the duration be 1 millisecond. Numbers greater than 1000 are + invalid and 1 millisecond will be used instead. +- phy-reset-active-high : If present then the reset sequence using the GPIO + specified in the "phy-reset-gpios" property is reversed (H=reset state, + L=operation state). +- phy-reset-post-delay : Post reset delay in milliseconds. If present then + a delay of phy-reset-post-delay milliseconds will be observed after the + phy-reset-gpios has been toggled. Can be omitted thus no delay is + observed. Delay is in range of 1ms to 1000ms. Other delays are invalid. + Example: ethernet@83fec000 { diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index 63c73fafe26d..0b61a90f1592 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -15,10 +15,10 @@ Required properties: Use "atmel,sama5d4-gem" for the GEM IP (10/100) available on Atmel sama5d4 SoCs. Use "cdns,zynq-gem" Xilinx Zynq-7xxx SoC. Use "cdns,zynqmp-gem" for Zynq Ultrascale+ MPSoC. - Use "sifive,fu540-macb" for SiFive FU540-C000 SoC. + Use "sifive,fu540-c000-gem" for SiFive FU540-C000 SoC. Or the generic form: "cdns,emac". - reg: Address and length of the register set for the device - For "sifive,fu540-macb", second range is required to specify the + For "sifive,fu540-c000-gem", second range is required to specify the address and length of the registers for GEMGXL Management block. - interrupts: Should contain macb interrupt - phy-mode: See ethernet.txt file in the same directory. diff --git a/Documentation/devicetree/bindings/net/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt index 770ff98d4524..72d03e07cf7c 100644 --- a/Documentation/devicetree/bindings/net/mediatek-net.txt +++ b/Documentation/devicetree/bindings/net/mediatek-net.txt @@ -12,6 +12,7 @@ Required properties: "mediatek,mt7623-eth", "mediatek,mt2701-eth": for MT7623 SoC "mediatek,mt7622-eth": for MT7622 SoC "mediatek,mt7629-eth": for MT7629 SoC + "ralink,rt5350-eth": for Ralink Rt5350F and MT7628/88 SoC - reg: Address and length of the register set for the device - interrupts: Should contain the three frame engines interrupts in numeric order. These are fe_int0, fe_int1 and fe_int2. diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt deleted file mode 100644 index 1321bb194ed9..000000000000 --- a/Documentation/devicetree/bindings/net/meson-dwmac.txt +++ /dev/null @@ -1,71 +0,0 @@ -* Amlogic Meson DWMAC Ethernet controller - -The device inherits all the properties of the dwmac/stmmac devices -described in the file stmmac.txt in the current directory with the -following changes. - -Required properties on all platforms: - -- compatible: Depending on the platform this should be one of: - - "amlogic,meson6-dwmac" - - "amlogic,meson8b-dwmac" - - "amlogic,meson8m2-dwmac" - - "amlogic,meson-gxbb-dwmac" - - "amlogic,meson-axg-dwmac" - Additionally "snps,dwmac" and any applicable more - detailed version number described in net/stmmac.txt - should be used. - -- reg: The first register range should be the one of the DWMAC - controller. The second range is is for the Amlogic specific - configuration (for example the PRG_ETHERNET register range - on Meson8b and newer) - -Required properties on Meson8b, Meson8m2, GXBB and newer: -- clock-names: Should contain the following: - - "stmmaceth" - see stmmac.txt - - "clkin0" - first parent clock of the internal mux - - "clkin1" - second parent clock of the internal mux - -Optional properties on Meson8b, Meson8m2, GXBB and newer: -- amlogic,tx-delay-ns: The internal RGMII TX clock delay (provided - by this driver) in nanoseconds. Allowed values - are: 0ns, 2ns, 4ns, 6ns. - When phy-mode is set to "rgmii" then the TX - delay should be explicitly configured. When - not configured a fallback of 2ns is used. - When the phy-mode is set to either "rgmii-id" - or "rgmii-txid" the TX clock delay is already - provided by the PHY. In that case this - property should be set to 0ns (which disables - the TX clock delay in the MAC to prevent the - clock from going off because both PHY and MAC - are adding a delay). - Any configuration is ignored when the phy-mode - is set to "rmii". - -Example for Meson6: - - ethmac: ethernet@c9410000 { - compatible = "amlogic,meson6-dwmac", "snps,dwmac"; - reg = <0xc9410000 0x10000 - 0xc1108108 0x4>; - interrupts = <0 8 1>; - interrupt-names = "macirq"; - clocks = <&clk81>; - clock-names = "stmmaceth"; - } - -Example for GXBB: - ethmac: ethernet@c9410000 { - compatible = "amlogic,meson-gxbb-dwmac", "snps,dwmac"; - reg = <0x0 0xc9410000 0x0 0x10000>, - <0x0 0xc8834540 0x0 0x8>; - interrupts = <0 8 1>; - interrupt-names = "macirq"; - clocks = <&clkc CLKID_ETH>, - <&clkc CLKID_FCLK_DIV2>, - <&clkc CLKID_MPLL2>; - clock-names = "stmmaceth", "clkin0", "clkin1"; - phy-mode = "rgmii"; - }; diff --git a/Documentation/devicetree/bindings/net/mscc-ocelot.txt b/Documentation/devicetree/bindings/net/mscc-ocelot.txt index 9e5c17d426ce..3b6290b45ce5 100644 --- a/Documentation/devicetree/bindings/net/mscc-ocelot.txt +++ b/Documentation/devicetree/bindings/net/mscc-ocelot.txt @@ -12,13 +12,15 @@ Required properties: - "sys" - "rew" - "qs" + - "ptp" (optional due to backward compatibility) - "qsys" - "ana" - "portX" with X from 0 to the number of last port index available on that switch -- interrupts: Should contain the switch interrupts for frame extraction and - frame injection -- interrupt-names: should contain the interrupt names: "xtr", "inj" +- interrupts: Should contain the switch interrupts for frame extraction, + frame injection and PTP ready. +- interrupt-names: should contain the interrupt names: "xtr", "inj". Can contain + "ptp_rdy" which is optional due to backward compatibility. - ethernet-ports: A container for child nodes representing switch ports. The ethernet-ports container has the following properties @@ -44,6 +46,7 @@ Example: reg = <0x1010000 0x10000>, <0x1030000 0x10000>, <0x1080000 0x100>, + <0x10e0000 0x10000>, <0x11e0000 0x100>, <0x11f0000 0x100>, <0x1200000 0x100>, @@ -57,11 +60,12 @@ Example: <0x1280000 0x100>, <0x1800000 0x80000>, <0x1880000 0x10000>; - reg-names = "sys", "rew", "qs", "port0", "port1", "port2", - "port3", "port4", "port5", "port6", "port7", - "port8", "port9", "port10", "qsys", "ana"; - interrupts = <21 22>; - interrupt-names = "xtr", "inj"; + reg-names = "sys", "rew", "qs", "ptp", "port0", "port1", + "port2", "port3", "port4", "port5", "port6", + "port7", "port8", "port9", "port10", "qsys", + "ana"; + interrupts = <18 21 22>; + interrupt-names = "ptp_rdy", "xtr", "inj"; ethernet-ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 76fea2be66ac..ebe4537a7cce 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -50,6 +50,11 @@ properties: - allwinner,sun8i-r40-emac - allwinner,sun8i-v3s-emac - allwinner,sun50i-a64-emac + - amlogic,meson6-dwmac + - amlogic,meson8b-dwmac + - amlogic,meson8m2-dwmac + - amlogic,meson-gxbb-dwmac + - amlogic,meson-axg-dwmac - snps,dwmac - snps,dwmac-3.50a - snps,dwmac-3.610 @@ -61,7 +66,8 @@ properties: - snps,dwxgmac-2.10 reg: - maxItems: 1 + minItems: 1 + maxItems: 2 interrupts: minItems: 1 @@ -106,6 +112,14 @@ properties: reset-names: const: stmmaceth + mac-mode: + maxItems: 1 + description: + The property is identical to 'phy-mode', and assumes that there is mode + converter in-between the MAC & PHY (e.g. GMII-to-RGMII). This converter + can be passive (no SW requirement), and requires that the MAC operate + in a different mode than the PHY in order to function. + snps,axi-config: $ref: /schemas/types.yaml#definitions/phandle description: diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.txt b/Documentation/devicetree/bindings/net/ti,dp83867.txt index db6aa3f2215b..388ff48f53ae 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83867.txt +++ b/Documentation/devicetree/bindings/net/ti,dp83867.txt @@ -37,6 +37,10 @@ Optional property: for applicable values. The CLK_OUT pin can also be disabled by this property. When omitted, the PHY's default will be left as is. + - ti,sgmii-ref-clock-output-enable - This denotes which + SGMII configuration is used (4 or 6-wire modes). + Some MACs work with differential SGMII clock. + See data manual for details. Note: ti,min-output-impedance and ti,max-output-impedance are mutually exclusive. When both properties are present ti,max-output-impedance diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 96ffd06d2ca8..904dadf3d07b 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -2,7 +2,7 @@ Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings This binding represents the on-chip eFuse OTP controller found on i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ, i.MX6SLL, -i.MX7D/S, i.MX7ULP and i.MX8MQ SoCs. +i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM and i.MX8MN SoCs. Required properties: - compatible: should be one of @@ -16,6 +16,7 @@ Required properties: "fsl,imx7ulp-ocotp" (i.MX7ULP), "fsl,imx8mq-ocotp" (i.MX8MQ), "fsl,imx8mm-ocotp" (i.MX8MM), + "fsl,imx8mn-ocotp" (i.MX8MN), followed by "syscon". - #address-cells : Should be 1 - #size-cells : Should be 1 diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 76b6c79604a5..68592271461f 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -140,8 +140,8 @@ Optional properties: frequency for a short duration of time limited by the device's power, current and thermal limits. -- opp-suspend: Marks the OPP to be used during device suspend. Only one OPP in - the table should have this. +- opp-suspend: Marks the OPP to be used during device suspend. If multiple OPPs + in the table have this, the OPP with highest opp-hz will be used. - opp-supported-hw: This enables us to select only a subset of OPPs from the larger OPP table, based on what version of the hardware we are running on. We diff --git a/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt index c2127b96805a..4751029b9b74 100644 --- a/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt +++ b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt @@ -1,25 +1,38 @@ -Qualcomm Technologies, Inc. KRYO CPUFreq and OPP bindings +Qualcomm Technologies, Inc. NVMEM CPUFreq and OPP bindings =================================== -In Certain Qualcomm Technologies, Inc. SoCs like apq8096 and msm8996 -that have KRYO processors, the CPU ferequencies subset and voltage value -of each OPP varies based on the silicon variant in use. +In Certain Qualcomm Technologies, Inc. SoCs like apq8096 and msm8996, +the CPU frequencies subset and voltage value of each OPP varies based on +the silicon variant in use. Qualcomm Technologies, Inc. Process Voltage Scaling Tables defines the voltage and frequency value based on the msm-id in SMEM and speedbin blown in the efuse combination. -The qcom-cpufreq-kryo driver reads the msm-id and efuse value from the SoC +The qcom-cpufreq-nvmem driver reads the msm-id and efuse value from the SoC to provide the OPP framework with required information (existing HW bitmap). This is used to determine the voltage and frequency value for each OPP of operating-points-v2 table when it is parsed by the OPP framework. Required properties: -------------------- -In 'cpus' nodes: +In 'cpu' nodes: - operating-points-v2: Phandle to the operating-points-v2 table to use. In 'operating-points-v2' table: - compatible: Should be - 'operating-points-v2-kryo-cpu' for apq8096 and msm8996. + +Optional properties: +-------------------- +In 'cpu' nodes: +- power-domains: A phandle pointing to the PM domain specifier which provides + the performance states available for active state management. + Please refer to the power-domains bindings + Documentation/devicetree/bindings/power/power_domain.txt + and also examples below. +- power-domain-names: Should be + - 'cpr' for qcs404. + +In 'operating-points-v2' table: - nvmem-cells: A phandle pointing to a nvmem-cells node representing the efuse registers that has information about the speedbin that is used to select the right frequency/voltage @@ -678,3 +691,105 @@ soc { }; }; }; + +Example 2: +--------- + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + CPU0: cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x100>; + .... + clocks = <&apcs_glb>; + operating-points-v2 = <&cpu_opp_table>; + power-domains = <&cpr>; + power-domain-names = "cpr"; + }; + + CPU1: cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x101>; + .... + clocks = <&apcs_glb>; + operating-points-v2 = <&cpu_opp_table>; + power-domains = <&cpr>; + power-domain-names = "cpr"; + }; + + CPU2: cpu@102 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x102>; + .... + clocks = <&apcs_glb>; + operating-points-v2 = <&cpu_opp_table>; + power-domains = <&cpr>; + power-domain-names = "cpr"; + }; + + CPU3: cpu@103 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x103>; + .... + clocks = <&apcs_glb>; + operating-points-v2 = <&cpu_opp_table>; + power-domains = <&cpr>; + power-domain-names = "cpr"; + }; + }; + + cpu_opp_table: cpu-opp-table { + compatible = "operating-points-v2-kryo-cpu"; + opp-shared; + + opp-1094400000 { + opp-hz = /bits/ 64 <1094400000>; + required-opps = <&cpr_opp1>; + }; + opp-1248000000 { + opp-hz = /bits/ 64 <1248000000>; + required-opps = <&cpr_opp2>; + }; + opp-1401600000 { + opp-hz = /bits/ 64 <1401600000>; + required-opps = <&cpr_opp3>; + }; + }; + + cpr_opp_table: cpr-opp-table { + compatible = "operating-points-v2-qcom-level"; + + cpr_opp1: opp1 { + opp-level = <1>; + qcom,opp-fuse-level = <1>; + }; + cpr_opp2: opp2 { + opp-level = <2>; + qcom,opp-fuse-level = <2>; + }; + cpr_opp3: opp3 { + opp-level = <3>; + qcom,opp-fuse-level = <3>; + }; + }; + +.... + +soc { +.... + cpr: power-controller@b018000 { + compatible = "qcom,qcs404-cpr", "qcom,cpr"; + reg = <0x0b018000 0x1000>; + .... + vdd-apc-supply = <&pms405_s3>; + #power-domain-cells = <0>; + operating-points-v2 = <&cpr_opp_table>; + .... + }; +}; diff --git a/Documentation/devicetree/bindings/opp/qcom-opp.txt b/Documentation/devicetree/bindings/opp/qcom-opp.txt new file mode 100644 index 000000000000..32eb0793c7e6 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/qcom-opp.txt @@ -0,0 +1,19 @@ +Qualcomm OPP bindings to describe OPP nodes + +The bindings are based on top of the operating-points-v2 bindings +described in Documentation/devicetree/bindings/opp/opp.txt +Additional properties are described below. + +* OPP Table Node + +Required properties: +- compatible: Allow OPPs to express their compatibility. It should be: + "operating-points-v2-qcom-level" + +* OPP Node + +Required properties: +- qcom,opp-fuse-level: A positive value representing the fuse corner/level + associated with this OPP node. Sometimes several corners/levels shares + a certain fuse corner/level. A fuse corner/level contains e.g. ref uV, + min uV, and max uV. diff --git a/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt b/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt new file mode 100644 index 000000000000..7deae57a587b --- /dev/null +++ b/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt @@ -0,0 +1,167 @@ +Allwinner Technologies, Inc. NVMEM CPUFreq and OPP bindings +=================================== + +For some SoCs, the CPU frequency subset and voltage value of each OPP +varies based on the silicon variant in use. Allwinner Process Voltage +Scaling Tables defines the voltage and frequency value based on the +speedbin blown in the efuse combination. The sun50i-cpufreq-nvmem driver +reads the efuse value from the SoC to provide the OPP framework with +required information. + +Required properties: +-------------------- +In 'cpus' nodes: +- operating-points-v2: Phandle to the operating-points-v2 table to use. + +In 'operating-points-v2' table: +- compatible: Should be + - 'allwinner,sun50i-h6-operating-points'. +- nvmem-cells: A phandle pointing to a nvmem-cells node representing the + efuse registers that has information about the speedbin + that is used to select the right frequency/voltage value + pair. Please refer the for nvmem-cells bindings + Documentation/devicetree/bindings/nvmem/nvmem.txt and + also examples below. + +In every OPP node: +- opp-microvolt-<name>: Voltage in micro Volts. + At runtime, the platform can pick a <name> and + matching opp-microvolt-<name> property. + [See: opp.txt] + HW: <name>: + sun50i-h6 speed0 speed1 speed2 + +Example 1: +--------- + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <0>; + enable-method = "psci"; + clocks = <&ccu CLK_CPUX>; + clock-latency-ns = <244144>; /* 8 32k periods */ + operating-points-v2 = <&cpu_opp_table>; + #cooling-cells = <2>; + }; + + cpu1: cpu@1 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <1>; + enable-method = "psci"; + clocks = <&ccu CLK_CPUX>; + clock-latency-ns = <244144>; /* 8 32k periods */ + operating-points-v2 = <&cpu_opp_table>; + #cooling-cells = <2>; + }; + + cpu2: cpu@2 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <2>; + enable-method = "psci"; + clocks = <&ccu CLK_CPUX>; + clock-latency-ns = <244144>; /* 8 32k periods */ + operating-points-v2 = <&cpu_opp_table>; + #cooling-cells = <2>; + }; + + cpu3: cpu@3 { + compatible = "arm,cortex-a53"; + device_type = "cpu"; + reg = <3>; + enable-method = "psci"; + clocks = <&ccu CLK_CPUX>; + clock-latency-ns = <244144>; /* 8 32k periods */ + operating-points-v2 = <&cpu_opp_table>; + #cooling-cells = <2>; + }; + }; + + cpu_opp_table: opp_table { + compatible = "allwinner,sun50i-h6-operating-points"; + nvmem-cells = <&speedbin_efuse>; + opp-shared; + + opp@480000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <480000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp@720000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <720000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp@816000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <816000000>; + + opp-microvolt-speed0 = <880000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp@888000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <888000000>; + + opp-microvolt-speed0 = <940000>; + opp-microvolt-speed1 = <820000>; + opp-microvolt-speed2 = <800000>; + }; + + opp@1080000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1080000000>; + + opp-microvolt-speed0 = <1060000>; + opp-microvolt-speed1 = <880000>; + opp-microvolt-speed2 = <840000>; + }; + + opp@1320000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1320000000>; + + opp-microvolt-speed0 = <1160000>; + opp-microvolt-speed1 = <940000>; + opp-microvolt-speed2 = <900000>; + }; + + opp@1488000000 { + clock-latency-ns = <244144>; /* 8 32k periods */ + opp-hz = /bits/ 64 <1488000000>; + + opp-microvolt-speed0 = <1160000>; + opp-microvolt-speed1 = <1000000>; + opp-microvolt-speed2 = <960000>; + }; + }; +.... +soc { +.... + sid: sid@3006000 { + compatible = "allwinner,sun50i-h6-sid"; + reg = <0x03006000 0x400>; + #address-cells = <1>; + #size-cells = <1>; + .... + speedbin_efuse: speed@1c { + reg = <0x1c 4>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/pci/pci-armada8k.txt b/Documentation/devicetree/bindings/pci/pci-armada8k.txt index 9e3fc15e1af8..8324a4ee6f06 100644 --- a/Documentation/devicetree/bindings/pci/pci-armada8k.txt +++ b/Documentation/devicetree/bindings/pci/pci-armada8k.txt @@ -17,6 +17,14 @@ Required properties: name must be "core" for the first clock and "reg" for the second one +Optional properties: +- phys: phandle(s) to PHY node(s) following the generic PHY bindings. + Either 1, 2 or 4 PHYs might be needed depending on the number of + PCIe lanes. +- phy-names: names of the PHYs corresponding to the number of lanes. + Must be "cp0-pcie0-x4-lane0-phy", "cp0-pcie0-x4-lane1-phy" for + 2 PHYs. + Example: pcie@f2600000 { diff --git a/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml new file mode 100644 index 000000000000..8a56a8526cef --- /dev/null +++ b/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/lantiq,vrx200-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq VRX200 and ARX300 PCIe PHY Device Tree Bindings + +maintainers: + - Martin Blumenstingl <martin.blumenstingl@googlemail.com> + +properties: + "#phy-cells": + const: 1 + description: selects the PHY mode as defined in <dt-bindings/phy/phy-lantiq-vrx200-pcie.h> + + compatible: + enum: + - lantiq,vrx200-pcie-phy + - lantiq,arx300-pcie-phy + + reg: + maxItems: 1 + + clocks: + items: + - description: PHY module clock + - description: PDI register clock + + clock-names: + items: + - const: phy + - const: pdi + + resets: + items: + - description: exclusive PHY reset line + - description: shared reset line between the PCIe PHY and PCIe controller + + resets-names: + items: + - const: phy + - const: pcie + + lantiq,rcu: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the RCU syscon + + lantiq,rcu-endian-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: the offset of the endian registers for this PHY instance in the RCU syscon + + lantiq,rcu-big-endian-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: the mask to set the PDI (PHY) registers for this PHY instance to big endian + + big-endian: + description: Configures the PDI (PHY) registers in big-endian mode + type: boolean + + little-endian: + description: Configures the PDI (PHY) registers in big-endian mode + type: boolean + +required: + - "#phy-cells" + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - lantiq,rcu + - lantiq,rcu-endian-offset + - lantiq,rcu-big-endian-mask + +additionalProperties: false + +examples: + - | + pcie0_phy: phy@106800 { + compatible = "lantiq,vrx200-pcie-phy"; + reg = <0x106800 0x100>; + lantiq,rcu = <&rcu0>; + lantiq,rcu-endian-offset = <0x4c>; + lantiq,rcu-big-endian-mask = <0x80>; /* bit 7 */ + big-endian; + clocks = <&pmu 32>, <&pmu 36>; + clock-names = "phy", "pdi"; + resets = <&reset0 12 24>, <&reset0 22 22>; + reset-names = "phy", "pcie"; + #phy-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt index cf2cd86db267..8c60e6985950 100644 --- a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt +++ b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt @@ -25,6 +25,13 @@ Required properties: - #address-cells: should be 1. - #size-cells: should be 0. +Optional properlties: + +- clocks: pointers to the reference clocks for this device (CP110 only), + consequently: MG clock, MG Core clock, AXI clock. +- clock-names: names of used clocks for CP110 only, must be : + "mg_clk", "mg_core_clk" and "axi_clk". + A sub-node is required for each comphy lane provided by the comphy. Required properties (child nodes): @@ -39,6 +46,9 @@ Examples: compatible = "marvell,comphy-cp110"; reg = <0x120000 0x6000>; marvell,system-controller = <&cpm_syscon0>; + clocks = <&CP110_LABEL(clk) 1 5>, <&CP110_LABEL(clk) 1 6>, + <&CP110_LABEL(clk) 1 18>; + clock-names = "mg_clk", "mg_core_clk", "axi_clk"; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index 91d3e78b3395..400df2da018a 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -37,7 +37,8 @@ properties: hwlocks: true st,syscfg: - $ref: "/schemas/types.yaml#/definitions/phandle-array" + allOf: + - $ref: "/schemas/types.yaml#/definitions/phandle-array" description: Should be phandle/offset/mask items: - description: Phandle to the syscon node which includes IRQ mux selection. diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml new file mode 100644 index 000000000000..aab70e8b681e --- /dev/null +++ b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 BayLibre, SAS +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/amlogic,meson-ee-pwrc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic Meson Everything-Else Power Domains + +maintainers: + - Neil Armstrong <narmstrong@baylibre.com> + +description: |+ + The Everything-Else Power Domains node should be the child of a syscon + node with the required property: + + - compatible: Should be the following: + "amlogic,meson-gx-hhi-sysctrl", "simple-mfd", "syscon" + + Refer to the the bindings described in + Documentation/devicetree/bindings/mfd/syscon.txt + +properties: + compatible: + enum: + - amlogic,meson-g12a-pwrc + - amlogic,meson-sm1-pwrc + + clocks: + minItems: 2 + + clock-names: + items: + - const: vpu + - const: vapb + + resets: + minItems: 11 + + reset-names: + items: + - const: viu + - const: venc + - const: vcbus + - const: bt656 + - const: rdma + - const: venci + - const: vencp + - const: vdac + - const: vdi6 + - const: vencl + - const: vid_lock + + "#power-domain-cells": + const: 1 + + amlogic,ao-sysctrl: + description: phandle to the AO sysctrl node + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - clocks + - clock-names + - resets + - reset-names + - "#power-domain-cells" + - amlogic,ao-sysctrl + +examples: + - | + pwrc: power-controller { + compatible = "amlogic,meson-sm1-pwrc"; + #power-domain-cells = <1>; + amlogic,ao-sysctrl = <&rti>; + resets = <&reset_viu>, + <&reset_venc>, + <&reset_vcbus>, + <&reset_bt656>, + <&reset_rdma>, + <&reset_venci>, + <&reset_vencp>, + <&reset_vdac>, + <&reset_vdi6>, + <&reset_vencl>, + <&reset_vid_lock>; + reset-names = "viu", "venc", "vcbus", "bt656", + "rdma", "venci", "vencp", "vdac", + "vdi6", "vencl", "vid_lock"; + clocks = <&clk_vpu>, <&clk_vapb>; + clock-names = "vpu", "vapb"; + }; diff --git a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt index 3ae9f1088845..b9f58e480349 100644 --- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt @@ -34,6 +34,9 @@ Optional input supply properties: - inl67-supply: The input supply for LDO_REG3 and LDO_REG4 Any standard regulator properties can be used to configure the single regulator. +regulator-initial-mode, regulator-allowed-modes and regulator-mode could be specified +for act8865 using mode values from dt-bindings/regulator/active-semi,8865-regulator.h +file. The valid names for regulators are: - for act8846: @@ -47,6 +50,8 @@ The valid names for regulators are: Example: -------- +#include <dt-bindings/regulator/active-semi,8865-regulator.h> + i2c1: i2c@f0018000 { pmic: act8865@5b { compatible = "active-semi,act8865"; @@ -65,9 +70,19 @@ Example: regulator-name = "VCC_1V2"; regulator-min-microvolt = <1100000>; regulator-max-microvolt = <1300000>; - regulator-suspend-mem-microvolt = <1150000>; - regulator-suspend-standby-microvolt = <1150000>; regulator-always-on; + + regulator-allowed-modes = <ACT8865_REGULATOR_MODE_FIXED>, + <ACT8865_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8865_REGULATOR_MODE_FIXED>; + + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-min-microvolt = <1150000>; + regulator-suspend-max-microvolt = <1150000>; + regulator-changeable-in-suspend; + regulator-mode = <ACT8865_REGULATOR_MODE_LOWPOWER>; + }; }; vcc_3v3_reg: DCDC_REG3 { @@ -82,6 +97,14 @@ Example: regulator-min-microvolt = <3300000>; regulator-max-microvolt = <3300000>; regulator-always-on; + + regulator-allowed-modes = <ACT8865_REGULATOR_MODE_NORMAL>, + <ACT8865_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8865_REGULATOR_MODE_NORMAL>; + + regulator-state-mem { + regulator-off-in-suspend; + }; }; vddfuse_reg: LDO_REG2 { diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index a650b457085d..a78150c47aa2 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -19,9 +19,19 @@ description: allOf: - $ref: "regulator.yaml#" +if: + properties: + compatible: + contains: + const: regulator-fixed-clock + required: + - clocks + properties: compatible: - const: regulator-fixed + enum: + - const: regulator-fixed + - const: regulator-fixed-clock regulator-name: true @@ -29,6 +39,13 @@ properties: description: gpio to use for enable control maxItems: 1 + clocks: + description: + clock to use for enable control. This binding is only available if + the compatible is chosen to regulator-fixed-clock. The clock binding + is mandatory if compatible is chosen to regulator-fixed-clock. + maxItems: 1 + startup-delay-us: description: startup time in microseconds $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt new file mode 100644 index 000000000000..9a90a92f2d7e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt @@ -0,0 +1,358 @@ +MediaTek MT6358 Regulator + +All voltage regulators provided by the MT6358 PMIC are described as the +subnodes of the MT6358 regulators node. Each regulator is named according +to its regulator type, buck_<name> and ldo_<name>. The definition for each +of these nodes is defined using the standard binding for regulators at +Documentation/devicetree/bindings/regulator/regulator.txt. + +The valid names for regulators are:: +BUCK: + buck_vdram1, buck_vcore, buck_vpa, buck_vproc11, buck_vproc12, buck_vgpu, + buck_vs2, buck_vmodem, buck_vs1 +LDO: + ldo_vdram2, ldo_vsim1, ldo_vibr, ldo_vrf12, ldo_vio18, ldo_vusb, ldo_vcamio, + ldo_vcamd, ldo_vcn18, ldo_vfe28, ldo_vsram_proc11, ldo_vcn28, ldo_vsram_others, + ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, ldo_vmch, ldo_vbif28, + ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, ldo_vrf18, + ldo_vcn33_bt, ldo_vcn33_wifi, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28, + ldo_vsim2 + +Example: + + pmic { + compatible = "mediatek,mt6358"; + + mt6358regulator: mt6358regulator { + compatible = "mediatek,mt6358-regulator"; + + mt6358_vdram1_reg: buck_vdram1 { + regulator-compatible = "buck_vdram1"; + regulator-name = "vdram1"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2087500>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-always-on; + }; + + mt6358_vcore_reg: buck_vcore { + regulator-name = "vcore"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-always-on; + }; + + mt6358_vpa_reg: buck_vpa { + regulator-name = "vpa"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <3650000>; + regulator-ramp-delay = <50000>; + regulator-enable-ramp-delay = <250>; + }; + + mt6358_vproc11_reg: buck_vproc11 { + regulator-name = "vproc11"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-always-on; + }; + + mt6358_vproc12_reg: buck_vproc12 { + regulator-name = "vproc12"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-always-on; + }; + + mt6358_vgpu_reg: buck_vgpu { + regulator-name = "vgpu"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + }; + + mt6358_vs2_reg: buck_vs2 { + regulator-name = "vs2"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <2087500>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-always-on; + }; + + mt6358_vmodem_reg: buck_vmodem { + regulator-name = "vmodem"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <900>; + regulator-always-on; + }; + + mt6358_vs1_reg: buck_vs1 { + regulator-name = "vs1"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <2587500>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-always-on; + }; + + mt6358_vdram2_reg: ldo_vdram2 { + regulator-name = "vdram2"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <3300>; + }; + + mt6358_vsim1_reg: ldo_vsim1 { + regulator-name = "vsim1"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <540>; + }; + + mt6358_vibr_reg: ldo_vibr { + regulator-name = "vibr"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <60>; + }; + + mt6358_vrf12_reg: ldo_vrf12 { + compatible = "regulator-fixed"; + regulator-name = "vrf12"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-enable-ramp-delay = <120>; + }; + + mt6358_vio18_reg: ldo_vio18 { + compatible = "regulator-fixed"; + regulator-name = "vio18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <2700>; + regulator-always-on; + }; + + mt6358_vusb_reg: ldo_vusb { + regulator-name = "vusb"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <270>; + regulator-always-on; + }; + + mt6358_vcamio_reg: ldo_vcamio { + compatible = "regulator-fixed"; + regulator-name = "vcamio"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vcamd_reg: ldo_vcamd { + regulator-name = "vcamd"; + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vcn18_reg: ldo_vcn18 { + compatible = "regulator-fixed"; + regulator-name = "vcn18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vfe28_reg: ldo_vfe28 { + compatible = "regulator-fixed"; + regulator-name = "vfe28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vsram_proc11_reg: ldo_vsram_proc11 { + regulator-name = "vsram_proc11"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + regulator-always-on; + }; + + mt6358_vcn28_reg: ldo_vcn28 { + compatible = "regulator-fixed"; + regulator-name = "vcn28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vsram_others_reg: ldo_vsram_others { + regulator-name = "vsram_others"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + regulator-always-on; + }; + + mt6358_vsram_gpu_reg: ldo_vsram_gpu { + regulator-name = "vsram_gpu"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + }; + + mt6358_vxo22_reg: ldo_vxo22 { + compatible = "regulator-fixed"; + regulator-name = "vxo22"; + regulator-min-microvolt = <2200000>; + regulator-max-microvolt = <2200000>; + regulator-enable-ramp-delay = <120>; + regulator-always-on; + }; + + mt6358_vefuse_reg: ldo_vefuse { + regulator-name = "vefuse"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <1900000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vaux18_reg: ldo_vaux18 { + compatible = "regulator-fixed"; + regulator-name = "vaux18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vmch_reg: ldo_vmch { + regulator-name = "vmch"; + regulator-min-microvolt = <2900000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <60>; + }; + + mt6358_vbif28_reg: ldo_vbif28 { + compatible = "regulator-fixed"; + regulator-name = "vbif28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vsram_proc12_reg: ldo_vsram_proc12 { + regulator-name = "vsram_proc12"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1293750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + regulator-always-on; + }; + + mt6358_vcama1_reg: ldo_vcama1 { + regulator-name = "vcama1"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3000000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vemc_reg: ldo_vemc { + regulator-name = "vemc"; + regulator-min-microvolt = <2900000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <60>; + regulator-always-on; + }; + + mt6358_vio28_reg: ldo_vio28 { + compatible = "regulator-fixed"; + regulator-name = "vio28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_va12_reg: ldo_va12 { + compatible = "regulator-fixed"; + regulator-name = "va12"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-enable-ramp-delay = <270>; + regulator-always-on; + }; + + mt6358_vrf18_reg: ldo_vrf18 { + compatible = "regulator-fixed"; + regulator-name = "vrf18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <120>; + }; + + mt6358_vcn33_bt_reg: ldo_vcn33_bt { + regulator-name = "vcn33_bt"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3500000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vcn33_wifi_reg: ldo_vcn33_wifi { + regulator-name = "vcn33_wifi"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3500000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vcama2_reg: ldo_vcama2 { + regulator-name = "vcama2"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3000000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vmc_reg: ldo_vmc { + regulator-name = "vmc"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <60>; + }; + + mt6358_vldo28_reg: ldo_vldo28 { + regulator-name = "vldo28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <3000000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vaud28_reg: ldo_vaud28 { + compatible = "regulator-fixed"; + regulator-name = "vaud28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <270>; + }; + + mt6358_vsim2_reg: ldo_vsim2 { + regulator-name = "vsim2"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <540>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt index 14d2eee96b3d..bab9f71140b8 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt @@ -22,9 +22,12 @@ 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 PM8998: smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 PMI8998: bob - PM8005: smps1 - smps4 ======================== First Level Nodes - PMIC @@ -33,9 +36,13 @@ First Level Nodes - PMIC - compatible Usage: required Value type: <string> - Definition: Must be one of: "qcom,pm8998-rpmh-regulators", - "qcom,pmi8998-rpmh-regulators" or - "qcom,pm8005-rpmh-regulators". + Definition: Must be one of below: + "qcom,pm8005-rpmh-regulators" + "qcom,pm8009-rpmh-regulators" + "qcom,pm8150-rpmh-regulators" + "qcom,pm8150l-rpmh-regulators" + "qcom,pm8998-rpmh-regulators" + "qcom,pmi8998-rpmh-regulators" - qcom,pmic-id Usage: required diff --git a/Documentation/devicetree/bindings/regulator/sy8824x.txt b/Documentation/devicetree/bindings/regulator/sy8824x.txt new file mode 100644 index 000000000000..c5e95850c427 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/sy8824x.txt @@ -0,0 +1,24 @@ +SY8824C/SY8824E/SY20276 Voltage regulator + +Required properties: +- compatible: Must be one of the following. + "silergy,sy8824c" + "silergy,sy8824e" + "silergy,sy20276" + "silergy,sy20278" +- reg: I2C slave address + +Any property defined as part of the core regulator binding, defined in +./regulator.txt, can also be used. + +Example: + + vcore: regulator@00 { + compatible = "silergy,sy8824c"; + reg = <0x66>; + regulator-name = "vcore"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1150000>; + regulator-boot-on; + regulator-always-on; + }; diff --git a/Documentation/devicetree/bindings/regulator/twl-regulator.txt b/Documentation/devicetree/bindings/regulator/twl-regulator.txt index 74a91c4f8530..549f80436deb 100644 --- a/Documentation/devicetree/bindings/regulator/twl-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/twl-regulator.txt @@ -71,3 +71,10 @@ Example: regulator-min-microvolt = <1000000>; regulator-max-microvolt = <3000000>; }; + +For twl6030 regulators/LDOs: + + - ti,retain-on-reset: Does not turn off the supplies during warm + reset. Could be needed for VMMC, as TWL6030 + reset sequence for this signal does not comply + with the SD specification. diff --git a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt b/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt index c9919f4b92d2..94fd38b0d163 100644 --- a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt @@ -13,6 +13,7 @@ this layer. These clocks and resets should be described in each property. Required properties: - compatible: Should be "socionext,uniphier-pro4-usb3-regulator" - for Pro4 SoC + "socionext,uniphier-pro5-usb3-regulator" - for Pro5 SoC "socionext,uniphier-pxs2-usb3-regulator" - for PXs2 SoC "socionext,uniphier-ld20-usb3-regulator" - for LD20 SoC "socionext,uniphier-pxs3-usb3-regulator" - for PXs3 SoC @@ -20,12 +21,12 @@ Required properties: - clocks: A list of phandles to the clock gate for USB3 glue layer. According to the clock-names, appropriate clocks are required. - clock-names: Should contain - "gio", "link" - for Pro4 SoC + "gio", "link" - for Pro4 and Pro5 SoCs "link" - for others - resets: A list of phandles to the reset control for USB3 glue layer. According to the reset-names, appropriate resets are required. - reset-names: Should contain - "gio", "link" - for Pro4 SoC + "gio", "link" - for Pro4 and Pro5 SoCs "link" - for others See Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt index 13e095182db4..c2489e41a801 100644 --- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt +++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt @@ -8,6 +8,7 @@ Required properties: - compatible: - For i.MX7 SoCs should be "fsl,imx7d-src", "syscon" - For i.MX8MQ SoCs should be "fsl,imx8mq-src", "syscon" + - For i.MX8MM SoCs should be "fsl,imx8mm-src", "fsl,imx8mq-src", "syscon" - reg: should be register base and length as documented in the datasheet - interrupts: Should contain SRC interrupt @@ -46,5 +47,6 @@ Example: For list of all valid reset indices see -<dt-bindings/reset/imx7-reset.h> for i.MX7 and -<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ +<dt-bindings/reset/imx7-reset.h> for i.MX7, +<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ and +<dt-bindings/reset/imx8mq-reset.h> for i.MX8MM diff --git a/Documentation/devicetree/bindings/reset/snps,dw-reset.txt b/Documentation/devicetree/bindings/reset/snps,dw-reset.txt new file mode 100644 index 000000000000..f94f911dd98d --- /dev/null +++ b/Documentation/devicetree/bindings/reset/snps,dw-reset.txt @@ -0,0 +1,30 @@ +Synopsys DesignWare Reset controller +======================================= + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +Required properties: + +- compatible: should be one of the following. + "snps,dw-high-reset" - for active high configuration + "snps,dw-low-reset" - for active low configuration + +- reg: physical base address of the controller and length of memory mapped + region. + +- #reset-cells: must be 1. + +example: + + dw_rst_1: reset-controller@0000 { + compatible = "snps,dw-high-reset"; + reg = <0x0000 0x4>; + #reset-cells = <1>; + }; + + dw_rst_2: reset-controller@1000 {i + compatible = "snps,dw-low-reset"; + reg = <0x1000 0x8>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/riscv/cpus.txt b/Documentation/devicetree/bindings/riscv/cpus.txt deleted file mode 100644 index adf7b7af5dc3..000000000000 --- a/Documentation/devicetree/bindings/riscv/cpus.txt +++ /dev/null @@ -1,162 +0,0 @@ -=================== -RISC-V CPU Bindings -=================== - -The device tree allows to describe the layout of CPUs in a system through -the "cpus" node, which in turn contains a number of subnodes (ie "cpu") -defining properties for every cpu. - -Bindings for CPU nodes follow the Devicetree Specification, available from: - -https://www.devicetree.org/specifications/ - -with updates for 32-bit and 64-bit RISC-V systems provided in this document. - -=========== -Terminology -=========== - -This document uses some terminology common to the RISC-V community that is not -widely used, the definitions of which are listed here: - -* hart: A hardware execution context, which contains all the state mandated by - the RISC-V ISA: a PC and some registers. This terminology is designed to - disambiguate software's view of execution contexts from any particular - microarchitectural implementation strategy. For example, my Intel laptop is - described as having one socket with two cores, each of which has two hyper - threads. Therefore this system has four harts. - -===================================== -cpus and cpu node bindings definition -===================================== - -The RISC-V architecture, in accordance with the Devicetree Specification, -requires the cpus and cpu nodes to be present and contain the properties -described below. - -- cpus node - - Description: Container of cpu nodes - - The node name must be "cpus". - - A cpus node must define the following properties: - - - #address-cells - Usage: required - Value type: <u32> - Definition: must be set to 1 - - #size-cells - Usage: required - Value type: <u32> - Definition: must be set to 0 - -- cpu node - - Description: Describes a hart context - - PROPERTIES - - - device_type - Usage: required - Value type: <string> - Definition: must be "cpu" - - reg - Usage: required - Value type: <u32> - Definition: The hart ID of this CPU node - - compatible: - Usage: required - Value type: <stringlist> - Definition: must contain "riscv", may contain one of - "sifive,rocket0" - - mmu-type: - Usage: optional - Value type: <string> - Definition: Specifies the CPU's MMU type. Possible values are - "riscv,sv32" - "riscv,sv39" - "riscv,sv48" - - riscv,isa: - Usage: required - Value type: <string> - Definition: Contains the RISC-V ISA string of this hart. These - ISA strings are defined by the RISC-V ISA manual. - -Example: SiFive Freedom U540G Development Kit ---------------------------------------------- - -This system contains two harts: a hart marked as disabled that's used for -low-level system tasks and should be ignored by Linux, and a second hart that -Linux is allowed to run on. - - cpus { - #address-cells = <1>; - #size-cells = <0>; - timebase-frequency = <1000000>; - cpu@0 { - clock-frequency = <1600000000>; - compatible = "sifive,rocket0", "riscv"; - device_type = "cpu"; - i-cache-block-size = <64>; - i-cache-sets = <128>; - i-cache-size = <16384>; - next-level-cache = <&L15 &L0>; - reg = <0>; - riscv,isa = "rv64imac"; - status = "disabled"; - L10: interrupt-controller { - #interrupt-cells = <1>; - compatible = "riscv,cpu-intc"; - interrupt-controller; - }; - }; - cpu@1 { - clock-frequency = <1600000000>; - compatible = "sifive,rocket0", "riscv"; - d-cache-block-size = <64>; - d-cache-sets = <64>; - d-cache-size = <32768>; - d-tlb-sets = <1>; - d-tlb-size = <32>; - device_type = "cpu"; - i-cache-block-size = <64>; - i-cache-sets = <64>; - i-cache-size = <32768>; - i-tlb-sets = <1>; - i-tlb-size = <32>; - mmu-type = "riscv,sv39"; - next-level-cache = <&L15 &L0>; - reg = <1>; - riscv,isa = "rv64imafdc"; - status = "okay"; - tlb-split; - L13: interrupt-controller { - #interrupt-cells = <1>; - compatible = "riscv,cpu-intc"; - interrupt-controller; - }; - }; - }; - -Example: Spike ISA Simulator with 1 Hart ----------------------------------------- - -This device tree matches the Spike ISA golden model as run with `spike -p1`. - - cpus { - cpu@0 { - device_type = "cpu"; - reg = <0x00000000>; - status = "okay"; - compatible = "riscv"; - riscv,isa = "rv64imafdc"; - mmu-type = "riscv,sv48"; - clock-frequency = <0x3b9aca00>; - interrupt-controller { - #interrupt-cells = <0x00000001>; - interrupt-controller; - compatible = "riscv,cpu-intc"; - } - } - } diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index c899111aa5e3..b261a3015f84 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -10,6 +10,18 @@ maintainers: - Paul Walmsley <paul.walmsley@sifive.com> - Palmer Dabbelt <palmer@sifive.com> +description: | + This document uses some terminology common to the RISC-V community + that is not widely used, the definitions of which are listed here: + + hart: A hardware execution context, which contains all the state + mandated by the RISC-V ISA: a PC and some registers. This + terminology is designed to disambiguate software's view of execution + contexts from any particular microarchitectural implementation + strategy. For example, an Intel laptop containing one socket with + two cores, each of which has two hyperthreads, could be described as + having four harts. + properties: compatible: items: @@ -50,6 +62,10 @@ properties: User-Level ISA document, available from https://riscv.org/specifications/ + While the isa strings in ISA specification are case + insensitive, letters in the riscv,isa string must be all + lowercase to simplify parsing. + timebase-frequency: type: integer minimum: 1 diff --git a/Documentation/devicetree/bindings/riscv/sifive.yaml b/Documentation/devicetree/bindings/riscv/sifive.yaml index 9d17dc2f3f84..3ab532713dc1 100644 --- a/Documentation/devicetree/bindings/riscv/sifive.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive.yaml @@ -19,7 +19,7 @@ properties: compatible: items: - enum: - - sifive,freedom-unleashed-a00 + - sifive,hifive-unleashed-a00 - const: sifive,fu540-c000 - const: sifive,fu540 ... diff --git a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt index 214940093b55..fb4846160047 100644 --- a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt +++ b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt @@ -12,7 +12,7 @@ Optional properties: which disables using this rng to automatically fill the kernel's entropy pool. -N.B. currently 'reg' must be four bytes wide and aligned +N.B. currently 'reg' must be at least four bytes wide and 32-bit aligned Example: diff --git a/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt new file mode 100644 index 000000000000..f1bbe0826be5 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt @@ -0,0 +1,22 @@ +* Freescale LINFlexD UART + +The LINFlexD controller implements several LIN protocol versions, as well as +support for full-duplex UART communication through 8-bit and 9-bit frames. + +See chapter 47 ("LINFlexD") in the reference manual[1]. + +Required properties: +- compatible : + - "fsl,s32v234-linflexuart" for LINFlexD configured in UART mode, which + is compatible with the one integrated on S32V234 SoC +- reg : Address and length of the register set for the device +- interrupts : Should contain uart interrupt + +Example: +uart0: serial@40053000 { + compatible = "fsl,s32v234-linflexuart"; + reg = <0x0 0x40053000 0x0 0x1000>; + interrupts = <0 59 4>; +}; + +[1] https://www.nxp.com/webapp/Download?colCode=S32V234RM diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt index 21483ba820bc..3495eee81d53 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt @@ -13,7 +13,10 @@ Required properties: - reg : Address and length of the register set for the device - interrupts : Should contain uart interrupt - clocks : phandle + clock specifier pairs, one for each entry in clock-names -- clock-names : should contain: "ipg" - the uart clock +- clock-names : For vf610/ls1021a/imx7ulp, "ipg" clock is for uart bus/baud + clock. For imx8qxp lpuart, "ipg" clock is bus clock that is used to access + lpuart controller registers, it also requires "baud" clock for module to + receive/transmit data. Optional properties: - dmas: A list of two dma specifiers, one for each entry in dma-names. diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 6fdffb735fb9..3a3b57079f0d 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -9,6 +9,7 @@ Required properties: * "mediatek,mt6589-uart" for MT6589 compatible UARTS * "mediatek,mt6755-uart" for MT6755 compatible UARTS * "mediatek,mt6765-uart" for MT6765 compatible UARTS + * "mediatek,mt6779-uart" for MT6779 compatible UARTS * "mediatek,mt6795-uart" for MT6795 compatible UARTS * "mediatek,mt6797-uart" for MT6797 compatible UARTS * "mediatek,mt7622-uart" for MT7622 compatible UARTS diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt index d7edf732eb7f..f709304036c2 100644 --- a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt +++ b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt @@ -1,7 +1,12 @@ NVIDIA Tegra20/Tegra30 high speed (DMA based) UART controller driver. Required properties: -- compatible : should be "nvidia,tegra30-hsuart", "nvidia,tegra20-hsuart". +- compatible : should be, + "nvidia,tegra20-hsuart" for Tegra20, + "nvidia,tegra30-hsuart" for Tegra30, + "nvidia,tegra186-hsuart" for Tegra186, + "nvidia,tegra194-hsuart" for Tegra194. + - reg: Should contain UART controller registers location and length. - interrupts: Should contain UART controller interrupts. - clocks: Must contain one entry, for the module clock. @@ -19,6 +24,37 @@ Required properties: Optional properties: - nvidia,enable-modem-interrupt: Enable modem interrupts. Should be enable only if all 8 lines of UART controller are pinmuxed. +- nvidia,adjust-baud-rates: List of entries providing percentage of baud rate + adjustment within a range. + Each entry contains sets of 3 values. Range low/high and adjusted rate. + <range_low range_high adjusted_rate> + When baud rate set on controller falls within the range mentioned in this + field, baud rate will be adjusted by percentage mentioned here. + Ex: <9600 115200 200> + Increase baud rate by 2% when set baud rate falls within range 9600 to 115200 + +Baud Rate tolerance: + Standard UART devices are expected to have tolerance for baud rate error by + -4 to +4 %. All Tegra devices till Tegra210 had this support. However, + Tegra186 chip has a known hardware issue. UART Rx baud rate tolerance level + is 0% to +4% in 1-stop config. Otherwise, the received data will have + corruption/invalid framing errors. Parker errata suggests adjusting baud + rate to be higher than the deviations observed in Tx. + + Tx deviation of connected device can be captured over scope (or noted from + its spec) for valid range and Tegra baud rate has to be set above actual + Tx baud rate observed. To do this we use nvidia,adjust-baud-rates + + As an example, consider there is deviation observed in Tx for baud rates as + listed below. + 0 to 9600 has 1% deviation + 9600 to 115200 2% deviation + This slight deviation is expcted and Tegra UART is expected to handle it. Due + to the issue stated above, baud rate on Tegra UART should be set equal to or + above deviation observed for avoiding frame errors. + Property should be set like this + nvidia,adjust-baud-rates = <0 9600 100>, + <9600 115200 200>; Example: @@ -33,4 +69,5 @@ serial@70006000 { reset-names = "serial"; dmas = <&apbdma 8>, <&apbdma 8>; dma-names = "rx", "tx"; + nvidia,adjust-baud-rates = <1000000 4000000 136>; /* 1.36% shift */ }; diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.txt b/Documentation/devicetree/bindings/serial/sifive-serial.txt deleted file mode 100644 index c86b1e524159..000000000000 --- a/Documentation/devicetree/bindings/serial/sifive-serial.txt +++ /dev/null @@ -1,33 +0,0 @@ -SiFive asynchronous serial interface (UART) - -Required properties: - -- compatible: should be something similar to - "sifive,<chip>-uart" for the UART as integrated - on a particular chip, and "sifive,uart<version>" for the - general UART IP block programming model. Supported - compatible strings as of the date of this writing are: - "sifive,fu540-c000-uart" for the SiFive UART v0 as - integrated onto the SiFive FU540 chip, or "sifive,uart0" - for the SiFive UART v0 IP block with no chip integration - tweaks (if any) -- reg: address and length of the register space -- interrupts: Should contain the UART interrupt identifier -- clocks: Should contain a clock identifier for the UART's parent clock - - -UART HDL that corresponds to the IP block version numbers can be found -here: - -https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/uart - - -Example: - -uart0: serial@10010000 { - compatible = "sifive,fu540-c000-uart", "sifive,uart0"; - interrupt-parent = <&plic0>; - interrupts = <80>; - reg = <0x0 0x10010000 0x0 0x1000>; - clocks = <&prci PRCI_CLK_TLCLK>; -}; diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.yaml b/Documentation/devicetree/bindings/serial/sifive-serial.yaml new file mode 100644 index 000000000000..e8d3aeda1202 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/sifive-serial.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/sifive-serial.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SiFive asynchronous serial interface (UART) + +maintainers: + - Pragnesh Patel <pragnesh.patel@sifive.com> + - Paul Walmsley <paul.walmsley@sifive.com> + - Palmer Dabbelt <palmer@sifive.com> + +allOf: + - $ref: /schemas/serial.yaml# + +properties: + compatible: + items: + - const: sifive,fu540-c000-uart + - const: sifive,uart0 + + description: + Should be something similar to "sifive,<chip>-uart" + for the UART as integrated on a particular chip, + and "sifive,uart<version>" for the general UART IP + block programming model. + + UART HDL that corresponds to the IP block version + numbers can be found here - + + https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/uart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sifive-fu540-prci.h> + serial@10010000 { + compatible = "sifive,fu540-c000-uart", "sifive,uart0"; + interrupt-parent = <&plic0>; + interrupts = <80>; + reg = <0x0 0x10010000 0x0 0x1000>; + clocks = <&prci PRCI_CLK_TLCLK>; + }; + +... diff --git a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt index a6b19485c9dc..8620f7fcbd50 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt +++ b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt @@ -20,6 +20,11 @@ Optional properties: linux,rs485-enabled-at-boot-time: see rs485.txt. - dmas: phandle(s) to DMA controller node(s). Refer to stm32-dma.txt - dma-names: "rx" and/or "tx" +- wakeup-source: bool flag to indicate this device has wakeup capabilities +- interrupt-names, if optional wake-up interrupt is used, should be: + - "event": the name for the interrupt line of the USART instance + - "wakeup" the name for the optional wake-up interrupt + Examples: usart4: serial@40004c00 { diff --git a/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt index 6bf6b43f8dd8..3dd563cec794 100644 --- a/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt +++ b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt @@ -11,6 +11,7 @@ Required properties: "amlogic,meson8b-clk-measure" for Meson8b SoCs "amlogic,meson-axg-clk-measure" for AXG SoCs "amlogic,meson-g12a-clk-measure" for G12a SoCs + "amlogic,meson-sm1-clk-measure" for SM1 SoCs - reg: base address and size of the Clock Measurer register space. Example: diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt index d7afaff5faff..05ec2a838c54 100644 --- a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt +++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt @@ -18,7 +18,8 @@ Required properties: - reg : offset and length of the device registers. - bus-frequency : the clock frequency for QUICC Engine. - fsl,qe-num-riscs: define how many RISC engines the QE has. -- fsl,qe-num-snums: define how many serial number(SNUM) the QE can use for the +- fsl,qe-snums: This property has to be specified as '/bits/ 8' value, + defining the array of serial number (SNUM) values for the virtual threads. Optional properties: @@ -34,6 +35,11 @@ Recommended properties - brg-frequency : the internal clock source frequency for baud-rate generators in Hz. +Deprecated properties +- fsl,qe-num-snums: define how many serial number(SNUM) the QE can use + for the threads. Use fsl,qe-snums instead to not only specify the + number of snums, but also their values. + Example: qe@e0100000 { #address-cells = <1>; @@ -44,6 +50,11 @@ Example: reg = <e0100000 480>; brg-frequency = <0>; bus-frequency = <179A7B00>; + fsl,qe-snums = /bits/ 8 < + 0x04 0x05 0x0C 0x0D 0x14 0x15 0x1C 0x1D + 0x24 0x25 0x2C 0x2D 0x34 0x35 0x88 0x89 + 0x98 0x99 0xA8 0xA9 0xB8 0xB9 0xC8 0xC9 + 0xD8 0xD9 0xE8 0xE9>; } * Multi-User RAM (MURAM) diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt index 954ffee0a9c4..4fc571e78f01 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt @@ -15,7 +15,10 @@ power-domains. - compatible: Usage: required Value type: <string> - Definition: must be "qcom,sdm845-aoss-qmp" + Definition: must be one of: + "qcom,sc7180-aoss-qmp" + "qcom,sdm845-aoss-qmp" + "qcom,sm8150-aoss-qmp" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt index f7b00a7c0f68..f541d1f776a2 100644 --- a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt +++ b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt @@ -19,8 +19,15 @@ child of the pmmc node. Required Properties: -------------------- - compatible: should be "ti,sci-pm-domain" -- #power-domain-cells: Must be 1 so that an id can be provided in each - device node. +- #power-domain-cells: Can be one of the following: + 1: Containing the device id of each node + 2: First entry should be device id + Second entry should be one of the floowing: + TI_SCI_PD_EXCLUSIVE: To allow device to be + exclusively controlled by + the requesting hosts. + TI_SCI_PD_SHARED: To allow device to be shared + by multiple hosts. Example (K2G): ------------- diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml index e0284d8c3b63..38d4cede0860 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml @@ -70,7 +70,9 @@ allOf: properties: compatible: contains: - const: allwinner,sun8i-h3-spdif + enum: + - allwinner,sun8i-h3-spdif + - allwinner,sun50i-h6-spdif then: properties: diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml new file mode 100644 index 000000000000..f290eb72a878 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/allwinner,sun50i-a64-codec-analog.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A64 Analog Codec Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + compatible: + const: allwinner,sun50i-a64-codec-analog + + reg: + maxItems: 1 + + cpvdd-supply: + description: + Regulator for the headphone amplifier + +required: + - compatible + - reg + - cpvdd-supply + +additionalProperties: false + +examples: + - | + codec_analog: codec-analog@1f015c0 { + compatible = "allwinner,sun50i-a64-codec-analog"; + reg = <0x01f015c0 0x4>; + cpvdd-supply = <®_eldo1>; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml new file mode 100644 index 000000000000..5e7cc05bbff1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/allwinner,sun8i-a33-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A33 Codec Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#sound-dai-cells": + const: 0 + + compatible: + const: allwinner,sun8i-a33-codec + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + +required: + - "#sound-dai-cells" + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + audio-codec@1c22e00 { + #sound-dai-cells = <0>; + compatible = "allwinner,sun8i-a33-codec"; + reg = <0x01c22e00 0x400>; + interrupts = <0 29 4>; + clocks = <&ccu 47>, <&ccu 92>; + clock-names = "bus", "mod"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt index 4330fc9dca6d..3080979350a0 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt @@ -4,13 +4,18 @@ Required properties: - compatible: 'amlogic,axg-toddr' or 'amlogic,axg-toddr' or 'amlogic,g12a-frddr' or - 'amlogic,g12a-toddr' + 'amlogic,g12a-toddr' or + 'amlogic,sm1-frddr' or + 'amlogic,sm1-toddr' - reg: physical base address of the controller and length of memory mapped region. - interrupts: interrupt specifier for the fifo. - clocks: phandle to the fifo peripheral clock provided by the audio clock controller. -- resets: phandle to memory ARB line provided by the arb reset controller. +- resets: list of reset phandle, one for each entry reset-names. +- reset-names: should contain the following: + * "arb" : memory ARB line (required) + * "rst" : dedicated device reset line (optional) - #sound-dai-cells: must be 0. Example of FRDDR A on the A113 SoC: diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt index 73f473a9365f..716878107a24 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt @@ -2,7 +2,8 @@ Required properties: - compatible: 'amlogic,axg-pdm' or - 'amlogic,g12a-pdm' + 'amlogic,g12a-pdm' or + 'amlogic,sm1-pdm' - reg: physical base address of the controller and length of memory mapped region. - clocks: list of clock phandle, one for each entry clock-names. @@ -12,6 +13,9 @@ Required properties: * "sysclk" : dsp system clock - #sound-dai-cells: must be 0. +Optional property: +- resets: phandle to the dedicated reset line of the pdm input. + Example of PDM on the A113 SoC: pdm: audio-controller@ff632000 { diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt index 0b82504fa419..df92a4ecf288 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt @@ -2,7 +2,8 @@ Required properties: - compatible: 'amlogic,axg-spdifin' or - 'amlogic,g12a-spdifin' + 'amlogic,g12a-spdifin' or + 'amlogic,sm1-spdifin' - interrupts: interrupt specifier for the spdif input. - clocks: list of clock phandle, one for each entry clock-names. - clock-names: should contain the following: @@ -10,6 +11,9 @@ Required properties: * "refclk" : spdif input reference clock - #sound-dai-cells: must be 0. +Optional property: +- resets: phandle to the dedicated reset line of the spdif input. + Example on the A113 SoC: spdifin: audio-controller@400 { diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt index 826152730508..28381dd1f633 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt @@ -2,13 +2,17 @@ Required properties: - compatible: 'amlogic,axg-spdifout' or - 'amlogic,g12a-spdifout' + 'amlogic,g12a-spdifout' or + 'amlogic,sm1-spdifout' - clocks: list of clock phandle, one for each entry clock-names. - clock-names: should contain the following: * "pclk" : peripheral clock. * "mclk" : master clock - #sound-dai-cells: must be 0. +Optional property: +- resets: phandle to the dedicated reset line of the spdif output. + Example on the A113 SoC: spdifout: audio-controller@480 { diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt index 8835a43edfbb..5996c0cd89c2 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt @@ -4,7 +4,9 @@ Required properties: - compatible: 'amlogic,axg-tdmin' or 'amlogic,axg-tdmout' or 'amlogic,g12a-tdmin' or - 'amlogic,g12a-tdmout' + 'amlogic,g12a-tdmout' or + 'amlogic,sm1-tdmin' or + 'amlogic,sm1-tdmout - reg: physical base address of the controller and length of memory mapped region. - clocks: list of clock phandle, one for each entry clock-names. diff --git a/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt b/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt index aa6c35570d31..4e8cd7eb7cec 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt @@ -1,10 +1,12 @@ * Amlogic HDMI Tx control glue Required properties: -- compatible: "amlogic,g12a-tohdmitx" +- compatible: "amlogic,g12a-tohdmitx" or + "amlogic,sm1-tohdmitx" - reg: physical base address of the controller and length of memory mapped region. - #sound-dai-cells: should be 1. +- resets: phandle to the dedicated reset line of the hdmitx glue. Example on the S905X2 SoC: @@ -12,6 +14,7 @@ tohdmitx: audio-controller@744 { compatible = "amlogic,g12a-tohdmitx"; reg = <0x0 0x744 0x0 0x4>; #sound-dai-cells = <1>; + resets = <&clkc_audio AUD_RESET_TOHDMITX>; }; Example of an 'amlogic,axg-sound-card': diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.txt b/Documentation/devicetree/bindings/sound/everest,es8316.txt new file mode 100644 index 000000000000..1bf03c5f2af4 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/everest,es8316.txt @@ -0,0 +1,23 @@ +Everest ES8316 audio CODEC + +This device supports both I2C and SPI. + +Required properties: + + - compatible : should be "everest,es8316" + - reg : the I2C address of the device for I2C + +Optional properties: + + - clocks : a list of phandle, should contain entries for clock-names + - clock-names : should include as follows: + "mclk" : master clock (MCLK) of the device + +Example: + +es8316: codec@11 { + compatible = "everest,es8316"; + reg = <0x11>; + clocks = <&clks 10>; + clock-names = "mclk"; +}; diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index 5b9914367610..0e6e2166f76c 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -7,8 +7,11 @@ other DSPs. It has up to six transmitters and four receivers. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-esai" or - "fsl,vf610-esai" + - compatible : Compatible list, should contain one of the following + compatibles: + "fsl,imx35-esai", + "fsl,vf610-esai", + "fsl,imx6ull-esai", - reg : Offset and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt index 2e726b983845..0dc83cc4a236 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -8,7 +8,9 @@ codec/DSP interfaces. Required properties: - compatible : Compatible list, contains "fsl,vf610-sai", - "fsl,imx6sx-sai" or "fsl,imx6ul-sai" + "fsl,imx6sx-sai", "fsl,imx6ul-sai", + "fsl,imx7ulp-sai", "fsl,imx8mq-sai" or + "fsl,imx8qm-sai". - reg : Offset and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt b/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt deleted file mode 100644 index 056a098495cc..000000000000 --- a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt +++ /dev/null @@ -1,14 +0,0 @@ -* Allwinner A64 Codec Analog Controls - -Required properties: -- compatible: must be one of the following compatibles: - - "allwinner,sun50i-a64-codec-analog" -- reg: must contain the registers location and length -- cpvdd-supply: Regulator supply for the headphone amplifier - -Example: - codec_analog: codec-analog@1f015c0 { - compatible = "allwinner,sun50i-a64-codec-analog"; - reg = <0x01f015c0 0x4>; - cpvdd-supply = <®_eldo1>; - }; diff --git a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt deleted file mode 100644 index 2ca3d138528e..000000000000 --- a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt +++ /dev/null @@ -1,63 +0,0 @@ -Allwinner SUN8I audio codec ------------------------------------- - -On Sun8i-A33 SoCs, the audio is separated in different parts: - - A DAI driver. It uses the "sun4i-i2s" driver which is - documented here: - Documentation/devicetree/bindings/sound/sun4i-i2s.txt - - An analog part of the codec which is handled as PRCM registers. - See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt - - An digital part of the codec which is documented in this current - binding documentation. - - And finally, an audio card which links all the above components. - The simple-audio card will be used. - See Documentation/devicetree/bindings/sound/simple-card.txt - -This bindings documentation exposes Sun8i codec (digital part). - -Required properties: -- compatible: must be "allwinner,sun8i-a33-codec" -- reg: must contain the registers location and length -- interrupts: must contain the codec interrupt -- clocks: a list of phandle + clock-specifer pairs, one for each entry - in clock-names. -- clock-names: should contain followings: - - "bus": the parent APB clock for this controller - - "mod": the parent module clock - -Here is an example to add a sound card and the codec binding on sun8i SoCs that -are similar to A33 using simple-card: - - sound { - compatible = "simple-audio-card"; - simple-audio-card,name = "sun8i-a33-audio"; - simple-audio-card,format = "i2s"; - simple-audio-card,frame-master = <&link_codec>; - simple-audio-card,bitclock-master = <&link_codec>; - simple-audio-card,mclk-fs = <512>; - simple-audio-card,aux-devs = <&codec_analog>; - simple-audio-card,routing = - "Left DAC", "Digital Left DAC", - "Right DAC", "Digital Right DAC"; - - simple-audio-card,cpu { - sound-dai = <&dai>; - }; - - link_codec: simple-audio-card,codec { - sound-dai = <&codec>; - }; - - soc@1c00000 { - [...] - - audio-codec@1c22e00 { - #sound-dai-cells = <0>; - compatible = "allwinner,sun8i-a33-codec"; - reg = <0x01c22e00 0x400>; - interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&ccu CLK_BUS_CODEC>, <&ccu CLK_AC_DIG>; - clock-names = "bus", "mod"; - }; - }; - diff --git a/Documentation/devicetree/bindings/sound/uda1334.txt b/Documentation/devicetree/bindings/sound/uda1334.txt new file mode 100644 index 000000000000..f64071b25e8d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/uda1334.txt @@ -0,0 +1,17 @@ +UDA1334 audio CODEC + +This device uses simple GPIO pins for controlling codec settings. + +Required properties: + + - compatible : "nxp,uda1334" + - nxp,mute-gpios: a GPIO spec for the MUTE pin. + - nxp,deemph-gpios: a GPIO spec for the De-emphasis pin + +Example: + +uda1334: audio-codec { + compatible = "nxp,uda1334"; + nxp,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>; + nxp,deemph-gpios = <&gpio3 3 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt new file mode 100644 index 000000000000..a388005842ad --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt @@ -0,0 +1,47 @@ +* Nuvoton FLASH Interface Unit (FIU) SPI Controller + +NPCM FIU supports single, dual and quad communication interface. + +The NPCM7XX supports three FIU modules, +FIU0 and FIUx supports two chip selects, +FIU3 support four chip select. + +Required properties: + - compatible : "nuvoton,npcm750-fiu" for the NPCM7XX BMC + - #address-cells : should be 1. + - #size-cells : should be 0. + - 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 "control" and "memory" + - clocks : phandle of FIU reference clock. + +Required properties in case the pins can be muxed: + - pinctrl-names : a pinctrl state named "default" must be defined. + - pinctrl-0 : phandle referencing pin configuration of the device. + +Optional property: + - nuvoton,spix-mode: enable spix-mode for an expansion bus to an ASIC or CPLD. + +Aliases: +- All the FIU controller nodes should be represented in the aliases node using + the following format 'fiu{n}' where n is a unique number for the alias. + In the NPCM7XX BMC: + fiu0 represent fiu 0 controller + fiu1 represent fiu 3 controller + fiu2 represent fiu x controller + +Example: +fiu3: spi@c00000000 { + compatible = "nuvoton,npcm750-fiu"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfb000000 0x1000>, <0x80000000 0x10000000>; + reg-names = "control", "memory"; + clocks = <&clk NPCM7XX_CLK_AHB>; + pinctrl-names = "default"; + pinctrl-0 = <&spi3_pins>; + spi-nor@0 { + ... + }; +}; + diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 876c0623f322..732339275848 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -31,7 +31,7 @@ properties: If that property is used, the number of chip selects will be increased automatically with max(cs-gpios, hardware chip selects). - So if, for example, the controller has 2 CS lines, and the + So if, for example, the controller has 4 CS lines, and the cs-gpios looks like this cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>; @@ -73,7 +73,6 @@ patternProperties: Compatible of the SPI device. reg: - maxItems: 1 minimum: 0 maximum: 256 description: diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt index dcc7eaada511..162e024b95a0 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt @@ -6,6 +6,7 @@ Required properties: or "fsl,ls2080a-dspi" followed by "fsl,ls2085a-dspi" "fsl,ls1012a-dspi" followed by "fsl,ls1021a-v1.0-dspi" + "fsl,ls1088a-dspi" followed by "fsl,ls1021a-v1.0-dspi" - reg : Offset and length of the register set for the device - interrupts : Should contain SPI controller interrupt - clocks: from common clock binding: handle to dspi clock. diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt index e8f1d627d288..69dc5d57b1ef 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt @@ -3,9 +3,8 @@ Required properties: - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi", "fsl,imx7d-qspi", "fsl,imx6ul-qspi", - "fsl,ls1021a-qspi" + "fsl,ls1021a-qspi", "fsl,ls2080a-qspi" or - "fsl,ls2080a-qspi" followed by "fsl,ls1021a-qspi", "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 @@ -34,7 +33,11 @@ qspi0: quadspi@40044000 { 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>; }; }; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index c0f6c8ecfa2e..3a8079eb18c8 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -5,6 +5,7 @@ Required properties: - mediatek,mt2701-spi: for mt2701 platforms - mediatek,mt2712-spi: for mt2712 platforms - mediatek,mt6589-spi: for mt6589 platforms + - mediatek,mt6765-spi: for mt6765 platforms - mediatek,mt7622-spi: for mt7622 platforms - "mediatek,mt7629-spi", "mediatek,mt7622-spi": for mt7629 platforms - mediatek,mt8135-spi: for mt8135 platforms diff --git a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt b/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt index 8de589b376ce..2567c829e2dc 100644 --- a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt +++ b/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt @@ -25,18 +25,23 @@ data by ADI software channels at the same time, or two parallel routine of setti ADI registers will make ADI controller registers chaos to lead incorrect results. Then we need one hardware spinlock to synchronize between the multiple subsystems. +The new version ADI controller supplies multiple master channels for different +subsystem accessing, that means no need to add hardware spinlock to synchronize, +thus change the hardware spinlock support to be optional to keep backward +compatibility. + Required properties: - compatible: Should be "sprd,sc9860-adi". - reg: Offset and length of ADI-SPI controller register space. -- hwlocks: Reference to a phandle of a hwlock provider node. -- hwlock-names: Reference to hwlock name strings defined in the same order - as the hwlocks, should be "adi". - #address-cells: Number of cells required to define a chip select address on the ADI-SPI bus. Should be set to 1. - #size-cells: Size of cells required to define a chip select address size on the ADI-SPI bus. Should be set to 0. Optional properties: +- hwlocks: Reference to a phandle of a hwlock provider node. +- hwlock-names: Reference to hwlock name strings defined in the same order + as the hwlocks, should be "adi". - sprd,hw-channels: This is an array of channel values up to 49 channels. The first value specifies the hardware channel id which is used to transfer data triggered by hardware automatically, and the second diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml new file mode 100644 index 000000000000..20adc1c8e9cc --- /dev/null +++ b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/allwinner,sun4i-a10-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 Timer Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + compatible: + enum: + - allwinner,sun4i-a10-timer + - allwinner,sun8i-a23-timer + - allwinner,sun8i-v3s-timer + - allwinner,suniv-f1c100s-timer + + reg: + maxItems: 1 + + interrupts: + description: + List of timers interrupts + + clocks: + maxItems: 1 + +allOf: + - if: + properties: + compatible: + items: + const: allwinner,sun4i-a10-timer + + then: + properties: + interrupts: + minItems: 6 + maxItems: 6 + + - if: + properties: + compatible: + items: + const: allwinner,sun8i-a23-timer + + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + + - if: + properties: + compatible: + items: + const: allwinner,sun8i-v3s-timer + + then: + properties: + interrupts: + minItems: 3 + maxItems: 3 + + - if: + properties: + compatible: + items: + const: allwinner,suniv-f1c100s-timer + + then: + properties: + interrupts: + minItems: 3 + maxItems: 3 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + timer { + compatible = "allwinner,sun4i-a10-timer"; + reg = <0x01c20c00 0x400>; + interrupts = <22>, + <23>, + <24>, + <25>, + <67>, + <68>; + clocks = <&osc>; + }; + +... diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt b/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt deleted file mode 100644 index 3da9d515c03a..000000000000 --- a/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt +++ /dev/null @@ -1,19 +0,0 @@ -Allwinner A1X SoCs Timer Controller - -Required properties: - -- compatible : should be one of the following: - "allwinner,sun4i-a10-timer" - "allwinner,suniv-f1c100s-timer" -- reg : Specifies base physical address and size of the registers. -- interrupts : The interrupt of the first timer -- clocks: phandle to the source clock (usually a 24 MHz fixed clock) - -Example: - -timer { - compatible = "allwinner,sun4i-a10-timer"; - reg = <0x01c20c00 0x400>; - interrupts = <22>; - clocks = <&osc>; -}; diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt deleted file mode 100644 index 2c5c1be78360..000000000000 --- a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt +++ /dev/null @@ -1,26 +0,0 @@ -Allwinner SoCs High Speed Timer Controller - -Required properties: - -- compatible : should be "allwinner,sun5i-a13-hstimer" or - "allwinner,sun7i-a20-hstimer" -- reg : Specifies base physical address and size of the registers. -- interrupts : The interrupts of these timers (2 for the sun5i IP, 4 for the sun7i - one) -- clocks: phandle to the source clock (usually the AHB clock) - -Optional properties: -- resets: phandle to a reset controller asserting the timer - -Example: - -timer@1c60000 { - compatible = "allwinner,sun7i-a20-hstimer"; - reg = <0x01c60000 0x1000>; - interrupts = <0 51 1>, - <0 52 1>, - <0 53 1>, - <0 54 1>; - clocks = <&ahb1_gates 19>; - resets = <&ahb1rst 19>; -}; diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml new file mode 100644 index 000000000000..dfa0c41fd261 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/allwinner,sun5i-a13-hstimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A13 High-Speed Timer Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + compatible: + oneOf: + - const: allwinner,sun5i-a13-hstimer + - const: allwinner,sun7i-a20-hstimer + - items: + - const: allwinner,sun6i-a31-hstimer + - const: allwinner,sun7i-a20-hstimer + + reg: + maxItems: 1 + + interrupts: + minItems: 2 + maxItems: 4 + items: + - description: Timer 0 Interrupt + - description: Timer 1 Interrupt + - description: Timer 2 Interrupt + - description: Timer 3 Interrupt + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +if: + properties: + compatible: + items: + const: allwinner,sun5i-a13-hstimer + +then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + +else: + properties: + interrupts: + minItems: 4 + maxItems: 4 + +additionalProperties: false + +examples: + - | + timer@1c60000 { + compatible = "allwinner,sun7i-a20-hstimer"; + reg = <0x01c60000 0x1000>; + interrupts = <0 51 1>, + <0 52 1>, + <0 53 1>, + <0 54 1>; + clocks = <&ahb1_gates 19>; + resets = <&ahb1rst 19>; + }; + +... diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt index c5220bcd852b..a444cfc5852a 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt @@ -12,16 +12,13 @@ datasheets. Required Properties: - compatible: must contain one or more of the following: - - "renesas,cmt-48-sh73a0" for the sh73A0 48-bit CMT - (CMT1) - - "renesas,cmt-48-r8a7740" for the r8a7740 48-bit CMT - (CMT1) - - "renesas,cmt-48" for all non-second generation 48-bit CMT - (CMT1 on sh73a0 and r8a7740) - This is a fallback for the above renesas,cmt-48-* entries. - - "renesas,r8a73a4-cmt0" for the 32-bit CMT0 device included in r8a73a4. - "renesas,r8a73a4-cmt1" for the 48-bit CMT1 device included in r8a73a4. + - "renesas,r8a7740-cmt0" for the 32-bit CMT0 device included in r8a7740. + - "renesas,r8a7740-cmt1" for the 48-bit CMT1 device included in r8a7740. + - "renesas,r8a7740-cmt2" for the 32-bit CMT2 device included in r8a7740. + - "renesas,r8a7740-cmt3" for the 32-bit CMT3 device included in r8a7740. + - "renesas,r8a7740-cmt4" for the 32-bit CMT4 device included in r8a7740. - "renesas,r8a7743-cmt0" for the 32-bit CMT0 device included in r8a7743. - "renesas,r8a7743-cmt1" for the 48-bit CMT1 device included in r8a7743. - "renesas,r8a7744-cmt0" for the 32-bit CMT0 device included in r8a7744. @@ -31,29 +28,38 @@ Required Properties: - "renesas,r8a77470-cmt0" for the 32-bit CMT0 device included in r8a77470. - "renesas,r8a77470-cmt1" for the 48-bit CMT1 device included in r8a77470. - "renesas,r8a774a1-cmt0" for the 32-bit CMT0 device included in r8a774a1. - - "renesas,r8a774a1-cmt1" for the 48-bit CMT1 device included in r8a774a1. + - "renesas,r8a774a1-cmt1" for the 48-bit CMT devices included in r8a774a1. - "renesas,r8a774c0-cmt0" for the 32-bit CMT0 device included in r8a774c0. - - "renesas,r8a774c0-cmt1" for the 48-bit CMT1 device included in r8a774c0. + - "renesas,r8a774c0-cmt1" for the 48-bit CMT devices included in r8a774c0. - "renesas,r8a7790-cmt0" for the 32-bit CMT0 device included in r8a7790. - "renesas,r8a7790-cmt1" for the 48-bit CMT1 device included in r8a7790. - "renesas,r8a7791-cmt0" for the 32-bit CMT0 device included in r8a7791. - "renesas,r8a7791-cmt1" for the 48-bit CMT1 device included in r8a7791. + - "renesas,r8a7792-cmt0" for the 32-bit CMT0 device included in r8a7792. + - "renesas,r8a7792-cmt1" for the 48-bit CMT1 device included in r8a7792. - "renesas,r8a7793-cmt0" for the 32-bit CMT0 device included in r8a7793. - "renesas,r8a7793-cmt1" for the 48-bit CMT1 device included in r8a7793. - "renesas,r8a7794-cmt0" for the 32-bit CMT0 device included in r8a7794. - "renesas,r8a7794-cmt1" for the 48-bit CMT1 device included in r8a7794. - "renesas,r8a7795-cmt0" for the 32-bit CMT0 device included in r8a7795. - - "renesas,r8a7795-cmt1" for the 48-bit CMT1 device included in r8a7795. + - "renesas,r8a7795-cmt1" for the 48-bit CMT devices included in r8a7795. - "renesas,r8a7796-cmt0" for the 32-bit CMT0 device included in r8a7796. - - "renesas,r8a7796-cmt1" for the 48-bit CMT1 device included in r8a7796. + - "renesas,r8a7796-cmt1" for the 48-bit CMT devices included in r8a7796. - "renesas,r8a77965-cmt0" for the 32-bit CMT0 device included in r8a77965. - - "renesas,r8a77965-cmt1" for the 48-bit CMT1 device included in r8a77965. + - "renesas,r8a77965-cmt1" for the 48-bit CMT devices included in r8a77965. - "renesas,r8a77970-cmt0" for the 32-bit CMT0 device included in r8a77970. - - "renesas,r8a77970-cmt1" for the 48-bit CMT1 device included in r8a77970. + - "renesas,r8a77970-cmt1" for the 48-bit CMT devices included in r8a77970. - "renesas,r8a77980-cmt0" for the 32-bit CMT0 device included in r8a77980. - - "renesas,r8a77980-cmt1" for the 48-bit CMT1 device included in r8a77980. + - "renesas,r8a77980-cmt1" for the 48-bit CMT devices included in r8a77980. - "renesas,r8a77990-cmt0" for the 32-bit CMT0 device included in r8a77990. - - "renesas,r8a77990-cmt1" for the 48-bit CMT1 device included in r8a77990. + - "renesas,r8a77990-cmt1" for the 48-bit CMT devices included in r8a77990. + - "renesas,r8a77995-cmt0" for the 32-bit CMT0 device included in r8a77995. + - "renesas,r8a77995-cmt1" for the 48-bit CMT devices included in r8a77995. + - "renesas,sh73a0-cmt0" for the 32-bit CMT0 device included in sh73a0. + - "renesas,sh73a0-cmt1" for the 48-bit CMT1 device included in sh73a0. + - "renesas,sh73a0-cmt2" for the 32-bit CMT2 device included in sh73a0. + - "renesas,sh73a0-cmt3" for the 32-bit CMT3 device included in sh73a0. + - "renesas,sh73a0-cmt4" for the 32-bit CMT4 device included in sh73a0. - "renesas,rcar-gen2-cmt0" for 32-bit CMT0 devices included in R-Car Gen2 and RZ/G1. @@ -63,7 +69,7 @@ Required Properties: listed above. - "renesas,rcar-gen3-cmt0" for 32-bit CMT0 devices included in R-Car Gen3 and RZ/G2. - - "renesas,rcar-gen3-cmt1" for 48-bit CMT1 devices included in R-Car Gen3 + - "renesas,rcar-gen3-cmt1" for 48-bit CMT devices included in R-Car Gen3 and RZ/G2. These are fallbacks for R-Car Gen3 and RZ/G2 entries listed above. diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 2e742d399e87..870ac52d2225 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -104,6 +104,8 @@ properties: - infineon,slb9645tt # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor - infineon,tlv493d-a1b6 + # Inspur Power System power supply unit version 1 + - inspur,ipsps1 # Intersil ISL29028 Ambient Light and Proximity Sensor - isil,isl29028 # Intersil ISL29030 Ambient Light and Proximity Sensor diff --git a/Documentation/devicetree/bindings/usb/cdns-usb3.txt b/Documentation/devicetree/bindings/usb/cdns-usb3.txt new file mode 100644 index 000000000000..b7dc606d37b5 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/cdns-usb3.txt @@ -0,0 +1,45 @@ +Binding for the Cadence USBSS-DRD controller + +Required properties: + - reg: Physical base address and size of the controller's register areas. + Controller has 3 different regions: + - HOST registers area + - DEVICE registers area + - OTG/DRD registers area + - reg-names - register memory area names: + "xhci" - for HOST registers space + "dev" - for DEVICE registers space + "otg" - for OTG/DRD registers space + - compatible: Should contain: "cdns,usb3" + - interrupts: Interrupts used by cdns3 controller: + "host" - interrupt used by XHCI driver. + "peripheral" - interrupt used by device driver + "otg" - interrupt used by DRD/OTG part of driver + +Optional properties: + - maximum-speed : valid arguments are "super-speed", "high-speed" and + "full-speed"; refer to usb/generic.txt + - dr_mode: Should be one of "host", "peripheral" or "otg". + - phys: reference to the USB PHY + - phy-names: from the *Generic PHY* bindings; + Supported names are: + - cdns3,usb2-phy + - cdns3,usb3-phy + + - cdns,on-chip-buff-size : size of memory intended as internal memory for endpoints + buffers expressed in KB + +Example: + usb@f3000000 { + compatible = "cdns,usb3"; + interrupts = <GIC_USB_IRQ 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_USB_IRQ 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_USB_IRQ 8 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "host", "peripheral", "otg"; + reg = <0xf3000000 0x10000>, /* memory area for HOST registers */ + <0xf3010000 0x10000>, /* memory area for DEVICE registers */ + <0xf3020000 0x10000>; /* memory area for OTG/DRD registers */ + reg-names = "xhci", "dev", "otg"; + phys = <&usb2_phy>, <&usb3_phy>; + phy-names = "cdns3,usb2-phy", "cnds3,usb3-phy"; + }; diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index a254386a91ad..cfc9f40ab641 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -10,6 +10,7 @@ Required properties: "fsl,imx6sx-usb" "fsl,imx6ul-usb" "fsl,imx7d-usb" + "fsl,imx7ulp-usb" "lsi,zevio-usb" "qcom,ci-hdrc" "chipidea,usb2" diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index b7111f43fa59..66c394f9e11f 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -12,13 +12,11 @@ Required properties: - interrupts: interrupt number to the cpu. - clocks: from common clock binding: handle to usb clock. - clock-names: from common clock binding: Shall be "usbhost". - - port: if in the SoC there are EHCI phys, they should be listed here. - One phy per port. Each port should have following entries: - - reg: port number on EHCI controller, e.g - On Exynos5250, port 0 is USB2.0 otg phy - port 1 is HSIC phy0 - port 2 is HSIC phy1 - - phys: from the *Generic PHY* bindings; specifying phy used by port. + - phys: from the *Generic PHY* bindings; array specifying phy(s) used + by the root port. + - phy-names: from the *Generic PHY* bindings; array of the names for + each phy for the root ports, must be a subset of the following: + "host", "hsic0", "hsic1". Optional properties: - samsung,vbus-gpio: if present, specifies the GPIO that @@ -35,12 +33,8 @@ Example: clocks = <&clock 285>; clock-names = "usbhost"; - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - phys = <&usb2phy 1>; - }; + phys = <&usb2phy 1>; + phy-names = "host"; }; OHCI @@ -52,13 +46,11 @@ Required properties: - interrupts: interrupt number to the cpu. - clocks: from common clock binding: handle to usb clock. - clock-names: from common clock binding: Shall be "usbhost". - - port: if in the SoC there are OHCI phys, they should be listed here. - One phy per port. Each port should have following entries: - - reg: port number on OHCI controller, e.g - On Exynos5250, port 0 is USB2.0 otg phy - port 1 is HSIC phy0 - port 2 is HSIC phy1 - - phys: from the *Generic PHY* bindings, specifying phy used by port. + - phys: from the *Generic PHY* bindings; array specifying phy(s) used + by the root port. + - phy-names: from the *Generic PHY* bindings; array of the names for + each phy for the root ports, must be a subset of the following: + "host", "hsic0", "hsic1". Example: usb@12120000 { @@ -69,13 +61,8 @@ Example: clocks = <&clock 285>; clock-names = "usbhost"; - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - phys = <&usb2phy 1>; - }; - + phys = <&usb2phy 1>; + phy-names = "host"; }; DWC3 diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt index a5d011d2efc8..ba2e32d500c0 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt +++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt @@ -11,13 +11,6 @@ Required sub-node: Documentation/devicetree/bindings/connector/usb-connector.txt -Deprecated properties : -- fcs,max-sink-microvolt : Maximum sink voltage accepted by port controller -- fcs,max-sink-microamp : Maximum sink current accepted by port controller -- fcs,max-sink-microwatt : Maximum sink power accepted by port controller -- fcs,operating-sink-microwatt : Minimum amount of power accepted from a sink - when negotiating - Example: diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt index 0a74ab8dfdc2..cf5a1ad456e6 100644 --- a/Documentation/devicetree/bindings/usb/generic.txt +++ b/Documentation/devicetree/bindings/usb/generic.txt @@ -30,6 +30,10 @@ Optional properties: optional for OTG device. - adp-disable: tells OTG controllers we want to disable OTG ADP, ADP is optional for OTG device. + - usb-role-switch: boolean, indicates that the device is capable of assigning + the USB data role (USB host or USB device) for a given + USB connector, such as Type-C, Type-B(micro). + see connector/usb-connector.txt. This is an attribute to a USB controller such as: diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt index 266c2d917a28..f3e4acecabe8 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt @@ -30,7 +30,8 @@ Required properties: the following ones are optional: "ref_ck": reference clock used by low power mode etc, "mcu_ck": mcu_bus clock for register access, - "dma_ck": dma_bus clock for data transfer by DMA + "dma_ck": dma_bus clock for data transfer by DMA, + "xhci_ck": controller clock - phys : see usb-hcd.txt in the current directory @@ -100,7 +101,7 @@ Required properties: - clocks : a list of phandle + clock-specifier pairs, one for each entry in clock-names - clock-names : must contain "sys_ck", and the following ones are optional: - "ref_ck", "mcu_ck" and "dma_ck" + "ref_ck", "mcu_ck" and "dma_ck", "xhci_ck" Optional properties: - vbus-supply : reference to the VBUS regulator; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt index 3382b5cb471d..b9af7f5ee91d 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt @@ -16,7 +16,7 @@ Required properties: entry in clock-names - clock-names : must contain "sys_ck" for clock of controller, the following clocks are optional: - "ref_ck", "mcu_ck" and "dam_ck"; + "ref_ck", "mcu_ck" and "dma_ck"; - phys : see usb-hcd.txt in the current directory - dr_mode : should be one of "host", "peripheral" or "otg", refer to usb/generic.txt @@ -28,8 +28,13 @@ Optional properties: parent's address space - extcon : external connector for vbus and idpin changes detection, needed when supports dual-role mode. + it's considered valid for compatibility reasons, not allowed for + new bindings, and use "usb-role-switch" property instead. - vbus-supply : reference to the VBUS regulator, needed when supports dual-role mode. + it's considered valid for compatibility reasons, not allowed for + new bindings, and put into a usb-connector node. + see connector/usb-connector.txt. - pinctrl-names : a pinctrl state named "default" is optional, and need be defined if auto drd switch is enabled, that means the property dr_mode is set as "otg", and meanwhile the property "mediatek,enable-manual-drd" @@ -39,6 +44,8 @@ Optional properties: - maximum-speed : valid arguments are "super-speed", "high-speed" and "full-speed"; refer to usb/generic.txt + - usb-role-switch : use USB Role Switch to support dual-role switch, but + not extcon; see usb/generic.txt. - enable-manual-drd : supports manual dual-role switch via debugfs; usually used when receptacle is TYPE-A and also wants to support dual-role mode. @@ -61,6 +68,9 @@ The xhci should be added as subnode to mtu3 as shown in the following example if host mode is enabled. The DT binding details of xhci can be found in: Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +The port would be added as subnode if use "usb-role-switch" property. + see graph.txt + Example: ssusb: usb@11271000 { compatible = "mediatek,mt8173-mtu3"; diff --git a/Documentation/devicetree/bindings/usb/renesas,usb3.txt b/Documentation/devicetree/bindings/usb/renesas,usb3-peri.txt index 35039e720515..35039e720515 100644 --- a/Documentation/devicetree/bindings/usb/renesas,usb3.txt +++ b/Documentation/devicetree/bindings/usb/renesas,usb3-peri.txt diff --git a/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt new file mode 100644 index 000000000000..3d05ae56cb0d --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt @@ -0,0 +1,30 @@ +USB GPIO Based Connection Detection + +This is typically used to switch dual role mode from the USB ID pin connected +to an input GPIO, and also used to enable/disable device mode from the USB +Vbus pin connected to an input GPIO. + +Required properties: +- compatible : should include "gpio-usb-b-connector" and "usb-b-connector". +- id-gpios, vbus-gpios : input gpios, either one of them must be present, + and both can be present as well. + see connector/usb-connector.txt + +Optional properties: +- vbus-supply : can be present if needed when supports dual role mode. + see connector/usb-connector.txt + +- Sub-nodes: + - port : can be present. + see graph.txt + +Example: + +&mtu3 { + connector { + compatible = "gpio-usb-b-connector", "usb-b-connector"; + type = "micro"; + id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>; + vbus-supply = <&usb_p0_vbus>; + }; +}; diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt index a85a631ec434..b353b9816487 100644 --- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -7,6 +7,7 @@ Required properties: "fsl,vf610-usbmisc" for Vybrid vf610 "fsl,imx6sx-usbmisc" for imx6sx "fsl,imx7d-usbmisc" for imx7d + "fsl,imx7ulp-usbmisc" for imx7ulp - reg: Should contain registers location and length Examples: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 6992bbbbffab..329b668dac0a 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -27,6 +27,8 @@ patternProperties: description: Abilis Systems "^abracon,.*": description: Abracon Corporation + "^acme,.*": + description: Acme Systems srl "^actions,.*": description: Actions Semiconductor Co., Ltd. "^active-semi,.*": @@ -81,6 +83,8 @@ patternProperties: description: Analogix Semiconductor, Inc. "^andestech,.*": description: Andes Technology Corporation + "^anvo,.*": + description: Anvo-Systems Dresden GmbH "^apm,.*": description: Applied Micro Circuits Corporation (APM) "^aptina,.*": @@ -269,6 +273,8 @@ patternProperties: description: Emerging Display Technologies "^eeti,.*": description: eGalax_eMPIA Technology Inc + "^einfochips,.*": + description: Einfochips "^elan,.*": description: Elan Microelectronic Corp. "^elgin,.*": @@ -503,6 +509,8 @@ patternProperties: description: Lantiq Semiconductor "^lattice,.*": description: Lattice Semiconductor + "^leez,.*": + description: Leez "^lego,.*": description: LEGO Systems A/S "^lemaker,.*": @@ -529,6 +537,8 @@ patternProperties: description: Linear Technology Corporation "^logicpd,.*": description: Logic PD, Inc. + "^longcheer,.*": + description: Longcheer Technology (Shanghai) Co., Ltd. "^lsi,.*": description: LSI Corp. (LSI Logic) "^lwn,.*": @@ -549,6 +559,8 @@ patternProperties: description: mCube "^meas,.*": description: Measurement Specialties + "^mecer,.*": + description: Mustek Limited "^mediatek,.*": description: MediaTek Inc. "^megachips,.*": @@ -575,6 +587,8 @@ patternProperties: description: Micro Crystal AG "^micron,.*": description: Micron Technology Inc. + "^microsoft,.*": + description: Microsoft Corporation "^mikroe,.*": description: MikroElektronika d.o.o. "^miniand,.*": @@ -813,6 +827,8 @@ patternProperties: description: Semtech Corporation "^sensirion,.*": description: Sensirion AG + "^sensortek,.*": + description: Sensortek Technology Corporation "^sff,.*": description: Small Form Factor Committee "^sgd,.*": diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md deleted file mode 100644 index dc032db36262..000000000000 --- a/Documentation/devicetree/writing-schema.md +++ /dev/null @@ -1,130 +0,0 @@ -# Writing DeviceTree Bindings in json-schema - -Devicetree bindings are written using json-schema vocabulary. Schema files are -written in a JSON compatible subset of YAML. YAML is used instead of JSON as it -considered more human readable and has some advantages such as allowing -comments (Prefixed with '#'). - -## Schema Contents - -Each schema doc is a structured json-schema which is defined by a set of -top-level properties. Generally, there is one binding defined per file. The -top-level json-schema properties used are: - -- __$id__ - A json-schema unique identifier string. The string must be a valid -URI typically containing the binding's filename and path. For DT schema, it must -begin with "http://devicetree.org/schemas/". The URL is used in constructing -references to other files specified in schema "$ref" properties. A $ref values -with a leading '/' will have the hostname prepended. A $ref value a relative -path or filename only will be prepended with the hostname and path components -of the current schema file's '$id' value. A URL is used even for local files, -but there may not actually be files present at those locations. - -- __$schema__ - Indicates the meta-schema the schema file adheres to. - -- __title__ - A one line description on the contents of the binding schema. - -- __maintainers__ - A DT specific property. Contains a list of email address(es) -for maintainers of this binding. - -- __description__ - Optional. A multi-line text block containing any detailed -information about this binding. It should contain things such as what the block -or device does, standards the device conforms to, and links to datasheets for -more information. - -- __select__ - Optional. A json-schema used to match nodes for applying the -schema. By default without 'select', nodes are matched against their possible -compatible string values or node name. Most bindings should not need select. - -- __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__ - 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. - - A property can also define a child DT node with child properties defined -under it. - - For more details on properties sections, see 'Property Schema' section. - -- __patternProperties__ - Optional. Similar to 'properties', but names are regex. - -- __required__ - A list of DT properties from the 'properties' section that -must always be present. - -- __examples__ - Optional. A list of one or more DTS hunks implementing the -binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. - -Unless noted otherwise, all properties are required. - -## Property Schema - -The 'properties' section of the schema contains all the DT properties for a -binding. Each property contains a set of constraints using json-schema -vocabulary for that property. The properties schemas are what is used for -validation of DT files. - -For common properties, only additional constraints not covered by the common -binding schema need to be defined such as how many values are valid or what -possible values are valid. - -Vendor specific properties will typically need more detailed schema. With the -exception of boolean properties, they should have a reference to a type in -schemas/types.yaml. A "description" property is always required. - -The Devicetree schemas don't exactly match the YAML encoded DT data produced by -dtc. They are simplified to make them more compact and avoid a bunch of -boilerplate. The tools process the schema files to produce the final schema for -validation. There are currently 2 transformations the tools perform. - -The default for arrays in json-schema is they are variable sized and allow more -entries than explicitly defined. This can be restricted by defining 'minItems', -'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed -size is desired in most cases, so these properties are added based on the -number of entries in an 'items' list. - -The YAML Devicetree format also makes all string values an array and scalar -values a matrix (in order to define groupings) even when only a single value -is present. Single entries in schemas are fixed up to match this encoding. - -## Testing - -### Dependencies - -The DT schema project must be installed in order to validate the DT schema -binding documents and validate DTS files using the DT schema. The DT schema -project can be installed with pip: - -`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master` - -dtc must also be built with YAML output support enabled. This requires that -libyaml and its headers be installed on the host system. - -### Running checks - -The DT schema binding documents must be validated using the meta-schema (the -schema for the schema) to ensure they are both valid json-schema and valid -binding schema. All of the DT binding documents can be validated using the -`dt_binding_check` target: - -`make dt_binding_check` - -In order to perform validation of DT source files, use the `dtbs_check` target: - -`make dtbs_check` - -This will first run the `dt_binding_check` which generates the processed schema. - -It is also possible to run checks with a single schema file by setting the -'DT_SCHEMA_FILES' variable to a specific schema file. - -`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml` - - -## json-schema Resources - -[JSON-Schema Specifications](http://json-schema.org/) - -[Using JSON Schema Book](http://usingjsonschema.com/) diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst new file mode 100644 index 000000000000..8f71d1e2ac52 --- /dev/null +++ b/Documentation/devicetree/writing-schema.rst @@ -0,0 +1,153 @@ +:orphan: + +Writing DeviceTree Bindings in json-schema +========================================== + +Devicetree bindings are written using json-schema vocabulary. Schema files are +written in a JSON compatible subset of YAML. YAML is used instead of JSON as it +considered more human readable and has some advantages such as allowing +comments (Prefixed with '#'). + +Schema Contents +--------------- + +Each schema doc is a structured json-schema which is defined by a set of +top-level properties. Generally, there is one binding defined per file. The +top-level json-schema properties used are: + +$id + A json-schema unique identifier string. The string must be a valid + URI typically containing the binding's filename and path. For DT schema, it must + begin with "http://devicetree.org/schemas/". The URL is used in constructing + references to other files specified in schema "$ref" properties. A $ref values + with a leading '/' will have the hostname prepended. A $ref value a relative + path or filename only will be prepended with the hostname and path components + of the current schema file's '$id' value. A URL is used even for local files, + but there may not actually be files present at those locations. + +$schema + Indicates the meta-schema the schema file adheres to. + +title + A one line description on the contents of the binding schema. + +maintainers + A DT specific property. Contains a list of email address(es) + for maintainers of this binding. + +description + Optional. A multi-line text block containing any detailed + information about this binding. It should contain things such as what the block + or device does, standards the device conforms to, and links to datasheets for + more information. + +select + Optional. A json-schema used to match nodes for applying the + schema. By default without 'select', nodes are matched against their possible + compatible string values or node name. Most bindings should not need select. + + 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 + 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. + +A property can also define a child DT node with child properties defined +under it. + +For more details on properties sections, see 'Property Schema' section. + +patternProperties + Optional. Similar to 'properties', but names are regex. + +required + A list of DT properties from the 'properties' section that + must always be present. + +examples + Optional. A list of one or more DTS hunks implementing the + binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. + +Unless noted otherwise, all properties are required. + +Property Schema +--------------- + +The 'properties' section of the schema contains all the DT properties for a +binding. Each property contains a set of constraints using json-schema +vocabulary for that property. The properties schemas are what is used for +validation of DT files. + +For common properties, only additional constraints not covered by the common +binding schema need to be defined such as how many values are valid or what +possible values are valid. + +Vendor specific properties will typically need more detailed schema. With the +exception of boolean properties, they should have a reference to a type in +schemas/types.yaml. A "description" property is always required. + +The Devicetree schemas don't exactly match the YAML encoded DT data produced by +dtc. They are simplified to make them more compact and avoid a bunch of +boilerplate. The tools process the schema files to produce the final schema for +validation. There are currently 2 transformations the tools perform. + +The default for arrays in json-schema is they are variable sized and allow more +entries than explicitly defined. This can be restricted by defining 'minItems', +'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed +size is desired in most cases, so these properties are added based on the +number of entries in an 'items' list. + +The YAML Devicetree format also makes all string values an array and scalar +values a matrix (in order to define groupings) even when only a single value +is present. Single entries in schemas are fixed up to match this encoding. + +Testing +------- + +Dependencies +~~~~~~~~~~~~ + +The DT schema project must be installed in order to validate the DT schema +binding documents and validate DTS files using the DT schema. The DT schema +project can be installed with pip:: + + pip3 install git+https://github.com/devicetree-org/dt-schema.git@master + +dtc must also be built with YAML output support enabled. This requires that +libyaml and its headers be installed on the host system. + +Running checks +~~~~~~~~~~~~~~ + +The DT schema binding documents must be validated using the meta-schema (the +schema for the schema) to ensure they are both valid json-schema and valid +binding schema. All of the DT binding documents can be validated using the +``dt_binding_check`` target:: + + make dt_binding_check + +In order to perform validation of DT source files, use the `dtbs_check` target:: + + make dtbs_check + +This will first run the `dt_binding_check` which generates the processed schema. + +It is also possible to run checks with a single schema file by setting the +``DT_SCHEMA_FILES`` variable to a specific schema file. + +:: + + make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml + + +json-schema Resources +--------------------- + + +`JSON-Schema Specifications <http://json-schema.org/>`_ + +`Using JSON Schema Book <http://usingjsonschema.com/>`_ diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst index ae1e3d0394b0..1b5020ec6517 100644 --- a/Documentation/driver-api/device_link.rst +++ b/Documentation/driver-api/device_link.rst @@ -78,8 +78,8 @@ typically deleted in its ``->remove`` callback for symmetry. That way, if the driver is compiled as a module, the device link is added on module load and orderly deleted on unload. The same restrictions that apply to device link addition (e.g. exclusion of a parallel suspend/resume transition) apply equally -to deletion. Device links with ``DL_FLAG_STATELESS`` unset (i.e. managed -device links) are deleted automatically by the driver core. +to deletion. Device links managed by the driver core are deleted automatically +by it. Several flags may be specified on device link addition, two of which have already been mentioned above: ``DL_FLAG_STATELESS`` to express that no diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst index 3026fa975937..b9df904d0a79 100644 --- a/Documentation/driver-api/dmaengine/index.rst +++ b/Documentation/driver-api/dmaengine/index.rst @@ -47,7 +47,7 @@ This book adds some notes about PXA DMA pxa_dma -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 921c71a3d683..3fdb32422f8a 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -69,9 +69,9 @@ driver code: The code implementing a gpio_chip should support multiple instances of the controller, preferably using the driver model. That code will configure each -gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``. -Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()`` -when it is unavoidable. +gpio_chip and issue gpiochip_add(), gpiochip_add_data(), or +devm_gpiochip_add_data(). Removing a GPIO controller should be rare; use +gpiochip_remove() when it is unavoidable. Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. @@ -259,7 +259,7 @@ most often cascaded off a parent interrupt controller, and in some special cases the GPIO logic is melded with a SoC's primary interrupt controller. The IRQ portions of the GPIO block are implemented using an irq_chip, using -the header <linux/irq.h>. So basically such a driver is utilizing two sub- +the header <linux/irq.h>. So this combined driver is utilizing two sub- systems simultaneously: gpio and irq. It is legal for any IRQ consumer to request an IRQ from any irqchip even if it @@ -391,25 +391,119 @@ Infrastructure helpers for GPIO irqchips ---------------------------------------- To help out in handling the set-up and management of GPIO irqchips and the -associated irqdomain and resource allocation callbacks, the gpiolib has -some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig -symbol: - -- gpiochip_irqchip_add(): adds a chained cascaded irqchip to a gpiochip. It - will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the - callbacks need to embed the gpio_chip in its state container and obtain a - pointer to the container using container_of(). - (See Documentation/driver-api/driver-model/design-patterns.rst) +associated irqdomain and resource allocation callbacks. These are activated +by selecting the Kconfig symbol GPIOLIB_IRQCHIP. If the symbol +IRQ_DOMAIN_HIERARCHY is also selected, hierarchical helpers will also be +provided. A big portion of overhead code will be managed by gpiolib, +under the assumption that your interrupts are 1-to-1-mapped to the +GPIO line index: + + GPIO line offset Hardware IRQ + 0 0 + 1 1 + 2 2 + ... ... + ngpio-1 ngpio-1 + +If some GPIO lines do not have corresponding IRQs, the bitmask valid_mask +and the flag need_valid_mask in gpio_irq_chip can be used to mask off some +lines as invalid for associating with IRQs. + +The preferred way to set up the helpers is to fill in the +struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip. +If you do this, the additional irq_chip will be set up by gpiolib at the +same time as setting up the rest of the GPIO functionality. The following +is a typical example of a cascaded interrupt handler using gpio_irq_chip: + + /* Typical state container with dynamic irqchip */ + struct my_gpio { + struct gpio_chip gc; + struct irq_chip irq; + }; + + int irq; /* from platform etc */ + struct my_gpio *g; + struct gpio_irq_chip *girq; + + /* Set up the irqchip dynamically */ + g->irq.name = "my_gpio_irq"; + g->irq.irq_ack = my_gpio_ack_irq; + g->irq.irq_mask = my_gpio_mask_irq; + g->irq.irq_unmask = my_gpio_unmask_irq; + g->irq.irq_set_type = my_gpio_set_irq_type; + + /* Get a pointer to the gpio_irq_chip */ + girq = &g->gc.irq; + girq->chip = &g->irq; + girq->parent_handler = ftgpio_gpio_irq_handler; + girq->num_parents = 1; + girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents), + GFP_KERNEL); + if (!girq->parents) + return -ENOMEM; + girq->default_type = IRQ_TYPE_NONE; + girq->handler = handle_bad_irq; + girq->parents[0] = irq; + + return devm_gpiochip_add_data(dev, &g->gc, g); + +The helper support using hierarchical interrupt controllers as well. +In this case the typical set-up will look like this: + + /* Typical state container with dynamic irqchip */ + struct my_gpio { + struct gpio_chip gc; + struct irq_chip irq; + struct fwnode_handle *fwnode; + }; + + int irq; /* from platform etc */ + struct my_gpio *g; + struct gpio_irq_chip *girq; + + /* Set up the irqchip dynamically */ + g->irq.name = "my_gpio_irq"; + g->irq.irq_ack = my_gpio_ack_irq; + g->irq.irq_mask = my_gpio_mask_irq; + g->irq.irq_unmask = my_gpio_unmask_irq; + g->irq.irq_set_type = my_gpio_set_irq_type; + + /* Get a pointer to the gpio_irq_chip */ + girq = &g->gc.irq; + girq->chip = &g->irq; + girq->default_type = IRQ_TYPE_NONE; + girq->handler = handle_bad_irq; + girq->fwnode = g->fwnode; + girq->parent_domain = parent; + girq->child_to_parent_hwirq = my_gpio_child_to_parent_hwirq; + + return devm_gpiochip_add_data(dev, &g->gc, g); + +As you can see pretty similar, but you do not supply a parent handler for +the IRQ, instead a parent irqdomain, an fwnode for the hardware and +a funcion .child_to_parent_hwirq() that has the purpose of looking up +the parent hardware irq from a child (i.e. this gpio chip) hardware irq. +As always it is good to look at examples in the kernel tree for advice +on how to find the required pieces. + +The old way of adding irqchips to gpiochips after registration is also still +available but we try to move away from this: + +- DEPRECATED: gpiochip_irqchip_add(): adds a chained cascaded irqchip to a + gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ + callbacks, so the callbacks need to embed the gpio_chip in its state + container and obtain a pointer to the container using container_of(). + (See Documentation/driver-model/design-patterns.txt) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The cascaded irq has to be handled by a threaded interrupt handler. Apart from that it works exactly like the chained irqchip. -- gpiochip_set_chained_irqchip(): sets up a chained cascaded irq handler for a - gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler - data. Notice that we pass is as the handler data, since the irqchip data is - likely used by the parent irqchip. +- DEPRECATED: gpiochip_set_chained_irqchip(): sets up a chained cascaded irq + handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* + as handler data. Notice that we pass is as the handler data, since the + irqchip data is likely used by the parent irqchip. - gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a gpio_chip from a parent IRQ. As the parent IRQ has usually been @@ -418,11 +512,11 @@ symbol: If there is a need to exclude certain GPIO lines from the IRQ domain handled by these helpers, we can set .irq.need_valid_mask of the gpiochip before -``[devm_]gpiochip_add_data()`` is called. This allocates an .irq.valid_mask with as -many bits set as there are GPIO lines in the chip, each bit representing line -0..n-1. Drivers can exclude GPIO lines by clearing bits from this mask. The mask -must be filled in before gpiochip_irqchip_add() or gpiochip_irqchip_add_nested() -is called. +devm_gpiochip_add_data() or gpiochip_add_data() is called. This allocates an +.irq.valid_mask with as many bits set as there are GPIO lines in the chip, each +bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits +from this mask. The mask must be filled in before gpiochip_irqchip_add() or +gpiochip_irqchip_add_nested() is called. To use the helpers please keep the following in mind: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d12a80f386a6..38e638abe3eb 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -65,6 +65,7 @@ available subsections can be seen below. dmaengine/index slimbus soundwire/index + thermal/index fpga/index acpi/index backlight/lp855x-driver.rst @@ -75,6 +76,7 @@ available subsections can be seen below. dell_rbu edid eisa + ipmb isa isapnp generic-counter diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst index 7e2265144157..3ec3baed84c4 100644 --- a/Documentation/driver-api/ipmb.rst +++ b/Documentation/driver-api/ipmb.rst @@ -83,7 +83,7 @@ Instantiate the device ---------------------- After loading the driver, you can instantiate the device as -described in 'Documentation/i2c/instantiating-devices'. +described in 'Documentation/i2c/instantiating-devices.rst'. If you have multiple BMCs, each connected to your Satellite MC via a different I2C bus, you can instantiate a device for each of those BMCs. diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst index f5333e3bf486..1f0437676762 100644 --- a/Documentation/driver-api/mtd/spi-nor.rst +++ b/Documentation/driver-api/mtd/spi-nor.rst @@ -59,7 +59,7 @@ Part III - How can drivers use the framework? The main API is spi_nor_scan(). Before you call the hook, a driver should initialize the necessary fields for spi_nor{}. Please see -drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c +drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c when you want to write a new driver for a SPI NOR controller. Another API is spi_nor_restore(), this is used to restore the status of SPI flash chip such as addressing mode. Call it whenever detach the driver from diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst index f3ad9fd26408..286e7ff4d2d9 100644 --- a/Documentation/driver-api/serial/n_gsm.rst +++ b/Documentation/driver-api/serial/n_gsm.rst @@ -18,18 +18,22 @@ How to use it 2. switch the serial line to using the n_gsm line discipline by using TIOCSETD ioctl, 3. configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, +4. obtain base gsmtty number for the used serial port, Major parts of the initialization program : (a good starting point is util-linux-ng/sys-utils/ldattach.c):: + #include <stdio.h> + #include <stdint.h> #include <linux/gsmmux.h> - #define N_GSM0710 21 /* GSM 0710 Mux */ + #include <linux/tty.h> #define DEFAULT_SPEED B115200 #define SERIAL_PORT /dev/ttyS0 int ldisc = N_GSM0710; struct gsm_config c; struct termios configuration; + uint32_t first; /* open the serial port connected to the modem */ fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); @@ -58,21 +62,14 @@ Major parts of the initialization program : c.mtu = 127; /* set the new configuration */ ioctl(fd, GSMIOC_SETCONF, &c); + /* get first gsmtty device node */ + ioctl(fd, GSMIOC_GETFIRST, &first); + printf("first muxed line: /dev/gsmtty%i\n", first); /* and wait for ever to keep the line discipline enabled */ daemon(0,0); pause(); -4. create the devices corresponding to the "virtual" serial ports (take care, - each modem has its configuration and some DLC have dedicated functions, - for example GPS), starting with minor 1 (DLC0 is reserved for the management - of the mux):: - - MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}` - for i in `seq 1 4`; do - mknod /dev/ttygsm$i c $MAJOR $i - done - 5. use these devices as plain serial ports. for example, it's possible: diff --git a/Documentation/driver-api/sgi-ioc4.rst b/Documentation/driver-api/sgi-ioc4.rst deleted file mode 100644 index 72709222d3c0..000000000000 --- a/Documentation/driver-api/sgi-ioc4.rst +++ /dev/null @@ -1,49 +0,0 @@ -==================================== -SGI IOC4 PCI (multi function) device -==================================== - -The SGI IOC4 PCI device is a bit of a strange beast, so some notes on -it are in order. - -First, even though the IOC4 performs multiple functions, such as an -IDE controller, a serial controller, a PS/2 keyboard/mouse controller, -and an external interrupt mechanism, it's not implemented as a -multifunction device. The consequence of this from a software -standpoint is that all these functions share a single IRQ, and -they can't all register to own the same PCI device ID. To make -matters a bit worse, some of the register blocks (and even registers -themselves) present in IOC4 are mixed-purpose between these several -functions, meaning that there's no clear "owning" device driver. - -The solution is to organize the IOC4 driver into several independent -drivers, "ioc4", "sgiioc4", and "ioc4_serial". Note that there is no -PS/2 controller driver as this functionality has never been wired up -on a shipping IO card. - -ioc4 -==== -This is the core (or shim) driver for IOC4. It is responsible for -initializing the basic functionality of the chip, and allocating -the PCI resources that are shared between the IOC4 functions. - -This driver also provides registration functions that the other -IOC4 drivers can call to make their presence known. Each driver -needs to provide a probe and remove function, which are invoked -by the core driver at appropriate times. The interface of these -IOC4 function probe and remove operations isn't precisely the same -as PCI device probe and remove operations, but is logically the -same operation. - -sgiioc4 -======= -This is the IDE driver for IOC4. Its name isn't very descriptive -simply for historical reasons (it used to be the only IOC4 driver -component). There's not much to say about it other than it hooks -up to the ioc4 driver via the appropriate registration, probe, and -remove functions. - -ioc4_serial -=========== -This is the serial driver for IOC4. There's not much to say about it -other than it hooks up to the ioc4 driver via the appropriate registration, -probe, and remove functions. diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst index 6db026028f27..234911a0db99 100644 --- a/Documentation/driver-api/soundwire/index.rst +++ b/Documentation/driver-api/soundwire/index.rst @@ -10,7 +10,7 @@ SoundWire Documentation error_handling locking -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst index 645d914c45a6..645d914c45a6 100644 --- a/Documentation/thermal/cpu-cooling-api.rst +++ b/Documentation/driver-api/thermal/cpu-cooling-api.rst diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst index 5bd556566c70..5bd556566c70 100644 --- a/Documentation/thermal/exynos_thermal.rst +++ b/Documentation/driver-api/thermal/exynos_thermal.rst diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst index c21d10838bc5..c21d10838bc5 100644 --- a/Documentation/thermal/exynos_thermal_emulation.rst +++ b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst index 8c1c00146cad..5ba61d19c6ae 100644 --- a/Documentation/thermal/index.rst +++ b/Documentation/driver-api/thermal/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ======= Thermal diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst index 3f6dfb0b3ea6..3f6dfb0b3ea6 100644 --- a/Documentation/thermal/intel_powerclamp.rst +++ b/Documentation/driver-api/thermal/intel_powerclamp.rst diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst index 37255fd6735d..37255fd6735d 100644 --- a/Documentation/thermal/nouveau_thermal.rst +++ b/Documentation/driver-api/thermal/nouveau_thermal.rst diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst index 67b6a3297238..67b6a3297238 100644 --- a/Documentation/thermal/power_allocator.rst +++ b/Documentation/driver-api/thermal/power_allocator.rst diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst index e4930761d3e5..fab2c9b36d08 100644 --- a/Documentation/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -552,7 +552,7 @@ emul_temp sustainable_power An estimate of the sustained power that can be dissipated by the thermal zone. Used by the power allocator governor. For - more information see Documentation/thermal/power_allocator.rst + more information see Documentation/driver-api/thermal/power_allocator.rst Unit: milliwatts @@ -563,7 +563,7 @@ k_po controller during temperature overshoot. Temperature overshoot is when the current temperature is above the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -572,7 +572,7 @@ k_pu controller during temperature undershoot. Temperature undershoot is when the current temperature is below the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -580,14 +580,14 @@ k_i The integral term of the power allocator governor's PID controller. This term allows the PID controller to compensate for long term drift. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional k_d The derivative term of the power allocator governor's PID controller. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -598,7 +598,7 @@ integral_cutoff example, if integral_cutoff is 0, then the integral term only accumulates error when temperature is above the desired temperature trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst Unit: millidegree Celsius diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst index f134dbd3f5a9..2ac42ccd236f 100644 --- a/Documentation/thermal/x86_pkg_temperature_thermal.rst +++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst @@ -40,7 +40,7 @@ This contains two trip points: - trip_point_1_temp User can set any temperature between 0 to TJ-Max temperature. Temperature units -are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for +are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for thermal sys-fs details. Any value other than 0 in these trip points, can trigger thermal notifications. diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 8fecfa11d4ff..84091cd25dc4 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -408,6 +408,13 @@ handler code. You also do not need to know anything about the chip's internal registers to create the kernel part of the driver. All you need to know is the irq number of the pin the chip is connected to. +When used in a device-tree enabled system, the driver needs to be +probed with the ``"of_id"`` module parameter set to the ``"compatible"`` +string of the node the driver is supposed to handle. By default, the +node's name (without the unit address) is exposed as name for the +UIO device in userspace. To set a custom name, a property named +``"linux,uio-name"`` may be specified in the DT node. + Using uio_dmem_genirq for platform devices ------------------------------------------ diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 7fc2e243dee9..cae7be2f7725 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -21,7 +21,7 @@ | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | TODO | | s390: | ok | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 68f266944d5f..4fae0464ddff 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -21,7 +21,7 @@ | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | TODO | | s390: | TODO | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index c683da198f31..ee922746a64c 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -30,5 +30,5 @@ | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index e3080b82aefd..c52116c1a049 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | ok | | c6x: | TODO | | csky: | TODO | | h8300: | TODO | @@ -30,5 +30,5 @@ | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt deleted file mode 100644 index 7521d7500fbe..000000000000 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ /dev/null @@ -1,34 +0,0 @@ -# -# Feature name: rwsem-optimized -# Kconfig: !RWSEM_GENERIC_SPINLOCK -# description: arch provides optimized rwsem APIs -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | ok | - | arc: | TODO | - | arm: | ok | - | arm64: | ok | - | c6x: | TODO | - | csky: | TODO | - | h8300: | TODO | - | hexagon: | TODO | - | ia64: | ok | - | m68k: | TODO | - | microblaze: | TODO | - | mips: | TODO | - | nds32: | TODO | - | nios2: | TODO | - | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | TODO | - | riscv: | TODO | - | s390: | ok | - | sh: | ok | - | sparc: | ok | - | um: | ok | - | unicore32: | TODO | - | x86: | ok | - | xtensa: | ok | - ----------------------- diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt index 545262c167c3..1711ad48e38a 100644 --- a/Documentation/filesystems/coda.txt +++ b/Documentation/filesystems/coda.txt @@ -421,14 +421,14 @@ kernel support. The CodaCred structure defines a variety of user and group ids as - they are set for the calling process. The vuid_t and guid_t are 32 bit + they are set for the calling process. The vuid_t and vgid_t are 32 bit unsigned integers. It also defines group membership in an array. On Unix the CodaCred has proven sufficient to implement good security semantics for Coda but the structure may have to undergo modification for the Windows environment when these mature. struct CodaCred { - vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/ + vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */ vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */ vgid_t cr_groups[NGROUPS]; /* Group membership for caller */ }; diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst index 4e32cb961e5b..de12016ee419 100644 --- a/Documentation/filesystems/directory-locking +++ b/Documentation/filesystems/directory-locking.rst @@ -1,12 +1,17 @@ - Locking scheme used for directory operations is based on two +================= +Directory Locking +================= + + +Locking scheme used for directory operations is based on two kinds of locks - per-inode (->i_rwsem) and per-filesystem (->s_vfs_rename_mutex). - When taking the i_rwsem on multiple non-directory objects, we +When taking the i_rwsem on multiple non-directory objects, we always acquire the locks in order by increasing address. We'll call that "inode pointer" order in the following. - For our purposes all operations fall in 5 classes: +For our purposes all operations fall in 5 classes: 1) read access. Locking rules: caller locks directory we are accessing. The lock is taken shared. @@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange case) shared. 5) link creation. Locking rules: + * lock parent * check that source is not a directory * lock source * call the method. + All locks are exclusive. 6) cross-directory rename. The trickiest in the whole bunch. Locking rules: + * lock the filesystem * lock parents in "ancestors first" order. * find source and target. * if old parent is equal to or is a descendent of target - fail with -ENOTEMPTY + fail with -ENOTEMPTY * if new parent is equal to or is a descendent of source - fail with -ELOOP + fail with -ELOOP * If it's an exchange, lock both the source and the target. * If the target exists, lock it. If the source is a non-directory, lock it. If we need to lock both, do so in inode pointer order. * call the method. + All ->i_rwsem are taken exclusive. Again, we might get away with locking the the source (and target in exchange case) shared. @@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller. If no directory is its own ancestor, the scheme above is deadlock-free. + Proof: First of all, at any moment we have a partial ordering of the -objects - A < B iff A is an ancestor of B. + objects - A < B iff A is an ancestor of B. That ordering can change. However, the following is true: @@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B. non-directory object, except renames, which take locks on source and target in inode pointer order in the case they are not directories.) - Now consider the minimal deadlock. Each process is blocked on +Now consider the minimal deadlock. Each process is blocked on attempt to acquire some lock and already holds at least one lock. Let's consider the set of contended locks. First of all, filesystem lock is not contended, since any process blocked on it is not holding any locks. Thus all processes are blocked on ->i_rwsem. - By (3), any process holding a non-directory lock can only be +By (3), any process holding a non-directory lock can only be waiting on another non-directory lock with a larger address. Therefore the process holding the "largest" such lock can always make progress, and non-directory objects are not included in the set of contended locks. - Thus link creation can't be a part of deadlock - it can't be +Thus link creation can't be a part of deadlock - it can't be blocked on source and it means that it doesn't hold any locks. - Any contended object is either held by cross-directory rename or +Any contended object is either held by cross-directory rename or has a child that is also contended. Indeed, suppose that it is held by operation other than cross-directory rename. Then the lock this operation is blocked on belongs to child of that object due to (1). - It means that one of the operations is cross-directory rename. +It means that one of the operations is cross-directory rename. Otherwise the set of contended objects would be infinite - each of them would have a contended child and we had assumed that no object is its own descendent. Moreover, there is exactly one cross-directory rename (see above). - Consider the object blocking the cross-directory rename. One +Consider the object blocking the cross-directory rename. One of its descendents is locked by cross-directory rename (otherwise we would again have an infinite set of contended objects). But that means that cross-directory rename is taking locks out of order. Due @@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor. Contradiction. I.e. deadlock is impossible. Q.E.D. - These operations are guaranteed to avoid loop creation. Indeed, +These operations are guaranteed to avoid loop creation. Indeed, the only operation that could introduce loops is cross-directory rename. Since the only new (parent, child) pair added by rename() is (new parent, source), such loop would have to contain these objects and the rest of it @@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when we had acquired filesystem lock and rename() would fail with -ELOOP in that case. - While this locking scheme works for arbitrary DAGs, it relies on +While this locking scheme works for arbitrary DAGs, it relies on ability to check that directory is a descendent of another object. Current implementation assumes that directory graph is a tree. This assumption is also preserved by all operations (cross-directory rename on a tree that would not introduce a cycle will leave it a tree and link() fails for directories). - Notice that "directory" in the above == "anything that might have +Notice that "directory" in the above == "anything that might have children", so if we are going to introduce hybrid objects we will need either to make sure that link(2) doesn't work for them or to make changes in is_subdir() that would make it work even in presence of such beasts. diff --git a/Documentation/filesystems/erofs.txt b/Documentation/filesystems/erofs.txt new file mode 100644 index 000000000000..b0c085326e2e --- /dev/null +++ b/Documentation/filesystems/erofs.txt @@ -0,0 +1,210 @@ +Overview +======== + +EROFS file-system stands for Enhanced Read-Only File System. Different +from other read-only file systems, it aims to be designed for flexibility, +scalability, but be kept simple and high performance. + +It is designed as a better filesystem solution for the following scenarios: + - read-only storage media or + + - part of a fully trusted read-only solution, which means it needs to be + immutable and bit-for-bit identical to the official golden image for + their releases due to security and other considerations and + + - hope to save some extra storage space with guaranteed end-to-end performance + by using reduced metadata and transparent file compression, especially + for those embedded devices with limited memory (ex, smartphone); + +Here is the main features of EROFS: + - Little endian on-disk design; + + - Currently 4KB block size (nobh) and therefore maximum 16TB address space; + + - Metadata & data could be mixed by design; + + - 2 inode versions for different requirements: + v1 v2 + Inode metadata size: 32 bytes 64 bytes + Max file size: 4 GB 16 EB (also limited by max. vol size) + Max uids/gids: 65536 4294967296 + File creation time: no yes (64 + 32-bit timestamp) + Max hardlinks: 65536 4294967296 + Metadata reserved: 4 bytes 14 bytes + + - Support extended attributes (xattrs) as an option; + + - Support xattr inline and tail-end data inline for all files; + + - Support POSIX.1e ACLs by using xattrs; + + - Support transparent file compression as an option: + LZ4 algorithm with 4 KB fixed-output compression for high performance; + +The following git tree provides the file system user-space tools under +development (ex, formatting tool mkfs.erofs): +>> git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git + +Bugs and patches are welcome, please kindly help us and send to the following +linux-erofs mailing list: +>> linux-erofs mailing list <linux-erofs@lists.ozlabs.org> + +Mount options +============= + +(no)user_xattr Setup Extended User Attributes. Note: xattr is enabled + by default if CONFIG_EROFS_FS_XATTR is selected. +(no)acl Setup POSIX Access Control List. Note: acl is enabled + by default if CONFIG_EROFS_FS_POSIX_ACL is selected. +cache_strategy=%s Select a strategy for cached decompression from now on: + disabled: In-place I/O decompression only; + readahead: Cache the last incomplete compressed physical + cluster for further reading. It still does + in-place I/O decompression for the rest + compressed physical clusters; + readaround: Cache the both ends of incomplete compressed + physical clusters for further reading. + It still does in-place I/O decompression + for the rest compressed physical clusters. + +On-disk details +=============== + +Summary +------- +Different from other read-only file systems, an EROFS volume is designed +to be as simple as possible: + + |-> aligned with the block size + ____________________________________________________________ + | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data | + |_|__|_|_____|__________|_____|______|__________|_____|______| + 0 +1K + +All data areas should be aligned with the block size, but metadata areas +may not. All metadatas can be now observed in two different spaces (views): + 1. Inode metadata space + Each valid inode should be aligned with an inode slot, which is a fixed + value (32 bytes) and designed to be kept in line with v1 inode size. + + Each inode can be directly found with the following formula: + inode offset = meta_blkaddr * block_size + 32 * nid + + |-> 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_advise: + + __________________ __________________ + | i_advise | | i_advise | + |__________________| |__________________| + | ... | | ... | + | | | | + |__________________| 32 bytes | | + | | + |__________________| 64 bytes + + Xattrs, extents, data inline are followed by the corresponding inode with + proper alignes, and they could be optional for different data mappings, + _currently_ there are totally 3 valid data mappings supported: + + 1) flat file data without data inline (no extent); + 2) fixed-output size data compression (must have extents); + 3) flat file data with tail-end data inline (no extent); + + The size of the optional xattrs is indicated by i_xattr_count in inode + header. Large xattrs or xattrs shared by many different files can be + stored in shared xattrs metadata rather than inlined right after inode. + + 2. Shared xattrs metadata space + Shared xattrs space is similar to the above inode space, started with + a specific block indicated by xattr_blkaddr, organized one by one with + proper align. + + 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 ... + |________|_____________|_____________|_____|______________|_______________ + +Directories +----------- +All directories are now organized in a compact on-disk format. Note that +each directory block is divided into index and name areas in order to support +random file lookup, and all directory entries are _strictly_ recorded in +alphabetical order in order to support improved prefix binary search +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 + +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-output clustersize 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. + diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 82efa41b0e6c..8a0700af9596 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -72,6 +72,9 @@ Online attacks fscrypt (and storage encryption in general) can only provide limited protection, if any at all, against online attacks. In detail: +Side-channel attacks +~~~~~~~~~~~~~~~~~~~~ + fscrypt is only resistant to side-channel attacks, such as timing or electromagnetic attacks, to the extent that the underlying Linux Cryptographic API algorithms are. If a vulnerable algorithm is used, @@ -80,29 +83,90 @@ attacker to mount a side channel attack against the online system. Side channel attacks may also be mounted against applications consuming decrypted data. -After an encryption key has been provided, fscrypt is not designed to -hide the plaintext file contents or filenames from other users on the -same system, regardless of the visibility of the keyring key. -Instead, existing access control mechanisms such as file mode bits, -POSIX ACLs, LSMs, or mount namespaces should be used for this purpose. -Also note that as long as the encryption keys are *anywhere* in -memory, an online attacker can necessarily compromise them by mounting -a physical attack or by exploiting any kernel security vulnerability -which provides an arbitrary memory read primitive. - -While it is ostensibly possible to "evict" keys from the system, -recently accessed encrypted files will remain accessible at least -until the filesystem is unmounted or the VFS caches are dropped, e.g. -using ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the -RAM is compromised before being powered off, it will likely still be -possible to recover portions of the plaintext file contents, if not -some of the encryption keys as well. (Since Linux v4.12, all -in-kernel keys related to fscrypt are sanitized before being freed. -However, userspace would need to do its part as well.) - -Currently, fscrypt does not prevent a user from maliciously providing -an incorrect key for another user's existing encrypted files. A -protection against this is planned. +Unauthorized file access +~~~~~~~~~~~~~~~~~~~~~~~~ + +After an encryption key has been added, fscrypt does not hide the +plaintext file contents or filenames from other users on the same +system. Instead, existing access control mechanisms such as file mode +bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose. + +(For the reasoning behind this, understand that while the key is +added, the confidentiality of the data, from the perspective of the +system itself, is *not* protected by the mathematical properties of +encryption but rather only by the correctness of the kernel. +Therefore, any encryption-specific access control checks would merely +be enforced by kernel *code* and therefore would be largely redundant +with the wide variety of access control mechanisms already available.) + +Kernel memory compromise +~~~~~~~~~~~~~~~~~~~~~~~~ + +An attacker who compromises the system enough to read from arbitrary +memory, e.g. by mounting a physical attack or by exploiting a kernel +security vulnerability, can compromise all encryption keys that are +currently in use. + +However, fscrypt allows encryption keys to be removed from the kernel, +which may protect them from later compromise. + +In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the +FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master +encryption key from kernel memory. If it does so, it will also try to +evict all cached inodes which had been "unlocked" using the key, +thereby wiping their per-file keys and making them once again appear +"locked", i.e. in ciphertext or encrypted form. + +However, these ioctls have some limitations: + +- Per-file keys for in-use files will *not* be removed or wiped. + Therefore, for maximum effect, userspace should close the relevant + encrypted files and directories before removing a master key, as + well as kill any processes whose working directory is in an affected + encrypted directory. + +- The kernel cannot magically wipe copies of the master key(s) that + userspace might have as well. Therefore, userspace must wipe all + copies of the master key(s) it makes as well; normally this should + be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting + for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies + to all higher levels in the key hierarchy. Userspace should also + follow other security precautions such as mlock()ing memory + containing keys to prevent it from being swapped out. + +- In general, decrypted contents and filenames in the kernel VFS + caches are freed but not wiped. Therefore, portions thereof may be + recoverable from freed memory, even after the corresponding key(s) + were wiped. To partially solve this, you can set + CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1 + to your kernel command line. However, this has a performance cost. + +- Secret keys might still exist in CPU registers, in crypto + accelerator hardware (if used by the crypto API to implement any of + the algorithms), or in other places not explicitly considered here. + +Limitations of v1 policies +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +v1 encryption policies have some weaknesses with respect to online +attacks: + +- There is no verification that the provided master key is correct. + Therefore, a malicious user can temporarily associate the wrong key + with another user's encrypted files to which they have read-only + access. Because of filesystem caching, the wrong key will then be + used by the other user's accesses to those files, even if the other + user has the correct key in their own keyring. This violates the + meaning of "read-only access". + +- A compromise of a per-file key also compromises the master key from + which it was derived. + +- Non-root users cannot securely remove encryption keys. + +All the above problems are fixed with v2 encryption policies. For +this reason among others, it is recommended to use v2 encryption +policies on all new encrypted directories. Key hierarchy ============= @@ -123,11 +187,52 @@ appropriate master key. There can be any number of master keys, each of which protects any number of directory trees on any number of filesystems. -Userspace should generate master keys either using a cryptographically -secure random number generator, or by using a KDF (Key Derivation -Function). Note that whenever a KDF is used to "stretch" a -lower-entropy secret such as a passphrase, it is critical that a KDF -designed for this purpose be used, such as scrypt, PBKDF2, or Argon2. +Master keys must be real cryptographic keys, i.e. indistinguishable +from random bytestrings of the same length. This implies that users +**must not** directly use a password as a master key, zero-pad a +shorter key, or repeat a shorter key. Security cannot be guaranteed +if userspace makes any such error, as the cryptographic proofs and +analysis would no longer apply. + +Instead, users should generate master keys either using a +cryptographically secure random number generator, or by using a KDF +(Key Derivation Function). The kernel does not do any key stretching; +therefore, if userspace derives the key from a low-entropy secret such +as a passphrase, it is critical that a KDF designed for this purpose +be used, such as scrypt, PBKDF2, or Argon2. + +Key derivation function +----------------------- + +With one exception, fscrypt never uses the master key(s) for +encryption directly. Instead, they are only used as input to a KDF +(Key Derivation Function) to derive the actual keys. + +The KDF used for a particular master key differs depending on whether +the key is used for v1 encryption policies or for v2 encryption +policies. Users **must not** use the same key for both v1 and v2 +encryption policies. (No real-world attack is currently known on this +specific case of key reuse, but its security cannot be guaranteed +since the cryptographic proofs and analysis would no longer apply.) + +For v1 encryption policies, the KDF only supports deriving per-file +encryption keys. It works by encrypting the master key with +AES-128-ECB, using the file's 16-byte nonce as the AES key. The +resulting ciphertext is used as the derived key. If the ciphertext is +longer than needed, then it is truncated to the needed length. + +For v2 encryption policies, the KDF is HKDF-SHA512. The master key is +passed as the "input keying material", no salt is used, and a distinct +"application-specific information string" is used for each distinct +key to be derived. For example, when a per-file encryption key is +derived, the application-specific information string is the file's +nonce prefixed with "fscrypt\\0" and a context byte. Different +context bytes are used for other types of derived keys. + +HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because +HKDF is more flexible, is nonreversible, and evenly distributes +entropy from the master key. HKDF is also standardized and widely +used by other software, whereas the AES-128-ECB based KDF is ad-hoc. Per-file keys ------------- @@ -138,29 +243,9 @@ files doesn't map to the same ciphertext, or vice versa. In most cases, fscrypt does this by deriving per-file keys. When a new encrypted inode (regular file, directory, or symlink) is created, fscrypt randomly generates a 16-byte nonce and stores it in the -inode's encryption xattr. Then, it uses a KDF (Key Derivation -Function) to derive the file's key from the master key and nonce. - -The Adiantum encryption mode (see `Encryption modes and usage`_) is -special, since it accepts longer IVs and is suitable for both contents -and filenames encryption. For it, a "direct key" option is offered -where the file's nonce is included in the IVs and the master key is -used for encryption directly. This improves performance; however, -users must not use the same master key for any other encryption mode. - -Below, the KDF and design considerations are described in more detail. - -The current KDF works by encrypting the master key with AES-128-ECB, -using the file's nonce as the AES key. The output is used as the -derived key. If the output is longer than needed, then it is -truncated to the needed length. - -Note: this KDF meets the primary security requirement, which is to -produce unique derived keys that preserve the entropy of the master -key, assuming that the master key is already a good pseudorandom key. -However, it is nonstandard and has some problems such as being -reversible, so it is generally considered to be a mistake! It may be -replaced with HKDF or another more standard KDF in the future. +inode's encryption xattr. Then, it uses a KDF (as described in `Key +derivation function`_) to derive the file's key from the master key +and nonce. Key derivation was chosen over key wrapping because wrapped keys would require larger xattrs which would be less likely to fit in-line in the @@ -176,6 +261,37 @@ rejected as it would have prevented ext4 filesystems from being resized, and by itself still wouldn't have been sufficient to prevent the same key from being directly reused for both XTS and CTS-CBC. +DIRECT_KEY and per-mode keys +---------------------------- + +The Adiantum encryption mode (see `Encryption modes and usage`_) is +suitable for both contents and filenames encryption, and it accepts +long IVs --- long enough to hold both an 8-byte logical block number +and a 16-byte per-file nonce. Also, the overhead of each Adiantum key +is greater than that of an AES-256-XTS key. + +Therefore, to improve performance and save memory, for Adiantum a +"direct key" configuration is supported. When the user has enabled +this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, +per-file keys are not used. Instead, whenever any data (contents or +filenames) is encrypted, the file's 16-byte nonce is included in the +IV. Moreover: + +- For v1 encryption policies, the encryption is done directly with the + master key. Because of this, users **must not** use the same master + key for any other purpose, even for other v1 policies. + +- For v2 encryption policies, the encryption is done with a per-mode + key derived using the KDF. Users may use the same master key for + other v2 encryption policies. + +Key identifiers +--------------- + +For master keys used for v2 encryption policies, a unique 16-byte "key +identifier" is also derived using the KDF. This value is stored in +the clear, since it is needed to reliably identify the key itself. + Encryption modes and usage ========================== @@ -225,9 +341,10 @@ a little endian number, except that: is encrypted with AES-256 where the AES-256 key is the SHA-256 hash of the file's data encryption key. -- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in - the fscrypt_policy), the file's nonce is also appended to the IV. - Currently this is only allowed with the Adiantum encryption mode. +- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY + set in the fscrypt_policy), the file's nonce is also appended to the + IV. Currently this is only allowed with the Adiantum encryption + mode. Filenames encryption -------------------- @@ -269,49 +386,77 @@ User API Setting an encryption policy ---------------------------- +FS_IOC_SET_ENCRYPTION_POLICY +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an empty directory or verifies that a directory or regular file already has the specified encryption policy. It takes in a pointer to a -:c:type:`struct fscrypt_policy`, defined as follows:: +:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct +fscrypt_policy_v2`, defined as follows:: - #define FS_KEY_DESCRIPTOR_SIZE 8 + #define FSCRYPT_POLICY_V1 0 + #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 + struct fscrypt_policy_v1 { + __u8 version; + __u8 contents_encryption_mode; + __u8 filenames_encryption_mode; + __u8 flags; + __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; + }; + #define fscrypt_policy fscrypt_policy_v1 - struct fscrypt_policy { + #define FSCRYPT_POLICY_V2 2 + #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 + struct fscrypt_policy_v2 { __u8 version; __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; - __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; + __u8 __reserved[4]; + __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; }; This structure must be initialized as follows: -- ``version`` must be 0. +- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is + :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct + is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original + policy version as "v1", though its version code is really 0.) For + new encrypted directories, use v2 policies. - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must - be set to constants from ``<linux/fs.h>`` which identify the - encryption modes to use. If unsure, use - FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` - and FS_ENCRYPTION_MODE_AES_256_CTS (4) for - ``filenames_encryption_mode``. + be set to constants from ``<linux/fscrypt.h>`` which identify the + encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS + (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS + (4) for ``filenames_encryption_mode``. -- ``flags`` must contain a value from ``<linux/fs.h>`` which +- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which identifies the amount of NUL-padding to use when encrypting - filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). - In addition, if the chosen encryption modes are both - FS_ENCRYPTION_MODE_ADIANTUM, this can contain - FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be - used directly, without key derivation. - -- ``master_key_descriptor`` specifies how to find the master key in - the keyring; see `Adding keys`_. It is up to userspace to choose a - unique ``master_key_descriptor`` for each master key. The e4crypt - and fscrypt tools use the first 8 bytes of + filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3). + Additionally, if the encryption modes are both + FSCRYPT_MODE_ADIANTUM, this can contain + FSCRYPT_POLICY_FLAG_DIRECT_KEY; see `DIRECT_KEY and per-mode keys`_. + +- For v2 encryption policies, ``__reserved`` must be zeroed. + +- For v1 encryption policies, ``master_key_descriptor`` specifies how + to find the master key in a keyring; see `Adding keys`_. It is up + to userspace to choose a unique ``master_key_descriptor`` for each + master key. The e4crypt and fscrypt tools use the first 8 bytes of ``SHA-512(SHA-512(master_key))``, but this particular scheme is not required. Also, the master key need not be in the keyring yet when FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added before any files can be created in the encrypted directory. + For v2 encryption policies, ``master_key_descriptor`` has been + replaced with ``master_key_identifier``, which is longer and cannot + be arbitrarily chosen. Instead, the key must first be added using + `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` + the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must + be used as the ``master_key_identifier`` in the :c:type:`struct + fscrypt_policy_v2`. + If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY verifies that the file is an empty directory. If so, the specified encryption policy is assigned to the directory, turning it into an @@ -327,6 +472,15 @@ policy exactly matches the actual one. If they match, then the ioctl returns 0. Otherwise, it fails with EEXIST. This works on both regular files and directories, including nonempty directories. +When a v2 encryption policy is assigned to a directory, it is also +required that either the specified key has been added by the current +user or that the caller has CAP_FOWNER in the initial user namespace. +(This is needed to prevent a user from encrypting their data with +another user's key.) The key must remain added while +FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new +encrypted directory does not need to be accessed immediately, then the +key can be removed right away afterwards. + Note that the ext4 filesystem does not allow the root directory to be encrypted, even if it is empty. Users who want to encrypt an entire filesystem with one key should consider using dm-crypt instead. @@ -339,7 +493,11 @@ FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: - ``EEXIST``: the file is already encrypted with an encryption policy different from the one specified - ``EINVAL``: an invalid encryption policy was specified (invalid - version, mode(s), or flags) + version, mode(s), or flags; or reserved bits were set) +- ``ENOKEY``: a v2 encryption policy was specified, but the key with + the specified ``master_key_identifier`` has not been added, nor does + the process have the CAP_FOWNER capability in the initial user + namespace - ``ENOTDIR``: the file is unencrypted and is a regular file, not a directory - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory @@ -358,25 +516,79 @@ FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: Getting an encryption policy ---------------------------- -The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct -fscrypt_policy`, if any, for a directory or regular file. See above -for the struct definition. No additional permissions are required -beyond the ability to open the file. +Two ioctls are available to get a file's encryption policy: + +- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ +- `FS_IOC_GET_ENCRYPTION_POLICY`_ + +The extended (_EX) version of the ioctl is more general and is +recommended to use when possible. However, on older kernels only the +original ioctl is available. Applications should try the extended +version, and if it fails with ENOTTY fall back to the original +version. + +FS_IOC_GET_ENCRYPTION_POLICY_EX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption +policy, if any, for a directory or regular file. No additional +permissions are required beyond the ability to open the file. It +takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`, +defined as follows:: + + struct fscrypt_get_policy_ex_arg { + __u64 policy_size; /* input/output */ + union { + __u8 version; + struct fscrypt_policy_v1 v1; + struct fscrypt_policy_v2 v2; + } policy; /* output */ + }; + +The caller must initialize ``policy_size`` to the size available for +the policy struct, i.e. ``sizeof(arg.policy)``. + +On success, the policy struct is returned in ``policy``, and its +actual size is returned in ``policy_size``. ``policy.version`` should +be checked to determine the version of policy returned. Note that the +version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1). -FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: +FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors: - ``EINVAL``: the file is encrypted, but it uses an unrecognized - encryption context format + encryption policy version - ``ENODATA``: the file is not encrypted -- ``ENOTTY``: this type of filesystem does not implement encryption +- ``ENOTTY``: this type of filesystem does not implement encryption, + or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX + (try FS_IOC_GET_ENCRYPTION_POLICY instead) - ``EOPNOTSUPP``: the kernel was not configured with encryption - support for this filesystem + support for this filesystem, or the filesystem superblock has not + had encryption enabled on it +- ``EOVERFLOW``: the file is encrypted and uses a recognized + encryption policy version, but the policy struct does not fit into + the provided buffer Note: if you only need to know whether a file is encrypted or not, on most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl and check for FS_ENCRYPT_FL, or to use the statx() system call and check for STATX_ATTR_ENCRYPTED in stx_attributes. +FS_IOC_GET_ENCRYPTION_POLICY +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the +encryption policy, if any, for a directory or regular file. However, +unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, +FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy +version. It takes in a pointer directly to a :c:type:`struct +fscrypt_policy_v1` rather than a :c:type:`struct +fscrypt_get_policy_ex_arg`. + +The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those +for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that +FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is +encrypted using a newer encryption policy version. + Getting the per-filesystem salt ------------------------------- @@ -392,8 +604,115 @@ generate and manage any needed salt(s) in userspace. Adding keys ----------- -To provide a master key, userspace must add it to an appropriate -keyring using the add_key() system call (see: +FS_IOC_ADD_ENCRYPTION_KEY +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to +the filesystem, making all files on the filesystem which were +encrypted using that key appear "unlocked", i.e. in plaintext form. +It can be executed on any file or directory on the target filesystem, +but using the filesystem's root directory is recommended. It takes in +a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as +follows:: + + struct fscrypt_add_key_arg { + struct fscrypt_key_specifier key_spec; + __u32 raw_size; + __u32 __reserved[9]; + __u8 raw[]; + }; + + #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 + #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 + + struct fscrypt_key_specifier { + __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ + __u32 __reserved; + union { + __u8 __reserved[32]; /* reserve some extra space */ + __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; + __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; + } u; + }; + +:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized +as follows: + +- If the key is being added for use by v1 encryption policies, then + ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and + ``key_spec.u.descriptor`` must contain the descriptor of the key + being added, corresponding to the value in the + ``master_key_descriptor`` field of :c:type:`struct + fscrypt_policy_v1`. To add this type of key, the calling process + must have the CAP_SYS_ADMIN capability in the initial user + namespace. + + Alternatively, if the key is being added for use by v2 encryption + policies, then ``key_spec.type`` must contain + FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is + an *output* field which the kernel fills in with a cryptographic + hash of the key. To add this type of key, the calling process does + not need any privileges. However, the number of keys that can be + added is limited by the user's quota for the keyrings service (see + ``Documentation/security/keys/core.rst``). + +- ``raw_size`` must be the size of the ``raw`` key provided, in bytes. + +- ``raw`` is a variable-length field which must contain the actual + key, ``raw_size`` bytes long. + +For v2 policy keys, the kernel keeps track of which user (identified +by effective user ID) added the key, and only allows the key to be +removed by that user --- or by "root", if they use +`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_. + +However, if another user has added the key, it may be desirable to +prevent that other user from unexpectedly removing it. Therefore, +FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key +*again*, even if it's already added by other user(s). In this case, +FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the +current user, rather than actually add the key again (but the raw key +must still be provided, as a proof of knowledge). + +FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to +the key was either added or already exists. + +FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors: + +- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the + caller does not have the CAP_SYS_ADMIN capability in the initial + user namespace +- ``EDQUOT``: the key quota for this user would be exceeded by adding + the key +- ``EINVAL``: invalid key size or key specifier type, or reserved bits + were set +- ``ENOTTY``: this type of filesystem does not implement encryption +- ``EOPNOTSUPP``: the kernel was not configured with encryption + support for this filesystem, or the filesystem superblock has not + had encryption enabled on it + +Legacy method +~~~~~~~~~~~~~ + +For v1 encryption policies, a master encryption key can also be +provided by adding it to a process-subscribed keyring, e.g. to a +session keyring, or to a user keyring if the user keyring is linked +into the session keyring. + +This method is deprecated (and not supported for v2 encryption +policies) for several reasons. First, it cannot be used in +combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_), +so for removing a key a workaround such as keyctl_unlink() in +combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would +have to be used. Second, it doesn't match the fact that the +locked/unlocked status of encrypted files (i.e. whether they appear to +be in plaintext form or in ciphertext form) is global. This mismatch +has caused much confusion as well as real problems when processes +running under different UIDs, such as a ``sudo`` command, need to +access encrypted files. + +Nevertheless, to add a key to one of the process-subscribed keyrings, +the add_key() system call can be used (see: ``Documentation/security/keys/core.rst``). The key type must be "logon"; keys of this type are kept in kernel memory and cannot be read back by userspace. The key description must be "fscrypt:" @@ -401,12 +720,12 @@ followed by the 16-character lower case hex representation of the ``master_key_descriptor`` that was set in the encryption policy. The key payload must conform to the following structure:: - #define FS_MAX_KEY_SIZE 64 + #define FSCRYPT_MAX_KEY_SIZE 64 struct fscrypt_key { - u32 mode; - u8 raw[FS_MAX_KEY_SIZE]; - u32 size; + __u32 mode; + __u8 raw[FSCRYPT_MAX_KEY_SIZE]; + __u32 size; }; ``mode`` is ignored; just set it to 0. The actual key is provided in @@ -418,26 +737,194 @@ with a filesystem-specific prefix such as "ext4:". However, the filesystem-specific prefixes are deprecated and should not be used in new programs. -There are several different types of keyrings in which encryption keys -may be placed, such as a session keyring, a user session keyring, or a -user keyring. Each key must be placed in a keyring that is "attached" -to all processes that might need to access files encrypted with it, in -the sense that request_key() will find the key. Generally, if only -processes belonging to a specific user need to access a given -encrypted directory and no session keyring has been installed, then -that directory's key should be placed in that user's user session -keyring or user keyring. Otherwise, a session keyring should be -installed if needed, and the key should be linked into that session -keyring, or in a keyring linked into that session keyring. - -Note: introducing the complex visibility semantics of keyrings here -was arguably a mistake --- especially given that by design, after any -process successfully opens an encrypted file (thereby setting up the -per-file key), possessing the keyring key is not actually required for -any process to read/write the file until its in-memory inode is -evicted. In the future there probably should be a way to provide keys -directly to the filesystem instead, which would make the intended -semantics clearer. +Removing keys +------------- + +Two ioctls are available for removing a key that was added by +`FS_IOC_ADD_ENCRYPTION_KEY`_: + +- `FS_IOC_REMOVE_ENCRYPTION_KEY`_ +- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ + +These two ioctls differ only in cases where v2 policy keys are added +or removed by non-root users. + +These ioctls don't work on keys that were added via the legacy +process-subscribed keyrings mechanism. + +Before using these ioctls, read the `Kernel memory compromise`_ +section for a discussion of the security goals and limitations of +these ioctls. + +FS_IOC_REMOVE_ENCRYPTION_KEY +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master +encryption key from the filesystem, and possibly removes the key +itself. It can be executed on any file or directory on the target +filesystem, but using the filesystem's root directory is recommended. +It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`, +defined as follows:: + + struct fscrypt_remove_key_arg { + struct fscrypt_key_specifier key_spec; + #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 + #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 + __u32 removal_status_flags; /* output */ + __u32 __reserved[5]; + }; + +This structure must be zeroed, then initialized as follows: + +- The key to remove is specified by ``key_spec``: + + - To remove a key used by v1 encryption policies, set + ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill + in ``key_spec.u.descriptor``. To remove this type of key, the + calling process must have the CAP_SYS_ADMIN capability in the + initial user namespace. + + - To remove a key used by v2 encryption policies, set + ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill + in ``key_spec.u.identifier``. + +For v2 policy keys, this ioctl is usable by non-root users. However, +to make this possible, it actually just removes the current user's +claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. +Only after all claims are removed is the key really removed. + +For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, +then the key will be "claimed" by uid 1000, and +FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if +both uids 1000 and 2000 added the key, then for each uid +FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only +once *both* are removed is the key really removed. (Think of it like +unlinking a file that may have hard links.) + +If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also +try to "lock" all files that had been unlocked with the key. It won't +lock files that are still in-use, so this ioctl is expected to be used +in cooperation with userspace ensuring that none of the files are +still open. However, if necessary, this ioctl can be executed again +later to retry locking any remaining files. + +FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed +(but may still have files remaining to be locked), the user's claim to +the key was removed, or the key was already removed but had files +remaining to be the locked so the ioctl retried locking them. In any +of these cases, ``removal_status_flags`` is filled in with the +following informational status flags: + +- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) + are still in-use. Not guaranteed to be set in the case where only + the user's claim to the key was removed. +- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the + user's claim to the key was removed, not the key itself + +FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors: + +- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type + was specified, but the caller does not have the CAP_SYS_ADMIN + capability in the initial user namespace +- ``EINVAL``: invalid key specifier type, or reserved bits were set +- ``ENOKEY``: the key object was not found at all, i.e. it was never + added in the first place or was already fully removed including all + files locked; or, the user does not have a claim to the key (but + someone else does). +- ``ENOTTY``: this type of filesystem does not implement encryption +- ``EOPNOTSUPP``: the kernel was not configured with encryption + support for this filesystem, or the filesystem superblock has not + had encryption enabled on it + +FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as +`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the +ALL_USERS version of the ioctl will remove all users' claims to the +key, not just the current user's. I.e., the key itself will always be +removed, no matter how many users have added it. This difference is +only meaningful if non-root users are adding and removing keys. + +Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires +"root", namely the CAP_SYS_ADMIN capability in the initial user +namespace. Otherwise it will fail with EACCES. + +Getting key status +------------------ + +FS_IOC_GET_ENCRYPTION_KEY_STATUS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a +master encryption key. It can be executed on any file or directory on +the target filesystem, but using the filesystem's root directory is +recommended. It takes in a pointer to a :c:type:`struct +fscrypt_get_key_status_arg`, defined as follows:: + + struct fscrypt_get_key_status_arg { + /* input */ + struct fscrypt_key_specifier key_spec; + __u32 __reserved[6]; + + /* output */ + #define FSCRYPT_KEY_STATUS_ABSENT 1 + #define FSCRYPT_KEY_STATUS_PRESENT 2 + #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 + __u32 status; + #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 + __u32 status_flags; + __u32 user_count; + __u32 __out_reserved[13]; + }; + +The caller must zero all input fields, then fill in ``key_spec``: + + - To get the status of a key for v1 encryption policies, set + ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill + in ``key_spec.u.descriptor``. + + - To get the status of a key for v2 encryption policies, set + ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill + in ``key_spec.u.identifier``. + +On success, 0 is returned and the kernel fills in the output fields: + +- ``status`` indicates whether the key is absent, present, or + incompletely removed. Incompletely removed means that the master + secret has been removed, but some files are still in use; i.e., + `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational + status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. + +- ``status_flags`` can contain the following flags: + + - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key + has added by the current user. This is only set for keys + identified by ``identifier`` rather than by ``descriptor``. + +- ``user_count`` specifies the number of users who have added the key. + This is only set for keys identified by ``identifier`` rather than + by ``descriptor``. + +FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors: + +- ``EINVAL``: invalid key specifier type, or reserved bits were set +- ``ENOTTY``: this type of filesystem does not implement encryption +- ``EOPNOTSUPP``: the kernel was not configured with encryption + support for this filesystem, or the filesystem superblock has not + had encryption enabled on it + +Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful +for determining whether the key for a given encrypted directory needs +to be added before prompting the user for the passphrase needed to +derive the key. + +FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in +the filesystem-level keyring, i.e. the keyring managed by +`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It +cannot get the status of a key that has only been added for use by v1 +encryption policies using the legacy mechanism involving +process-subscribed keyrings. Access semantics ================ @@ -500,7 +987,7 @@ Without the key Some filesystem operations may be performed on encrypted regular files, directories, and symlinks even before their encryption key has -been provided: +been added, or after their encryption key has been removed: - File metadata may be read, e.g. using stat(). @@ -565,33 +1052,44 @@ Encryption context ------------------ An encryption policy is represented on-disk by a :c:type:`struct -fscrypt_context`. It is up to individual filesystems to decide where -to store it, but normally it would be stored in a hidden extended -attribute. It should *not* be exposed by the xattr-related system -calls such as getxattr() and setxattr() because of the special -semantics of the encryption xattr. (In particular, there would be -much confusion if an encryption policy were to be added to or removed -from anything other than an empty directory.) The struct is defined -as follows:: - - #define FS_KEY_DESCRIPTOR_SIZE 8 +fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is +up to individual filesystems to decide where to store it, but normally +it would be stored in a hidden extended attribute. It should *not* be +exposed by the xattr-related system calls such as getxattr() and +setxattr() because of the special semantics of the encryption xattr. +(In particular, there would be much confusion if an encryption policy +were to be added to or removed from anything other than an empty +directory.) These structs are defined as follows:: + #define FS_KEY_DERIVATION_NONCE_SIZE 16 - struct fscrypt_context { - u8 format; + #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 + struct fscrypt_context_v1 { + u8 version; + u8 contents_encryption_mode; + u8 filenames_encryption_mode; + u8 flags; + u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; + u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; + }; + + #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 + struct fscrypt_context_v2 { + u8 version; u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; - u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; + u8 __reserved[4]; + u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; }; -Note that :c:type:`struct fscrypt_context` contains the same -information as :c:type:`struct fscrypt_policy` (see `Setting an -encryption policy`_), except that :c:type:`struct fscrypt_context` -also contains a nonce. The nonce is randomly generated by the kernel -and is used to derive the inode's encryption key as described in -`Per-file keys`_. +The context structs contain the same information as the corresponding +policy structs (see `Setting an encryption policy`_), except that the +context structs also contain a nonce. The nonce is randomly generated +by the kernel and is used as KDF input or as a tweak to cause +different files to be encrypted differently; see `Per-file keys`_ and +`DIRECT_KEY and per-mode keys`_. Data path changes ----------------- diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 54f2c6aac187..fd2bcf99cda0 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -20,6 +20,10 @@ algorithms work. path-lookup api-summary splice + locking + directory-locking + + porting Filesystem support layers ========================= diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst index 204dd3ea36bb..fc3a0704553c 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/locking.rst @@ -1,14 +1,22 @@ - The text below describes the locking rules for VFS-related methods. +======= +Locking +======= + +The text below describes the locking rules for VFS-related methods. It is (believed to be) up-to-date. *Please*, if you change anything in prototypes or locking protocols - update this file. And update the relevant instances in the tree, don't leave that to maintainers of filesystems/devices/ etc. At the very least, put the list of dubious cases in the end of this file. Don't turn it into log - maintainers of out-of-the-tree code are supposed to be able to use diff(1). - Thing currently missing here: socket operations. Alexey? ---------------------------- dentry_operations -------------------------- -prototypes: +Thing currently missing here: socket operations. Alexey? + +dentry_operations +================= + +prototypes:: + int (*d_revalidate)(struct dentry *, unsigned int); int (*d_weak_revalidate)(struct dentry *, unsigned int); int (*d_hash)(const struct dentry *, struct qstr *); @@ -24,23 +32,30 @@ prototypes: struct dentry *(*d_real)(struct dentry *, const struct inode *); locking rules: - rename_lock ->d_lock may block rcu-walk -d_revalidate: no no yes (ref-walk) maybe -d_weak_revalidate:no no yes no -d_hash no no no maybe -d_compare: yes no no maybe -d_delete: no yes no no -d_init: no no yes no -d_release: no no yes no -d_prune: no yes no no -d_iput: no no yes no -d_dname: no no no no -d_automount: no no yes no -d_manage: no no yes (ref-walk) maybe -d_real no no yes no - ---------------------------- inode_operations --------------------------- -prototypes: + +================== =========== ======== ============== ======== +ops rename_lock ->d_lock may block rcu-walk +================== =========== ======== ============== ======== +d_revalidate: no no yes (ref-walk) maybe +d_weak_revalidate: no no yes no +d_hash no no no maybe +d_compare: yes no no maybe +d_delete: no yes no no +d_init: no no yes no +d_release: no no yes no +d_prune: no yes no no +d_iput: no no yes no +d_dname: no no no no +d_automount: no no yes no +d_manage: no no yes (ref-walk) maybe +d_real no no yes no +================== =========== ======== ============== ======== + +inode_operations +================ + +prototypes:: + int (*create) (struct inode *,struct dentry *,umode_t, bool); struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); int (*link) (struct dentry *,struct inode *,struct dentry *); @@ -68,7 +83,10 @@ prototypes: locking rules: all may block - i_rwsem(inode) + +============ ============================================= +ops i_rwsem(inode) +============ ============================================= lookup: shared create: exclusive link: exclusive (both) @@ -89,17 +107,21 @@ fiemap: no update_time: no atomic_open: exclusive tmpfile: no +============ ============================================= Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem exclusive on victim. cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. -See Documentation/filesystems/directory-locking for more detailed discussion +See Documentation/filesystems/directory-locking.rst for more detailed discussion of the locking scheme for directory operations. ------------------------ xattr_handler operations ----------------------- -prototypes: +xattr_handler operations +======================== + +prototypes:: + bool (*list)(struct dentry *dentry); int (*get)(const struct xattr_handler *handler, struct dentry *dentry, struct inode *inode, const char *name, void *buffer, @@ -110,13 +132,20 @@ prototypes: locking rules: all may block - i_rwsem(inode) + +===== ============== +ops i_rwsem(inode) +===== ============== list: no get: no set: exclusive +===== ============== + +super_operations +================ + +prototypes:: ---------------------------- super_operations --------------------------- -prototypes: struct inode *(*alloc_inode)(struct super_block *sb); void (*free_inode)(struct inode *); void (*destroy_inode)(struct inode *); @@ -138,7 +167,10 @@ prototypes: locking rules: All may block [not true, see below] - s_umount + +====================== ============ ======================== +ops s_umount note +====================== ============ ======================== alloc_inode: free_inode: called from RCU callback destroy_inode: @@ -157,6 +189,7 @@ show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) bdev_try_to_free_page: no (see below) +====================== ============ ======================== ->statfs() has s_umount (shared) when called by ustat(2) (native or compat), but that's an accident of bad API; s_umount is used to pin @@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to identify the superblock. Everything else (statfs(), fstatfs(), etc.) doesn't hold it when calling ->statfs() - superblock is pinned down by resolving the pathname passed to syscall. + ->quota_read() and ->quota_write() functions are both guaranteed to be the only ones operating on the quota file by the quota code (via dqio_sem) (unless an admin really wants to screw up something and writes to quota files with quotas on). For other details about locking see also dquot_operations section. + ->bdev_try_to_free_page is called from the ->releasepage handler of the block device inode. See there for more details. ---------------------------- file_system_type --------------------------- -prototypes: +file_system_type +================ + +prototypes:: + struct dentry *(*mount) (struct file_system_type *, int, const char *, void *); void (*kill_sb) (struct super_block *); + locking rules: - may block + +======= ========= +ops may block +======= ========= mount yes kill_sb yes +======= ========= ->mount() returns ERR_PTR or the root dentry; its superblock should be locked on return. + ->kill_sb() takes a write-locked superblock, does all shutdown work on it, unlocks and drops the reference. ---------------------------- address_space_operations -------------------------- -prototypes: +address_space_operations +======================== +prototypes:: + int (*writepage)(struct page *page, struct writeback_control *wbc); int (*readpage)(struct file *, struct page *); int (*writepages)(struct address_space *, struct writeback_control *); @@ -218,14 +264,16 @@ prototypes: locking rules: All except set_page_dirty and freepage may block - PageLocked(page) i_rwsem +====================== ======================== ========= +ops PageLocked(page) i_rwsem +====================== ======================== ========= writepage: yes, unlocks (see below) readpage: yes, unlocks writepages: set_page_dirty no readpages: -write_begin: locks the page exclusive -write_end: yes, unlocks exclusive +write_begin: locks the page exclusive +write_end: yes, unlocks exclusive bmap: invalidatepage: yes releasepage: yes @@ -239,17 +287,18 @@ is_partially_uptodate: yes error_remove_page: yes swap_activate: no swap_deactivate: no +====================== ======================== ========= - ->write_begin(), ->write_end() and ->readpage() may be called from +->write_begin(), ->write_end() and ->readpage() may be called from the request handler (/dev/loop). - ->readpage() unlocks the page, either synchronously or via I/O +->readpage() unlocks the page, either synchronously or via I/O completion. - ->readpages() populates the pagecache with the passed pages and starts +->readpages() populates the pagecache with the passed pages and starts I/O against them. They come unlocked upon I/O completion. - ->writepage() is used for two purposes: for "memory cleansing" and for +->writepage() is used for two purposes: for "memory cleansing" and for "sync". These are quite different operations and the behaviour may differ depending upon the mode. @@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the radix tree. This incoherency can lead to all sorts of hard-to-debug problems in the filesystem like having dirty inodes at umount and losing written data. - ->writepages() is used for periodic writeback and for syscall-initiated +->writepages() is used for periodic writeback and for syscall-initiated sync operations. The address_space should start I/O against at least -*nr_to_write pages. *nr_to_write must be decremented for each page which is -written. The address_space implementation may write more (or less) pages -than *nr_to_write asks for, but it should try to be reasonably close. If -nr_to_write is NULL, all dirty pages must be written. +``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page +which is written. The address_space implementation may write more (or less) +pages than ``*nr_to_write`` asks for, but it should try to be reasonably close. +If nr_to_write is NULL, all dirty pages must be written. writepages should _only_ write pages which are present on mapping->io_pages. - ->set_page_dirty() is called from various places in the kernel +->set_page_dirty() is called from various places in the kernel when the target page is marked as needing writeback. It may be called under spinlock (it cannot block) and is sometimes called with the page not locked. - ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some +->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some filesystems and by the swapper. The latter will eventually go away. Please, keep it that way and don't breed new callers. - ->invalidatepage() is called when the filesystem must attempt to drop +->invalidatepage() is called when the filesystem must attempt to drop some or all of the buffers from the page when it is being truncated. It returns zero on success. If ->invalidatepage is zero, the kernel uses block_invalidatepage() instead. - ->releasepage() is called when the kernel is about to try to drop the +->releasepage() is called when the kernel is about to try to drop the buffers from the page in preparation for freeing it. It returns zero to indicate that the buffers are (or may be) freeable. If ->releasepage is zero, the kernel assumes that the fs has no private interest in the buffers. - ->freepage() is called when the kernel is done dropping the page +->freepage() is called when the kernel is done dropping the page from the page cache. - ->launder_page() may be called prior to releasing a page if +->launder_page() may be called prior to releasing a page if it is still found to be dirty. It returns zero if the page was successfully cleaned, or an error value if not. Note that in order to prevent the page getting mapped back in and redirtied, it needs to be kept locked across the entire operation. - ->swap_activate will be called with a non-zero argument on +->swap_activate will be called with a non-zero argument on files backing (non block device backed) swapfiles. A return value of zero indicates success, in which case this file can be used for backing swapspace. The swapspace operations will be proxied to the address space operations. - ->swap_deactivate() will be called in the sys_swapoff() +->swap_deactivate() will be called in the sys_swapoff() path after ->swap_activate() returned success. ------------------------ file_lock_operations ------------------------------ -prototypes: +file_lock_operations +==================== + +prototypes:: + void (*fl_copy_lock)(struct file_lock *, struct file_lock *); void (*fl_release_private)(struct file_lock *); locking rules: - inode->i_lock may block + +=================== ============= ========= +ops inode->i_lock may block +=================== ============= ========= fl_copy_lock: yes no -fl_release_private: maybe maybe[1] +fl_release_private: maybe maybe[1]_ +=================== ============= ========= + +.. [1]: + ->fl_release_private for flock or POSIX locks is currently allowed + to block. Leases however can still be freed while the i_lock is held and + so fl_release_private called on a lease should not block. -[1]: ->fl_release_private for flock or POSIX locks is currently allowed -to block. Leases however can still be freed while the i_lock is held and -so fl_release_private called on a lease should not block. +lock_manager_operations +======================= + +prototypes:: ------------------------ lock_manager_operations --------------------------- -prototypes: void (*lm_notify)(struct file_lock *); /* unblock callback */ int (*lm_grant)(struct file_lock *, struct file_lock *, int); void (*lm_break)(struct file_lock *); /* break_lease callback */ @@ -368,24 +428,33 @@ prototypes: locking rules: - inode->i_lock blocked_lock_lock may block +========== ============= ================= ========= +ops inode->i_lock blocked_lock_lock may block +========== ============= ================= ========= lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no +========== ============= ================= ========= + +buffer_head +=========== + +prototypes:: ---------------------------- buffer_head ----------------------------------- -prototypes: void (*b_end_io)(struct buffer_head *bh, int uptodate); locking rules: - called from interrupts. In other words, extreme care is needed here. + +called from interrupts. In other words, extreme care is needed here. bh is locked, but that's all warranties we have here. Currently only RAID1, highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices call this method upon the IO completion. ---------------------------- block_device_operations ----------------------- -prototypes: +block_device_operations +======================= +prototypes:: + int (*open) (struct block_device *, fmode_t); int (*release) (struct gendisk *, fmode_t); int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); @@ -399,7 +468,10 @@ prototypes: void (*swap_slot_free_notify) (struct block_device *, unsigned long); locking rules: - bd_mutex + +======================= =================== +ops bd_mutex +======================= =================== open: yes release: yes ioctl: no @@ -410,6 +482,7 @@ unlock_native_capacity: no revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) +======================= =================== media_changed, unlock_native_capacity and revalidate_disk are called only from check_disk_change(). @@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock held. ---------------------------- file_operations ------------------------------- -prototypes: +file_operations +=============== + +prototypes:: + loff_t (*llseek) (struct file *, loff_t, int); ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); @@ -455,7 +531,6 @@ prototypes: size_t, unsigned int); int (*setlease)(struct file *, long, struct file_lock **, void **); long (*fallocate)(struct file *, int, loff_t, loff_t); -}; locking rules: All may block. @@ -490,8 +565,11 @@ in sys_read() and friends. the lease within the individual filesystem to record the result of the operation ---------------------------- dquot_operations ------------------------------- -prototypes: +dquot_operations +================ + +prototypes:: + int (*write_dquot) (struct dquot *); int (*acquire_dquot) (struct dquot *); int (*release_dquot) (struct dquot *); @@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations. What filesystem should expect from the generic quota functions: - FS recursion Held locks when called +============== ============ ========================= +ops FS recursion Held locks when called +============== ============ ========================= write_dquot: yes dqonoff_sem or dqptr_sem acquire_dquot: yes dqonoff_sem or dqptr_sem release_dquot: yes dqonoff_sem or dqptr_sem mark_dirty: no - write_info: yes dqonoff_sem +============== ============ ========================= FS recursion means calling ->quota_read() and ->quota_write() from superblock operations. More details about quota locking can be found in fs/dquot.c. ---------------------------- vm_operations_struct ----------------------------- -prototypes: +vm_operations_struct +==================== + +prototypes:: + void (*open)(struct vm_area_struct*); void (*close)(struct vm_area_struct*); vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); @@ -525,7 +609,10 @@ prototypes: int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); locking rules: - mmap_sem PageLocked(page) + +============= ======== =========================== +ops mmap_sem PageLocked(page) +============= ======== =========================== open: yes close: yes fault: yes can return with page locked @@ -533,8 +620,9 @@ map_pages: yes page_mkwrite: yes can return with page locked pfn_mkwrite: yes access: yes +============= ======== =========================== - ->fault() is called when a previously not present pte is about +->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated with the passed in "pgoff" in the vm_fault structure. If it is possible that the page may be truncated and/or invalidated, then the filesystem must lock @@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block subsequent truncate), and then return with VM_FAULT_LOCKED, and the page locked. The VM will unlock the page. - ->map_pages() is called when VM asks to map easy accessible pages. +->map_pages() is called when VM asks to map easy accessible pages. Filesystem should find and map pages associated with offsets from "start_pgoff" till "end_pgoff". ->map_pages() is called with page table locked and must not block. If it's not possible to reach a page without blocking, @@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in "pte" field in vm_fault structure. Pointers to entries for other offsets should be calculated relative to "pte". - ->page_mkwrite() is called when a previously read-only pte is +->page_mkwrite() is called when a previously read-only pte is about to become writeable. The filesystem again must ensure that there are no truncate/invalidate races, and then return with the page locked. If the page has been truncated, the filesystem should not look up a new page like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to retry the fault. - ->pfn_mkwrite() is the same as page_mkwrite but when the pte is +->pfn_mkwrite() is the same as page_mkwrite but when the pte is VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior after this call is to make the pte read-write, unless pfn_mkwrite returns an error. - ->access() is called when get_user_pages() fails in +->access() is called when get_user_pages() fails in access_process_vm(), typically used to debug a process through /proc/pid/mem or ptrace. This function is needed only for VM_IO | VM_PFNMAP VMAs. -================================================================================ +-------------------------------------------------------------------------------- + Dubious stuff (if you break something or notice that it is broken and do not fix it yourself diff --git a/Documentation/filesystems/mandatory-locking.txt b/Documentation/filesystems/mandatory-locking.txt index 0979d1d2ca8b..a251ca33164a 100644 --- a/Documentation/filesystems/mandatory-locking.txt +++ b/Documentation/filesystems/mandatory-locking.txt @@ -169,3 +169,13 @@ havoc if they lock crucial files. The way around it is to change the file permissions (remove the setgid bit) before trying to read or write to it. Of course, that might be a bit tricky if the system is hung :-( +7. The "mand" mount option +-------------------------- +Mandatory locking is disabled on all filesystems by default, and must be +administratively enabled by mounting with "-o mand". That mount option +is only allowed if the mounting task has the CAP_SYS_ADMIN capability. + +Since kernel v4.5, it is possible to disable mandatory locking +altogether by setting CONFIG_MANDATORY_FILE_LOCKING to "n". A kernel +with this disabled will reject attempts to mount filesystems with the +"mand" mount option with the error status EPERM. diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst index 63889149f532..33d588a01ace 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/exporting.rst @@ -1,3 +1,4 @@ +:orphan: Making Filesystems Exportable ============================= @@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix for the object. This leads to two related but distinct features of the dcache that are not needed for normal filesystem access. -1/ The dcache must sometimes contain objects that are not part of the +1. The dcache must sometimes contain objects that are not part of the proper prefix. i.e that are not connected to the root. -2/ The dcache must be prepared for a newly found (via ->lookup) directory +2. The dcache must be prepared for a newly found (via ->lookup) directory to already have a (non-connected) dentry, and must be able to move that dentry into place (based on the parent and name in the ->lookup). This is particularly needed for directories as @@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access. To implement these features, the dcache has: -a/ A dentry flag DCACHE_DISCONNECTED which is set on +a. A dentry flag DCACHE_DISCONNECTED which is set on any dentry that might not be part of the proper prefix. This is set when anonymous dentries are created, and cleared when a dentry is noticed to be a child of a dentry which is in the proper @@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on dentries. That guarantees that we won't need to hunt them down upon umount. -b/ A primitive for creation of secondary roots - d_obtain_root(inode). +b. A primitive for creation of secondary roots - d_obtain_root(inode). Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the per-superblock list (->s_roots), so they can be located at umount time for eviction purposes. -c/ Helper routines to allocate anonymous dentries, and to help attach +c. Helper routines to allocate anonymous dentries, and to help attach loose directory dentries at lookup time. They are: + d_obtain_alias(inode) will return a dentry for the given inode. If the inode already has a dentry, one of those is returned. + If it doesn't, a new anonymous (IS_ROOT and - DCACHE_DISCONNECTED) dentry is allocated and attached. + DCACHE_DISCONNECTED) dentry is allocated and attached. + In the case of a directory, care is taken that only one dentry can ever be attached. + d_splice_alias(inode, dentry) will introduce a new dentry into the tree; either the passed-in dentry or a preexisting alias for the given inode (such as an anonymous one created by d_obtain_alias), if appropriate. It returns NULL when the passed-in dentry is used, following the calling convention of ->lookup. - + Filesystem Issues ----------------- For a filesystem to be exportable it must: - - 1/ provide the filehandle fragment routines described below. - 2/ make sure that d_splice_alias is used rather than d_add + + 1. provide the filehandle fragment routines described below. + 2. make sure that d_splice_alias is used rather than d_add when ->lookup finds an inode for a given parent and name. - If inode is NULL, d_splice_alias(inode, dentry) is equivalent to + If inode is NULL, d_splice_alias(inode, dentry) is equivalent to:: d_add(dentry, inode), NULL Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err) - Typically the ->lookup routine will simply end with a: + Typically the ->lookup routine will simply end with a:: return d_splice_alias(inode, dentry); } - A file system implementation declares that instances of the filesystem +A file system implementation declares that instances of the filesystem are exportable by setting the s_export_op field in the struct super_block. This field must point to a "struct export_operations" struct which has the following members: diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting deleted file mode 100644 index 6b7a41cfcaed..000000000000 --- a/Documentation/filesystems/porting +++ /dev/null @@ -1,686 +0,0 @@ -Changes since 2.5.0: - ---- -[recommended] - -New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(), - sb_set_blocksize() and sb_min_blocksize(). - -Use them. - -(sb_find_get_block() replaces 2.4's get_hash_table()) - ---- -[recommended] - -New methods: ->alloc_inode() and ->destroy_inode(). - -Remove inode->u.foo_inode_i -Declare - struct foo_inode_info { - /* fs-private stuff */ - struct inode vfs_inode; - }; - static inline struct foo_inode_info *FOO_I(struct inode *inode) - { - return list_entry(inode, struct foo_inode_info, vfs_inode); - } - -Use FOO_I(inode) instead of &inode->u.foo_inode_i; - -Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate -foo_inode_info and return the address of ->vfs_inode, the latter should free -FOO_I(inode) (see in-tree filesystems for examples). - -Make them ->alloc_inode and ->destroy_inode in your super_operations. - -Keep in mind that now you need explicit initialization of private data -typically between calling iget_locked() and unlocking the inode. - -At some point that will become mandatory. - ---- -[mandatory] - -Change of file_system_type method (->read_super to ->get_sb) - -->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV. - -Turn your foo_read_super() into a function that would return 0 in case of -success and negative number in case of error (-EINVAL unless you have more -informative error value to report). Call it foo_fill_super(). Now declare - -int foo_get_sb(struct file_system_type *fs_type, - int flags, const char *dev_name, void *data, struct vfsmount *mnt) -{ - return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super, - mnt); -} - -(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of -filesystem). - -Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as -foo_get_sb. - ---- -[mandatory] - -Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames. -Most likely there is no need to change anything, but if you relied on -global exclusion between renames for some internal purpose - you need to -change your internal locking. Otherwise exclusion warranties remain the -same (i.e. parents and victim are locked, etc.). - ---- -[informational] - -Now we have the exclusion between ->lookup() and directory removal (by -->rmdir() and ->rename()). If you used to need that exclusion and do -it by internal locking (most of filesystems couldn't care less) - you -can relax your locking. - ---- -[mandatory] - -->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(), -->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename() -and ->readdir() are called without BKL now. Grab it on entry, drop upon return -- that will guarantee the same locking you used to have. If your method or its -parts do not need BKL - better yet, now you can shift lock_kernel() and -unlock_kernel() so that they would protect exactly what needs to be -protected. - ---- -[mandatory] - -BKL is also moved from around sb operations. BKL should have been shifted into -individual fs sb_op functions. If you don't need it, remove it. - ---- -[informational] - -check for ->link() target not being a directory is done by callers. Feel -free to drop it... - ---- -[informational] - -->link() callers hold ->i_mutex on the object we are linking to. Some of your -problems might be over... - ---- -[mandatory] - -new file_system_type method - kill_sb(superblock). If you are converting -an existing filesystem, set it according to ->fs_flags: - FS_REQUIRES_DEV - kill_block_super - FS_LITTER - kill_litter_super - neither - kill_anon_super -FS_LITTER is gone - just remove it from fs_flags. - ---- -[mandatory] - - FS_SINGLE is gone (actually, that had happened back when ->get_sb() -went in - and hadn't been documented ;-/). Just remove it from fs_flags -(and see ->get_sb() entry for other actions). - ---- -[mandatory] - -->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so -watch for ->i_mutex-grabbing code that might be used by your ->setattr(). -Callers of notify_change() need ->i_mutex now. - ---- -[recommended] - -New super_block field "struct export_operations *s_export_op" for -explicit support for exporting, e.g. via NFS. The structure is fully -documented at its declaration in include/linux/fs.h, and in -Documentation/filesystems/nfs/Exporting. - -Briefly it allows for the definition of decode_fh and encode_fh operations -to encode and decode filehandles, and allows the filesystem to use -a standard helper function for decode_fh, and provide file-system specific -support for this helper, particularly get_parent. - -It is planned that this will be required for exporting once the code -settles down a bit. - -[mandatory] - -s_export_op is now required for exporting a filesystem. -isofs, ext2, ext3, resierfs, fat -can be used as examples of very different filesystems. - ---- -[mandatory] - -iget4() and the read_inode2 callback have been superseded by iget5_locked() -which has the following prototype, - - struct inode *iget5_locked(struct super_block *sb, unsigned long ino, - int (*test)(struct inode *, void *), - int (*set)(struct inode *, void *), - void *data); - -'test' is an additional function that can be used when the inode -number is not sufficient to identify the actual file object. 'set' -should be a non-blocking function that initializes those parts of a -newly created inode to allow the test function to succeed. 'data' is -passed as an opaque value to both test and set functions. - -When the inode has been created by iget5_locked(), it will be returned with the -I_NEW flag set and will still be locked. The filesystem then needs to finalize -the initialization. Once the inode is initialized it must be unlocked by -calling unlock_new_inode(). - -The filesystem is responsible for setting (and possibly testing) i_ino -when appropriate. There is also a simpler iget_locked function that -just takes the superblock and inode number as arguments and does the -test and set for you. - -e.g. - inode = iget_locked(sb, ino); - if (inode->i_state & I_NEW) { - err = read_inode_from_disk(inode); - if (err < 0) { - iget_failed(inode); - return err; - } - unlock_new_inode(inode); - } - -Note that if the process of setting up a new inode fails, then iget_failed() -should be called on the inode to render it dead, and an appropriate error -should be passed back to the caller. - ---- -[recommended] - -->getattr() finally getting used. See instances in nfs, minix, etc. - ---- -[mandatory] - -->revalidate() is gone. If your filesystem had it - provide ->getattr() -and let it call whatever you had as ->revlidate() + (for symlinks that -had ->revalidate()) add calls in ->follow_link()/->readlink(). - ---- -[mandatory] - -->d_parent changes are not protected by BKL anymore. Read access is safe -if at least one of the following is true: - * filesystem has no cross-directory rename() - * we know that parent had been locked (e.g. we are looking at -->d_parent of ->lookup() argument). - * we are called from ->rename(). - * the child's ->d_lock is held -Audit your code and add locking if needed. Notice that any place that is -not protected by the conditions above is risky even in the old tree - you -had been relying on BKL and that's prone to screwups. Old tree had quite -a few holes of that kind - unprotected access to ->d_parent leading to -anything from oops to silent memory corruption. - ---- -[mandatory] - - FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags -(see rootfs for one kind of solution and bdev/socket/pipe for another). - ---- -[recommended] - - Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter -is still alive, but only because of the mess in drivers/s390/block/dasd.c. -As soon as it gets fixed is_read_only() will die. - ---- -[mandatory] - -->permission() is called without BKL now. Grab it on entry, drop upon -return - that will guarantee the same locking you used to have. If -your method or its parts do not need BKL - better yet, now you can -shift lock_kernel() and unlock_kernel() so that they would protect -exactly what needs to be protected. - ---- -[mandatory] - -->statfs() is now called without BKL held. BKL should have been -shifted into individual fs sb_op functions where it's not clear that -it's safe to remove it. If you don't need it, remove it. - ---- -[mandatory] - - is_read_only() is gone; use bdev_read_only() instead. - ---- -[mandatory] - - destroy_buffers() is gone; use invalidate_bdev(). - ---- -[mandatory] - - fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is -deliberate; as soon as struct block_device * is propagated in a reasonable -way by that code fixing will become trivial; until then nothing can be -done. - -[mandatory] - - block truncatation on error exit from ->write_begin, and ->direct_IO -moved from generic methods (block_write_begin, cont_write_begin, -nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at -ext2_write_failed and callers for an example. - -[mandatory] - - ->truncate is gone. The whole truncate sequence needs to be -implemented in ->setattr, which is now mandatory for filesystems -implementing on-disk size changes. Start with a copy of the old inode_setattr -and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to -be in order of zeroing blocks using block_truncate_page or similar helpers, -size update and on finally on-disk truncation which should not fail. -setattr_prepare (which used to be inode_change_ok) now includes the size checks -for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally. - -[mandatory] - - ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should -be used instead. It gets called whenever the inode is evicted, whether it has -remaining links or not. Caller does *not* evict the pagecache or inode-associated -metadata buffers; the method has to use truncate_inode_pages_final() to get rid -of those. Caller makes sure async writeback cannot be running for the inode while -(or after) ->evict_inode() is called. - - ->drop_inode() returns int now; it's called on final iput() with -inode->i_lock held and it returns true if filesystems wants the inode to be -dropped. As before, generic_drop_inode() is still the default and it's been -updated appropriately. generic_delete_inode() is also alive and it consists -simply of return 1. Note that all actual eviction work is done by caller after -->drop_inode() returns. - - As before, clear_inode() must be called exactly once on each call of -->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike -before, if you are using inode-associated metadata buffers (i.e. -mark_buffer_dirty_inode()), it's your responsibility to call -invalidate_inode_buffers() before clear_inode(). - - NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out -if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() -may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly -free the on-disk inode, you may end up doing that while ->write_inode() is writing -to it. - ---- -[mandatory] - - .d_delete() now only advises the dcache as to whether or not to cache -unreferenced dentries, and is now only called when the dentry refcount goes to -0. Even on 0 refcount transition, it must be able to tolerate being called 0, -1, or more times (eg. constant, idempotent). - ---- -[mandatory] - - .d_compare() calling convention and locking rules are significantly -changed. Read updated documentation in Documentation/filesystems/vfs.rst (and -look at examples of other filesystems) for guidance. - ---- -[mandatory] - - .d_hash() calling convention and locking rules are significantly -changed. Read updated documentation in Documentation/filesystems/vfs.rst (and -look at examples of other filesystems) for guidance. - ---- -[mandatory] - dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c -for details of what locks to replace dcache_lock with in order to protect -particular things. Most of the time, a filesystem only needs ->d_lock, which -protects *all* the dcache state of a given dentry. - --- -[mandatory] - - Filesystems must RCU-free their inodes, if they can have been accessed -via rcu-walk path walk (basically, if the file can have had a path name in the -vfs namespace). - - Even though i_dentry and i_rcu share storage in a union, we will -initialize the former in inode_init_always(), so just leave it alone in -the callback. It used to be necessary to clean it there, but not anymore -(starting at 3.2). - --- -[recommended] - vfs now tries to do path walking in "rcu-walk mode", which avoids -atomic operations and scalability hazards on dentries and inodes (see -Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes -(above) are examples of the changes required to support this. For more complex -filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so -no changes are required to the filesystem. However, this is costly and loses -the benefits of rcu-walk mode. We will begin to add filesystem callbacks that -are rcu-walk aware, shown below. Filesystems should take advantage of this -where possible. - --- -[mandatory] - d_revalidate is a callback that is made on every path element (if -the filesystem provides it), which requires dropping out of rcu-walk mode. This -may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be -returned if the filesystem cannot handle rcu-walk. See -Documentation/filesystems/vfs.rst for more details. - - permission is an inode permission check that is called on many or all -directory inodes on the way down a path walk (to check for exec permission). It -must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See -Documentation/filesystems/vfs.rst for more details. - --- -[mandatory] - In ->fallocate() you must check the mode option passed in. If your -filesystem does not support hole punching (deallocating space in the middle of a -file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode. -Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set, -so the i_size should not change when hole punching, even when puching the end of -a file off. - --- -[mandatory] - ->get_sb() is gone. Switch to use of ->mount(). Typically it's just -a matter of switching from calling get_sb_... to mount_... and changing the -function type. If you were doing it manually, just switch from setting ->mnt_root -to some pointer to returning that pointer. On errors return ERR_PTR(...). - --- -[mandatory] - ->permission() and generic_permission()have lost flags -argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask. - generic_permission() has also lost the check_acl argument; ACL checking -has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl -to read an ACL from disk. - --- -[mandatory] - If you implement your own ->llseek() you must handle SEEK_HOLE and -SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to -support it in some way. The generic handler assumes that the entire file is -data and there is a virtual hole at the end of the file. So if the provided -offset is less than i_size and SEEK_DATA is specified, return the same offset. -If the above is true for the offset and you are given SEEK_HOLE, return the end -of the file. If the offset is i_size or greater return -ENXIO in either case. - -[mandatory] - If you have your own ->fsync() you must make sure to call -filemap_write_and_wait_range() so that all dirty pages are synced out properly. -You must also keep in mind that ->fsync() is not called with i_mutex held -anymore, so if you require i_mutex locking you must make sure to take it and -release it yourself. - --- -[mandatory] - d_alloc_root() is gone, along with a lot of bugs caused by code -misusing it. Replacement: d_make_root(inode). On success d_make_root(inode) -allocates and returns a new dentry instantiated with the passed in inode. -On failure NULL is returned and the passed in inode is dropped so the reference -to inode is consumed in all cases and failure handling need not do any cleanup -for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL -and also requires no further error handling. Typical usage is: - - inode = foofs_new_inode(....); - s->s_root = d_make_root(inode); - if (!s->s_root) - /* Nothing needed for the inode cleanup */ - return -ENOMEM; - ... - --- -[mandatory] - The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and -->lookup() do *not* take struct nameidata anymore; just the flags. --- -[mandatory] - ->create() doesn't take struct nameidata *; unlike the previous -two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that -local filesystems can ignore tha argument - they are guaranteed that the -object doesn't exist. It's remote/distributed ones that might care... --- -[mandatory] - FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate() -in your dentry operations instead. --- -[mandatory] - vfs_readdir() is gone; switch to iterate_dir() instead --- -[mandatory] - ->readdir() is gone now; switch to ->iterate() -[mandatory] - vfs_follow_link has been removed. Filesystems must use nd_set_link - from ->follow_link for normal symlinks, or nd_jump_link for magic - /proc/<pid> style links. --- -[mandatory] - iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be - called with both ->i_lock and inode_hash_lock held; the former is *not* - taken anymore, so verify that your callbacks do not rely on it (none - of the in-tree instances did). inode_hash_lock is still held, - of course, so they are still serialized wrt removal from inode hash, - as well as wrt set() callback of iget5_locked(). --- -[mandatory] - d_materialise_unique() is gone; d_splice_alias() does everything you - need now. Remember that they have opposite orders of arguments ;-/ --- -[mandatory] - f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid - it entirely. --- -[mandatory] - never call ->read() and ->write() directly; use __vfs_{read,write} or - wrappers; instead of checking for ->write or ->read being NULL, look for - FMODE_CAN_{WRITE,READ} in file->f_mode. --- -[mandatory] - do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL - instead. --- -[mandatory] - ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter. ---- -[recommended] - for embedded ("fast") symlinks just set inode->i_link to wherever the - symlink body is and use simple_follow_link() as ->follow_link(). --- -[mandatory] - calling conventions for ->follow_link() have changed. Instead of returning - cookie and using nd_set_link() to store the body to traverse, we return - the body to traverse and store the cookie using explicit void ** argument. - nameidata isn't passed at all - nd_jump_link() doesn't need it and - nd_[gs]et_link() is gone. --- -[mandatory] - calling conventions for ->put_link() have changed. It gets inode instead of - dentry, it does not get nameidata at all and it gets called only when cookie - is non-NULL. Note that link body isn't available anymore, so if you need it, - store it as cookie. --- -[mandatory] - any symlink that might use page_follow_link_light/page_put_link() must - have inode_nohighmem(inode) called before anything might start playing with - its pagecache. No highmem pages should end up in the pagecache of such - symlinks. That includes any preseeding that might be done during symlink - creation. __page_symlink() will honour the mapping gfp flags, so once - you've done inode_nohighmem() it's safe to use, but if you allocate and - insert the page manually, make sure to use the right gfp flags. --- -[mandatory] - ->follow_link() is replaced with ->get_link(); same API, except that - * ->get_link() gets inode as a separate argument - * ->get_link() may be called in RCU mode - in that case NULL - dentry is passed --- -[mandatory] - ->get_link() gets struct delayed_call *done now, and should do - set_delayed_call() where it used to set *cookie. - ->put_link() is gone - just give the destructor to set_delayed_call() - in ->get_link(). --- -[mandatory] - ->getxattr() and xattr_handler.get() get dentry and inode passed separately. - dentry might be yet to be attached to inode, so do _not_ use its ->d_inode - in the instances. Rationale: !@#!@# security_d_instantiate() needs to be - called before we attach dentry to inode. --- -[mandatory] - symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/ - i_pipe/i_link union zeroed out at inode eviction. As the result, you can't - assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that - it's a symlink. Checking ->i_mode is really needed now. In-tree we had - to fix shmem_destroy_callback() that used to take that kind of shortcut; - watch out, since that shortcut is no longer valid. --- -[mandatory] - ->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as - they used to - they just take it exclusive. However, ->lookup() may be - called with parent locked shared. Its instances must not - * use d_instantiate) and d_rehash() separately - use d_add() or - d_splice_alias() instead. - * use d_rehash() alone - call d_add(new_dentry, NULL) instead. - * in the unlikely case when (read-only) access to filesystem - data structures needs exclusion for some reason, arrange it - yourself. None of the in-tree filesystems needed that. - * rely on ->d_parent and ->d_name not changing after dentry has - been fed to d_add() or d_splice_alias(). Again, none of the - in-tree instances relied upon that. - We are guaranteed that lookups of the same name in the same directory - will not happen in parallel ("same" in the sense of your ->d_compare()). - Lookups on different names in the same directory can and do happen in - parallel now. --- -[recommended] - ->iterate_shared() is added; it's a parallel variant of ->iterate(). - Exclusion on struct file level is still provided (as well as that - between it and lseek on the same struct file), but if your directory - has been opened several times, you can get these called in parallel. - Exclusion between that method and all directory-modifying ones is - still provided, of course. - - Often enough ->iterate() can serve as ->iterate_shared() without any - changes - it is a read-only operation, after all. If you have any - per-inode or per-dentry in-core data structures modified by ->iterate(), - you might need something to serialize the access to them. If you - do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for - that; look for in-tree examples. - - Old method is only used if the new one is absent; eventually it will - be removed. Switch while you still can; the old one won't stay. --- -[mandatory] - ->atomic_open() calls without O_CREAT may happen in parallel. --- -[mandatory] - ->setxattr() and xattr_handler.set() get dentry and inode passed separately. - dentry might be yet to be attached to inode, so do _not_ use its ->d_inode - in the instances. Rationale: !@#!@# security_d_instantiate() needs to be - called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack - ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well. --- -[mandatory] - ->d_compare() doesn't get parent as a separate argument anymore. If you - used it for finding the struct super_block involved, dentry->d_sb will - work just as well; if it's something more complicated, use dentry->d_parent. - Just be careful not to assume that fetching it more than once will yield - the same value - in RCU mode it could change under you. --- -[mandatory] - ->rename() has an added flags argument. Any flags not handled by the - filesystem should result in EINVAL being returned. --- -[recommended] - ->readlink is optional for symlinks. Don't set, unless filesystem needs - to fake something for readlink(2). --- -[mandatory] - ->getattr() is now passed a struct path rather than a vfsmount and - dentry separately, and it now has request_mask and query_flags arguments - to specify the fields and sync type requested by statx. Filesystems not - supporting any statx-specific features may ignore the new arguments. --- -[mandatory] - ->atomic_open() calling conventions have changed. Gone is int *opened, - along with FILE_OPENED/FILE_CREATED. In place of those we have - FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return - value for 'called finish_no_open(), open it yourself' case has become - 0, not 1. Since finish_no_open() itself is returning 0 now, that part - does not need any changes in ->atomic_open() instances. --- -[mandatory] - alloc_file() has become static now; two wrappers are to be used instead. - alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases - when dentry needs to be created; that's the majority of old alloc_file() - users. Calling conventions: on success a reference to new struct file - is returned and callers reference to inode is subsumed by that. On - failure, ERR_PTR() is returned and no caller's references are affected, - so the caller needs to drop the inode reference it held. - alloc_file_clone(file, flags, ops) does not affect any caller's references. - On success you get a new struct file sharing the mount/dentry with the - original, on failure - ERR_PTR(). --- -[mandatory] - ->clone_file_range() and ->dedupe_file_range have been replaced with - ->remap_file_range(). See Documentation/filesystems/vfs.rst for more - information. --- -[recommended] - ->lookup() instances doing an equivalent of - if (IS_ERR(inode)) - return ERR_CAST(inode); - return d_splice_alias(inode, dentry); - don't need to bother with the check - d_splice_alias() will do the - right thing when given ERR_PTR(...) as inode. Moreover, passing NULL - inode to d_splice_alias() will also do the right thing (equivalent of - d_add(dentry, NULL); return NULL;), so that kind of special cases - also doesn't need a separate treatment. --- -[strongly recommended] - take the RCU-delayed parts of ->destroy_inode() into a new method - - ->free_inode(). If ->destroy_inode() becomes empty - all the better, - just get rid of it. Synchronous work (e.g. the stuff that can't - be done from an RCU callback, or any WARN_ON() where we want the - stack trace) *might* be movable to ->evict_inode(); however, - that goes only for the things that are not needed to balance something - done by ->alloc_inode(). IOW, if it's cleaning up the stuff that - might have accumulated over the life of in-core inode, ->evict_inode() - might be a fit. - - Rules for inode destruction: - * if ->destroy_inode() is non-NULL, it gets called - * if ->free_inode() is non-NULL, it gets scheduled by call_rcu() - * combination of NULL ->destroy_inode and NULL ->free_inode is - treated as NULL/free_inode_nonrcu, to preserve the compatibility. - - Note that the callback (be it via ->free_inode() or explicit call_rcu() - in ->destroy_inode()) is *NOT* ordered wrt superblock destruction; - as the matter of fact, the superblock and all associated structures - might be already gone. The filesystem driver is guaranteed to be still - there, but that's it. Freeing memory in the callback is fine; doing - more than that is possible, but requires a lot of care and is best - avoided. --- -[mandatory] - DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the - default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any - business doing so. --- -[mandatory] - d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are - very suspect (and won't work in modules). Such uses are very likely to - be misspelled d_alloc_anon(). diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst new file mode 100644 index 000000000000..f18506083ced --- /dev/null +++ b/Documentation/filesystems/porting.rst @@ -0,0 +1,852 @@ +==================== +Changes since 2.5.0: +==================== + +--- + +**recommended** + +New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(), +sb_set_blocksize() and sb_min_blocksize(). + +Use them. + +(sb_find_get_block() replaces 2.4's get_hash_table()) + +--- + +**recommended** + +New methods: ->alloc_inode() and ->destroy_inode(). + +Remove inode->u.foo_inode_i + +Declare:: + + struct foo_inode_info { + /* fs-private stuff */ + struct inode vfs_inode; + }; + static inline struct foo_inode_info *FOO_I(struct inode *inode) + { + return list_entry(inode, struct foo_inode_info, vfs_inode); + } + +Use FOO_I(inode) instead of &inode->u.foo_inode_i; + +Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate +foo_inode_info and return the address of ->vfs_inode, the latter should free +FOO_I(inode) (see in-tree filesystems for examples). + +Make them ->alloc_inode and ->destroy_inode in your super_operations. + +Keep in mind that now you need explicit initialization of private data +typically between calling iget_locked() and unlocking the inode. + +At some point that will become mandatory. + +--- + +**mandatory** + +Change of file_system_type method (->read_super to ->get_sb) + +->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV. + +Turn your foo_read_super() into a function that would return 0 in case of +success and negative number in case of error (-EINVAL unless you have more +informative error value to report). Call it foo_fill_super(). Now declare:: + + int foo_get_sb(struct file_system_type *fs_type, + int flags, const char *dev_name, void *data, struct vfsmount *mnt) + { + return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super, + mnt); + } + +(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of +filesystem). + +Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as +foo_get_sb. + +--- + +**mandatory** + +Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames. +Most likely there is no need to change anything, but if you relied on +global exclusion between renames for some internal purpose - you need to +change your internal locking. Otherwise exclusion warranties remain the +same (i.e. parents and victim are locked, etc.). + +--- + +**informational** + +Now we have the exclusion between ->lookup() and directory removal (by +->rmdir() and ->rename()). If you used to need that exclusion and do +it by internal locking (most of filesystems couldn't care less) - you +can relax your locking. + +--- + +**mandatory** + +->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(), +->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename() +and ->readdir() are called without BKL now. Grab it on entry, drop upon return +- that will guarantee the same locking you used to have. If your method or its +parts do not need BKL - better yet, now you can shift lock_kernel() and +unlock_kernel() so that they would protect exactly what needs to be +protected. + +--- + +**mandatory** + +BKL is also moved from around sb operations. BKL should have been shifted into +individual fs sb_op functions. If you don't need it, remove it. + +--- + +**informational** + +check for ->link() target not being a directory is done by callers. Feel +free to drop it... + +--- + +**informational** + +->link() callers hold ->i_mutex on the object we are linking to. Some of your +problems might be over... + +--- + +**mandatory** + +new file_system_type method - kill_sb(superblock). If you are converting +an existing filesystem, set it according to ->fs_flags:: + + FS_REQUIRES_DEV - kill_block_super + FS_LITTER - kill_litter_super + neither - kill_anon_super + +FS_LITTER is gone - just remove it from fs_flags. + +--- + +**mandatory** + +FS_SINGLE is gone (actually, that had happened back when ->get_sb() +went in - and hadn't been documented ;-/). Just remove it from fs_flags +(and see ->get_sb() entry for other actions). + +--- + +**mandatory** + +->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so +watch for ->i_mutex-grabbing code that might be used by your ->setattr(). +Callers of notify_change() need ->i_mutex now. + +--- + +**recommended** + +New super_block field ``struct export_operations *s_export_op`` for +explicit support for exporting, e.g. via NFS. The structure is fully +documented at its declaration in include/linux/fs.h, and in +Documentation/filesystems/nfs/exporting.rst. + +Briefly it allows for the definition of decode_fh and encode_fh operations +to encode and decode filehandles, and allows the filesystem to use +a standard helper function for decode_fh, and provide file-system specific +support for this helper, particularly get_parent. + +It is planned that this will be required for exporting once the code +settles down a bit. + +**mandatory** + +s_export_op is now required for exporting a filesystem. +isofs, ext2, ext3, resierfs, fat +can be used as examples of very different filesystems. + +--- + +**mandatory** + +iget4() and the read_inode2 callback have been superseded by iget5_locked() +which has the following prototype:: + + struct inode *iget5_locked(struct super_block *sb, unsigned long ino, + int (*test)(struct inode *, void *), + int (*set)(struct inode *, void *), + void *data); + +'test' is an additional function that can be used when the inode +number is not sufficient to identify the actual file object. 'set' +should be a non-blocking function that initializes those parts of a +newly created inode to allow the test function to succeed. 'data' is +passed as an opaque value to both test and set functions. + +When the inode has been created by iget5_locked(), it will be returned with the +I_NEW flag set and will still be locked. The filesystem then needs to finalize +the initialization. Once the inode is initialized it must be unlocked by +calling unlock_new_inode(). + +The filesystem is responsible for setting (and possibly testing) i_ino +when appropriate. There is also a simpler iget_locked function that +just takes the superblock and inode number as arguments and does the +test and set for you. + +e.g.:: + + inode = iget_locked(sb, ino); + if (inode->i_state & I_NEW) { + err = read_inode_from_disk(inode); + if (err < 0) { + iget_failed(inode); + return err; + } + unlock_new_inode(inode); + } + +Note that if the process of setting up a new inode fails, then iget_failed() +should be called on the inode to render it dead, and an appropriate error +should be passed back to the caller. + +--- + +**recommended** + +->getattr() finally getting used. See instances in nfs, minix, etc. + +--- + +**mandatory** + +->revalidate() is gone. If your filesystem had it - provide ->getattr() +and let it call whatever you had as ->revlidate() + (for symlinks that +had ->revalidate()) add calls in ->follow_link()/->readlink(). + +--- + +**mandatory** + +->d_parent changes are not protected by BKL anymore. Read access is safe +if at least one of the following is true: + + * filesystem has no cross-directory rename() + * we know that parent had been locked (e.g. we are looking at + ->d_parent of ->lookup() argument). + * we are called from ->rename(). + * the child's ->d_lock is held + +Audit your code and add locking if needed. Notice that any place that is +not protected by the conditions above is risky even in the old tree - you +had been relying on BKL and that's prone to screwups. Old tree had quite +a few holes of that kind - unprotected access to ->d_parent leading to +anything from oops to silent memory corruption. + +--- + +**mandatory** + +FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags +(see rootfs for one kind of solution and bdev/socket/pipe for another). + +--- + +**recommended** + +Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter +is still alive, but only because of the mess in drivers/s390/block/dasd.c. +As soon as it gets fixed is_read_only() will die. + +--- + +**mandatory** + +->permission() is called without BKL now. Grab it on entry, drop upon +return - that will guarantee the same locking you used to have. If +your method or its parts do not need BKL - better yet, now you can +shift lock_kernel() and unlock_kernel() so that they would protect +exactly what needs to be protected. + +--- + +**mandatory** + +->statfs() is now called without BKL held. BKL should have been +shifted into individual fs sb_op functions where it's not clear that +it's safe to remove it. If you don't need it, remove it. + +--- + +**mandatory** + +is_read_only() is gone; use bdev_read_only() instead. + +--- + +**mandatory** + +destroy_buffers() is gone; use invalidate_bdev(). + +--- + +**mandatory** + +fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is +deliberate; as soon as struct block_device * is propagated in a reasonable +way by that code fixing will become trivial; until then nothing can be +done. + +**mandatory** + +block truncatation on error exit from ->write_begin, and ->direct_IO +moved from generic methods (block_write_begin, cont_write_begin, +nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at +ext2_write_failed and callers for an example. + +**mandatory** + +->truncate is gone. The whole truncate sequence needs to be +implemented in ->setattr, which is now mandatory for filesystems +implementing on-disk size changes. Start with a copy of the old inode_setattr +and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to +be in order of zeroing blocks using block_truncate_page or similar helpers, +size update and on finally on-disk truncation which should not fail. +setattr_prepare (which used to be inode_change_ok) now includes the size checks +for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally. + +**mandatory** + +->clear_inode() and ->delete_inode() are gone; ->evict_inode() should +be used instead. It gets called whenever the inode is evicted, whether it has +remaining links or not. Caller does *not* evict the pagecache or inode-associated +metadata buffers; the method has to use truncate_inode_pages_final() to get rid +of those. Caller makes sure async writeback cannot be running for the inode while +(or after) ->evict_inode() is called. + +->drop_inode() returns int now; it's called on final iput() with +inode->i_lock held and it returns true if filesystems wants the inode to be +dropped. As before, generic_drop_inode() is still the default and it's been +updated appropriately. generic_delete_inode() is also alive and it consists +simply of return 1. Note that all actual eviction work is done by caller after +->drop_inode() returns. + +As before, clear_inode() must be called exactly once on each call of +->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike +before, if you are using inode-associated metadata buffers (i.e. +mark_buffer_dirty_inode()), it's your responsibility to call +invalidate_inode_buffers() before clear_inode(). + +NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out +if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() +may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly +free the on-disk inode, you may end up doing that while ->write_inode() is writing +to it. + +--- + +**mandatory** + +.d_delete() now only advises the dcache as to whether or not to cache +unreferenced dentries, and is now only called when the dentry refcount goes to +0. Even on 0 refcount transition, it must be able to tolerate being called 0, +1, or more times (eg. constant, idempotent). + +--- + +**mandatory** + +.d_compare() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.rst (and +look at examples of other filesystems) for guidance. + +--- + +**mandatory** + +.d_hash() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.rst (and +look at examples of other filesystems) for guidance. + +--- + +**mandatory** + +dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c +for details of what locks to replace dcache_lock with in order to protect +particular things. Most of the time, a filesystem only needs ->d_lock, which +protects *all* the dcache state of a given dentry. + +--- + +**mandatory** + +Filesystems must RCU-free their inodes, if they can have been accessed +via rcu-walk path walk (basically, if the file can have had a path name in the +vfs namespace). + +Even though i_dentry and i_rcu share storage in a union, we will +initialize the former in inode_init_always(), so just leave it alone in +the callback. It used to be necessary to clean it there, but not anymore +(starting at 3.2). + +--- + +**recommended** + +vfs now tries to do path walking in "rcu-walk mode", which avoids +atomic operations and scalability hazards on dentries and inodes (see +Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes +(above) are examples of the changes required to support this. For more complex +filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so +no changes are required to the filesystem. However, this is costly and loses +the benefits of rcu-walk mode. We will begin to add filesystem callbacks that +are rcu-walk aware, shown below. Filesystems should take advantage of this +where possible. + +--- + +**mandatory** + +d_revalidate is a callback that is made on every path element (if +the filesystem provides it), which requires dropping out of rcu-walk mode. This +may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be +returned if the filesystem cannot handle rcu-walk. See +Documentation/filesystems/vfs.rst for more details. + +permission is an inode permission check that is called on many or all +directory inodes on the way down a path walk (to check for exec permission). It +must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See +Documentation/filesystems/vfs.rst for more details. + +--- + +**mandatory** + +In ->fallocate() you must check the mode option passed in. If your +filesystem does not support hole punching (deallocating space in the middle of a +file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode. +Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set, +so the i_size should not change when hole punching, even when puching the end of +a file off. + +--- + +**mandatory** + +->get_sb() is gone. Switch to use of ->mount(). Typically it's just +a matter of switching from calling ``get_sb_``... to ``mount_``... and changing +the function type. If you were doing it manually, just switch from setting +->mnt_root to some pointer to returning that pointer. On errors return +ERR_PTR(...). + +--- + +**mandatory** + +->permission() and generic_permission()have lost flags +argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask. + +generic_permission() has also lost the check_acl argument; ACL checking +has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl +to read an ACL from disk. + +--- + +**mandatory** + +If you implement your own ->llseek() you must handle SEEK_HOLE and +SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to +support it in some way. The generic handler assumes that the entire file is +data and there is a virtual hole at the end of the file. So if the provided +offset is less than i_size and SEEK_DATA is specified, return the same offset. +If the above is true for the offset and you are given SEEK_HOLE, return the end +of the file. If the offset is i_size or greater return -ENXIO in either case. + +**mandatory** + +If you have your own ->fsync() you must make sure to call +filemap_write_and_wait_range() so that all dirty pages are synced out properly. +You must also keep in mind that ->fsync() is not called with i_mutex held +anymore, so if you require i_mutex locking you must make sure to take it and +release it yourself. + +--- + +**mandatory** + +d_alloc_root() is gone, along with a lot of bugs caused by code +misusing it. Replacement: d_make_root(inode). On success d_make_root(inode) +allocates and returns a new dentry instantiated with the passed in inode. +On failure NULL is returned and the passed in inode is dropped so the reference +to inode is consumed in all cases and failure handling need not do any cleanup +for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL +and also requires no further error handling. Typical usage is:: + + inode = foofs_new_inode(....); + s->s_root = d_make_root(inode); + if (!s->s_root) + /* Nothing needed for the inode cleanup */ + return -ENOMEM; + ... + +--- + +**mandatory** + +The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and +->lookup() do *not* take struct nameidata anymore; just the flags. + +--- + +**mandatory** + +->create() doesn't take ``struct nameidata *``; unlike the previous +two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that +local filesystems can ignore tha argument - they are guaranteed that the +object doesn't exist. It's remote/distributed ones that might care... + +--- + +**mandatory** + +FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate() +in your dentry operations instead. + +--- + +**mandatory** + +vfs_readdir() is gone; switch to iterate_dir() instead + +--- + +**mandatory** + +->readdir() is gone now; switch to ->iterate() + +**mandatory** + +vfs_follow_link has been removed. Filesystems must use nd_set_link +from ->follow_link for normal symlinks, or nd_jump_link for magic +/proc/<pid> style links. + +--- + +**mandatory** + +iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be +called with both ->i_lock and inode_hash_lock held; the former is *not* +taken anymore, so verify that your callbacks do not rely on it (none +of the in-tree instances did). inode_hash_lock is still held, +of course, so they are still serialized wrt removal from inode hash, +as well as wrt set() callback of iget5_locked(). + +--- + +**mandatory** + +d_materialise_unique() is gone; d_splice_alias() does everything you +need now. Remember that they have opposite orders of arguments ;-/ + +--- + +**mandatory** + +f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid +it entirely. + +--- + +**mandatory** + +never call ->read() and ->write() directly; use __vfs_{read,write} or +wrappers; instead of checking for ->write or ->read being NULL, look for +FMODE_CAN_{WRITE,READ} in file->f_mode. + +--- + +**mandatory** + +do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL +instead. + +--- + +**mandatory** + ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter. + +--- + +**recommended** + +for embedded ("fast") symlinks just set inode->i_link to wherever the +symlink body is and use simple_follow_link() as ->follow_link(). + +--- + +**mandatory** + +calling conventions for ->follow_link() have changed. Instead of returning +cookie and using nd_set_link() to store the body to traverse, we return +the body to traverse and store the cookie using explicit void ** argument. +nameidata isn't passed at all - nd_jump_link() doesn't need it and +nd_[gs]et_link() is gone. + +--- + +**mandatory** + +calling conventions for ->put_link() have changed. It gets inode instead of +dentry, it does not get nameidata at all and it gets called only when cookie +is non-NULL. Note that link body isn't available anymore, so if you need it, +store it as cookie. + +--- + +**mandatory** + +any symlink that might use page_follow_link_light/page_put_link() must +have inode_nohighmem(inode) called before anything might start playing with +its pagecache. No highmem pages should end up in the pagecache of such +symlinks. That includes any preseeding that might be done during symlink +creation. __page_symlink() will honour the mapping gfp flags, so once +you've done inode_nohighmem() it's safe to use, but if you allocate and +insert the page manually, make sure to use the right gfp flags. + +--- + +**mandatory** + +->follow_link() is replaced with ->get_link(); same API, except that + + * ->get_link() gets inode as a separate argument + * ->get_link() may be called in RCU mode - in that case NULL + dentry is passed + +--- + +**mandatory** + +->get_link() gets struct delayed_call ``*done`` now, and should do +set_delayed_call() where it used to set ``*cookie``. + +->put_link() is gone - just give the destructor to set_delayed_call() +in ->get_link(). + +--- + +**mandatory** + +->getxattr() and xattr_handler.get() get dentry and inode passed separately. +dentry might be yet to be attached to inode, so do _not_ use its ->d_inode +in the instances. Rationale: !@#!@# security_d_instantiate() needs to be +called before we attach dentry to inode. + +--- + +**mandatory** + +symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/ +i_pipe/i_link union zeroed out at inode eviction. As the result, you can't +assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that +it's a symlink. Checking ->i_mode is really needed now. In-tree we had +to fix shmem_destroy_callback() that used to take that kind of shortcut; +watch out, since that shortcut is no longer valid. + +--- + +**mandatory** + +->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as +they used to - they just take it exclusive. However, ->lookup() may be +called with parent locked shared. Its instances must not + + * use d_instantiate) and d_rehash() separately - use d_add() or + d_splice_alias() instead. + * use d_rehash() alone - call d_add(new_dentry, NULL) instead. + * in the unlikely case when (read-only) access to filesystem + data structures needs exclusion for some reason, arrange it + yourself. None of the in-tree filesystems needed that. + * rely on ->d_parent and ->d_name not changing after dentry has + been fed to d_add() or d_splice_alias(). Again, none of the + in-tree instances relied upon that. + +We are guaranteed that lookups of the same name in the same directory +will not happen in parallel ("same" in the sense of your ->d_compare()). +Lookups on different names in the same directory can and do happen in +parallel now. + +--- + +**recommended** + +->iterate_shared() is added; it's a parallel variant of ->iterate(). +Exclusion on struct file level is still provided (as well as that +between it and lseek on the same struct file), but if your directory +has been opened several times, you can get these called in parallel. +Exclusion between that method and all directory-modifying ones is +still provided, of course. + +Often enough ->iterate() can serve as ->iterate_shared() without any +changes - it is a read-only operation, after all. If you have any +per-inode or per-dentry in-core data structures modified by ->iterate(), +you might need something to serialize the access to them. If you +do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for +that; look for in-tree examples. + +Old method is only used if the new one is absent; eventually it will +be removed. Switch while you still can; the old one won't stay. + +--- + +**mandatory** + +->atomic_open() calls without O_CREAT may happen in parallel. + +--- + +**mandatory** + +->setxattr() and xattr_handler.set() get dentry and inode passed separately. +dentry might be yet to be attached to inode, so do _not_ use its ->d_inode +in the instances. Rationale: !@#!@# security_d_instantiate() needs to be +called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack +->d_instantiate() uses not just ->getxattr() but ->setxattr() as well. + +--- + +**mandatory** + +->d_compare() doesn't get parent as a separate argument anymore. If you +used it for finding the struct super_block involved, dentry->d_sb will +work just as well; if it's something more complicated, use dentry->d_parent. +Just be careful not to assume that fetching it more than once will yield +the same value - in RCU mode it could change under you. + +--- + +**mandatory** + +->rename() has an added flags argument. Any flags not handled by the +filesystem should result in EINVAL being returned. + +--- + + +**recommended** + +->readlink is optional for symlinks. Don't set, unless filesystem needs +to fake something for readlink(2). + +--- + +**mandatory** + +->getattr() is now passed a struct path rather than a vfsmount and +dentry separately, and it now has request_mask and query_flags arguments +to specify the fields and sync type requested by statx. Filesystems not +supporting any statx-specific features may ignore the new arguments. + +--- + +**mandatory** + +->atomic_open() calling conventions have changed. Gone is ``int *opened``, +along with FILE_OPENED/FILE_CREATED. In place of those we have +FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return +value for 'called finish_no_open(), open it yourself' case has become +0, not 1. Since finish_no_open() itself is returning 0 now, that part +does not need any changes in ->atomic_open() instances. + +--- + +**mandatory** + +alloc_file() has become static now; two wrappers are to be used instead. +alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases +when dentry needs to be created; that's the majority of old alloc_file() +users. Calling conventions: on success a reference to new struct file +is returned and callers reference to inode is subsumed by that. On +failure, ERR_PTR() is returned and no caller's references are affected, +so the caller needs to drop the inode reference it held. +alloc_file_clone(file, flags, ops) does not affect any caller's references. +On success you get a new struct file sharing the mount/dentry with the +original, on failure - ERR_PTR(). + +--- + +**mandatory** + +->clone_file_range() and ->dedupe_file_range have been replaced with +->remap_file_range(). See Documentation/filesystems/vfs.rst for more +information. + +--- + +**recommended** + +->lookup() instances doing an equivalent of:: + + if (IS_ERR(inode)) + return ERR_CAST(inode); + return d_splice_alias(inode, dentry); + +don't need to bother with the check - d_splice_alias() will do the +right thing when given ERR_PTR(...) as inode. Moreover, passing NULL +inode to d_splice_alias() will also do the right thing (equivalent of +d_add(dentry, NULL); return NULL;), so that kind of special cases +also doesn't need a separate treatment. + +--- + +**strongly recommended** + +take the RCU-delayed parts of ->destroy_inode() into a new method - +->free_inode(). If ->destroy_inode() becomes empty - all the better, +just get rid of it. Synchronous work (e.g. the stuff that can't +be done from an RCU callback, or any WARN_ON() where we want the +stack trace) *might* be movable to ->evict_inode(); however, +that goes only for the things that are not needed to balance something +done by ->alloc_inode(). IOW, if it's cleaning up the stuff that +might have accumulated over the life of in-core inode, ->evict_inode() +might be a fit. + +Rules for inode destruction: + + * if ->destroy_inode() is non-NULL, it gets called + * if ->free_inode() is non-NULL, it gets scheduled by call_rcu() + * combination of NULL ->destroy_inode and NULL ->free_inode is + treated as NULL/free_inode_nonrcu, to preserve the compatibility. + +Note that the callback (be it via ->free_inode() or explicit call_rcu() +in ->destroy_inode()) is *NOT* ordered wrt superblock destruction; +as the matter of fact, the superblock and all associated structures +might be already gone. The filesystem driver is guaranteed to be still +there, but that's it. Freeing memory in the callback is fine; doing +more than that is possible, but requires a lot of care and is best +avoided. + +--- + +**mandatory** + +DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the +default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any +business doing so. + +--- + +**mandatory** + +d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are +very suspect (and won't work in modules). Such uses are very likely to +be misspelled d_alloc_anon(). diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst index 23e698167141..6a9584f6ff46 100644 --- a/Documentation/filesystems/ubifs-authentication.md +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -1,8 +1,11 @@ -% UBIFS Authentication -% sigma star gmbh -% 2018 +:orphan: -# Introduction +.. UBIFS Authentication +.. sigma star gmbh +.. 2018 + +Introduction +============ UBIFS utilizes the fscrypt framework to provide confidentiality for file contents and file names. This prevents attacks where an attacker is able to @@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also be possible to use UBIFS authentication without using encryption. -## MTD, UBI & UBIFS +MTD, UBI & UBIFS +---------------- On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform interface to access raw flash devices. One of the more prominent subsystems that @@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear leveling and some flash specifics are left to UBI, while UBIFS focuses on scalability, performance and recoverability. - +:: +------------+ +*******+ +-----------+ +-----+ | | * UBIFS * | UBI-BLOCK | | ... | @@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in [UBIFS-WP]. -### UBIFS Index & Tree Node Cache +UBIFS Index & Tree Node Cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file @@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes marked as dirty are written to the flash to update the persisted index. -### Journal +Journal +~~~~~~~ To avoid wearing out the flash, the index is only persisted (*commited*) when -certain conditions are met (eg. `fsync(2)`). The journal is used to record +certain conditions are met (eg. ``fsync(2)``). The journal is used to record any changes (in form of inode nodes, data nodes etc.) between commits of the index. During mount, the journal is read from the flash and replayed onto the TNC (which will be created on-demand from the on-flash index). UBIFS reserves a bunch of LEBs just for the journal called *log area*. The amount of log area LEBs is configured on filesystem creation (using -`mkfs.ubifs`) and stored in the superblock node. The log area contains only +``mkfs.ubifs``) and stored in the superblock node. The log area contains only two types of nodes: *reference nodes* and *commit start nodes*. A commit start node is written whenever an index commit is performed. Reference nodes are written on every journal update. Each reference node points to the position of @@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt because of a power cut. If the recovery fails, UBIFS will not mount. An error for every other LEB will directly cause UBIFS to fail the mount operation. +:: | ---- LOG AREA ---- | ---------- MAIN AREA ------------ | @@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation. containing their buds -### LEB Property Tree/Table +LEB Property Tree/Table +~~~~~~~~~~~~~~~~~~~~~~~ The LEB property tree is used to store per-LEB information. This includes the -LEB type and amount of free and *dirty* (old, obsolete content) space [1] on +LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on the LEB. The type is important, because UBIFS never mixes index nodes with data nodes on a single LEB and thus each LEB has a specific purpose. This again is useful for free space calculations. See [UBIFS-WP] for more details. @@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every commit. Thus, saving the LPT is an atomic operation. -[1] Since LEBs can only be appended and never overwritten, there is a -difference between free space ie. the remaining space left on the LEB to be -written to without erasing it and previously written content that is obsolete -but can't be overwritten without erasing the full LEB. +.. [1] Since LEBs can only be appended and never overwritten, there is a + difference between free space ie. the remaining space left on the LEB to be + written to without erasing it and previously written content that is obsolete + but can't be overwritten without erasing the full LEB. -# UBIFS Authentication +UBIFS Authentication +==================== This chapter introduces UBIFS authentication which enables UBIFS to verify the authenticity and integrity of metadata and file contents stored on flash. -## Threat Model +Threat Model +------------ UBIFS authentication enables detection of offline data modification. While it does not prevent it, it enables (trusted) code to check the integrity and @@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to ensure that only trusted code is executed on a device. -## Authentication +Authentication +-------------- To be able to fully trust data read from flash, all UBIFS data structures stored on flash are authenticated. That is: @@ -236,7 +247,8 @@ stored on flash are authenticated. That is: - The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting -### Index Authentication +Index Authentication +~~~~~~~~~~~~~~~~~~~~ Through UBIFS' concept of a wandering tree, it already takes care of only updating and persisting changed parts from leaf node up to the root node @@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces the storage overhead which is precious for users of UBIFS (ie. embedded devices). +:: +---------------+ | Master Node | @@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted atomically together with its respective node. -### Journal Authentication +Journal Authentication +~~~~~~~~~~~~~~~~~~~~~~ The journal is authenticated too. Since the journal is continuously written it is necessary to also add authentication information frequently to the @@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last authentication node. The tail of the journal which may not have a authentication node cannot be authenticated and is skipped during journal replay. -We get this picture for journal authentication: +We get this picture for journal authentication:: ,,,,,,,, ,......,........................................... @@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only modified on feature flag or similar changes, but never on file changes. -### LPT Authentication +LPT Authentication +~~~~~~~~~~~~~~~~~~ The location of the LPT root node on the flash is stored in the UBIFS master node. Since the LPT is written and read atomically on every commit, there is @@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the LTP hash stored there with the hash computed from the read on-flash LPT. -## Key Management +Key Management +-------------- For simplicity, UBIFS authentication uses a single key to compute the HMACs of superblock, master, commit start and reference nodes. This key has to be @@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2 [FSCRYPT-POLICY2]. -# Future Extensions +Future Extensions +================= In certain cases where a vendor wants to provide an authenticated filesystem image to customers, it should be possible to do so without sharing the secret @@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key will then have to be provided beforehand in the normal way. -# References +References +========== [CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 0f85ab21c2ca..7d4d09dd5e6d 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist. VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on are called from a process context. Filesystem locking is described in -the document Documentation/filesystems/Locking. +the document Documentation/filesystems/locking.rst. Directory Entry Cache (dcache) diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/firmware-guide/acpi/dsd/leds.rst index cc58b1a574c5..946efe2b2936 100644 --- a/Documentation/acpi/dsd/leds.txt +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -1,4 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +======================================== Describing and referring to LEDs in ACPI +======================================== Individual LEDs are described by hierarchical data extension [6] nodes under the device node, the LED driver chip. The "reg" property in the LED specific nodes @@ -25,8 +30,12 @@ entry shall contain the string "led@" followed by the number of the LED, followed by the referred object name. That object shall be named "LED" followed by the number of the LED. -An ASL example of a camera sensor device and a LED driver device for two LEDs. -Objects not relevant for LEDs or the references to them have been omitted. +Example +======= + +An ASL example of a camera sensor device and a LED driver device for two LEDs is +show below. Objects not relevant for LEDs or the references to them have been +omitted. :: Device (LED) { @@ -71,12 +80,15 @@ Objects not relevant for LEDs or the references to them have been omitted. } where +:: LED LED driver device LED0 First LED LED1 Second LED - SEN Camera sensor device (or another device the LED is - related to) + SEN Camera sensor device (or another device the LED is related to) + +References +========== [1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 90c90d42d9ad..ad3b5afdae77 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,6 +10,7 @@ ACPI Support namespace dsd/graph dsd/data-node-references + dsd/leds enumeration osi method-customizing diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 2f125abd777f..6fa483fc823e 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -87,6 +87,8 @@ The following functions are exposed through ioctls: - Get driver API version (DFL_FPGA_GET_API_VERSION) - Check for extensions (DFL_FPGA_CHECK_EXTENSION) - Program bitstream (DFL_FPGA_FME_PORT_PR) +- Assign port to PF (DFL_FPGA_FME_PORT_ASSIGN) +- Release port from PF (DFL_FPGA_FME_PORT_RELEASE) More functions are exposed through sysfs (/sys/class/fpga_region/regionX/dfl-fme.n/): @@ -102,6 +104,10 @@ More functions are exposed through sysfs one FPGA device may have more than one port, this sysfs interface indicates how many ports the FPGA device has. + Global error reporting management (errors/) + error reporting sysfs interfaces allow user to read errors detected by the + hardware, and clear the logged errors. + FIU - PORT ========== @@ -143,6 +149,10 @@ More functions are exposed through sysfs: Read Accelerator GUID (afu_id) afu_id indicates which PR bitstream is programmed to this AFU. + Error reporting (errors/) + error reporting sysfs interfaces allow user to read port/afu errors + detected by the hardware, and clear the logged errors. + DFL Framework Overview ====================== @@ -218,6 +228,101 @@ the compat_id exposed by the target FPGA region. This check is usually done by userspace before calling the reconfiguration IOCTL. +FPGA virtualization - PCIe SRIOV +================================ +This section describes the virtualization support on DFL based FPGA device to +enable accessing an accelerator from applications running in a virtual machine +(VM). This section only describes the PCIe based FPGA device with SRIOV support. + +Features supported by the particular FPGA device are exposed through Device +Feature Lists, as illustrated below: + +:: + + +-------------------------------+ +-------------+ + | PF | | VF | + +-------------------------------+ +-------------+ + ^ ^ ^ ^ + | | | | + +-----|------------|---------|--------------|-------+ + | | | | | | + | +-----+ +-------+ +-------+ +-------+ | + | | FME | | Port0 | | Port1 | | Port2 | | + | +-----+ +-------+ +-------+ +-------+ | + | ^ ^ ^ | + | | | | | + | +-------+ +------+ +-------+ | + | | AFU | | AFU | | AFU | | + | +-------+ +------+ +-------+ | + | | + | DFL based FPGA PCIe Device | + +---------------------------------------------------+ + +FME is always accessed through the physical function (PF). + +Ports (and related AFUs) are accessed via PF by default, but could be exposed +through virtual function (VF) devices via PCIe SRIOV. Each VF only contains +1 Port and 1 AFU for isolation. Users could assign individual VFs (accelerators) +created via PCIe SRIOV interface, to virtual machines. + +The driver organization in virtualization case is illustrated below: +:: + + +-------++------++------+ | + | FME || FME || FME | | + | FPGA || FPGA || FPGA | | + |Manager||Bridge||Region| | + +-------++------++------+ | + +-----------------------+ +--------+ | +--------+ + | FME | | AFU | | | AFU | + | Module | | Module | | | Module | + +-----------------------+ +--------+ | +--------+ + +-----------------------+ | +-----------------------+ + | FPGA Container Device | | | FPGA Container Device | + | (FPGA Base Region) | | | (FPGA Base Region) | + +-----------------------+ | +-----------------------+ + +------------------+ | +------------------+ + | FPGA PCIE Module | | Virtual | FPGA PCIE Module | + +------------------+ Host | Machine +------------------+ + -------------------------------------- | ------------------------------ + +---------------+ | +---------------+ + | PCI PF Device | | | PCI VF Device | + +---------------+ | +---------------+ + +FPGA PCIe device driver is always loaded first once a FPGA PCIe PF or VF device +is detected. It: + +* Finishes enumeration on both FPGA PCIe PF and VF device using common + interfaces from DFL framework. +* Supports SRIOV. + +The FME device driver plays a management role in this driver architecture, it +provides ioctls to release Port from PF and assign Port to PF. After release +a port from PF, then it's safe to expose this port through a VF via PCIe SRIOV +sysfs interface. + +To enable accessing an accelerator from applications running in a VM, the +respective AFU's port needs to be assigned to a VF using the following steps: + +#. The PF owns all AFU ports by default. Any port that needs to be + reassigned to a VF must first be released through the + DFL_FPGA_FME_PORT_RELEASE ioctl on the FME device. + +#. Once N ports are released from PF, then user can use command below + to enable SRIOV and VFs. Each VF owns only one Port with AFU. + + :: + + echo N > $PCI_DEVICE_PATH/sriov_numvfs + +#. Pass through the VFs to VMs + +#. The AFU under VF is accessible from applications in VM (using the + same driver inside the VF). + +Note that an FME can't be assigned to a VF, thus PR and other management +functions are only available via the PF. + Device enumeration ================== This section introduces how applications enumerate the fpga device from diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst index 6cbb0f75fe00..116fb2019956 100644 --- a/Documentation/hwmon/adm1021.rst +++ b/Documentation/hwmon/adm1021.rst @@ -142,7 +142,7 @@ loading the adm1021 module, then things are good. If nothing happens when loading the adm1021 module, and you are certain that your specific Xeon processor model includes compatible sensors, you will have to explicitly instantiate the sensor chips from user-space. See -method 4 in Documentation/i2c/instantiating-devices. Possible slave +method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that only temp2 will be correct and temp1 will have to be ignored. diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst index 9a1913e5b4d9..49966ed70ec6 100644 --- a/Documentation/hwmon/adm1275.rst +++ b/Documentation/hwmon/adm1275.rst @@ -75,7 +75,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. The ADM1075, unlike many other PMBus devices, does not support internal voltage diff --git a/Documentation/hwmon/ads1015.rst b/Documentation/hwmon/ads1015.rst deleted file mode 100644 index e0951c4e57bb..000000000000 --- a/Documentation/hwmon/ads1015.rst +++ /dev/null @@ -1,90 +0,0 @@ -Kernel driver ads1015 -===================== - -Supported chips: - - * Texas Instruments ADS1015 - - Prefix: 'ads1015' - - Datasheet: Publicly available at the Texas Instruments website: - - http://focus.ti.com/lit/ds/symlink/ads1015.pdf - - * Texas Instruments ADS1115 - - Prefix: 'ads1115' - - Datasheet: Publicly available at the Texas Instruments website: - - http://focus.ti.com/lit/ds/symlink/ads1115.pdf - -Authors: - Dirk Eibach, Guntermann & Drunck GmbH <eibach@gdsys.de> - -Description ------------ - -This driver implements support for the Texas Instruments ADS1015/ADS1115. - -This device is a 12/16-bit A-D converter with 4 inputs. - -The inputs can be used single ended or in certain differential combinations. - -The inputs can be made available by 8 sysfs input files in0_input - in7_input: - - - in0: Voltage over AIN0 and AIN1. - - in1: Voltage over AIN0 and AIN3. - - in2: Voltage over AIN1 and AIN3. - - in3: Voltage over AIN2 and AIN3. - - in4: Voltage over AIN0 and GND. - - in5: Voltage over AIN1 and GND. - - in6: Voltage over AIN2 and GND. - - in7: Voltage over AIN3 and GND. - -Which inputs are available can be configured using platform data or devicetree. - -By default all inputs are exported. - -Platform Data -------------- - -In linux/platform_data/ads1015.h platform data is defined, channel_data contains -configuration data for the used input combinations: - -- pga is the programmable gain amplifier (values are full scale) - - - 0: +/- 6.144 V - - 1: +/- 4.096 V - - 2: +/- 2.048 V - - 3: +/- 1.024 V - - 4: +/- 0.512 V - - 5: +/- 0.256 V - -- data_rate in samples per second - - - 0: 128 - - 1: 250 - - 2: 490 - - 3: 920 - - 4: 1600 - - 5: 2400 - - 6: 3300 - -Example:: - - struct ads1015_platform_data data = { - .channel_data = { - [2] = { .enabled = true, .pga = 1, .data_rate = 0 }, - [4] = { .enabled = true, .pga = 4, .data_rate = 5 }, - } - }; - -In this case only in2_input (FS +/- 4.096 V, 128 SPS) and in4_input -(FS +/- 0.512 V, 2400 SPS) would be created. - -Devicetree ----------- - -Configuration is also possible via devicetree: -Documentation/devicetree/bindings/hwmon/ads1015.txt diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst index 649bd4be4fc2..e95d373eb693 100644 --- a/Documentation/hwmon/hih6130.rst +++ b/Documentation/hwmon/hih6130.rst @@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27) can be used in the board setup code. -Please see Documentation/i2c/instantiating-devices for details on how to +Please see Documentation/i2c/instantiating-devices.rst for details on how to instantiate I2C devices. sysfs-Interface diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst index 52e74e39463a..ef8f3f806968 100644 --- a/Documentation/hwmon/ibm-cffps.rst +++ b/Documentation/hwmon/ibm-cffps.rst @@ -17,7 +17,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index ee090e51653a..8147c3f218bf 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -30,7 +30,6 @@ Hardware Monitoring Kernel Drivers adm1031 adm1275 adm9240 - ads1015 ads7828 adt7410 adt7411 @@ -130,6 +129,7 @@ Hardware Monitoring Kernel Drivers pcf8591 pmbus powr1220 + pxe1610 pwm-fan raspberrypi-hwmon sch5627 diff --git a/Documentation/hwmon/inspur-ipsps1.rst b/Documentation/hwmon/inspur-ipsps1.rst new file mode 100644 index 000000000000..2b871ae3448f --- /dev/null +++ b/Documentation/hwmon/inspur-ipsps1.rst @@ -0,0 +1,79 @@ +Kernel driver inspur-ipsps1 +======================= + +Supported chips: + + * Inspur Power System power supply unit + +Author: John Wang <wangzqbj@inspur.com> + +Description +----------- + +This driver supports Inspur Power System power supplies. This driver +is a client to the core PMBus driver. + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices for +details. + +Sysfs entries +------------- + +The following attributes are supported: + +======================= ====================================================== +curr1_input Measured input current +curr1_label "iin" +curr1_max Maximum current +curr1_max_alarm Current high alarm +curr2_input Measured output current in mA. +curr2_label "iout1" +curr2_crit Critical maximum current +curr2_crit_alarm Current critical high alarm +curr2_max Maximum current +curr2_max_alarm Current high alarm + +fan1_alarm Fan 1 warning. +fan1_fault Fan 1 fault. +fan1_input Fan 1 speed in RPM. + +in1_alarm Input voltage under-voltage alarm. +in1_input Measured input voltage in mV. +in1_label "vin" +in2_input Measured output voltage in mV. +in2_label "vout1" +in2_lcrit Critical minimum output voltage +in2_lcrit_alarm Output voltage critical low alarm +in2_max Maximum output voltage +in2_max_alarm Output voltage high alarm +in2_min Minimum output voltage +in2_min_alarm Output voltage low alarm + +power1_alarm Input fault or alarm. +power1_input Measured input power in uW. +power1_label "pin" +power1_max Input power limit +power2_max_alarm Output power high alarm +power2_max Output power limit +power2_input Measured output power in uW. +power2_label "pout" + +temp[1-3]_input Measured temperature +temp[1-2]_max Maximum temperature +temp[1-3]_max_alarm Temperature high alarm + +vendor Manufacturer name +model Product model +part_number Product part number +serial_number Product serial number +fw_version Firmware version +hw_version Hardware version +mode Work mode. Can be set to active or + standby, when set to standby, PSU will + automatically switch between standby + and redundancy mode. +======================= ====================================================== diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst index da15e3094c8c..30e6e77fb3c8 100644 --- a/Documentation/hwmon/lm25066.rst +++ b/Documentation/hwmon/lm25066.rst @@ -76,7 +76,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/lm75.rst b/Documentation/hwmon/lm75.rst index ba8acbd2a6cb..e749f827c002 100644 --- a/Documentation/hwmon/lm75.rst +++ b/Documentation/hwmon/lm75.rst @@ -119,9 +119,9 @@ Supported chips: http://www.ti.com/product/tmp275 - * NXP LM75B + * NXP LM75B, PCT2075 - Prefix: 'lm75b' + Prefix: 'lm75b', 'pct2075' Addresses scanned: none @@ -129,6 +129,8 @@ Supported chips: http://www.nxp.com/documents/data_sheet/LM75B.pdf + http://www.nxp.com/docs/en/data-sheet/PCT2075.pdf + Author: Frodo Looijaard <frodol@dds.nl> Description diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst index 6d5e9538991f..c06249292557 100644 --- a/Documentation/hwmon/max16064.rst +++ b/Documentation/hwmon/max16064.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst index fa5c852a178c..45f69f334f25 100644 --- a/Documentation/hwmon/max16065.rst +++ b/Documentation/hwmon/max16065.rst @@ -79,7 +79,7 @@ Usage Notes This driver does not probe for devices, since there is no register which can be safely used to identify the chip. You will have to instantiate -the devices explicitly. Please see Documentation/i2c/instantiating-devices for +the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. WARNING: Do not access chip registers using the i2cdump command, and do not use diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst index aa4469be6674..fe701e07eaf5 100644 --- a/Documentation/hwmon/max20751.rst +++ b/Documentation/hwmon/max20751.rst @@ -30,7 +30,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst index 939138e12b02..5744df100a5d 100644 --- a/Documentation/hwmon/max34440.rst +++ b/Documentation/hwmon/max34440.rst @@ -83,7 +83,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. For MAX34446, the value of the currX_crit attribute determines if current or diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst index 253482add082..7952b6ecaa2d 100644 --- a/Documentation/hwmon/max6650.rst +++ b/Documentation/hwmon/max6650.rst @@ -55,7 +55,7 @@ Usage notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Module parameters diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst index 009487759c61..71e7f2cbe2e2 100644 --- a/Documentation/hwmon/max8688.rst +++ b/Documentation/hwmon/max8688.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst index 1f0c6b2235ab..978691d5956d 100644 --- a/Documentation/hwmon/menf21bmc.rst +++ b/Documentation/hwmon/menf21bmc.rst @@ -28,7 +28,7 @@ Usage Notes This driver is part of the MFD driver named "menf21bmc" and does not auto-detect devices. You will have to instantiate the MFD driver explicitly. -Please see Documentation/i2c/instantiating-devices for +Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst index e98bd542a441..5c4e85f53177 100644 --- a/Documentation/hwmon/pcf8591.rst +++ b/Documentation/hwmon/pcf8591.rst @@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface The PCF8591 is plainly impossible to detect! Thus the driver won't even try. You have to explicitly instantiate the device at the relevant address (in the interval [0x48..0x4f]) either through platform data, or -using the sysfs interface. See Documentation/i2c/instantiating-devices +using the sysfs interface. See Documentation/i2c/instantiating-devices.rst for details. Directories are being created for each instantiated PCF8591: diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610.rst index 211cedeefb44..4f2388840d06 100644 --- a/Documentation/hwmon/pxe1610 +++ b/Documentation/hwmon/pxe1610.rst @@ -2,19 +2,29 @@ Kernel driver pxe1610 ===================== Supported chips: + * Infineon PXE1610 + Prefix: 'pxe1610' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. * Infineon PXE1110 + Prefix: 'pxe1110' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. * Infineon PXM1310 + Prefix: 'pxm1310' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. Author: Vijay Khemka <vijaykhemka@fb.com> @@ -25,14 +35,19 @@ Description PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers and compliant to - -- Intel VR13 DC-DC converter specifications. - -- Intel SVID protocol. + + - Intel VR13 DC-DC converter specifications. + - Intel SVID protocol. + Used for Vcore power regulation for Intel VR13 based microprocessors - -- Servers, Workstations, and High-end desktops + + - Servers, Workstations, and High-end desktops PXM1310 is a Multi-rail Controller and it is compliant to - -- Intel VR13 DC-DC converter specifications. - -- Intel SVID protocol. + + - Intel VR13 DC-DC converter specifications. + - Intel SVID protocol. + Used for DDR3/DDR4 Memory power regulation for Intel VR13 and IMVP8 based systems @@ -44,10 +59,10 @@ This driver does not probe for PMBus devices. You will have to instantiate devices explicitly. Example: the following commands will load the driver for an PXE1610 -at address 0x70 on I2C bus #4: +at address 0x70 on I2C bus #4:: -# modprobe pxe1610 -# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device + # modprobe pxe1610 + # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device It can also be instantiated by declaring in device tree @@ -55,6 +70,7 @@ It can also be instantiated by declaring in device tree Sysfs attributes ---------------- +====================== ==================================== curr1_label "iin" curr1_input Measured input current curr1_alarm Current high alarm @@ -88,3 +104,4 @@ temp[1-3]_crit Critical high temperature temp[1-3]_crit_alarm Chip temperature critical high alarm temp[1-3]_max Maximum temperature temp[1-3]_max_alarm Chip temperature high alarm +====================== ==================================== diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst index 978a7117e4b2..95a850d5b2c1 100644 --- a/Documentation/hwmon/sht3x.rst +++ b/Documentation/hwmon/sht3x.rst @@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500. The device communicates with the I2C protocol. Sensors can have the I2C addresses 0x44 or 0x45, depending on the wiring. See -Documentation/i2c/instantiating-devices for methods to instantiate the device. +Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of sht3x_platform_data: diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst index aa116332ba26..08380f21ab6a 100644 --- a/Documentation/hwmon/shtc1.rst +++ b/Documentation/hwmon/shtc1.rst @@ -19,7 +19,17 @@ Supported chips: Addresses scanned: none - Datasheet: Not publicly available + Datasheet: http://www.sensirion.com/file/datasheet_shtw1 + + + + * Sensirion SHTC3 + + Prefix: 'shtc3' + + Addresses scanned: none + + Datasheet: http://www.sensirion.com/file/datasheet_shtc3 @@ -30,13 +40,12 @@ Author: Description ----------- -This driver implements support for the Sensirion SHTC1 chip, a humidity and -temperature sensor. Temperature is measured in degrees celsius, relative -humidity is expressed as a percentage. Driver can be used as well for SHTW1 -chip, which has the same electrical interface. +This driver implements support for the Sensirion SHTC1, SHTW1, and SHTC3 +chips, a humidity and temperature sensor. Temperature is measured in degrees +celsius, relative humidity is expressed as a percentage. The device communicates with the I2C protocol. All sensors are set to I2C -address 0x70. See Documentation/i2c/instantiating-devices for methods to +address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of shtc1_platform_data: diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index 452fc28d8e0b..9a218ea996d8 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -20,6 +20,10 @@ increase the chances of your change being accepted. errors, no warnings, and few if any check messages. If there are any messages, please be prepared to explain. +* Please use the standard multi-line comment style. Do not mix C and C++ + style comments in a single driver (with the exception of the SPDX license + identifier). + * If your patch generates checkpatch errors, warnings, or check messages, please refrain from explanations such as "I prefer that coding style". Keep in mind that each unnecessary message helps hiding a real problem, @@ -120,8 +124,8 @@ increase the chances of your change being accepted. completely initialize your chip and your driver first, then register with the hwmon subsystem. -* Use devm_hwmon_device_register_with_groups() or, if your driver needs a remove - function, hwmon_device_register_with_groups() to register your driver with the +* Use devm_hwmon_device_register_with_info() or, if your driver needs a remove + function, hwmon_device_register_with_info() to register your driver with the hwmon subsystem. Try using devm_add_action() instead of a remove function if possible. Do not use hwmon_device_register(). diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst index 15d25806d585..205de6148fcb 100644 --- a/Documentation/hwmon/tmp103.rst +++ b/Documentation/hwmon/tmp103.rst @@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see Documentation/hwmon/sysfs-interface.rst under Temperatures). Please refer how to instantiate this driver: -Documentation/i2c/instantiating-devices +Documentation/i2c/instantiating-devices.rst diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst index b691e30479dd..8fe3e1c3572e 100644 --- a/Documentation/hwmon/tps40422.rst +++ b/Documentation/hwmon/tps40422.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst index ebc4f2b3bfea..746f21fcb48c 100644 --- a/Documentation/hwmon/ucd9000.rst +++ b/Documentation/hwmon/ucd9000.rst @@ -64,7 +64,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst index b819dfd75f71..4f0e7c3ca6f4 100644 --- a/Documentation/hwmon/ucd9200.rst +++ b/Documentation/hwmon/ucd9200.rst @@ -40,7 +40,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst index a343c35df740..7ab9ddebcf79 100644 --- a/Documentation/hwmon/via686a.rst +++ b/Documentation/hwmon/via686a.rst @@ -40,7 +40,7 @@ all as a 686A. The Via 686a southbridge has integrated hardware monitor functionality. It also has an I2C bus, but this driver only supports the hardware monitor. -For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro> +For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst> The Via 686a implements three temperature sensors, two fan rotation speed sensors, five voltage sensors and alarms. diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst index 41513bb7fe51..968aff10ce0a 100644 --- a/Documentation/hwmon/zl6100.rst +++ b/Documentation/hwmon/zl6100.rst @@ -121,7 +121,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. .. warning:: diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst index 5d46342e486a..6941064730dc 100644 --- a/Documentation/i2c/busses/i2c-ali1535 +++ b/Documentation/i2c/busses/i2c-ali1535.rst @@ -1,16 +1,19 @@ +========================= Kernel driver i2c-ali1535 +========================= Supported adapters: * Acer Labs, Inc. ALI 1535 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Dan Eaton <dan.eaton@rocketlogix.com>, - Stephen Rousset<stephen.rousset@rocketlogix.com> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Dan Eaton <dan.eaton@rocketlogix.com>, + - Stephen Rousset<stephen.rousset@rocketlogix.com> Description ----------- diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst index 41b1a077e4c7..eec32c3ba92a 100644 --- a/Documentation/i2c/busses/i2c-ali1563 +++ b/Documentation/i2c/busses/i2c-ali1563.rst @@ -1,7 +1,10 @@ +========================= Kernel driver i2c-ali1563 +========================= Supported adapters: * Acer Labs, Inc. ALI 1563 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst index 42888d8ac124..d4c1a2a419cb 100644 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ b/Documentation/i2c/busses/i2c-ali15x3.rst @@ -1,20 +1,23 @@ +========================= Kernel driver i2c-ali15x3 +========================= Supported adapters: * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Mark D. Studebaker <mdsxyz123@yahoo.com> Module Parameters ----------------- * force_addr: int - Initialize the base address of the i2c controller + Initialize the base address of the i2c controller Notes @@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in lspci. Don't use this unless the driver complains that the base address is not set. -Example: 'modprobe i2c-ali15x3 force_addr=0xe800' +Example:: + + modprobe i2c-ali15x3 force_addr=0xe800 SMBus periodically hangs on ASUS P5A motherboards and can only be cleared by a power cycle. Cause unknown (see Issues below). @@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) M1541 and M1543C South Bridges. The M1543C is a South bridge for desktop systems. + The M1541 is a South bridge for portable systems. + They are part of the following ALI chipsets: * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and - 100MHz CPU Front Side bus + 100MHz CPU Front Side bus * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz - CPU Front Side bus + CPU Front Side bus + Some Aladdin V motherboards: - Asus P5A - Atrend ATC-5220 - BCM/GVC VP1541 - Biostar M5ALA - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't - enable the 7101 device! **) - Iwill XA100 Plus - Micronics C200 - Microstar (MSI) MS-5169 + - Asus P5A + - Atrend ATC-5220 + - BCM/GVC VP1541 + - Biostar M5ALA + - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't + enable the 7101 device!) + - Iwill XA100 Plus + - Micronics C200 + - Microstar (MSI) MS-5169 * "Aladdin IV" includes the M1541 Socket 7 North bridge - with host bus up to 83.3 MHz. + with host bus up to 83.3 MHz. For an overview of these chips see http://www.acerlabs.com. At this time the full data sheets on the web site are password protected, however if you contact the ALI office in San Jose they may give you the password. The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An -output of lspci will show something similar to the following: +output of lspci will show something similar to the following:: 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03) 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3) 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1) -** IMPORTANT ** -** If you have a M1533 or M1543C on the board and you get -** "ali15x3: Error: Can't detect ali15x3!" -** then run lspci. -** If you see the 1533 and 5229 devices but NOT the 7101 device, -** then you must enable ACPI, the PMU, SMB, or something similar -** in the BIOS. -** The driver won't work if it can't find the M7101 device. +.. important:: + + If you have a M1533 or M1543C on the board and you get + "ali15x3: Error: Can't detect ali15x3!" + then run lspci. + + If you see the 1533 and 5229 devices but NOT the 7101 device, + then you must enable ACPI, the PMU, SMB, or something similar + in the BIOS. + + The driver won't work if it can't find the M7101 device. The SMB controller is part of the M7101 device, which is an ACPI-compliant Power Management Unit (PMU). @@ -109,4 +120,3 @@ There may be electrical problems on this board. On the P5A, the W83781D sensor chip is on both the ISA and SMBus. Therefore the SMBus hangs can generally be avoided by accessing the W83781D on the ISA bus only. - diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2 deleted file mode 100644 index 6571487171f4..000000000000 --- a/Documentation/i2c/busses/i2c-amd-mp2 +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-amd-mp2 - -Supported adapters: - * AMD MP2 PCIe interface - -Datasheet: not publicly available. - -Authors: - Shyam Sundar S K <Shyam-sundar.S-k@amd.com> - Nehal Shah <nehal-bakulchandra.shah@amd.com> - Elie Morisse <syniurge@gmail.com> - -Description ------------ - -The MP2 is an ARM processor programmed as an I2C controller and communicating -with the x86 host through PCI. - -If you see something like this: - -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 - -in your 'lspci -v', then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst new file mode 100644 index 000000000000..ebc2fa899325 --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst @@ -0,0 +1,25 @@ +========================= +Kernel driver i2c-amd-mp2 +========================= + +Supported adapters: + * AMD MP2 PCIe interface + +Datasheet: not publicly available. + +Authors: + - Shyam Sundar S K <Shyam-sundar.S-k@amd.com> + - Nehal Shah <nehal-bakulchandra.shah@amd.com> + - Elie Morisse <syniurge@gmail.com> + +Description +----------- + +The MP2 is an ARM processor programmed as an I2C controller and communicating +with the x86 host through PCI. + +If you see something like this:: + + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 + +in your ``lspci -v``, then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst index 67f30874d0bf..bc93f392a4fc 100644 --- a/Documentation/i2c/busses/i2c-amd756 +++ b/Documentation/i2c/busses/i2c-amd756.rst @@ -1,18 +1,22 @@ +======================== Kernel driver i2c-amd756 +======================== Supported adapters: * AMD 756 * AMD 766 * AMD 768 * AMD 8111 + Datasheets: Publicly available on AMD website * nVidia nForce + Datasheet: Unavailable Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com> Description ----------- diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst index 460dd6635fd2..d08bf0a7f0ac 100644 --- a/Documentation/i2c/busses/i2c-amd8111 +++ b/Documentation/i2c/busses/i2c-amd8111.rst @@ -1,4 +1,6 @@ +========================= Kernel driver i2c-adm8111 +========================= Supported adapters: * AMD-8111 SMBus 2.0 PCI interface @@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz> Description ----------- -If you see something like this: +If you see something like this:: -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 - Flags: medium devsel, IRQ 19 - I/O ports at d400 [size=32] + 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) + Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 + Flags: medium devsel, IRQ 19 + I/O ports at d400 [size=32] -in your 'lspci -v', then this driver is for your chipset. +in your ``lspci -v``, then this driver is for your chipset. Process Call Support -------------------- diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst index 0d6018c316c7..c18cbdcdf73c 100644 --- a/Documentation/i2c/busses/i2c-diolan-u2c +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst @@ -1,7 +1,10 @@ +============================ Kernel driver i2c-diolan-u2c +============================ Supported adapters: * Diolan U2C-12 I2C-USB adapter + Documentation: http://www.diolan.com/i2c/u2c12.html diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst index f426c13c63a9..2a570c214880 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-i801 +====================== + Supported adapters: * Intel 82801AA and 82801AB (ICH and ICH0 - part of the @@ -39,28 +42,33 @@ Supported adapters: * Intel Comet Lake (PCH) * Intel Elkhart Lake (PCH) * Intel Tiger Lake (PCH) + Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller and the additional 'Integrated Device Function' controllers are supported. -Authors: - Mark Studebaker <mdsxyz123@yahoo.com> - Jean Delvare <jdelvare@suse.de> +Authors: + - Mark Studebaker <mdsxyz123@yahoo.com> + - Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- * disable_features (bit vector) + Disable selected features normally supported by the device. This makes it possible to work around possible driver or hardware bugs if the feature in question doesn't work as intended for whatever reason. Bit values: + + ==== ========================================= 0x01 disable SMBus PEC 0x02 disable the block buffer 0x08 disable the I2C block read functionality 0x10 don't use interrupts 0x20 disable SMBus Host Notify + ==== ========================================= Description @@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others. The ICH chips contain at least SEVEN separate PCI functions in TWO logical PCI devices. An output of lspci will show something similar to the -following: +following:: 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01) 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01) @@ -139,14 +147,14 @@ and you think there's something interesting on the SMBus (e.g. a hardware monitoring chip), you need to add your board to the list. The motherboard is identified using the subvendor and subdevice IDs of the -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0": +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``:: -00:00.0 Class 0600: 8086:2570 (rev 02) - Subsystem: 1043:80f2 - Flags: bus master, fast devsel, latency 0 - Memory at fc000000 (32-bit, prefetchable) [size=32M] - Capabilities: [e4] #09 [2106] - Capabilities: [a0] AGP version 3.0 + 00:00.0 Class 0600: 8086:2570 (rev 02) + Subsystem: 1043:80f2 + Flags: bus master, fast devsel, latency 0 + Memory at fc000000 (32-bit, prefetchable) [size=32M] + Capabilities: [e4] #09 [2106] + Capabilities: [a0] AGP version 3.0 Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic @@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's anything interesting on your hidden ICH SMBus. -********************** +---------------------------------------------------------------------------- + The lm_sensors project gratefully acknowledges the support of Texas Instruments in the initial development of this driver. diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst index 737355822c0b..8e74919a3fdf 100644 --- a/Documentation/i2c/busses/i2c-ismt +++ b/Documentation/i2c/busses/i2c-ismt.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-ismt +====================== + Supported adapters: * Intel S12xx series SOCs @@ -11,16 +14,21 @@ Module Parameters ----------------- * bus_speed (unsigned int) + Allows changing of the bus speed. Normally, the bus speed is set by the BIOS and never needs to be changed. However, some SMBus analyzers are too slow for monitoring the bus during debug, thus the need for this module parameter. Specify the bus speed in kHz. + Available bus frequency settings: - 0 no change - 80 kHz - 100 kHz - 400 kHz - 1000 kHz + + ==== ========= + 0 no change + 80 kHz + 100 kHz + 400 kHz + 1000 kHz + ==== ========= Description @@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers targeted primarily at the microserver and storage markets. The S12xx series contain a pair of PCI functions. An output of lspci will show -something similar to the following: +something similar to the following:: 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst index 925904aa9b57..9a0b2916aa71 100644 --- a/Documentation/i2c/busses/i2c-mlxcpld +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst @@ -1,9 +1,12 @@ +================== Driver i2c-mlxcpld +================== Author: Michael Shych <michaelsh@mellanox.com> This is the Mellanox I2C controller logic, implemented in Lattice CPLD device. + Device supports: - Master mode. - One physical bus. @@ -20,6 +23,8 @@ The next transaction types are supported: - Write Byte/Block. Registers: + +=============== === ======================================================================= CPBLTY 0x0 - capability reg. Bits [6:5] - transaction length. b01 - 72B is supported, 36B in other case. @@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs. For read transactions address is sent in a separate transaction and specified in the four first bytes (DATA0 - DATA3). Data is read starting from DATA0. +=============== === ======================================================================= diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst index 9698c396b830..83181445268f 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2.rst @@ -1,10 +1,12 @@ +========================= Kernel driver i2c-nforce2 +========================= Supported adapters: - * nForce2 MCP 10de:0064 - * nForce2 Ultra 400 MCP 10de:0084 - * nForce3 Pro150 MCP 10de:00D4 - * nForce3 250Gb MCP 10de:00E4 + * nForce2 MCP 10de:0064 + * nForce2 Ultra 400 MCP 10de:0084 + * nForce3 Pro150 MCP 10de:00D4 + * nForce3 250Gb MCP 10de:00E4 * nForce4 MCP 10de:0052 * nForce4 MCP-04 10de:0034 * nForce MCP51 10de:0264 @@ -16,26 +18,27 @@ Supported adapters: * nForce MCP78S 10de:0752 * nForce MCP79 10de:0AA2 -Datasheet: not publicly available, but seems to be similar to the +Datasheet: + not publicly available, but seems to be similar to the AMD-8111 SMBus 2.0 adapter. Authors: - Hans-Frieder Vogt <hfvogt@gmx.net>, - Thomas Leibold <thomas@plx.com>, - Patrick Dreker <patrick@dreker.de> - + - Hans-Frieder Vogt <hfvogt@gmx.net>, + - Thomas Leibold <thomas@plx.com>, + - Patrick Dreker <patrick@dreker.de> + Description ----------- i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. -If your 'lspci -v' listing shows something like the following, +If your ``lspci -v`` listing shows something like the following:: -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) - Subsystem: Asustek Computer, Inc.: Unknown device 0c11 - Flags: 66Mhz, fast devsel, IRQ 5 - I/O ports at c000 [size=32] - Capabilities: <available only to root> + 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) + Subsystem: Asustek Computer, Inc.: Unknown device 0c11 + Flags: 66Mhz, fast devsel, IRQ 5 + I/O ports at c000 [size=32] + Capabilities: <available only to root> then this driver should support the SMBuses of your motherboard. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst index 31884d2b2eb5..38fb8a4c8756 100644 --- a/Documentation/i2c/busses/i2c-nvidia-gpu +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst @@ -1,4 +1,6 @@ +============================ Kernel driver i2c-nvidia-gpu +============================ Datasheet: not publicly available. @@ -11,8 +13,8 @@ Description i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing and later GPUs and it is used to communicate with Type-C controller on GPUs. -If your 'lspci -v' listing shows something like the following, +If your ``lspci -v`` listing shows something like the following:: -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst index 9caaf7df1b2f..f5e175f2a2a6 100644 --- a/Documentation/i2c/busses/i2c-ocores +++ b/Documentation/i2c/busses/i2c-ocores.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-ocores +======================== Supported adapters: * OpenCores.org I2C controller by Richard Herveille (see datasheet link) @@ -23,9 +25,9 @@ distance between registers and the input clock speed. There is also a possibility to attach a list of i2c_board_info which the i2c-ocores driver will add to the bus upon creation. -E.G. something like: +E.G. something like:: -static struct resource ocores_resources[] = { + static struct resource ocores_resources[] = { [0] = { .start = MYI2C_BASEADDR, .end = MYI2C_BASEADDR + 8, @@ -36,10 +38,10 @@ static struct resource ocores_resources[] = { .end = MYI2C_IRQ, .flags = IORESOURCE_IRQ, }, -}; + }; -/* optional board info */ -struct i2c_board_info ocores_i2c_board_info[] = { + /* optional board info */ + struct i2c_board_info ocores_i2c_board_info[] = { { I2C_BOARD_INFO("tsc2003", 0x48), .platform_data = &tsc2003_platform_data, @@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = { I2C_BOARD_INFO("adv7180", 0x42 >> 1), .irq = ADV_IRQ } -}; + }; -static struct ocores_i2c_platform_data myi2c_data = { + static struct ocores_i2c_platform_data myi2c_data = { .regstep = 2, /* two bytes between registers */ .clock_khz = 50000, /* input clock of 50MHz */ .devices = ocores_i2c_board_info, /* optional table of devices */ .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ -}; + }; -static struct platform_device myi2c = { + static struct platform_device myi2c = { .name = "ocores-i2c", .dev = { .platform_data = &myi2c_data, }, .num_resources = ARRAY_SIZE(ocores_resources), .resource = ocores_resources, -}; + }; diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport deleted file mode 100644 index c3dbb3bfd814..000000000000 --- a/Documentation/i2c/busses/i2c-parport +++ /dev/null @@ -1,178 +0,0 @@ -Kernel driver i2c-parport - -Author: Jean Delvare <jdelvare@suse.de> - -This is a unified driver for several i2c-over-parallel-port adapters, -such as the ones made by Philips, Velleman or ELV. This driver is -meant as a replacement for the older, individual drivers: - * i2c-philips-par - * i2c-elv - * i2c-velleman - * video/i2c-parport (NOT the same as this one, dedicated to home brew - teletext adapters) - -It currently supports the following devices: - * (type=0) Philips adapter - * (type=1) home brew teletext adapter - * (type=2) Velleman K8000 adapter - * (type=3) ELV adapter - * (type=4) Analog Devices ADM1032 evaluation board - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 - * (type=6) Barco LPT->DVI (K5800236) adapter - * (type=7) One For All JP1 parallel port adapter - * (type=8) VCT-jig - -These devices use different pinout configurations, so you have to tell -the driver what you have, using the type module parameter. There is no -way to autodetect the devices. Support for different pinout configurations -can be easily added when needed. - -Earlier kernels defaulted to type=0 (Philips). But now, if the type -parameter is missing, the driver will simply fail to initialize. - -SMBus alert support is available on adapters which have this line properly -connected to the parallel port's interrupt pin. - - -Building your own adapter -------------------------- - -If you want to build you own i2c-over-parallel-port adapter, here is -a sample electronics schema (credits go to Sylvain Munaut): - -Device PC -Side ___________________Vdd (+) Side - | | | - --- --- --- - | | | | | | - |R| |R| |R| - | | | | | | - --- --- --- - | | | - | | /| | -SCL ----------x--------o |-----------x------------------- pin 2 - | \| | | - | | | - | |\ | | -SDA ----------x----x---| o---x--------------------------- pin 13 - | |/ | - | | - | /| | - ---------o |----------------x-------------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - -Remarks: - - This is the exact pinout and electronics used on the Analog Devices - evaluation boards. - /| - - All inverters -o |- must be 74HC05, they must be open collector output. - \| - - All resitors are 10k. - - Pins 18-25 of the parallel port connected to GND. - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. - The ADM1032 evaluation board uses D4-D7. Beware that the amount of - current you can draw from the parallel port is limited. Also note that - all connected lines MUST BE driven at the same state, else you'll short - circuit the output buffers! So plugging the I2C adapter after loading - the i2c-parport module might be a good safety since data line state - prior to init may be unknown. - - This is 5V! - - Obviously you cannot read SCL (so it's not really standard-compliant). - Pretty easy to add, just copy the SDA part and use another input pin. - That would give (ELV compatible pinout): - - -Device PC -Side ______________________________Vdd (+) Side - | | | | - --- --- --- --- - | | | | | | | | - |R| |R| |R| |R| - | | | | | | | | - --- --- --- --- - | | | | - | | |\ | | -SCL ----------x--------x--| o---x------------------------ pin 15 - | | |/ | - | | | - | | /| | - | ---o |-------------x-------------- pin 2 - | \| | | - | | | - | | | - | |\ | | -SDA ---------------x---x--| o--------x------------------- pin 10 - | |/ | - | | - | /| | - ---o |------------------x--------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - - -If possible, you should use the same pinout configuration as existing -adapters do, so you won't even have to change the code. - - -Similar (but different) drivers -------------------------------- - -This driver is NOT the same as the i2c-pport driver found in the i2c -package. The i2c-pport driver makes use of modern parallel port features so -that you don't need additional electronics. It has other restrictions -however, and was not ported to Linux 2.6 (yet). - -This driver is also NOT the same as the i2c-pcf-epp driver found in the -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as -an I2C bus directly. Instead, it uses it to control an external I2C bus -master. That driver was not ported to Linux 2.6 (yet) either. - - -Legacy documentation for Velleman adapter ------------------------------------------ - -Useful links: -Velleman http://www.velleman.be/ -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html - -The project has lead to new libs for the Velleman K8000 and K8005: - LIBK8000 v1.99.1 and LIBK8005 v0.21 -With these libs, you can control the K8000 interface card and the K8005 -stepper motor card with the simple commands which are in the original -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and -many more, using /dev/velleman. - http://home.wanadoo.nl/hihihi/libk8000.htm - http://home.wanadoo.nl/hihihi/libk8005.htm - http://struyve.mine.nu:8080/index.php?block=k8000 - http://sourceforge.net/projects/libk8005/ - - -One For All JP1 parallel port adapter -------------------------------------- - -The JP1 project revolves around a set of remote controls which expose -the I2C bus their internal configuration EEPROM lives on via a 6 pin -jumper in the battery compartment. More details can be found at: - -http://www.hifi-remote.com/jp1/ - -Details of the simple parallel port hardware can be found at: - -http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst index 7071b8ba0af4..e73af975d2c8 100644 --- a/Documentation/i2c/busses/i2c-parport-light +++ b/Documentation/i2c/busses/i2c-parport-light.rst @@ -1,13 +1,15 @@ +=============================== Kernel driver i2c-parport-light +=============================== Author: Jean Delvare <jdelvare@suse.de> -This driver is a light version of i2c-parport. It doesn't depend +This driver is a light version of i2c-parport. It doesn't depend on the parport driver, and uses direct I/O access instead. This might be preferred on embedded systems where wasting memory for the clean but heavy parport handling is not an option. The drawback is a reduced portability -and the impossibility to daisy-chain other parallel port devices. - +and the impossibility to daisy-chain other parallel port devices. + Please see i2c-parport for documentation. Module parameters: diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst new file mode 100644 index 000000000000..a9b4e8133700 --- /dev/null +++ b/Documentation/i2c/busses/i2c-parport.rst @@ -0,0 +1,190 @@ +========================= +Kernel driver i2c-parport +========================= + +Author: Jean Delvare <jdelvare@suse.de> + +This is a unified driver for several i2c-over-parallel-port adapters, +such as the ones made by Philips, Velleman or ELV. This driver is +meant as a replacement for the older, individual drivers: + + * i2c-philips-par + * i2c-elv + * i2c-velleman + * video/i2c-parport + (NOT the same as this one, dedicated to home brew teletext adapters) + +It currently supports the following devices: + + * (type=0) Philips adapter + * (type=1) home brew teletext adapter + * (type=2) Velleman K8000 adapter + * (type=3) ELV adapter + * (type=4) Analog Devices ADM1032 evaluation board + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 + * (type=6) Barco LPT->DVI (K5800236) adapter + * (type=7) One For All JP1 parallel port adapter + * (type=8) VCT-jig + +These devices use different pinout configurations, so you have to tell +the driver what you have, using the type module parameter. There is no +way to autodetect the devices. Support for different pinout configurations +can be easily added when needed. + +Earlier kernels defaulted to type=0 (Philips). But now, if the type +parameter is missing, the driver will simply fail to initialize. + +SMBus alert support is available on adapters which have this line properly +connected to the parallel port's interrupt pin. + + +Building your own adapter +------------------------- + +If you want to build you own i2c-over-parallel-port adapter, here is +a sample electronics schema (credits go to Sylvain Munaut):: + + Device PC + Side ___________________Vdd (+) Side + | | | + --- --- --- + | | | | | | + |R| |R| |R| + | | | | | | + --- --- --- + | | | + | | /| | + SCL ----------x--------o |-----------x------------------- pin 2 + | \| | | + | | | + | |\ | | + SDA ----------x----x---| o---x--------------------------- pin 13 + | |/ | + | | + | /| | + ---------o |----------------x-------------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + +Remarks: + - This is the exact pinout and electronics used on the Analog Devices + evaluation boards. + - All inverters:: + + /| + -o |- + \| + + must be 74HC05, they must be open collector output. + - All resitors are 10k. + - Pins 18-25 of the parallel port connected to GND. + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. + The ADM1032 evaluation board uses D4-D7. Beware that the amount of + current you can draw from the parallel port is limited. Also note that + all connected lines MUST BE driven at the same state, else you'll short + circuit the output buffers! So plugging the I2C adapter after loading + the i2c-parport module might be a good safety since data line state + prior to init may be unknown. + - This is 5V! + - Obviously you cannot read SCL (so it's not really standard-compliant). + Pretty easy to add, just copy the SDA part and use another input pin. + That would give (ELV compatible pinout):: + + + Device PC + Side ______________________________Vdd (+) Side + | | | | + --- --- --- --- + | | | | | | | | + |R| |R| |R| |R| + | | | | | | | | + --- --- --- --- + | | | | + | | |\ | | + SCL ----------x--------x--| o---x------------------------ pin 15 + | | |/ | + | | | + | | /| | + | ---o |-------------x-------------- pin 2 + | \| | | + | | | + | | | + | |\ | | + SDA ---------------x---x--| o--------x------------------- pin 10 + | |/ | + | | + | /| | + ---o |------------------x--------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + + +If possible, you should use the same pinout configuration as existing +adapters do, so you won't even have to change the code. + + +Similar (but different) drivers +------------------------------- + +This driver is NOT the same as the i2c-pport driver found in the i2c +package. The i2c-pport driver makes use of modern parallel port features so +that you don't need additional electronics. It has other restrictions +however, and was not ported to Linux 2.6 (yet). + +This driver is also NOT the same as the i2c-pcf-epp driver found in the +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as +an I2C bus directly. Instead, it uses it to control an external I2C bus +master. That driver was not ported to Linux 2.6 (yet) either. + + +Legacy documentation for Velleman adapter +----------------------------------------- + +Useful links: + +- Velleman http://www.velleman.be/ +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html + +The project has lead to new libs for the Velleman K8000 and K8005: + + LIBK8000 v1.99.1 and LIBK8005 v0.21 + +With these libs, you can control the K8000 interface card and the K8005 +stepper motor card with the simple commands which are in the original +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and +many more, using /dev/velleman. + + - http://home.wanadoo.nl/hihihi/libk8000.htm + - http://home.wanadoo.nl/hihihi/libk8005.htm + - http://struyve.mine.nu:8080/index.php?block=k8000 + - http://sourceforge.net/projects/libk8005/ + + +One For All JP1 parallel port adapter +------------------------------------- + +The JP1 project revolves around a set of remote controls which expose +the I2C bus their internal configuration EEPROM lives on via a 6 pin +jumper in the battery compartment. More details can be found at: + +http://www.hifi-remote.com/jp1/ + +Details of the simple parallel port hardware can be found at: + +http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst index b044e5265488..a254010c8055 100644 --- a/Documentation/i2c/busses/i2c-pca-isa +++ b/Documentation/i2c/busses/i2c-pca-isa.rst @@ -1,6 +1,9 @@ +========================= Kernel driver i2c-pca-isa +========================= Supported adapters: + This driver supports ISA boards using the Philips PCA 9564 Parallel bus to I2C bus controller @@ -10,11 +13,11 @@ Module Parameters ----------------- * base int - I/O base address + I/O base address * irq int - IRQ interrupt + IRQ interrupt * clock int - Clock rate as described in table 1 of PCA9564 datasheet + Clock rate as described in table 1 of PCA9564 datasheet Description ----------- diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst index 2703bc3acad0..cc9000259223 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4.rst @@ -1,4 +1,6 @@ +======================= Kernel driver i2c-piix4 +======================= Supported adapters: * Intel 82371AB PIIX4 and PIIX4E @@ -20,9 +22,9 @@ Supported adapters: * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge Datasheet: Publicly available at the SMSC website http://www.smsc.com -Authors: - Frodo Looijaard <frodol@dds.nl> - Philip Edelbrock <phil@netroedge.com> +Authors: + - Frodo Looijaard <frodol@dds.nl> + - Philip Edelbrock <phil@netroedge.com> Module Parameters @@ -39,16 +41,16 @@ Description The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of functionality. Among other things, it implements the PCI bus. One of its -minor functions is implementing a System Management Bus. This is a true +minor functions is implementing a System Management Bus. This is a true SMBus - you can not access it on I2C levels. The good news is that it natively understands SMBus commands and you do not have to worry about timing problems. The bad news is that non-SMBus devices connected to it can confuse it mightily. Yes, this is known to happen... -Do 'lspci -v' and see whether it contains an entry like this: +Do ``lspci -v`` and see whether it contains an entry like this:: -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) - Flags: medium devsel, IRQ 9 + 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) + Flags: medium devsel, IRQ 9 Bus and device numbers may differ, but the function number must be identical (like many PCI devices, the PIIX4 incorporates a number of @@ -91,7 +93,7 @@ the SMI mode. device is located at 00:0f.0. 2) Now you just need to change the value in 0xD2 register. Get it first with command: lspci -xxx -s 00:0f.0 - If the value is 0x3 then you need to change it to 0x1 + If the value is 0x3 then you need to change it to 0x1: setpci -s 00:0f.0 d2.b=1 Please note that you don't need to do that in all cases, just when the SMBus is diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst index ecd21fb49a8f..b85630c84a96 100644 --- a/Documentation/i2c/busses/i2c-sis5595 +++ b/Documentation/i2c/busses/i2c-sis5595.rst @@ -1,9 +1,11 @@ +========================= Kernel driver i2c-sis5595 +========================= Authors: - Frodo Looijaard <frodol@dds.nl>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Philip Edelbrock <phil@netroedge.com> + - Frodo Looijaard <frodol@dds.nl>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Philip Edelbrock <phil@netroedge.com> Supported adapters: * Silicon Integrated Systems Corp. SiS5595 Southbridge @@ -11,14 +13,19 @@ Supported adapters: Note: all have mfr. ID 0x1039. + ========= ====== SUPPORTED PCI ID + ========= ====== 5595 0008 + ========= ====== Note: these chips contain a 0008 device which is incompatible with the 5595. We recognize these by the presence of the listed "blacklist" PCI ID and refuse to load. + ============= ====== ================ NOT SUPPORTED PCI ID BLACKLIST PCI ID + ============= ====== ================ 540 0008 0540 550 0008 0550 5513 0008 5511 @@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039. 735 0008 0735 745 0008 0745 746 0008 0746 + ============= ====== ================ Module Parameters ----------------- -* force_addr=0xaddr Set the I/O base address. Useful for boards +================== ===================================================== +force_addr=0xaddr Set the I/O base address. Useful for boards that don't set the address in the BIOS. Does not do a PCI force; the device must still be present in lspci. Don't use this unless the driver complains that the base address is not set. +================== ===================================================== Description ----------- @@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595 chip, you want the sis5595 driver for those, not this driver. This driver is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP drivers to access chips on the bus. - diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 deleted file mode 100644 index ee7943631074..000000000000 --- a/Documentation/i2c/busses/i2c-sis630 +++ /dev/null @@ -1,58 +0,0 @@ -Kernel driver i2c-sis630 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) - 730 chipset - 964 chipset - * Possible other SiS chipsets ? - -Author: Alexander Malysh <amalysh@web.de> - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support - -Module Parameters ------------------ - -* force = [1|0] Forcibly enable the SIS630. DANGEROUS! - This can be interesting for chipsets not named - above to check if it works for you chipset, but DANGEROUS! - -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, - what your BIOS use). DANGEROUS! This should be a bit - faster, but freeze some systems (i.e. my Laptop). - SIS630/730 chip only. - - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipsets. - -If you see something like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] - LPC Controller (rev 36) - -in your 'lspci' output , then this driver is for your chipset. - -Thank You ---------- -Philip Edelbrock <phil@netroedge.com> -- testing SiS730 support -Mark M. Hoffman <mhoffman@lightlink.com> -- bug fixes - -To anyone else which I forgot here ;), thanks! - diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst new file mode 100644 index 000000000000..9fcd74b18781 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis630.rst @@ -0,0 +1,63 @@ +======================== +Kernel driver i2c-sis630 +======================== + +Supported adapters: + * Silicon Integrated Systems Corp (SiS) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) + 730 chipset + 964 chipset + * Possible other SiS chipsets ? + +Author: + - Alexander Malysh <amalysh@web.de> + - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support + +Module Parameters +----------------- + +================== ===================================================== +force = [1|0] Forcibly enable the SIS630. DANGEROUS! + This can be interesting for chipsets not named + above to check if it works for you chipset, + but DANGEROUS! + +high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, + what your BIOS use). DANGEROUS! This should be a bit + faster, but freeze some systems (i.e. my Laptop). + SIS630/730 chip only. +================== ===================================================== + + +Description +----------- + +This SMBus only driver is known to work on motherboards with the above +named chipsets. + +If you see something like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] + LPC Controller (rev 36) + +in your ``lspci`` output , then this driver is for your chipset. + +Thank You +--------- +Philip Edelbrock <phil@netroedge.com> +- testing SiS730 support +Mark M. Hoffman <mhoffman@lightlink.com> +- bug fixes + +To anyone else which I forgot here ;), thanks! diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst index 0b979f3252a4..437cc1d89588 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x.rst @@ -1,13 +1,18 @@ +======================== Kernel driver i2c-sis96x +======================== Replaces 2.4.x i2c-sis645 Supported adapters: + * Silicon Integrated Systems Corp (SiS) + Any combination of these host bridges: 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 + and these south bridges: - 961, 962, 963(L) + 961, 962, 963(L) Author: Mark M. Hoffman <mhoffman@lightlink.com> @@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different place. Thanks to Alexander Malysh <amalysh@web.de> for providing the SiS630 datasheet (and driver). -The command "lspci" as root should produce something like these lines: +The command ``lspci`` as root should produce something like these lines:: -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 -or perhaps this... +or perhaps this:: -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 (kernel versions later than 2.4.18 may fill in the "Unknown"s) @@ -50,7 +55,7 @@ TO DOs ------ * The driver does not support SMBus block reads/writes; I may add them if a -scenario is found where they're needed. + scenario is found where they're needed. Thank You @@ -58,16 +63,20 @@ Thank You Mark D. Studebaker <mdsxyz123@yahoo.com> - design hints and bug fixes + Alexander Maylsh <amalysh@web.de> - ditto, plus an important datasheet... almost the one I really wanted + Hans-Günter Lütke Uphues <hg_lu@t-online.de> - patch for SiS735 + Robert Zwerus <arzie@dds.nl> - testing for SiS645DX + Kianusch Sayah Karadji <kianusch@sk-tech.net> - patch for SiS645DX/962 + Ken Healy - patch for SiS655 To anyone else who has written w/ feedback, thanks! - diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst index 60299555dcf0..f342e313ee3d 100644 --- a/Documentation/i2c/busses/i2c-taos-evm +++ b/Documentation/i2c/busses/i2c-taos-evm.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-taos-evm +========================== Author: Jean Delvare <jdelvare@suse.de> @@ -23,10 +25,10 @@ Using this driver In order to use this driver, you'll need the serport driver, and the inputattach tool, which is part of the input-utils package. The following commands will tell the kernel that you have a TAOS EVM on the first -serial port: +serial port:: -# modprobe serport -# inputattach --taos-evm /dev/ttyS0 + # modprobe serport + # inputattach --taos-evm /dev/ttyS0 Technical details diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst index 343870661ac3..846aa17d80a2 100644 --- a/Documentation/i2c/busses/i2c-via +++ b/Documentation/i2c/busses/i2c-via.rst @@ -1,4 +1,6 @@ +===================== Kernel driver i2c-via +===================== Supported adapters: * VIA Technologies, InC. VT82C586B @@ -12,23 +14,27 @@ Description i2c-via is an i2c bus driver for motherboards with VIA chipset. The following VIA pci chipsets are supported: - - MVP3, VP3, VP2/97, VPX/97 + - MVP3, VP3, VP2/97, VPX/97 - others with South bridge VT82C586B -Your lspci listing must show this : +Your ``lspci`` listing must show this :: Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10) - Problems? - - Q: You have VT82C586B on the motherboard, but not in the listing. - - A: Go to your BIOS setup, section PCI devices or similar. - Turn USB support on, and try again. +Problems? +--------- - Q: No error messages, but still i2c doesn't seem to work. + Q: + You have VT82C586B on the motherboard, but not in the listing. - A: This can happen. This driver uses the pins VIA recommends in their + A: + Go to your BIOS setup, section PCI devices or similar. + Turn USB support on, and try again. + + Q: + No error messages, but still i2c doesn't seem to work. + + A: + This can happen. This driver uses the pins VIA recommends in their datasheets, but there are several ways the motherboard manufacturer can actually wire the lines. - diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst index ab64ce21c254..1762f0cf93d0 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-viapro +======================== Supported adapters: * VIA Technologies, Inc. VT82C596A/B @@ -26,9 +28,9 @@ Supported adapters: Datasheet: available on http://linux.via.com.tw Authors: - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Jean Delvare <jdelvare@suse.de> + - Kyösti Mälkki <kmalkki@cc.hut.fi>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- @@ -44,8 +46,9 @@ Description i2c-viapro is a true SMBus host driver for motherboards with one of the supported VIA south bridges. -Your lspci -n listing must show one of these : +Your ``lspci -n`` listing must show one of these : + ================ ====================== device 1106:3050 (VT82C596A function 3) device 1106:3051 (VT82C596B function 3) device 1106:3057 (VT82C686 function 4) @@ -61,6 +64,7 @@ Your lspci -n listing must show one of these : device 1106:8353 (VX800/VX820) device 1106:8409 (VX855/VX875) device 1106:8410 (VX900) + ================ ====================== If none of these show up, you should look in the BIOS for settings like enable ACPI / SMBus or even USB. diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst new file mode 100644 index 000000000000..97ca4d510816 --- /dev/null +++ b/Documentation/i2c/busses/index.rst @@ -0,0 +1,33 @@ +. SPDX-License-Identifier: GPL-2.0 + +=============== +I2C Bus Drivers +=============== + +.. toctree:: + :maxdepth: 1 + + i2c-ali1535 + i2c-ali1563 + i2c-ali15x3 + i2c-amd756 + i2c-amd8111 + i2c-amd-mp2 + i2c-diolan-u2c + i2c-i801 + i2c-ismt + i2c-mlxcpld + i2c-nforce2 + i2c-nvidia-gpu + i2c-ocores + i2c-parport-light + i2c-parport + i2c-pca-isa + i2c-piix4 + i2c-sis5595 + i2c-sis630 + i2c-sis96x + i2c-taos-evm + i2c-viapro + i2c-via + scx200_acb diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst index ce83c871fe95..8dc7c352508c 100644 --- a/Documentation/i2c/busses/scx200_acb +++ b/Documentation/i2c/busses/scx200_acb.rst @@ -1,4 +1,6 @@ +======================== Kernel driver scx200_acb +======================== Author: Christer Weinigel <wingel@nano-system.com> @@ -25,8 +27,11 @@ Device-specific notes The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. If the scx200_acb driver is built into the kernel, add the following -parameter to your boot command line: +parameter to your boot command line:: + scx200_acb.base=0x810,0x820 + If the scx200_acb driver is built as a module, add the following line to -a configuration file in /etc/modprobe.d/ instead: +a configuration file in /etc/modprobe.d/ instead:: + options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst index fbed645ccd75..69c23a3c2b1b 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface.rst @@ -1,3 +1,7 @@ +==================== +I2C Device Interface +==================== + Usually, i2c devices are controlled by a kernel driver. But it is also possible to access all devices on an adapter from userspace, through the /dev interface. You need to load module i2c-dev for this. @@ -18,7 +22,7 @@ C example ========= So let's say you want to access an i2c adapter from a C program. -First, you need to include these two headers: +First, you need to include these two headers:: #include <linux/i2c-dev.h> #include <i2c/smbus.h> @@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. Adapter numbers are assigned somewhat dynamically, so you can not assume much about them. They can even change from one boot to the next. -Next thing, open the device file, as follows: +Next thing, open the device file, as follows:: int file; int adapter_nr = 2; /* probably dynamically determined */ @@ -42,7 +46,7 @@ Next thing, open the device file, as follows: } When you have opened the device, you must specify with what device -address you want to communicate: +address you want to communicate:: int addr = 0x40; /* The I2C address */ @@ -53,7 +57,7 @@ address you want to communicate: Well, you are all set up now. You can now use SMBus commands or plain I2C to communicate with your device. SMBus commands are preferred if -the device supports them. Both are illustrated below. +the device supports them. Both are illustrated below:: __u8 reg = 0x10; /* Device register to access */ __s32 res; @@ -100,35 +104,35 @@ Full interface description The following IOCTLs are defined: -ioctl(file, I2C_SLAVE, long addr) +``ioctl(file, I2C_SLAVE, long addr)`` Change slave address. The address is passed in the 7 lower bits of the argument (except for 10 bit addresses, passed in the 10 lower bits in this case). -ioctl(file, I2C_TENBIT, long select) +``ioctl(file, I2C_TENBIT, long select)`` Selects ten bit addresses if select not equals 0, selects normal 7 bit addresses if select equals 0. Default 0. This request is only valid if the adapter has I2C_FUNC_10BIT_ADDR. -ioctl(file, I2C_PEC, long select) +``ioctl(file, I2C_PEC, long select)`` Selects SMBus PEC (packet error checking) generation and verification if select not equals 0, disables if select equals 0. Default 0. Used only for SMBus transactions. This request only has an effect if the the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just doesn't have any effect. -ioctl(file, I2C_FUNCS, unsigned long *funcs) - Gets the adapter functionality and puts it in *funcs. +``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` + Gets the adapter functionality and puts it in ``*funcs``. -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` Do combined read/write transaction without stop in between. Only valid if the adapter has I2C_FUNC_I2C. The argument is - a pointer to a + a pointer to a:: - struct i2c_rdwr_ioctl_data { + struct i2c_rdwr_ioctl_data { struct i2c_msg *msgs; /* ptr to array of simple messages */ int nmsgs; /* number of messages to exchange */ - } + } The msgs[] themselves contain further pointers into data buffers. The function will write or read data to or from that buffers depending @@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) The slave address and whether to use ten bit address mode has to be set in each message, overriding the values set with the above ioctl's. -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) - If possible, use the provided i2c_smbus_* methods described below instead +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` + If possible, use the provided ``i2c_smbus_*`` methods described below instead of issuing direct ioctls. You can do plain i2c transactions by using read(2) and write(2) calls. @@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through ioctl I2C_SLAVE before you try to access the device. You can do SMBus level transactions (see documentation file smbus-protocol -for details) through the following functions: +for details) through the following functions:: + __s32 i2c_smbus_write_quick(int file, __u8 value); __s32 i2c_smbus_read_byte(int file); __s32 i2c_smbus_write_byte(int file, __u8 value); @@ -157,6 +162,7 @@ for details) through the following functions: __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, __u8 *values); + All these transactions return -1 on failure; you can read errno to see what happened. The 'write' transactions return 0 on success; the 'read' transactions return the read value, except for read_block, which @@ -174,39 +180,39 @@ Implementation details For the interested, here's the code flow which happens inside the kernel when you use the /dev interface to I2C: -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in -section "C example" above. - -2* These open() and ioctl() calls are handled by the i2c-dev kernel -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), -respectively. You can think of i2c-dev as a generic I2C chip driver -that can be programmed from user-space. - -3* Some ioctl() calls are for administrative tasks and are handled by -i2c-dev directly. Examples include I2C_SLAVE (set the address of the -device you want to access) and I2C_PEC (enable or disable SMBus error -checking on future transactions.) - -4* Other ioctl() calls are converted to in-kernel function calls by -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). - -The i2c-dev driver is responsible for checking all the parameters that -come from user-space for validity. After this point, there is no -difference between these calls that came from user-space through i2c-dev -and calls that would have been performed by kernel I2C chip drivers -directly. This means that I2C bus drivers don't need to implement -anything special to support access from user-space. - -5* These i2c.h functions are wrappers to the actual implementation of -your I2C bus driver. Each adapter must declare callback functions -implementing these standard calls. i2c.h:i2c_get_functionality() calls -i2c_adapter.algo->functionality(), while -i2c-core-smbus.c:i2c_smbus_xfer() calls either -adapter.algo->smbus_xfer() if it is implemented, or if not, -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls -i2c_adapter.algo->master_xfer(). +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in + section "C example" above. + +2) These open() and ioctl() calls are handled by the i2c-dev kernel + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), + respectively. You can think of i2c-dev as a generic I2C chip driver + that can be programmed from user-space. + +3) Some ioctl() calls are for administrative tasks and are handled by + i2c-dev directly. Examples include I2C_SLAVE (set the address of the + device you want to access) and I2C_PEC (enable or disable SMBus error + checking on future transactions.) + +4) Other ioctl() calls are converted to in-kernel function calls by + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). + + The i2c-dev driver is responsible for checking all the parameters that + come from user-space for validity. After this point, there is no + difference between these calls that came from user-space through i2c-dev + and calls that would have been performed by kernel I2C chip drivers + directly. This means that I2C bus drivers don't need to implement + anything special to support access from user-space. + +5) These i2c.h functions are wrappers to the actual implementation of + your I2C bus driver. Each adapter must declare callback functions + implementing these standard calls. i2c.h:i2c_get_functionality() calls + i2c_adapter.algo->functionality(), while + i2c-core-smbus.c:i2c_smbus_xfer() calls either + adapter.algo->smbus_xfer() if it is implemented, or if not, + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls + i2c_adapter.algo->master_xfer(). After your I2C bus driver has processed these requests, execution runs up the call chain, with almost no processing done, except by i2c-dev to diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst index 203002054120..203002054120 100644 --- a/Documentation/i2c/DMA-considerations +++ b/Documentation/i2c/dma-considerations.rst diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst index 0cee0fc545b4..80b14e718b52 100644 --- a/Documentation/i2c/fault-codes +++ b/Documentation/i2c/fault-codes.rst @@ -1,3 +1,7 @@ +===================== +I2C/SMBUS Fault Codes +===================== + This is a summary of the most important conventions for use of fault codes in the I2C/SMBus stack. @@ -125,4 +129,3 @@ ETIMEDOUT when a slave stretches clocks too far. I2C has no such timeouts, but it's normal for I2C adapters to impose some arbitrary limits (much longer than SMBus!) too. - diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst index 4aae8ed15873..377507c56162 100644 --- a/Documentation/i2c/functionality +++ b/Documentation/i2c/functionality.rst @@ -1,11 +1,15 @@ +======================= +I2C/SMBus Functionality +======================= + INTRODUCTION ------------ -Because not every I2C or SMBus adapter implements everything in the +Because not every I2C or SMBus adapter implements everything in the I2C specifications, a client can not trust that everything it needs is implemented when it is given the option to attach to an adapter: the client needs some way to check whether an adapter has the needed -functionality. +functionality. FUNCTIONALITY CONSTANTS @@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS For the most up-to-date list of functionality constants, please check <uapi/linux/i2c.h>! + =============================== ============================================== I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus adapters typically can not do these) I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions @@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command + =============================== ============================================== A few combinations of the above flags are also defined for your convenience: + ========================= ====================================== I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte and write_byte commands I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data @@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience: I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be emulated by a real I2C adapter (using the transparent emulation layer) + ========================= ====================================== In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as part of I2C_FUNC_PROTOCOL_MANGLING. @@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION ---------------------- When you write a new adapter driver, you will have to implement a -function callback `functionality'. Typical implementations are given +function callback ``functionality``. Typical implementations are given below. A typical SMBus-only adapter would list all the SMBus transactions it -supports. This example comes from the i2c-piix4 driver: +supports. This example comes from the i2c-piix4 driver:: static u32 piix4_func(struct i2c_adapter *adapter) { @@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver: } A typical full-I2C adapter would use the following (from the i2c-pxa -driver): +driver):: static u32 i2c_pxa_functionality(struct i2c_adapter *adap) { @@ -94,7 +102,7 @@ CLIENT CHECKING Before a client tries to attach to an adapter, or even do tests to check whether one of the devices it supports is present on an adapter, it should check whether the needed functionality is present. The typical way to do -this is (from the lm75 driver): +this is (from the lm75 driver):: static int lm75_detect(...) { @@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have to use the /dev interface. You will still have to check whether the functionality you need is supported, of course. This is done using the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is -below: +below:: int file; if (file = open("/dev/i2c-0", O_RDWR) < 0) { diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst index c87f416d53dd..9dca6ec7d266 100644 --- a/Documentation/i2c/gpio-fault-injection +++ b/Documentation/i2c/gpio-fault-injection.rst @@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost should be detected beforehand. Also note, that SCL going down is monitored using interrupts, so the interrupt latency might cause the first bits to be not corrupted. A good starting point for using this fault injector on an otherwise -idle bus is: +idle bus is:: -# echo 200 > lose_arbitration & -# i2cget -y <bus_to_test> 0x3f + # echo 200 > lose_arbitration & + # i2cget -y <bus_to_test> 0x3f Panic during transfer ===================== @@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The process is interruptible, though. Start of a transfer is detected by waiting for SCL going down by the master -under test. A good starting point for using this fault injector is: +under test. A good starting point for using this fault injector is:: -# echo 0 > inject_panic & -# i2cget -y <bus_to_test> <some_address> + # echo 0 > inject_panic & + # i2cget -y <bus_to_test> <some_address> Note that there doesn't need to be a device listening to the address you are using. Results may vary depending on that, though. diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst index ff6d6cee6c7e..2f8fcf671b2e 100644 --- a/Documentation/i2c/i2c-protocol +++ b/Documentation/i2c/i2c-protocol.rst @@ -1,8 +1,13 @@ +============ +I2C Protocol +============ + This document describes the i2c protocol. Or will, when it is finished :-) Key to symbols ============== +=============== ============================================================= S (1 bit) : Start bit P (1 bit) : Stop bit Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. @@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. Count (8 bits): A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. +[..]: Data sent by I2C device, as opposed to data sent by the + host adapter. +=============== ============================================================= Simple send transaction -====================== +======================= -This corresponds to i2c_master_send. +This corresponds to i2c_master_send:: S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P Simple receive transaction -=========================== +========================== -This corresponds to i2c_master_recv +This corresponds to i2c_master_recv:: S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Combined transactions -==================== +===================== This corresponds to i2c_transfer They are just like the above transactions, but instead of a stop bit P a start bit S is sent and the transaction continues. An example of -a byte read, followed by a byte write: +a byte read, followed by a byte write:: S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P @@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK: I2C_M_NOSTART: In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some point. For example, setting I2C_M_NOSTART on the second partial message - generates something like: + generates something like:: + S Addr Rd [A] [Data] NA Data [A] P + If you set the I2C_M_NOSTART variable for the first partial message, we do not generate Addr, but we do generate the startbit S. This will probably confuse all other clients on your bus, so don't try this. @@ -79,7 +88,8 @@ I2C_M_NOSTART: I2C_M_REV_DIR_ADDR: This toggles the Rd/Wr flag. That is, if you want to do a write, but need to emit an Rd instead of a Wr, or vice versa, you set this - flag. For example: + flag. For example:: + S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P I2C_M_STOP: diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst index a16924fbd289..a6fc6916d6bc 100644 --- a/Documentation/i2c/i2c-stub +++ b/Documentation/i2c/i2c-stub.rst @@ -1,6 +1,9 @@ -MODULE: i2c-stub +======== +i2c-stub +======== -DESCRIPTION: +Description +=========== This module is a very simple fake I2C/SMBus driver. It implements six types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) @@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always return the number of bytes selected with the largest write so far. The typical use-case is like this: + 1. load this module 2. use i2cset (from the i2c-tools project) to pre-load some data 3. load the target chip driver module @@ -36,7 +40,8 @@ The typical use-case is like this: There's a script named i2c-stub-from-dump in the i2c-tools package which can load register values automatically from a chip dump. -PARAMETERS: +Parameters +========== int chip_addr[10]: The SMBus addresses to emulate chips at. @@ -47,18 +52,15 @@ unsigned long functionality: value 0x1f0000 would only enable the quick, byte and byte data commands. -u8 bank_reg[10] -u8 bank_mask[10] -u8 bank_start[10] -u8 bank_end[10]: +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]: Optional bank settings. They tell which bits in which register select the active bank, as well as the range of banked registers. -CAVEATS: +Caveats +======= If your target driver polls some byte or word waiting for it to change, the stub could lock it up. Use i2cset to unlock it. If you spam it hard enough, printk can be lossy. This module really wants something like relayfs. - diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst index f74d78b53d4d..0c1ae95f6a97 100644 --- a/Documentation/i2c/i2c-topology +++ b/Documentation/i2c/i2c-topology.rst @@ -1,3 +1,4 @@ +============ I2C topology ============ @@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices. that has to be operated before the device can be accessed. Etc +=== These constructs are represented as i2c adapter trees by Linux, where each adapter has a parent adapter (except the root adapter) and zero or @@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be useful to know if a mux is mux-locked or if it is parent-locked. The following list was correct at the time of writing: -In drivers/i2c/muxes/ +In drivers/i2c/muxes/: + +====================== ============================================= i2c-arb-gpio-challenge Parent-locked i2c-mux-gpio Normally parent-locked, mux-locked iff all involved gpio pins are controlled by the @@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff all involved pinctrl devices are controlled by the same i2c root adapter that they mux. i2c-mux-reg Parent-locked +====================== ============================================= + +In drivers/iio/: -In drivers/iio/ +====================== ============================================= gyro/mpu3050 Mux-locked imu/inv_mpu6050/ Mux-locked +====================== ============================================= -In drivers/media/ +In drivers/media/: + +======================= ============================================= dvb-frontends/lgdt3306a Mux-locked dvb-frontends/m88ds3103 Parent-locked dvb-frontends/rtl2830 Parent-locked dvb-frontends/rtl2832 Mux-locked dvb-frontends/si2168 Mux-locked usb/cx231xx/ Parent-locked +======================= ============================================= Mux-locked muxes @@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different stages of the transaction. This has the benefit that the mux driver may be easier and cleaner to implement, but it has some caveats. +==== ===================================================================== ML1. If you build a topology with a mux-locked mux being the parent of a parent-locked mux, this might break the expectation from the parent-locked mux that the root adapter is locked during the @@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state, Otherwise garbage may appear on the bus as seen from devices behind the mux, when an unrelated i2c transfer is in flight during the non-i2c mux-changing operation. +==== ===================================================================== Mux-locked Example ------------------ + +:: + .----------. .--------. .--------. | mux- |-----| dev D1 | | root |--+--| locked | '--------' @@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g. __i2c_transfer), or a deadlock will follow. There are a couple of caveats. +==== ==================================================================== PL1. If you build a topology with a parent-locked mux being the child of another mux, this might break a possible assumption from the child mux that the root adapter is unused between its select op @@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio, caused by these subsystems are unlocked. This can be convoluted to accomplish, maybe even impossible if an acceptably clean solution is sought. +==== ==================================================================== Parent-locked Example --------------------- +:: + .----------. .--------. .--------. | parent- |-----| dev D1 | | root |--+--| locked | '--------' @@ -177,20 +197,20 @@ Parent-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. - 2. M1 locks muxes on its parent (the root adapter in this case). - 3. M1 locks its parent adapter. - 4. M1 calls ->select to ready the mux. - 5. If M1 does any i2c-transfers (on this root adapter) as part of - its select, those transfers must be unlocked i2c-transfers so - that they do not deadlock the root adapter. - 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an - unlocked i2c-transfer, so that it does not deadlock the parent - adapter. - 7. M1 calls ->deselect, if it has one. - 8. Same rules as in step 5, but for ->deselect. - 9. M1 unlocks its parent adapter. -10. M1 unlocks muxes on its parent. + 1. Someone issues an i2c-transfer to D1. + 2. M1 locks muxes on its parent (the root adapter in this case). + 3. M1 locks its parent adapter. + 4. M1 calls ->select to ready the mux. + 5. If M1 does any i2c-transfers (on this root adapter) as part of + its select, those transfers must be unlocked i2c-transfers so + that they do not deadlock the root adapter. + 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an + unlocked i2c-transfer, so that it does not deadlock the parent + adapter. + 7. M1 calls ->deselect, if it has one. + 8. Same rules as in step 5, but for ->deselect. + 9. M1 unlocks its parent adapter. + 10. M1 unlocks muxes on its parent. This means that accesses to both D2 and D3 are locked out for the full @@ -203,7 +223,7 @@ Complex Examples Parent-locked mux as parent of parent-locked mux ------------------------------------------------ -This is a useful topology, but it can be bad. +This is a useful topology, but it can be bad:: .----------. .----------. .--------. .--------. | parent- |-----| parent- |-----| dev D1 | @@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely. Mux-locked mux as parent of mux-locked mux ------------------------------------------ -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | mux- |-----| mux- |-----| dev D1 | @@ -248,7 +268,7 @@ are still possibly interleaved. Mux-locked mux as parent of parent-locked mux --------------------------------------------- -This is probably a bad topology. +This is probably a bad topology:: .----------. .----------. .--------. .--------. | mux- |-----| parent- |-----| dev D1 | @@ -282,7 +302,7 @@ auto-closing, the topology is fine. Parent-locked mux as parent of mux-locked mux --------------------------------------------- -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | parent- |-----| mux- |-----| dev D1 | @@ -306,7 +326,7 @@ adapter is locked directly. Two mux-locked sibling muxes ---------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time. Two parent-locked sibling muxes ------------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -354,7 +374,7 @@ out. Mux-locked and parent-locked sibling muxes ------------------------------------------ -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst new file mode 100644 index 000000000000..cd8d020f7ac5 --- /dev/null +++ b/Documentation/i2c/index.rst @@ -0,0 +1,37 @@ +. SPDX-License-Identifier: GPL-2.0 + +=================== +I2C/SMBus Subsystem +=================== + +.. toctree:: + :maxdepth: 1 + + dev-interface + dma-considerations + fault-codes + functionality + gpio-fault-injection + i2c-protocol + i2c-stub + i2c-topology + instantiating-devices + old-module-parameters + slave-eeprom-backend + slave-interface + smbus-protocol + summary + ten-bit-addresses + upgrading-clients + writing-clients + + muxes/i2c-mux-gpio + + busses/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst index 345e9ea8281a..1238f1fa3382 100644 --- a/Documentation/i2c/instantiating-devices +++ b/Documentation/i2c/instantiating-devices.rst @@ -1,3 +1,4 @@ +============================== How to instantiate I2C devices ============================== @@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C devices which live on this bus. This is done with an array of struct i2c_board_info which is registered by calling i2c_register_board_info(). -Example (from omap2 h4): +Example (from omap2 h4):: -static struct i2c_board_info h4_i2c_board_info[] __initdata = { + static struct i2c_board_info h4_i2c_board_info[] __initdata = { { I2C_BOARD_INFO("isp1301_omap", 0x2d), .irq = OMAP_GPIO_IRQ(125), @@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = { I2C_BOARD_INFO("24c01", 0x57), .platform_data = &m24c01, }, -}; + }; -static void __init omap_h4_init(void) -{ + static void __init omap_h4_init(void) + { (...) i2c_register_board_info(1, h4_i2c_board_info, ARRAY_SIZE(h4_i2c_board_info)); (...) -} + } The above code declares 3 devices on I2C bus 1, including their respective addresses and custom data needed by their drivers. When the I2C bus in @@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree This method has the same implications as method 1a. The declaration of I2C devices is here done via devicetree as subnodes of the master controller. -Example: +Example:: i2c1: i2c@400a0000 { /* ... master properties skipped ... */ @@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead, you can instantiate your I2C devices explicitly. This is done by filling a struct i2c_board_info and calling i2c_new_device(). -Example (from the sfe4001 network driver): +Example (from the sfe4001 network driver):: -static struct i2c_board_info sfe4001_hwmon_info = { + static struct i2c_board_info sfe4001_hwmon_info = { I2C_BOARD_INFO("max6647", 0x4e), -}; + }; -int sfe4001_init(struct efx_nic *efx) -{ + int sfe4001_init(struct efx_nic *efx) + { (...) efx->board_info.hwmon_client = i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); (...) -} + } The above code instantiates 1 I2C device on the I2C bus which is on the network adapter in question. @@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer changing its design without notice). In this case, you can call i2c_new_probed_device() instead of i2c_new_device(). -Example (from the nxp OHCI driver): +Example (from the nxp OHCI driver):: -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; -static int usb_hcd_nxp_probe(struct platform_device *pdev) -{ + static int usb_hcd_nxp_probe(struct platform_device *pdev) + { (...) struct i2c_adapter *i2c_adap; struct i2c_board_info i2c_info; @@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev) normal_i2c, NULL); i2c_put_adapter(i2c_adap); (...) -} + } The above code instantiates up to 1 I2C device on the I2C bus which is on the OHCI adapter in question. It first tries at address 0x2c, if nothing @@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their drivers are loaded, and if any is found, an I2C device will be instantiated automatically. In order to prevent any misbehavior of this mechanism, the following restrictions apply: + * The I2C device driver must implement the detect() method, which identifies a supported device by reading from arbitrary registers. * Only buses which are likely to have a supported device and agree to be @@ -189,6 +191,7 @@ first. Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 kernels will find out that this method 3 is essentially similar to what was done there. Two significant differences are: + * Probing is only one way to instantiate I2C devices now, while it was the only way back then. Where possible, methods 1 and 2 should be preferred. Method 3 should only be used when there is no other way, as it can have @@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C segment, the address is sufficient to uniquely identify the device to be deleted. -Example: -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device +Example:: + + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device While this interface should only be used when in-kernel device declaration can't be done, there is a variety of cases where it can be helpful: + * The I2C driver usually detects devices (method 3 above) but the bus segment your device lives on doesn't have the proper class bit set and thus detection doesn't trigger. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst index 893ecdfe6e43..7d27444035c3 100644 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-mux-gpio +========================== Author: Peter Korsgaard <peter.korsgaard@barco.com> @@ -8,7 +10,7 @@ Description i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments from a master I2C bus and a hardware MUX controlled through GPIO pins. -E.G.: +E.G.:: ---------- ---------- Bus segment 1 - - - - - | | SCL/SDA | |-------------- | | @@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used to control it. See include/linux/platform_data/i2c-mux-gpio.h for details. E.G. something like this for a MUX providing 4 bus segments -controlled through 3 GPIO pins: +controlled through 3 GPIO pins:: -#include <linux/platform_data/i2c-mux-gpio.h> -#include <linux/platform_device.h> + #include <linux/platform_data/i2c-mux-gpio.h> + #include <linux/platform_device.h> -static const unsigned myboard_gpiomux_gpios[] = { + static const unsigned myboard_gpiomux_gpios[] = { AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 -}; + }; -static const unsigned myboard_gpiomux_values[] = { + static const unsigned myboard_gpiomux_values[] = { 0, 1, 2, 3 -}; + }; -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .parent = 1, .base_nr = 2, /* optional */ .values = myboard_gpiomux_values, @@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .gpios = myboard_gpiomux_gpios, .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), .idle = 4, /* optional */ -}; + }; -static struct platform_device myboard_i2cmux = { + static struct platform_device myboard_i2cmux = { .name = "i2c-mux-gpio", .id = 0, .dev = { .platform_data = &myboard_i2cmux_data, }, -}; + }; If you don't know the absolute GPIO pin numbers at registration time, you can instead provide a chip name (.chip_name) and relative GPIO pin diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst index 8e2b629d533c..a1939512ad66 100644 --- a/Documentation/i2c/old-module-parameters +++ b/Documentation/i2c/old-module-parameters.rst @@ -1,3 +1,4 @@ +================================================= I2C device driver binding control from user-space ================================================= @@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface. Attaching a driver to an I2C device ----------------------------------- -Old method (module parameters): -# modprobe <driver> probe=1,0x2d -# modprobe <driver> force=1,0x2d -# modprobe <driver> force_<device>=1,0x2d +Old method (module parameters):: + + # modprobe <driver> probe=1,0x2d + # modprobe <driver> force=1,0x2d + # modprobe <driver> force_<device>=1,0x2d + +New method (sysfs interface):: -New method (sysfs interface): -# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device + # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device Preventing a driver from attaching to an I2C device --------------------------------------------------- -Old method (module parameters): -# modprobe <driver> ignore=1,0x2f +Old method (module parameters):: + + # modprobe <driver> ignore=1,0x2f + +New method (sysfs interface):: -New method (sysfs interface): -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device -# modprobe <driver> + # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe <driver> Of course, it is important to instantiate the "dummy" device before loading the driver. The dummy device will be handled by i2c-core itself, preventing diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst index 04f8d8a9b817..0b8cd83698e0 100644 --- a/Documentation/i2c/slave-eeprom-backend +++ b/Documentation/i2c/slave-eeprom-backend.rst @@ -1,3 +1,4 @@ +============================== Linux I2C slave eeprom backend ============================== @@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 This is a proof-of-concept backend which acts like an EEPROM on the connected I2C bus. The memory contents can be modified from userspace via this file -located in sysfs: +located in sysfs:: /sys/bus/i2c/devices/<device-directory>/slave-eeprom As of 2015, Linux doesn't support poll on binary sysfs files, so there is no notification when another master changed the content. - diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst index 7e2a228f21bc..c769bd6a15bf 100644 --- a/Documentation/i2c/slave-interface +++ b/Documentation/i2c/slave-interface.rst @@ -1,3 +1,4 @@ +===================================== Linux I2C slave interface description ===================================== @@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as needed. The backend driver and the I2C bus driver communicate via events. Here is a small graph visualizing the data flow and the means by which data is transported. The dotted line marks only one example. The backend could also -use a character device, be in-kernel only, or something completely different: +use a character device, be in-kernel only, or something completely different:: e.g. sysfs I2C slave events I/O registers @@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference is that i2c slave backends have their own address space. So, you have to add 0x1000 to the address you would originally request. An example for instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 -on bus 1: +on bus 1:: # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device @@ -54,7 +55,7 @@ drivers and writing backends will be given. I2C slave events ---------------- -The bus driver sends an event to the backend using the following function: +The bus driver sends an event to the backend using the following function:: ret = i2c_slave_event(client, event, &val) @@ -69,8 +70,9 @@ Event types: * I2C_SLAVE_WRITE_REQUESTED (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 Another I2C master wants to write data to us. This event should be sent once our own address and the write bit was detected. The data did not arrive yet, so @@ -79,8 +81,9 @@ to be done, though. * I2C_SLAVE_READ_REQUESTED (mandatory) -'val': backend returns first byte to be sent -'ret': always 0 + 'val': backend returns first byte to be sent + + 'ret': always 0 Another I2C master wants to read data from us. This event should be sent once our own address and the read bit was detected. After returning, the bus driver @@ -88,8 +91,9 @@ should transmit the first byte. * I2C_SLAVE_WRITE_RECEIVED (mandatory) -'val': bus driver delivers received byte -'ret': 0 if the byte should be acked, some errno if the byte should be nacked + 'val': bus driver delivers received byte + + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte @@ -97,8 +101,9 @@ should be nacked. * I2C_SLAVE_READ_PROCESSED (mandatory) -'val': backend returns next byte to be sent -'ret': always 0 + 'val': backend returns next byte to be sent + + 'ret': always 0 The bus driver requests the next byte to be sent to another I2C master in 'val'. Important: This does not mean that the previous byte has been acked, it @@ -111,8 +116,9 @@ your backend, though. * I2C_SLAVE_STOP (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 A stop condition was received. This can happen anytime and the backend should reset its state machine for I2C transfers to be able to receive new requests. @@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers: * A master can send STOP at any time. For partially transferred buffers, this means additional code to handle this exception. Such code tends to be error-prone. - diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst index 092d474f5843..e30eb1d274c6 100644 --- a/Documentation/i2c/smbus-protocol +++ b/Documentation/i2c/smbus-protocol.rst @@ -1,3 +1,4 @@ +====================== SMBus Protocol Summary ====================== @@ -27,17 +28,18 @@ Each transaction type corresponds to a functionality flag. Before calling a transaction function, a device driver should always check (just once) for the corresponding functionality flag to ensure that the underlying I2C adapter supports the transaction in question. See -<file:Documentation/i2c/functionality> for the details. +<file:Documentation/i2c/functionality.rst> for the details. Key to symbols ============== +=============== ============================================================= S (1 bit) : Start bit P (1 bit) : Stop bit Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to +A, NA (1 bit) : Accept and reverse accept bit. +Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to get a 10 bit I2C address. Comm (8 bits): Command byte, a data byte which often selects a register on the device. @@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. Count (8 bits): A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. +[..]: Data sent by I2C device, as opposed to data sent by the host + adapter. +=============== ============================================================= SMBus Quick Command =================== -This sends a single bit to the device, at the place of the Rd/Wr bit. +This sends a single bit to the device, at the place of the Rd/Wr bit:: -A Addr Rd/Wr [A] P + A Addr Rd/Wr [A] P Functionality flag: I2C_FUNC_SMBUS_QUICK @@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte() This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for others, it is a shorthand if you want to read the same register as in -the previous SMBus command. +the previous SMBus command:: -S Addr Rd [A] [Data] NA P + S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE @@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte() This operation is the reverse of Receive Byte: it sends a single byte to a device. See Receive Byte for more information. -S Addr Wr [A] Data [A] P +:: + + S Addr Wr [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE @@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data() ============================================ This reads a single byte from a device, from a designated register. -The register is specified through the Comm byte. +The register is specified through the Comm byte:: -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA @@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data() This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm -byte. But this time, the data is a complete word (16 bits). +byte. But this time, the data is a complete word (16 bits):: -S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA @@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of the Read Byte operation. -S Addr Wr [A] Comm [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA @@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data() This is the opposite of the Read Word operation. 16 bits of data is written to a device, to the designated register that is -specified through the Comm byte. +specified through the Comm byte.:: -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA @@ -141,10 +149,10 @@ SMBus Process Call: =================== This command selects a device register (through the Comm byte), sends -16 bits of data to it, and reads 16 bits of data in return. +16 bits of data to it, and reads 16 bits of data in return:: -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] - S Addr Rd [A] [DataLow] A [DataHigh] NA P + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] + S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_PROC_CALL @@ -152,12 +160,14 @@ Functionality flag: I2C_FUNC_SMBUS_PROC_CALL SMBus Block Read: i2c_smbus_read_block_data() ============================================== -This command reads a block of up to 32 bytes from a device, from a +This command reads a block of up to 32 bytes from a device, from a designated register that is specified through the Comm byte. The amount of data is specified by the device in the Count byte. -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P +:: + + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA @@ -165,11 +175,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA SMBus Block Write: i2c_smbus_write_block_data() ================================================ -The opposite of the Block Read command, this writes up to 32 bytes to +The opposite of the Block Read command, this writes up to 32 bytes to a device, to a designated register that is specified through the Comm byte. The amount of data is specified in the Count byte. -S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA @@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in Revision 2.0 of the specification. This command selects a device register (through the Comm byte), sends -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return. +1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return:: -S Addr Wr [A] Comm [A] Count [A] Data [A] ... - S Addr Rd [A] [Count] A [Data] ... A P + S Addr Wr [A] Comm [A] Count [A] Data [A] ... + S Addr Rd [A] [Count] A [Data] ... A P Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL @@ -197,9 +209,12 @@ SMBus host acting as a slave. It is the same form as Write Word, with the command code replaced by the alerting device's address. -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] +:: + + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] This is implemented in the following way in the Linux kernel: + * I2C bus drivers which support SMBus Host Notify should report I2C_FUNC_SMBUS_HOST_NOTIFY. * I2C bus drivers trigger SMBus Host Notify by a call to @@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master to know which slave triggered the interrupt. This is implemented the following way in the Linux kernel: + * I2C bus drivers which support SMBus alert should call i2c_setup_smbus_alert() to setup SMBus alert support. * I2C drivers for devices which can trigger SMBus alerts should implement @@ -261,11 +277,11 @@ but the SMBus layer places a limit of 32 bytes. I2C Block Read: i2c_smbus_read_i2c_block_data() ================================================ -This command reads a block of bytes from a device, from a -designated register that is specified through the Comm byte. +This command reads a block of bytes from a device, from a +designated register that is specified through the Comm byte:: -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK @@ -273,11 +289,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK I2C Block Write: i2c_smbus_write_i2c_block_data() ================================================== -The opposite of the Block Read command, this writes bytes to +The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the Comm byte. Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data. -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst index 809541ab352f..3a24eac17375 100644 --- a/Documentation/i2c/summary +++ b/Documentation/i2c/summary.rst @@ -1,7 +1,8 @@ +============= I2C and SMBus ============= -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a +I2C (pronounce: I squared C) is a protocol developed by Philips. It is a slow two-wire protocol (variable speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides an inexpensive bus for connecting many types of devices with infrequent or low bandwidth communications needs. @@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages. Terminology =========== -When we talk about I2C, we use the following terms: +When we talk about I2C, we use the following terms:: + Bus -> Algorithm Adapter Device -> Driver diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst index 7b2d11e53a49..5c765aff16d5 100644 --- a/Documentation/i2c/ten-bit-addresses +++ b/Documentation/i2c/ten-bit-addresses.rst @@ -1,3 +1,7 @@ +===================== +I2C Ten-bit Addresses +===================== + The I2C protocol knows about two kinds of device addresses: normal 7 bit addresses, and an extended set of 10 bit addresses. The sets of addresses do not intersect: the 7 bit address 0x10 is not the same as the 10 bit @@ -12,6 +16,7 @@ See the I2C specification for the details. The current 10 bit address support is minimal. It should work, however you can expect some problems along the way: + * Not all bus drivers support 10-bit addresses. Some don't because the hardware doesn't support them (SMBus doesn't require 10-bit address support for example), some don't because nobody bothered adding the diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst index 96392cc5b5c7..27d29032c138 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients.rst @@ -1,3 +1,4 @@ +================================================= Upgrading I2C Drivers to the new 2.6 Driver Model ================================================= @@ -13,21 +14,22 @@ the old to the new new binding methods. Example old-style driver ------------------------ +:: -struct example_state { + struct example_state { struct i2c_client client; .... -}; + }; -static struct i2c_driver example_driver; + static struct i2c_driver example_driver; -static unsigned short ignore[] = { I2C_CLIENT_END }; -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + static unsigned short ignore[] = { I2C_CLIENT_END }; + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -I2C_CLIENT_INSMOD; + I2C_CLIENT_INSMOD; -static int example_attach(struct i2c_adapter *adap, int addr, int kind) -{ + static int example_attach(struct i2c_adapter *adap, int addr, int kind) + { struct example_state *state; struct device *dev = &adap->dev; /* to use for dev_ reports */ int ret; @@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind) dev_info(dev, "example client created\n"); return 0; -} + } -static int example_detach(struct i2c_client *client) -{ + static int example_detach(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); i2c_detach_client(client); kfree(state); return 0; -} + } -static int example_attach_adapter(struct i2c_adapter *adap) -{ + static int example_attach_adapter(struct i2c_adapter *adap) + { return i2c_probe(adap, &addr_data, example_attach); -} + } -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, }, .attach_adapter = example_attach_adapter, .detach_client = example_detach, -}; + }; Updating the client @@ -93,38 +95,38 @@ The new style binding model will check against a list of supported devices and their associated address supplied by the code registering the busses. This means that the driver .attach_adapter and .detach_client methods can be removed, along with the addr_data, -as follows: +as follows:: -- static struct i2c_driver example_driver; + - static struct i2c_driver example_driver; -- static unsigned short ignore[] = { I2C_CLIENT_END }; -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + - static unsigned short ignore[] = { I2C_CLIENT_END }; + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -- I2C_CLIENT_INSMOD; + - I2C_CLIENT_INSMOD; -- static int example_attach_adapter(struct i2c_adapter *adap) -- { -- return i2c_probe(adap, &addr_data, example_attach); -- } + - static int example_attach_adapter(struct i2c_adapter *adap) + - { + - return i2c_probe(adap, &addr_data, example_attach); + - } - static struct i2c_driver example_driver = { -- .attach_adapter = example_attach_adapter, -- .detach_client = example_detach, - } + static struct i2c_driver example_driver = { + - .attach_adapter = example_attach_adapter, + - .detach_client = example_detach, + } -Add the probe and remove methods to the i2c_driver, as so: +Add the probe and remove methods to the i2c_driver, as so:: - static struct i2c_driver example_driver = { -+ .probe = example_probe, -+ .remove = example_remove, - } + static struct i2c_driver example_driver = { + + .probe = example_probe, + + .remove = example_remove, + } Change the example_attach method to accept the new parameters -which include the i2c_client that it will be working with: +which include the i2c_client that it will be working with:: -- static int example_attach(struct i2c_adapter *adap, int addr, int kind) -+ static int example_probe(struct i2c_client *client, -+ const struct i2c_device_id *id) + - static int example_attach(struct i2c_adapter *adap, int addr, int kind) + + static int example_probe(struct i2c_client *client, + + const struct i2c_device_id *id) Change the name of example_attach to example_probe to align it with the i2c_driver entry names. The rest of the probe routine will now need to be @@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use. The necessary client fields have already been setup before the probe function is called, so the following client setup -can be removed: +can be removed:: -- example->client.addr = addr; -- example->client.flags = 0; -- example->client.adapter = adap; -- -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); + - example->client.addr = addr; + - example->client.flags = 0; + - example->client.adapter = adap; + - + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); -The i2c_set_clientdata is now: +The i2c_set_clientdata is now:: -- i2c_set_clientdata(&state->client, state); -+ i2c_set_clientdata(client, state); + - i2c_set_clientdata(&state->client, state); + + i2c_set_clientdata(client, state); The call to i2c_attach_client is no longer needed, if the probe routine exits successfully, then the driver will be automatically -attached by the core. Change the probe routine as so: +attached by the core. Change the probe routine as so:: -- ret = i2c_attach_client(&state->i2c_client); -- if (ret < 0) { -- dev_err(dev, "failed to attach client\n"); -- kfree(state); -- return ret; -- } + - ret = i2c_attach_client(&state->i2c_client); + - if (ret < 0) { + - dev_err(dev, "failed to attach client\n"); + - kfree(state); + - return ret; + - } Remove the storage of 'struct i2c_client' from the 'struct example_state' as we are provided with the i2c_client in our example_probe. Instead we store a pointer to it for when it is needed. -struct example_state { -- struct i2c_client client; -+ struct i2c_client *client; +:: + + struct example_state { + - struct i2c_client client; + + struct i2c_client *client; -the new i2c client as so: +the new i2c client as so:: -- struct device *dev = &adap->dev; /* to use for dev_ reports */ -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ + - struct device *dev = &adap->dev; /* to use for dev_ reports */ + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ And remove the change after our client is attached, as the driver no -longer needs to register a new client structure with the core: +longer needs to register a new client structure with the core:: -- dev = &state->i2c_client.dev; + - dev = &state->i2c_client.dev; In the probe routine, ensure that the new state has the client stored -in it: +in it:: -static int example_probe(struct i2c_client *i2c_client, + static int example_probe(struct i2c_client *i2c_client, const struct i2c_device_id *id) -{ + { struct example_state *state; - struct device *dev = &i2c_client->dev; + struct device *dev = &i2c_client->dev; int ret; state = kzalloc(sizeof(struct example_state), GFP_KERNEL); @@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client, return -ENOMEM; } -+ state->client = i2c_client; + + state->client = i2c_client; Update the detach method, by changing the name to _remove and to delete the i2c_detach_client call. It is possible that you can also remove the ret variable as it is not needed for any of the core functions. -- static int example_detach(struct i2c_client *client) -+ static int example_remove(struct i2c_client *client) -{ +:: + + - static int example_detach(struct i2c_client *client) + + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); -- i2c_detach_client(client); + - i2c_detach_client(client); And finally ensure that we have the correct ID table for the i2c-core -and other utilities: +and other utilities:: -+ struct i2c_device_id example_idtable[] = { -+ { "example", 0 }, -+ { } -+}; -+ -+MODULE_DEVICE_TABLE(i2c, example_idtable); + + struct i2c_device_id example_idtable[] = { + + { "example", 0 }, + + { } + +}; + + + +MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", }, -+ .id_table = example_ids, + + .id_table = example_ids, -Our driver should now look like this: +Our driver should now look like this:: -struct example_state { + struct example_state { struct i2c_client *client; .... -}; + }; -static int example_probe(struct i2c_client *client, - const struct i2c_device_id *id) -{ + static int example_probe(struct i2c_client *client, + const struct i2c_device_id *id) + { struct example_state *state; struct device *dev = &client->dev; @@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client, dev_info(dev, "example client created\n"); return 0; -} + } -static int example_remove(struct i2c_client *client) -{ + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); kfree(state); return 0; -} + } -static struct i2c_device_id example_idtable[] = { + static struct i2c_device_id example_idtable[] = { { "example", 0 }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, example_idtable); + MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, @@ -276,4 +282,4 @@ static struct i2c_driver example_driver = { .id_table = example_idtable, .probe = example_probe, .remove = example_remove, -}; + }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst index a755b141fa4a..dddf0a14ab7c 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients.rst @@ -1,3 +1,7 @@ +=================== +Writing I2C Clients +=================== + This is a small guide for those who want to write kernel drivers for I2C or SMBus devices, using Linux as the protocol host/master (not slave). @@ -12,7 +16,7 @@ General remarks Try to keep the kernel namespace as clean as possible. The best way to do this is to use a unique prefix for all global symbols. This is especially important for exported symbols, but it is a good idea to do -it for non-exported symbols too. We will use the prefix `foo_' in this +it for non-exported symbols too. We will use the prefix ``foo_`` in this tutorial. @@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you provide. A client structure holds device-specific information like the driver model device node, and its I2C address. -static struct i2c_device_id foo_idtable[] = { +:: + + static struct i2c_device_id foo_idtable[] = { { "foo", my_id_for_foo }, { "bar", my_id_for_bar }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, foo_idtable); + MODULE_DEVICE_TABLE(i2c, foo_idtable); -static struct i2c_driver foo_driver = { + static struct i2c_driver foo_driver = { .driver = { .name = "foo", .pm = &foo_pm_ops, /* optional */ @@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = { .shutdown = foo_shutdown, /* optional */ .command = foo_command, /* optional, deprecated */ -} + } The name field is the driver name, and must not contain spaces. It should match the module name (if the driver can be compiled as a module), @@ -64,16 +70,18 @@ below. Extra client data ================= -Each client structure has a special `data' field that can point to any +Each client structure has a special ``data`` field that can point to any structure at all. You should use this to keep device-specific data. +:: + /* store the value */ void i2c_set_clientdata(struct i2c_client *client, void *data); /* retrieve the value */ void *i2c_get_clientdata(const struct i2c_client *client); -Note that starting with kernel 2.6.34, you don't have to set the `data' field +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field to NULL in remove() or if probe() failed anymore. The i2c-core does this automatically on these occasions. Those are also the only times the core will touch this field. @@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily be encapsulated. The below functions are simple examples, and should not be copied -literally. +literally:: -int foo_read_value(struct i2c_client *client, u8 reg) -{ + int foo_read_value(struct i2c_client *client, u8 reg) + { if (reg < 0x10) /* byte-sized register */ return i2c_smbus_read_byte_data(client, reg); else /* word-sized register */ return i2c_smbus_read_word_data(client, reg); -} + } -int foo_write_value(struct i2c_client *client, u8 reg, u16 value) -{ + int foo_write_value(struct i2c_client *client, u8 reg, u16 value) + { if (reg == 0x10) /* Impossible to write - driver error! */ return -EINVAL; else if (reg < 0x10) /* byte-sized register */ return i2c_smbus_write_byte_data(client, reg, value); else /* word-sized register */ return i2c_smbus_write_word_data(client, reg, value); -} + } Probing and attaching @@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other kind of driver in Linux: they provide a probe() method to bind to those devices, and a remove() method to unbind. +:: + static int foo_probe(struct i2c_client *client, const struct i2c_device_id *id); static int foo_remove(struct i2c_client *client); @@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted, you have to do some initializing. Fortunately, just registering the driver module is usually enough. -static int __init foo_init(void) -{ +:: + + static int __init foo_init(void) + { return i2c_add_driver(&foo_driver); -} -module_init(foo_init); + } + module_init(foo_init); -static void __exit foo_cleanup(void) -{ + static void __exit foo_cleanup(void) + { i2c_del_driver(&foo_driver); -} -module_exit(foo_cleanup); + } + module_exit(foo_cleanup); -The module_i2c_driver() macro can be used to reduce above code. + The module_i2c_driver() macro can be used to reduce above code. -module_i2c_driver(foo_driver); + module_i2c_driver(foo_driver); -Note that some functions are marked by `__init'. These functions can +Note that some functions are marked by ``__init``. These functions can be removed after kernel booting (or module loading) is completed. -Likewise, functions marked by `__exit' are dropped by the compiler when +Likewise, functions marked by ``__exit`` are dropped by the compiler when the code is built into the kernel, as they would never be called. Driver Information ================== -/* Substitute your own name and email address */ -MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); +:: -/* a few non-GPL license types are also allowed */ -MODULE_LICENSE("GPL"); + /* Substitute your own name and email address */ + MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); + + /* a few non-GPL license types are also allowed */ + MODULE_LICENSE("GPL"); Power Management @@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C! Plain I2C communication ----------------------- +:: + int i2c_master_send(struct i2c_client *client, const char *buf, int count); int i2c_master_recv(struct i2c_client *client, char *buf, int count); @@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be less than 64k since msg.len is u16.) Returned is the actual number of bytes read/written. +:: + int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); @@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains for each message the client address, the number of bytes of the message and the message data itself. -You can read the file `i2c-protocol' for more information about the +You can read the file ``i2c-protocol`` for more information about the actual I2C protocol. SMBus communication ------------------- +:: + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data); @@ -357,6 +377,8 @@ SMBus communication This is the generic SMBus function. All functions below are implemented in terms of it. Never use this function directly! +:: + s32 i2c_smbus_read_byte(struct i2c_client *client); s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); @@ -376,7 +398,7 @@ in terms of it. Never use this function directly! const u8 *values); These ones were removed from i2c-core because they had no users, but could -be added back later if needed: +be added back later if needed:: s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); s32 i2c_smbus_process_call(struct i2c_client *client, @@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read value, except for block transactions, which return the number of values read. The block buffers need not be longer than 32 bytes. -You can read the file `smbus-protocol' for more information about the +You can read the file ``smbus-protocol`` for more information about the actual SMBus protocol. @@ -397,7 +419,7 @@ General purpose routines ======================== Below all general purpose routines are listed, that were not mentioned -before. +before:: /* Return the adapter number for a specific adapter */ int i2c_adapter_id(struct i2c_adapter *adap); diff --git a/Documentation/index.rst b/Documentation/index.rst index 2df5a3da563c..b5fd87e7dbee 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -104,7 +104,9 @@ needed). fb/index fpga/index hid/index + i2c/index iio/index + isdn/index infiniband/index leds/index media/index @@ -114,8 +116,10 @@ needed). power/index target/index timers/index + spi/index + w1/index watchdog/index - virtual/index + virt/index input/index hwmon/index gpu/index @@ -146,6 +150,10 @@ implementation. ia64/index m68k/index powerpc/index + mips/index + nios2/nios2 + openrisc/index + parisc/index riscv/index s390/index sh/index diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 6be70342e709..307fe22d9668 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -23,7 +23,7 @@ devices capable of tracking identifiable contacts (type B), the protocol describes how to send updates for individual contacts via event slots. .. note:: - MT potocol type A is obsolete, all kernel drivers have been + MT protocol type A is obsolete, all kernel drivers have been converted to use type B. Protocol Usage diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst index 9e075484ef1e..de3961e67553 100644 --- a/Documentation/isdn/README.avmb1 +++ b/Documentation/isdn/avmb1.rst @@ -1,4 +1,6 @@ -Driver for active AVM Controller. +================================ +Driver for active AVM Controller +================================ The driver provides a kernel capi2.0 Interface (kernelcapi) and on top of this a User-Level-CAPI2.0-interface (capi) @@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils. t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware Currently supported cards: - B1 ISA (all versions) - B1 PCI - T1/T1B (HEMA card) - M1 - M2 - B1 PCMCIA + + - B1 ISA (all versions) + - B1 PCI + - T1/T1B (HEMA card) + - M1 + - M2 + - B1 PCMCIA Installing ---------- You need at least /dev/capi20 to load the firmware. -mknod /dev/capi20 c 68 0 -mknod /dev/capi20.00 c 68 1 -mknod /dev/capi20.01 c 68 2 -. -. -. -mknod /dev/capi20.19 c 68 20 +:: + + mknod /dev/capi20 c 68 0 + mknod /dev/capi20.00 c 68 1 + mknod /dev/capi20.01 c 68 2 + . + . + . + mknod /dev/capi20.19 c 68 20 Running ------- @@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware. AVM GmbH provides several t4-files for the different D-channel protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn. -if you configure as modules load the modules this way: +if you configure as modules load the modules this way:: + + insmod /lib/modules/current/misc/capiutil.o + insmod /lib/modules/current/misc/b1.o + insmod /lib/modules/current/misc/kernelcapi.o + insmod /lib/modules/current/misc/capidrv.o + insmod /lib/modules/current/misc/capi.o -insmod /lib/modules/current/misc/capiutil.o -insmod /lib/modules/current/misc/b1.o -insmod /lib/modules/current/misc/kernelcapi.o -insmod /lib/modules/current/misc/capidrv.o -insmod /lib/modules/current/misc/capi.o +if you have an B1-PCI card load the module b1pci.o:: -if you have an B1-PCI card load the module b1pci.o -insmod /lib/modules/current/misc/b1pci.o -and load the firmware with -avmcapictrl load /lib/isdn/b1.t4 1 + insmod /lib/modules/current/misc/b1pci.o + +and load the firmware with:: + + avmcapictrl load /lib/isdn/b1.t4 1 if you have an B1-ISA card load the module b1isa.o -and add the card by calling -avmcapictrl add 0x150 15 -and load the firmware by calling -avmcapictrl load /lib/isdn/b1.t4 1 +and add the card by calling:: + + avmcapictrl add 0x150 15 + +and load the firmware by calling:: + + avmcapictrl load /lib/isdn/b1.t4 1 if you have an T1-ISA card load the module t1isa.o -and add the card by calling -avmcapictrl add 0x450 15 T1 0 -and load the firmware by calling -avmcapictrl load /lib/isdn/t1.t4 1 +and add the card by calling:: + + avmcapictrl add 0x450 15 T1 0 + +and load the firmware by calling:: + + avmcapictrl load /lib/isdn/t1.t4 1 if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o before you insert the card. Leased Lines with B1 -------------------- + Init card and load firmware. + For an D64S use "FV: 1" as phone number + For an D64S2 use "FV: 1" and "FV: 2" for multilink or "FV: 1,2" to use CAPI channel bundling. /proc-Interface ----------------- -/proc/capi: +/proc/capi:: + dr-xr-xr-x 2 root root 0 Jul 1 14:03 . dr-xr-xr-x 82 root root 0 Jun 30 19:08 .. -r--r--r-- 1 root root 0 Jul 1 14:03 applications @@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling. /proc/capi/applications: applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen - level3cnt: capi_register parameter - datablkcnt: capi_register parameter - ncci-cnt: current number of nccis (connections) - recvqueuelen: number of messages on receive queue - for example: -1 -2 16 2048 1 0 -2 2 7 2048 1 0 + level3cnt: + capi_register parameter + datablkcnt: + capi_register parameter + ncci-cnt: + current number of nccis (connections) + recvqueuelen: + number of messages on receive queue + + for example:: + + 1 -2 16 2048 1 0 + 2 2 7 2048 1 0 /proc/capi/applstats: applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg - recvctlmsg: capi messages received without DATA_B3_IND - recvdatamsg: capi DATA_B3_IND received - sentctlmsg: capi messages sent without DATA_B3_REQ - sentdatamsg: capi DATA_B3_REQ sent - for example: -1 2057 1699 1721 1699 + recvctlmsg: + capi messages received without DATA_B3_IND + recvdatamsg: + capi DATA_B3_IND received + sentctlmsg: + capi messages sent without DATA_B3_REQ + sentdatamsg: + capi DATA_B3_REQ sent + + for example:: + + 1 2057 1699 1721 1699 /proc/capi/capi20: statistics of capi.o (/dev/capi20) minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - minor: minor device number of capi device - nopen: number of calls to devices open - nrecvdropmsg: capi messages dropped (messages in recvqueue in close) - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent - - for example: -1 2 18 0 16 2 + minor: + minor device number of capi device + nopen: + number of calls to devices open + nrecvdropmsg: + capi messages dropped (messages in recvqueue in close) + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent + + for example:: + + 1 2 18 0 16 2 /proc/capi/capidrv: statistics of capidrv.o (capi messages) nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent + for example: -2780 2226 2256 2226 + 2780 2226 2256 2226 /proc/capi/controller: controller drivername state cardname controllerinfo - for example: -1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19 -2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0 -3 b1pcmcia running m2-150 B1 3.07-01 0x150 5 + + for example:: + + 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19 + 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0 + 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5 /proc/capi/contrstats: controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent - for example: -1 2845 2272 2310 2274 -2 2 0 2 0 -3 2 0 2 0 + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent + + for example:: + + 1 2845 2272 2310 2274 + 2 2 0 2 0 + 3 2 0 2 0 /proc/capi/driver: drivername ncontroller - for example: -b1pci 1 -t1isa 1 -b1pcmcia 1 -b1isa 0 + + for example:: + + b1pci 1 + t1isa 1 + b1pcmcia 1 + b1isa 0 /proc/capi/ncci: apllid ncci winsize sendwindow - for example: -1 0x10101 8 0 + + for example:: + + 1 0x10101 8 0 /proc/capi/users: kernelmodules that use the kernelcapi. name - for example: -capidrv -capi20 + + for example:: + + capidrv + capi20 Questions --------- + Check out the FAQ (ftp.isdn4linux.de) or subscribe to the linux-avmb1@calle.in-berlin.de mailing list by sending a mail to majordomo@calle.in-berlin.de with @@ -178,9 +236,10 @@ in the body. German documentation and several scripts can be found at ftp://ftp.avm.de/cardware/b1/linux/ -Bugs +Bugs ---- -If you find any please let me know. + +If you find any please let me know. Enjoy, diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst index c1679e913fca..319323f2091f 100644 --- a/Documentation/isdn/CREDITS +++ b/Documentation/isdn/credits.rst @@ -1,3 +1,7 @@ +======= +Credits +======= + I want to thank all who contributed to this project and especially to: (in alphabetical order) @@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de) For creating and maintaining the FAQ. Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de) - For creating the FAQ, and the leafsite HOWTO. + For creating the FAQ, and the leafsite HOWTO. Michael 'Ghandi' Herold (michael@abadonna.franken.de) For contribution of the vbox answering machine. @@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de) Thomas Uhl (uhl@think.de) For distributing the cards. For pushing me to work ;-) - diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst index f6184b637182..98b4ec521c51 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/gigaset.rst @@ -1,33 +1,36 @@ +========================== GigaSet 307x Device Driver ========================== 1. Requirements - ------------ +================= + 1.1. Hardware - -------- +------------- + This driver supports the connection of the Gigaset 307x/417x family of ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB connection. The following devices are reported to be compatible: Bases: - Siemens Gigaset 3070/3075 isdn - Siemens Gigaset 4170/4175 isdn - Siemens Gigaset SX205/255 - Siemens Gigaset SX353 - T-Com Sinus 45 [AB] isdn - T-Com Sinus 721X[A] [SE] - Vox Chicago 390 ISDN (KPN Telecom) + - Siemens Gigaset 3070/3075 isdn + - Siemens Gigaset 4170/4175 isdn + - Siemens Gigaset SX205/255 + - Siemens Gigaset SX353 + - T-Com Sinus 45 [AB] isdn + - T-Com Sinus 721X[A] [SE] + - Vox Chicago 390 ISDN (KPN Telecom) RS232 data boxes: - Siemens Gigaset M101 Data - T-Com Sinus 45 Data 1 + - Siemens Gigaset M101 Data + - T-Com Sinus 45 Data 1 USB data boxes: - Siemens Gigaset M105 Data - Siemens Gigaset USB Adapter DECT - T-Com Sinus 45 Data 2 - T-Com Sinus 721 data - Chicago 390 USB (KPN) + - Siemens Gigaset M105 Data + - Siemens Gigaset USB Adapter DECT + - T-Com Sinus 45 Data 2 + - T-Com Sinus 721 data + - Chicago 390 USB (KPN) See also http://www.erbze.info/sinus_gigaset.htm (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and @@ -37,17 +40,21 @@ GigaSet 307x Device Driver with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.) If you have another device that works with our driver, please let us know. - Chances of getting an USB device to work are good if the output of - lsusb - at the command line contains one of the following: - ID 0681:0001 - ID 0681:0002 - ID 0681:0009 - ID 0681:0021 - ID 0681:0022 + Chances of getting an USB device to work are good if the output of:: + + lsusb + + at the command line contains one of the following:: + + ID 0681:0001 + ID 0681:0002 + ID 0681:0009 + ID 0681:0021 + ID 0681:0022 1.2. Software - -------- +------------- + The driver works with the Kernel CAPI subsystem and can be used with any software which is able to use CAPI 2.0 for ISDN connections (voice or data). @@ -58,9 +65,11 @@ GigaSet 307x Device Driver 2. How to use the driver - --------------------- +========================== + 2.1. Modules - ------- +------------ + For the devices to work, the proper kernel modules have to be loaded. This normally happens automatically when the system detects the USB device (base, M105) or when the line discipline is attached (M101). It @@ -71,13 +80,17 @@ GigaSet 307x Device Driver which uses the regular serial port driver to access the device, and must therefore be attached to the serial device to which the M101 is connected. The ldattach(8) command (included in util-linux-ng release 2.14 or later) - can be used for that purpose, for example: + can be used for that purpose, for example:: + ldattach GIGASET_M101 /dev/ttyS1 + This will open the device file, attach the line discipline to it, and then sleep in the background, keeping the device open so that the line discipline remains active. To deactivate it, kill the daemon, for example - with + with:: + killall ldattach + before disconnecting the device. To have this happen automatically at system startup/shutdown on an LSB compatible system, create and activate an appropriate LSB startup script /etc/init.d/gigaset. (The init name @@ -86,9 +99,10 @@ GigaSet 307x Device Driver The modules accept the following parameters: - Module Parameter Meaning + =============== ========== ========================================== + Module Parameter Meaning - gigaset debug debug level (see section 3.2.) + gigaset debug debug level (see section 3.2.) startmode initial operation mode (see section 2.5.): bas_gigaset ) 1=CAPI (default), 0=Unimodem @@ -96,11 +110,14 @@ GigaSet 307x Device Driver usb_gigaset ) cidmode initial Call-ID mode setting (see section 2.5.): 1=on (default), 0=off + =============== ========== ========================================== + Depending on your distribution you may want to create a separate module configuration file like /etc/modprobe.d/gigaset.conf for these. 2.2. Device nodes for user space programs - ------------------------------------ +----------------------------------------- + The device can be accessed from user space (eg. by the user space tools mentioned in 1.2.) through the device nodes: @@ -113,46 +130,56 @@ GigaSet 307x Device Driver You can also set a "default device" for the user space tools to use when no device node is given as parameter, by creating a symlink /dev/ttyG to - one of them, eg.: + one of them, eg.:: ln -s /dev/ttyGB0 /dev/ttyG The devices accept the following device specific ioctl calls (defined in gigaset_dev.h): - ioctl(int fd, GIGASET_REDIR, int *cmd); + ``ioctl(int fd, GIGASET_REDIR, int *cmd);`` + If cmd==1, the device is set to be controlled exclusively through the character device node; access from the ISDN subsystem is blocked. + If cmd==0, the device is set to be used from the ISDN subsystem and does not communicate through the character device node. - ioctl(int fd, GIGASET_CONFIG, int *cmd); + ``ioctl(int fd, GIGASET_CONFIG, int *cmd);`` + (ser_gigaset and usb_gigaset only) + If cmd==1, the device is set to adapter configuration mode where commands are interpreted by the M10x DECT adapter itself instead of being forwarded to the base station. In this mode, the device accepts the commands described in Siemens document "AT-Kommando Alignment M10x Data" for setting the operation mode, associating with a base station and querying parameters like field strengh and signal quality. + Note that there is no ioctl command for leaving adapter configuration mode and returning to regular operation. In order to leave adapter configuration mode, write the command ATO to the device. - ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]); + ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);`` + (usb_gigaset only) + Set the break characters on an M105's internal serial adapter to the six bytes stored in brkchars[]. Unused bytes should be set to zero. ioctl(int fd, GIGASET_VERSION, unsigned version[4]); Retrieve version information from the driver. version[0] must be set to one of: + - GIGVER_DRIVER: retrieve driver version - GIGVER_COMPAT: retrieve interface compatibility version - GIGVER_FWBASE: retrieve the firmware version of the base + Upon return, version[] is filled with the requested version information. 2.3. CAPI - ---- +--------- + The devices will show up as CAPI controllers as soon as the corresponding driver module is loaded, and can then be used with CAPI 2.0 kernel and user space applications. For user space access, @@ -165,21 +192,22 @@ GigaSet 307x Device Driver driver. 2.5. Unimodem mode - ------------- +------------------ + In this mode the device works like a modem connected to a serial port - (the /dev/ttyGU0, ... mentioned above) which understands the commands - - ATZ init, reset - => OK or ERROR - ATD - ATDT dial - => OK, CONNECT, - BUSY, - NO DIAL TONE, - NO CARRIER, - NO ANSWER - <pause>+++<pause> change to command mode when connected - ATH hangup + (the /dev/ttyGU0, ... mentioned above) which understands the commands:: + + ATZ init, reset + => OK or ERROR + ATD + ATDT dial + => OK, CONNECT, + BUSY, + NO DIAL TONE, + NO CARRIER, + NO ANSWER + <pause>+++<pause> change to command mode when connected + ATH hangup You can use some configuration tool of your distribution to configure this "modem" or configure pppd/wvdial manually. There are some example ppp @@ -189,40 +217,52 @@ GigaSet 307x Device Driver control lines. This means you must use "Stupid Mode" if you are using wvdial or you should use the nocrtscts option of pppd. You must also assure that the ppp_async module is loaded with the parameter - flag_time=0. You can do this e.g. by adding a line like + flag_time=0. You can do this e.g. by adding a line like:: + + options ppp_async flag_time=0 - options ppp_async flag_time=0 + to an appropriate module configuration file, like:: - to an appropriate module configuration file, like - /etc/modprobe.d/gigaset.conf. + /etc/modprobe.d/gigaset.conf. Unimodem mode is needed for making some devices [e.g. SX100] work which do not support the regular Gigaset command set. If debug output (see - section 3.2.) shows something like this when dialing: - CMD Received: ERROR - Available Params: 0 - Connection State: 0, Response: -1 - gigaset_process_response: resp_code -1 in ConState 0 ! - Timeout occurred + section 3.2.) shows something like this when dialing:: + + CMD Received: ERROR + Available Params: 0 + Connection State: 0, Response: -1 + gigaset_process_response: resp_code -1 in ConState 0 ! + Timeout occurred + then switching to unimodem mode may help. If you have installed the command line tool gigacontr, you can enter - unimodem mode using - gigacontr --mode unimodem - You can switch back using - gigacontr --mode isdn + unimodem mode using:: + + gigacontr --mode unimodem + + You can switch back using:: + + gigacontr --mode isdn You can also put the driver directly into Unimodem mode when it's loaded, by passing the module parameter startmode=0 to the hardware specific - module, e.g. + module, e.g.:: + modprobe usb_gigaset startmode=0 - or by adding a line like + + or by adding a line like:: + options usb_gigaset startmode=0 - to an appropriate module configuration file, like - /etc/modprobe.d/gigaset.conf + + to an appropriate module configuration file, like:: + + /etc/modprobe.d/gigaset.conf 2.6. Call-ID (CID) mode - ------------------ +----------------------- + Call-IDs are numbers used to tag commands to, and responses from, the Gigaset base in order to support the simultaneous handling of multiple ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem @@ -238,6 +278,7 @@ GigaSet 307x Device Driver During active operation, the driver switches to the necessary mode automatically. However, for the reasons above, the mode chosen when the device is not in use (idle) can be selected by the user. + - If you want to receive incoming calls, you can use the default settings (CID mode). - If you have several DECT data devices (M10x) which you want to use @@ -247,25 +288,27 @@ GigaSet 307x Device Driver If you want both of these at once, you are out of luck. You can also use the tty class parameter "cidmode" of the device to - change its CID mode while the driver is loaded, eg. - echo 0 > /sys/class/tty/ttyGU0/cidmode + change its CID mode while the driver is loaded, eg.:: + + echo 0 > /sys/class/tty/ttyGU0/cidmode 2.7. Dialing Numbers - --------------- - The called party number provided by an application for dialing out must +-------------------- +provided by an application for dialing out must be a public network number according to the local dialing plan, without any dial prefix for getting an outside line. Internal calls can be made by providing an internal extension number - prefixed with "**" (two asterisks) as the called party number. So to dial - eg. the first registered DECT handset, give "**11" as the called party - number. Dialing "***" (three asterisks) calls all extensions + prefixed with ``**`` (two asterisks) as the called party number. So to dial + eg. the first registered DECT handset, give ``**11`` as the called party + number. Dialing ``***`` (three asterisks) calls all extensions simultaneously (global call). Unimodem mode does not support internal calls. 2.8. Unregistered Wireless Devices (M101/M105) - ----------------------------------------- +---------------------------------------------- + The main purpose of the ser_gigaset and usb_gigaset drivers is to allow the M101 and M105 wireless devices to be used as ISDN devices for ISDN connections through a Gigaset base. Therefore they assume that the device @@ -279,73 +322,91 @@ GigaSet 307x Device Driver modes. See the gigacontr(8) manpage for details. 3. Troubleshooting - --------------- +==================== + 3.1. Solutions to frequently reported problems - ----------------------------------------- +---------------------------------------------- + Problem: - You have a slow provider and isdn4linux gives up dialing too early. + You have a slow provider and isdn4linux gives up dialing too early. Solution: - Load the isdn module using the dialtimeout option. You can do this e.g. - by adding a line like + Load the isdn module using the dialtimeout option. You can do this e.g. + by adding a line like:: - options isdn dialtimeout=15 + options isdn dialtimeout=15 - to /etc/modprobe.d/gigaset.conf or a similar file. + to /etc/modprobe.d/gigaset.conf or a similar file. Problem: - The isdnlog program emits error messages or just doesn't work. + The isdnlog program emits error messages or just doesn't work. Solution: - Isdnlog supports only the HiSax driver. Do not attempt to use it with + Isdnlog supports only the HiSax driver. Do not attempt to use it with other drivers such as Gigaset. Problem: - You have two or more DECT data adapters (M101/M105) and only the - first one you turn on works. + You have two or more DECT data adapters (M101/M105) and only the + first one you turn on works. Solution: - Select Unimodem mode for all DECT data adapters. (see section 2.5.) + Select Unimodem mode for all DECT data adapters. (see section 2.5.) Problem: - Messages like this: + Messages like this:: + usb_gigaset 3-2:1.0: Could not initialize the device. + appear in your syslog. Solution: Check whether your M10x wireless device is correctly registered to the Gigaset base. (see section 2.7.) 3.2. Telling the driver to provide more information - ---------------------------------------------- +--------------------------------------------------- Building the driver with the "Gigaset debugging" kernel configuration option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional information useful for debugging. You can control the amount of debugging information the driver produces by - writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g. - echo 0 > /sys/module/gigaset/parameters/debug + writing an appropriate value to /sys/module/gigaset/parameters/debug, + e.g.:: + + echo 0 > /sys/module/gigaset/parameters/debug + switches off debugging output completely, - echo 0x302020 > /sys/module/gigaset/parameters/debug + + :: + + echo 0x302020 > /sys/module/gigaset/parameters/debug + enables a reasonable set of debugging output messages. These values are bit patterns where every bit controls a certain type of debugging output. See the constants DEBUG_* in the source file gigaset.h for details. The initial value can be set using the debug parameter when loading the - module "gigaset", e.g. by adding a line - options gigaset debug=0 + module "gigaset", e.g. by adding a line:: + + options gigaset debug=0 + to your module configuration file, eg. /etc/modprobe.d/gigaset.conf Generated debugging information can be found - - as output of the command - dmesg + - as output of the command:: + + dmesg + - in system log files written by your syslog daemon, usually in /var/log/, e.g. /var/log/messages. 3.3. Reporting problems and bugs - --------------------------- +-------------------------------- If you can't solve problems with the driver on your own, feel free to use one of the forums, bug trackers, or mailing lists on - https://sourceforge.net/projects/gigaset307x + + https://sourceforge.net/projects/gigaset307x + or write an electronic mail to the maintainers. Try to provide as much information as possible, such as + - distribution - kernel version (uname -r) - gcc version (gcc --version) @@ -362,7 +423,7 @@ GigaSet 307x Device Driver appropriate forums and newsgroups. 3.4. Reporting problem solutions - --------------------------- +-------------------------------- If you solved a problem with our drivers, wrote startup scripts for your distribution, ... feel free to contact us (using one of the places mentioned in 3.3.). We'd like to add scripts, hints, documentation @@ -370,34 +431,35 @@ GigaSet 307x Device Driver 4. Links, other software - --------------------- +========================== + - Sourceforge project developing this driver and associated tools - https://sourceforge.net/projects/gigaset307x + https://sourceforge.net/projects/gigaset307x - Yahoo! Group on the Siemens Gigaset family of devices - https://de.groups.yahoo.com/group/Siemens-Gigaset + https://de.groups.yahoo.com/group/Siemens-Gigaset - Siemens Gigaset/T-Sinus compatibility table - http://www.erbze.info/sinus_gigaset.htm + http://www.erbze.info/sinus_gigaset.htm (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) 5. Credits - ------- +============ + Thanks to Karsten Keil - for his help with isdn4linux + for his help with isdn4linux Deti Fliegl - for his base driver code + for his base driver code Dennis Dietrich - for his kernel 2.6 patches + for his kernel 2.6 patches Andreas Rummel - for his work and logs to get unimodem mode working + for his work and logs to get unimodem mode working Andreas Degert - for his logs and patches to get cx 100 working + for his logs and patches to get cx 100 working Dietrich Feist - for his generous donation of one M105 and two M101 cordless adapters + for his generous donation of one M105 and two M101 cordless adapters Christoph Schweers - for his generous donation of a M34 device + for his generous donation of a M34 device and all the other people who sent logs and other information. - diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst index eeca11f00ccd..0a168d1cbffc 100644 --- a/Documentation/isdn/README.hysdn +++ b/Documentation/isdn/hysdn.rst @@ -1,4 +1,7 @@ -$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $ +============ +Hysdn Driver +============ + The hysdn driver has been written by Werner Cornelius (werner@isdn4linux.de or werner@titro.de) for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver @@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany. along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -Table of contents -================= +.. Table of contents -1. About the driver + 1. About the driver -2. Loading/Unloading the driver + 2. Loading/Unloading the driver -3. Entries in the /proc filesystem + 3. Entries in the /proc filesystem -4. The /proc/net/hysdn/cardconfX file + 4. The /proc/net/hysdn/cardconfX file -5. The /proc/net/hysdn/cardlogX file + 5. The /proc/net/hysdn/cardlogX file -6. Where to get additional info and help + 6. Where to get additional info and help 1. About the driver +=================== - The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active + The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active PCI isdn cards Champ, Ergo and Metro. To enable support for this cards enable ISDN support in the kernel config and support for HYSDN cards in - the active cards submenu. The driver may only be compiled and used if + the active cards submenu. The driver may only be compiled and used if support for loadable modules and the process filesystem have been enabled. These cards provide two different interfaces to the kernel. Without the @@ -52,22 +55,23 @@ Table of contents handlers for various protocols like ppp and others as well as config info and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de. - With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 - compliant devices with either CAPI 2.0 applications + With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 + compliant devices with either CAPI 2.0 applications (check isdn4k-utils) or -using the capidrv module- as a regular - isdn4linux device. This is done via the same mechanism as with the + isdn4linux device. This is done via the same mechanism as with the active AVM cards and in fact uses the same module. - + 2. Loading/Unloading the driver +=============================== The module has no command line parameters and auto detects up to 10 cards in the id-range 0-9. If a loaded driver shall be unloaded all open files in the /proc/net/hysdn - subdir need to be closed and all ethernet interfaces allocated by this + subdir need to be closed and all ethernet interfaces allocated by this driver must be shut down. Otherwise the module counter will avoid a module unload. - + If you are using the CAPI 2.0-interface, make sure to load/modprobe the kernelcapi-module first. @@ -76,52 +80,57 @@ Table of contents any avm-specific modules). 3. Entries in the /proc filesystem +================================== - When the module has been loaded it adds the directory hysdn in the - /proc/net tree. This directory contains exactly 2 file entries for each + When the module has been loaded it adds the directory hysdn in the + /proc/net tree. This directory contains exactly 2 file entries for each card. One is called cardconfX and the other cardlogX, where X is the - card id number from 0 to 9. + card id number from 0 to 9. The cards are numbered in the order found in the PCI config data. 4. The /proc/net/hysdn/cardconfX file +===================================== - This file may be read to get by everyone to get info about the cards type, + This file may be read to get by everyone to get info about the cards type, actual state, available features and used resources. The first 3 entries (id, bus and slot) are PCI info fields, the following type field gives the information about the cards type: - 4 -> Ergo card (server card with 2 b-chans) - 5 -> Metro card (server card with 4 or 8 b-chans) - 6 -> Champ card (client card with 2 b-chans) + - 4 -> Ergo card (server card with 2 b-chans) + - 5 -> Metro card (server card with 4 or 8 b-chans) + - 6 -> Champ card (client card with 2 b-chans) The following 3 fields show the hardware assignments for irq, iobase and the dual ported memory (dp-mem). + The fields b-chans and fax-chans announce the available card resources of this types for the user. + The state variable indicates the actual drivers state for this card with the following assignments. - 0 -> card has not been booted since driver load - 1 -> card booting is actually in progess - 2 -> card is in an error state due to a previous boot failure - 3 -> card is booted and active + - 0 -> card has not been booted since driver load + - 1 -> card booting is actually in progess + - 2 -> card is in an error state due to a previous boot failure + - 3 -> card is booted and active And the last field (device) shows the name of the ethernet device assigned to this card. Up to the first successful boot this field only shows a - to tell that no net device has been allocated up to now. Once a net device has been allocated it remains assigned to this card, even if a card is - rebooted and an boot error occurs. + rebooted and an boot error occurs. - Writing to the cardconfX file boots the card or transfers config lines to - the cards firmware. The type of data is automatically detected when the + Writing to the cardconfX file boots the card or transfers config lines to + the cards firmware. The type of data is automatically detected when the first data is written. Only root has write access to this file. The firmware boot files are normally called hyclient.pof for client cards and hyserver.pof for server cards. After successfully writing the boot file, complete config files or single config lines may be copied to this file. - If an error occurs the return value given to the writing process has the + If an error occurs the return value given to the writing process has the following additional codes (decimal): + ==== ============================================ 1000 Another process is currently bootng the card 1001 Invalid firmware header 1002 Boards dual-port RAM test failed @@ -131,34 +140,39 @@ Table of contents 1006 Second boot stage failure 1007 Timeout waiting for card ready during boot 1008 Operation only allowed in booted state - 1009 Config line too long - 1010 Invalid channel number + 1009 Config line too long + 1010 Invalid channel number 1011 Timeout sending config data + ==== ============================================ - Additional info about error reasons may be fetched from the log output. + Additional info about error reasons may be fetched from the log output. 5. The /proc/net/hysdn/cardlogX file - - The cardlogX file entry may be opened multiple for reading by everyone to +==================================== + + The cardlogX file entry may be opened multiple for reading by everyone to get the cards and drivers log data. Card messages always start with the - keyword LOG. All other lines are output from the driver. - The driver log data may be redirected to the syslog by selecting the + keyword LOG. All other lines are output from the driver. + The driver log data may be redirected to the syslog by selecting the appropriate bitmask. The cards log messages will always be send to this interface but never to the syslog. A root user may write a decimal or hex (with 0x) value t this file to select - desired output options. As mentioned above the cards log dat is always + desired output options. As mentioned above the cards log dat is always written to the cardlog file independent of the following options only used to check and debug the driver itself: - For example: - echo "0x34560078" > /proc/net/hysdn/cardlog0 + For example:: + + echo "0x34560078" > /proc/net/hysdn/cardlog0 + to output the hex log mask 34560078 for card 0. - - The written value is regarded as an unsigned 32-Bit value, bit ored for + + The written value is regarded as an unsigned 32-Bit value, bit ored for desired output. The following bits are already assigned: - 0x80000000 All driver log data is alternatively via syslog + ========== ============================================================ + 0x80000000 All driver log data is alternatively via syslog 0x00000001 Log memory allocation errors 0x00000010 Firmware load start and close are logged 0x00000020 Log firmware record parser @@ -171,25 +185,12 @@ Table of contents 0x00100000 Log all open and close actions to /proc/net/hysdn/card files 0x00200000 Log all actions from /proc file entries 0x00010000 Log network interface init and deinit - + ========== ============================================================ + 6. Where to get additional info and help +======================================== - If you have any problems concerning the driver or configuration contact + If you have any problems concerning the driver or configuration contact the Hypercope support team (support@hypercope.de) and or the authors Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or Ulrich Albrecht (ualbrecht@hypercope.de). - - - - - - - - - - - - - - - diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst new file mode 100644 index 000000000000..407e74b78372 --- /dev/null +++ b/Documentation/isdn/index.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +ISDN +==== + +.. toctree:: + :maxdepth: 2 + + interface_capi + + avmb1 + gigaset + hysdn + m_isdn + + credits + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst index 021aa9cf139d..01a4b5ade9a4 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/interface_capi.rst @@ -1,7 +1,9 @@ +========================================= Kernel CAPI Interface to Hardware Drivers ------------------------------------------ +========================================= 1. Overview +=========== From the CAPI 2.0 specification: COMMON-ISDN-API (CAPI) is an application programming interface standard used @@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org. 2. Driver and Device Registration +================================= CAPI drivers optionally register themselves with Kernel CAPI by calling the Kernel CAPI function register_capi_driver() with a pointer to a struct @@ -50,6 +53,7 @@ callback functions by Kernel CAPI. 3. Application Registration and Communication +============================================= Kernel CAPI forwards registration requests from applications (calls to CAPI operation CAPI_REGISTER) to an appropriate hardware driver by calling its @@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore. 4. Data Structures +================== 4.1 struct capi_driver +---------------------- This structure describes a Kernel CAPI driver itself. It is used in the register_capi_driver() and unregister_capi_driver() functions, and contains the following non-private fields, all to be set by the driver before calling register_capi_driver(): -char name[32] +``char name[32]`` the name of the driver, as a zero-terminated ASCII string -char revision[32] +``char revision[32]`` the revision number of the driver, as a zero-terminated ASCII string -int (*add_card)(struct capi_driver *driver, capicardparams *data) +``int (*add_card)(struct capi_driver *driver, capicardparams *data)`` a callback function pointer (may be NULL) 4.2 struct capi_ctr +------------------- This structure describes an ISDN device (controller) handled by a Kernel CAPI driver. After registration via the attach_capi_ctr() function it is passed to @@ -96,88 +103,109 @@ identify the controller to operate on. It contains the following non-private fields: -- to be set by the driver before calling attach_capi_ctr(): +to be set by the driver before calling attach_capi_ctr(): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -struct module *owner +``struct module *owner`` pointer to the driver module owning the device -void *driverdata +``void *driverdata`` an opaque pointer to driver specific data, not touched by Kernel CAPI -char name[32] +``char name[32]`` the name of the controller, as a zero-terminated ASCII string -char *driver_name +``char *driver_name`` the name of the driver, as a zero-terminated ASCII string -int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) +``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)`` (optional) pointer to a callback function for sending firmware and configuration data to the device + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_ready(). + Return value: 0 on success, error code on error Called in process context. -void (*reset_ctr)(struct capi_ctr *ctrlr) +``void (*reset_ctr)(struct capi_ctr *ctrlr)`` (optional) pointer to a callback function for stopping the device, releasing all registered applications + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_down(). + Called in process context. -void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, - capi_register_params *rparam) -void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) - pointers to callback functions for registration and deregistration of +``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)`` + pointers to callback function for registration of applications with the device + Calls to these functions are serialized by Kernel CAPI so that only one call to any of them is active at any time. -u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) +``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)`` + pointers to callback functions deregistration of + applications with the device + + Calls to these functions are serialized by Kernel CAPI so that only + one call to any of them is active at any time. + +``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)`` pointer to a callback function for sending a CAPI message to the device + Return value: CAPI error code + If the method returns 0 (CAPI_NOERROR) the driver has taken ownership of the skb and the caller may no longer access it. If it returns a non-zero (error) value then ownership of the skb returns to the caller who may reuse or free it. + The return value should only be used to signal problems with respect to accepting or queueing the message. Errors occurring during the actual processing of the message should be signaled with an appropriate reply message. + May be called in process or interrupt context. + Calls to this function are not serialized by Kernel CAPI, ie. it must be prepared to be re-entered. -char *(*procinfo)(struct capi_ctr *ctrlr) +``char *(*procinfo)(struct capi_ctr *ctrlr)`` pointer to a callback function returning the entry for the device in the CAPI controller info table, /proc/capi/controller -const struct file_operations *proc_fops +``const struct file_operations *proc_fops`` pointers to callback functions for the device's proc file system entry, /proc/capi/controllers/<n>; pointer to the device's capi_ctr structure is available from struct proc_dir_entry::data which is available from struct inode. -Note: Callback functions except send_message() are never called in interrupt -context. +Note: + Callback functions except send_message() are never called in interrupt + context. -- to be filled in before calling capi_ctr_ready(): +to be filled in before calling capi_ctr_ready(): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -u8 manu[CAPI_MANUFACTURER_LEN] +``u8 manu[CAPI_MANUFACTURER_LEN]`` value to return for CAPI_GET_MANUFACTURER -capi_version version +``capi_version version`` value to return for CAPI_GET_VERSION -capi_profile profile +``capi_profile profile`` value to return for CAPI_GET_PROFILE -u8 serial[CAPI_SERIAL_LEN] +``u8 serial[CAPI_SERIAL_LEN]`` value to return for CAPI_GET_SERIAL 4.3 SKBs +-------- CAPI messages are passed between Kernel CAPI and the driver via send_message() and capi_ctr_handle_message(), stored in the data portion of a socket buffer @@ -192,6 +220,7 @@ instead of 30. 4.4 The _cmsg Structure +----------------------- (declared in <linux/isdn/capiutil.h>) @@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data types are: +=========== ================================================================= u8 for CAPI parameters of type 'byte' u16 for CAPI parameters of type 'word' @@ -235,6 +265,7 @@ _cmstruct alternative representation for CAPI parameters of type 'struct' CAPI_COMPOSE: The parameter is present. Subparameter values are stored individually in the corresponding _cmsg structure members. +=========== ================================================================= Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert messages between their transport encoding described in the CAPI 2.0 standard @@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message. 5. Lower Layer Interface Functions +================================== (declared in <linux/isdn/capilli.h>) -void register_capi_driver(struct capi_driver *drvr) -void unregister_capi_driver(struct capi_driver *drvr) - register/unregister a driver with Kernel CAPI +:: + + void register_capi_driver(struct capi_driver *drvr) + void unregister_capi_driver(struct capi_driver *drvr) + +register/unregister a driver with Kernel CAPI + +:: + + int attach_capi_ctr(struct capi_ctr *ctrlr) + int detach_capi_ctr(struct capi_ctr *ctrlr) + +register/unregister a device (controller) with Kernel CAPI -int attach_capi_ctr(struct capi_ctr *ctrlr) -int detach_capi_ctr(struct capi_ctr *ctrlr) - register/unregister a device (controller) with Kernel CAPI +:: -void capi_ctr_ready(struct capi_ctr *ctrlr) -void capi_ctr_down(struct capi_ctr *ctrlr) - signal controller ready/not ready + void capi_ctr_ready(struct capi_ctr *ctrlr) + void capi_ctr_down(struct capi_ctr *ctrlr) -void capi_ctr_suspend_output(struct capi_ctr *ctrlr) -void capi_ctr_resume_output(struct capi_ctr *ctrlr) - signal suspend/resume +signal controller ready/not ready -void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, - struct sk_buff *skb) - pass a received CAPI message to Kernel CAPI - for forwarding to the specified application +:: + + void capi_ctr_suspend_output(struct capi_ctr *ctrlr) + void capi_ctr_resume_output(struct capi_ctr *ctrlr) + +signal suspend/resume + +:: + + void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, + struct sk_buff *skb) + +pass a received CAPI message to Kernel CAPI +for forwarding to the specified application 6. Helper Functions and Macros +============================== Library functions (from <linux/isdn/capilli.h>): -void capilib_new_ncci(struct list_head *head, u16 applid, +:: + + void capilib_new_ncci(struct list_head *head, u16 applid, u32 ncci, u32 winsize) -void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) -void capilib_release_appl(struct list_head *head, u16 applid) -void capilib_release(struct list_head *head) -void capilib_data_b3_conf(struct list_head *head, u16 applid, + void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) + void capilib_release_appl(struct list_head *head, u16 applid) + void capilib_release(struct list_head *head) + void capilib_data_b3_conf(struct list_head *head, u16 applid, u32 ncci, u16 msgid) -u16 capilib_data_b3_req(struct list_head *head, u16 applid, + u16 capilib_data_b3_req(struct list_head *head, u16 applid, u32 ncci, u16 msgid) Macros to extract/set element values from/in a CAPI message header (from <linux/isdn/capiutil.h>): +====================== ============================= ==================== Get Macro Set Macro Element (Type) - +====================== ============================= ==================== CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) @@ -300,31 +351,31 @@ CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI (u32) CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) +====================== ============================= ==================== Library functions for working with _cmsg structures (from <linux/isdn/capiutil.h>): -unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) - Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the - result in *msg. +``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)`` + Assembles a CAPI 2.0 message from the parameters in ``*cmsg``, + storing the result in ``*msg``. -unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) - Disassembles the CAPI 2.0 message in *msg, storing the parameters in - *cmsg. +``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)`` + Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters + in ``*cmsg``. -unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, - u16 Messagenumber, u32 Controller) - Fills the header part and address field of the _cmsg structure *cmsg +``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)`` + Fills the header part and address field of the _cmsg structure ``*cmsg`` with the given values, zeroing the remainder of the structure so only parameters with non-default values need to be changed before sending the message. -void capi_cmsg_answer(_cmsg *cmsg) - Sets the low bit of the Subcommand field in *cmsg, thereby converting - _REQ to _CONF and _IND to _RESP. +``void capi_cmsg_answer(_cmsg *cmsg)`` + Sets the low bit of the Subcommand field in ``*cmsg``, thereby + converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``. -char *capi_cmd2str(u8 Command, u8 Subcommand) +``char *capi_cmd2str(u8 Command, u8 Subcommand)`` Returns the CAPI 2.0 message name corresponding to the given command and subcommand values, as a static ASCII string. The return value may be NULL if the command/subcommand is not one of those defined in the @@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand) 7. Debugging +============ The module kernelcapi has a module parameter showcapimsgs controlling some debugging output produced by the module. It can only be set when the module is diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst index cd8bf920e77b..9957de349e69 100644 --- a/Documentation/isdn/README.mISDN +++ b/Documentation/isdn/m_isdn.rst @@ -1,6 +1,9 @@ +============ +mISDN Driver +============ + mISDN is a new modular ISDN driver, in the long term it should replace the old I4L driver architecture for passiv ISDN cards. It was designed to allow a broad range of applications and interfaces but only have the basic function in kernel, the interface to the user space is based on sockets with a own address family AF_ISDN. - diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst index e323a3f2cc81..0f144fad99a6 100644 --- a/Documentation/kbuild/index.rst +++ b/Documentation/kbuild/index.rst @@ -18,6 +18,7 @@ Kernel Build System headers_install issues + reproducible-builds .. only:: subproject and html diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst new file mode 100644 index 000000000000..ab92e98c89c8 --- /dev/null +++ b/Documentation/kbuild/reproducible-builds.rst @@ -0,0 +1,122 @@ +=================== +Reproducible builds +=================== + +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. This makes it possible to verify that the build +infrastructure for a binary distribution or embedded system has not +been subverted. This can also make it easier to verify that a source +or tool change does not make any difference to the resulting binaries. + +The `Reproducible Builds project`_ has more information about this +general topic. This document covers the various reasons why building +the kernel may be unreproducible, and how to avoid them. + +Timestamps +---------- + +The kernel embeds a timestamp in two places: + +* The version string exposed by ``uname()`` and included in + ``/proc/version`` + +* File timestamps in the embedded initramfs + +By default the timestamp is the current time. This must be overridden +using the `KBUILD_BUILD_TIMESTAMP`_ variable. If you are building +from a git commit, you could use its commit date. + +The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, +and enables warnings if they are used. If you incorporate external +code that does use these, you must override the timestamp they +correspond to by setting the `SOURCE_DATE_EPOCH`_ environment +variable. + +User, host +---------- + +The kernel embeds the building user and host names in +``/proc/version``. These must be overridden using the +`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are +building from a git commit, you could use its committer address. + +Absolute filenames +------------------ + +When the kernel is built out-of-tree, debug information may include +absolute filenames for the source files. This must be overridden by +including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. + +Depending on the compiler used, the ``__FILE__`` macro may also expand +to an absolute filename in an out-of-tree build. Kbuild automatically +uses the ``-fmacro-prefix-map`` option to prevent this, if it is +supported. + +The Reproducible Builds web site has more information about these +`prefix-map options`_. + +Generated files in source packages +---------------------------------- + +The build processes for some programs under the ``tools/`` +subdirectory do not completely support out-of-tree builds. This may +cause a later source package build using e.g. ``make rpm-pkg`` to +include generated files. You should ensure the source tree is +pristine by running ``make mrproper`` or ``git clean -d -f -x`` before +building a source package. + +Module signing +-------------- + +If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to +generate a different temporary key for each build, resulting in the +modules being unreproducible. However, including a signing key with +your source would presumably defeat the purpose of signing modules. + +One approach to this is to divide up the build process so that the +unreproducible parts can be treated as sources: + +1. Generate a persistent signing key. Add the certificate for the key + to the kernel source. + +2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the + signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an + empty string, and disable ``CONFIG_MODULE_SIG_ALL``. + Build the kernel and modules. + +3. Create detached signatures for the modules, and publish them as + sources. + +4. Perform a second build that attaches the module signatures. It + can either rebuild the modules or use the output of step 2. + +Structure randomisation +----------------------- + +If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to +pre-generate the random seed in +``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value +is used in rebuilds. + +Debug info conflicts +-------------------- + +This is not a problem of unreproducibility, but of generated files +being *too* reproducible. + +Once you set all the necessary variables for a reproducible build, a +vDSO's debug information may be identical even for different kernel +versions. This can result in file conflicts between debug information +packages for the different kernel versions. + +To avoid this, you can make the vDSO different for different +kernel versions by including an arbitrary string of "salt" in it. +This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. + +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host +.. _KCFLAGS: kbuild.html#kcflags +.. _prefix-map options: https://reproducible-builds.org/docs/build-path/ +.. _Reproducible Builds project: https://reproducible-builds.org/ +.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst index df0120a1ee3c..a0708d3f3d0b 100644 --- a/Documentation/leds/leds-class.rst +++ b/Documentation/leds/leds-class.rst @@ -43,9 +43,73 @@ LED Device Naming Is currently of the form: - "devicename:colour:function" - -There have been calls for LED properties such as colour to be exported as + "devicename:color:function" + +- devicename: + it should refer to a unique identifier created by the kernel, + like e.g. phyN for network devices or inputN for input devices, rather + than to the hardware; the information related to the product and the bus + to which given device is hooked is available in sysfs and can be + retrieved using get_led_device_info.sh script from tools/leds; generally + this section is expected mostly for LEDs that are somehow associated with + other devices. + +- color: + one of LED_COLOR_ID_* definitions from the header + include/dt-bindings/leds/common.h. + +- function: + one of LED_FUNCTION_* definitions from the header + include/dt-bindings/leds/common.h. + +If required color or function is missing, please submit a patch +to linux-leds@vger.kernel.org. + +It is possible that more than one LED with the same color and function will +be required for given platform, differing only with an ordinal number. +In this case it is preferable to just concatenate the predefined LED_FUNCTION_* +name with required "-N" suffix in the driver. fwnode based drivers can use +function-enumerator property for that and then the concatenation will be handled +automatically by the LED core upon LED class device registration. + +LED subsystem has also a protection against name clash, that may occur +when LED class device is created by a driver of hot-pluggable device and +it doesn't provide unique devicename section. In this case numerical +suffix (e.g. "_1", "_2", "_3" etc.) is added to the requested LED class +device name. + +There might be still LED class drivers around using vendor or product name +for devicename, but this approach is now deprecated as it doesn't convey +any added value. Product information can be found in other places in sysfs +(see tools/leds/get_led_device_info.sh). + +Examples of proper LED names: + + - "red:disk" + - "white:flash" + - "red:indicator" + - "phy1:green:wlan" + - "phy3::wlan" + - ":kbd_backlight" + - "input5::kbd_backlight" + - "input3::numlock" + - "input3::scrolllock" + - "input3::capslock" + - "mmc1::status" + - "white:status" + +get_led_device_info.sh script can be used for verifying if the LED name +meets the requirements pointed out here. It performs validation of the LED class +devicename sections and gives hints on expected value for a section in case +the validation fails for it. So far the script supports validation +of associations between LEDs and following types of devices: + + - input devices + - ieee80211 compliant USB devices + +The script is open to extensions. + +There have been calls for LED properties such as color to be exported as individual led class attributes. As a solution which doesn't incur as much overhead, I suggest these become part of the device name. The naming scheme above leaves scope for further attributes should they be needed. If sections diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst index e93ec6645238..66e3792f8a36 100644 --- a/Documentation/locking/spinlocks.rst +++ b/Documentation/locking/spinlocks.rst @@ -139,18 +139,6 @@ on other CPU's, because an interrupt on another CPU doesn't interrupt the CPU that holds the lock, so the lock-holder can continue and eventually releases the lock). -Note that you can be clever with read-write locks and interrupts. For -example, if you know that the interrupt only ever gets a read-lock, then -you can use a non-irq version of read locks everywhere - because they -don't block on each other (and thus there is no dead-lock wrt interrupts. -But when you do the write-lock, you have to use the irq-safe version. - -For an example of being clever with rw-locks, see the "waitqueue_lock" -handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from -within an interrupt, they only read the queue in order to know whom to -wake up. So read-locks are safe (which is good: they are very common -indeed), while write-locks need to protect themselves against interrupts. - Linus ---- diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst index 3ea9827ba3c7..20e401413991 100644 --- a/Documentation/m68k/README.buddha +++ b/Documentation/m68k/buddha-driver.rst @@ -1,3 +1,6 @@ +===================================== +Amiga Buddha and Catweasel IDE Driver +===================================== The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by Geert Uytterhoeven based on the following specifications: @@ -12,12 +15,12 @@ described in their manuals, no tricks have been used (for example leaving some address lines out of the equations...). If you want to configure the board yourself (for example let a Linux kernel configure the card), look at the Commodore -Docs. Reading the nibbles should give this information: +Docs. Reading the nibbles should give this information:: -Vendor number: 4626 ($1212) -product number: 0 (42 for Catweasel Z-II) -Serial number: 0 -Rom-vector: $1000 + Vendor number: 4626 ($1212) + product number: 0 (42 for Catweasel Z-II) + Serial number: 0 + Rom-vector: $1000 The card should be a Z-II board, size 64K, not for freemem list, Rom-Vektor is valid, no second Autoconfig-board on the @@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-). The local memory-map is even active when mapped to $e8: +============== =========================================== $0-$7e Autokonfig-space, see Z-II docs. $80-$7fd reserved @@ -50,50 +54,51 @@ $a00-$aff IDE-Select 2 (Port 1, Register set 0) $b00-$bff IDE-Select 3 (Port 1, Register set 1) $c00-$cff IDE-Select 4 (Port 2, Register set 0, - Catweasel only!) + Catweasel only!) $d00-$dff IDE-Select 5 (Port 3, Register set 1, - Catweasel only!) + Catweasel only!) -$e00-$eff local expansion port, on Catweasel Z-II the +$e00-$eff local expansion port, on Catweasel Z-II the Catweasel registers are also mapped here. Never touch, use multidisk.device! - -$f00 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 0. + +$f00 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 0. $f01-$f3f mirror of $f00 -$f40 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 1. +$f40 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 1. $f41-$f7f mirror of $f40 -$f80 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 2. +$f80 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 2. (Catweasel only!) $f81-$fbf mirror of $f80 $fc0 write-only: Writing any value to this - register enables IRQs to be passed from the - IDE ports to the Zorro bus. This mechanism - has been implemented to be compatible with + register enables IRQs to be passed from the + IDE ports to the Zorro bus. This mechanism + has been implemented to be compatible with harddisks that are either defective or have - a buggy firmware and pull the IRQ line up - while starting up. If interrupts would - always be passed to the bus, the computer - might not start up. Once enabled, this flag - can not be disabled again. The level of the - flag can not be determined by software + a buggy firmware and pull the IRQ line up + while starting up. If interrupts would + always be passed to the bus, the computer + might not start up. Once enabled, this flag + can not be disabled again. The level of the + flag can not be determined by software (what for? Write to me if it's necessary!). $fc1-$fff mirror of $fc0 $1000-$ffff Buddha-Rom with offset $1000 in the rom - chip. The addresses $0 to $fff of the rom + chip. The addresses $0 to $fff of the rom chip cannot be read. Rom is Byte-wide and mapped to even addresses. +============== =========================================== The IDE ports issue an INT2. You can read the level of the IRQ-lines of the IDE-ports by reading from the three (two @@ -128,7 +133,8 @@ must always be set to 1 to be compatible with later Buddha versions (if I'll ever update this one). I presume that I'll never use the lower four bits, but they have to be set to 1 by definition. - The values in this table have to be shifted 5 bits to the + +The values in this table have to be shifted 5 bits to the left and or'd with $1f (this sets the lower 5 bits). All the timings have in common: Select and IOR/IOW rise at @@ -138,44 +144,36 @@ values are no multiple of 71. One clock-cycle is 71ns long (exactly 70,5 at 14,18 Mhz on PAL systems). value 0 (Default after reset) - -497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles) -(same timing as the Amiga 1200 does on it's IDE port without -accelerator card) + 497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles) + (same timing as the Amiga 1200 does on it's IDE port without + accelerator card) value 1 - -639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles) + 639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles) value 2 - -781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles) + 781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles) value 3 - -355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) + 355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) value 4 - -355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles) + 355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles) value 5 - -355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles) + 355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles) value 6 - -1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles) + 1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles) value 7 - -355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) + 355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) When accessing IDE registers with A6=1 (for example $84x), the timing will always be mode 0 8-bit compatible, no matter what you have selected in the speed register: -781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. +781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. All the timings with a very short select-signal (the 355ns fast accesses) depend on the accelerator card used in the @@ -204,7 +202,8 @@ always shows a "no IRQ here" on the Buddha, and accesses to the third IDE port are going into data's Nirwana on the Buddha. - Jens Schönfeld february 19th, 1997 - updated may 27th, 1997 - eMail: sysop@nostlgic.tng.oche.de +Jens Schönfeld february 19th, 1997 + +updated may 27th, 1997 +eMail: sysop@nostlgic.tng.oche.de diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst index 3a5ba7fe1703..b89cb6a86d9b 100644 --- a/Documentation/m68k/index.rst +++ b/Documentation/m68k/index.rst @@ -8,6 +8,7 @@ m68k Architecture :maxdepth: 2 kernel-options + buddha-driver .. only:: subproject and html diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst index 22b271de0304..1a2f99b67d25 100644 --- a/Documentation/maintainer/pull-requests.rst +++ b/Documentation/maintainer/pull-requests.rst @@ -29,7 +29,7 @@ request to. In order to create the pull request you must first tag the branch that you have just created. It is recommended that you choose a meaningful tag name, in a way that you and others can understand, even after some time. A good -practice is to include in the name an indicator of the sybsystem of origin +practice is to include in the name an indicator of the subsystem of origin and the target kernel version. Greg offers the following. A pull request with miscellaneous stuff for diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst index a7e75e2eba85..030a5c41ec75 100644 --- a/Documentation/media/kapi/csi2.rst +++ b/Documentation/media/kapi/csi2.rst @@ -49,9 +49,13 @@ where The transmitter drivers must, if possible, configure the CSI-2 transmitter to *LP-11 mode* whenever the transmitter is powered on but -not active. Some transmitters do this automatically but some have to -be explicitly programmed to do so, and some are unable to do so -altogether due to hardware constraints. +not active, and maintain *LP-11 mode* until stream on. Only at stream +on should the transmitter activate the clock on the clock lane and +transition to *HS mode*. + +Some transmitters do this automatically but some have to be explicitly +programmed to do so, and some are unable to do so altogether due to +hardware constraints. Stopping the transmitter ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,3 +76,10 @@ the transmitter up by using the :c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take place either indirectly by using :c:func:`v4l2_pipeline_pm_use` or directly. + +Formats +------- + +The media bus pixel codes document parallel formats. Should the pixel data be +transported over a serial bus, the media bus pixel code that describes a +parallel format that transfers a sample on a single clock cycle is used. diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index b359f1804bbe..4c5a15c53dbf 100644 --- a/Documentation/media/kapi/v4l2-dev.rst +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -288,6 +288,7 @@ Mask Description 0x08 Log the read and write file operations and the VIDIOC_QBUF and VIDIOC_DQBUF ioctls. 0x10 Log the poll file operation. +0x20 Log error and messages in the control operations. ===== ================================================================ Video device cleanup diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 1a901d8e1797..b68c01693939 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -20,6 +20,9 @@ data between userspace and kernelspace. Fundamentally, it is just a chardev file_operations defined on it. With respect to transporting raw IR and decoded scancodes to and fro, the essential fops are read, write and ioctl. +It is also possible to attach a BPF program to a LIRC device for decoding +raw IR into scancodes. + Example dmesg output upon a driver registering w/LIRC: .. code-block:: none @@ -34,6 +37,16 @@ What you should see for a chardev: $ ls -l /dev/lirc* crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 +Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ +contains tools for working with LIRC devices: + + - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC + device features. + + - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load + BPF IR decoders and test IR decoding. Some BPF IR decoders are also + provided. + .. _lirc_modes: ********** @@ -53,11 +66,12 @@ on the following table. For transmitting (aka sending), create a ``struct lirc_scancode`` with the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` - set the IR protocol, and all other members set to 0. Write this struct to - the lirc device. + set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other + members set to 0. Write this struct to the lirc device. - For receiving, you read ``struct lirc_scancode`` from the lirc device, - with ``scancode`` set to the received scancode and the IR protocol + For receiving, you read ``struct lirc_scancode`` from the LIRC device. + The ``scancode`` field is set to the received scancode and the + :ref:`IR protocol <Remote_controllers_Protocols>` is set in :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set in the ``keycode`` field, else it is set to ``KEY_RESERVED``. @@ -129,12 +143,29 @@ on the following table. This mode is used only for IR send. - -************************** -Remote Controller protocol -************************** - -An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the -supported IR protocols: - -.. kernel-doc:: include/uapi/linux/lirc.h +******************** +BPF based IR decoder +******************** + +The kernel has support for decoding the most common +:ref:`IR protocols <Remote_controllers_Protocols>`, but there +are many protocols which are not supported. To support these, it is possible +to load an BPF program which does the decoding. This can only be done on +LIRC devices which support reading raw IR. + +First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, +program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached +to the LIRC device, this program will be called for each pulse, space or +timeout event on the LIRC device. The context for the BPF program is a +pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` +value. When the program has decoded the scancode, it can be submitted using +the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer +movements can be reported using ``bpf_rc_pointer_rel()``. + +Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF +program, it can be attached to the LIRC device using the `bpf(2)`_ syscall. +The target must be the file descriptor for the LIRC device, and the +attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be +attached to a single LIRC device at a time. + +.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index a8fedfaaf0ab..256e520bc27e 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -62,7 +62,8 @@ read from the chardev. Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available, in this mode scancodes which are either decoded by software decoders, or by hardware decoders. The :c:type:`rc_proto` member is set to the -protocol used for transmission, and ``scancode`` to the decoded scancode, +:ref:`IR protocol <Remote_controllers_Protocols>` +used for transmission, and ``scancode`` to the decoded scancode, and the ``keycode`` set to the keycode or ``KEY_RESERVED``. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 6adf5ddbac99..eafe13203ea3 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -64,7 +64,8 @@ driver returns ``EINVAL``. When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one ``struct lirc_scancode`` must be written to the chardev at a time, else ``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, -and the protocol in the :c:type:`rc_proto`: member. All other members must be +and the :ref:`IR protocol <Remote_controllers_Protocols>` in the +:c:type:`rc_proto`: member. All other members must be set to 0, else ``EINVAL`` is returned. If there is no protocol encoder for the protocol or the scancode is not valid for the specified protocol, ``EINVAL`` is returned. The write function blocks until the scancode diff --git a/Documentation/media/uapi/rc/rc-protos.rst b/Documentation/media/uapi/rc/rc-protos.rst new file mode 100644 index 000000000000..b250ebe301d5 --- /dev/null +++ b/Documentation/media/uapi/rc/rc-protos.rst @@ -0,0 +1,456 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _Remote_controllers_Protocols: + +***************************************** +Remote Controller Protocols and Scancodes +***************************************** + +IR is encoded as a series of pulses and spaces, using a protocol. These +protocols can encode e.g. an address (which device should respond) and a +command: what it should do. The values for these are not always consistent +across different devices for a given protocol. + +Therefore out the output of the IR decoder is a scancode; a single u32 +value. Using keymap tables this can be mapped to linux key codes. + +Other things can be encoded too. Some IR protocols encode a toggle bit; this +is to distinguish whether the same button is being held down, or has been +released and pressed again. If has been released and pressed again, the +toggle bit will invert from one IR message to the next. + +Some remotes have a pointer-type device which can used to control the +mouse; some air conditioning systems can have their target temperature +target set in IR. + +The following are the protocols the kernel knows about and also lists +how scancodes are encoded for each protocol. + +rc-5 (RC_PROTO_RC5) +------------------- + +This IR protocol uses manchester encoding to encode 14 bits. There is a +detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php. + +The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5 +protocol, or the manchester BPF decoder. + +.. flat-table:: rc5 bits scancode mapping + :widths: 1 1 2 + + * - rc-5 bit + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 6 (inverted) + + - 2nd start bit in rc5, re-used as 6th command bit + + * - 1 + + - none + + - Toggle bit + + * - 5 + + - 8 to 13 + + - Address + + * - 6 + + - 0 to 5 + + - Command + +There is a variant of rc5 called either rc5x or extended rc5 +where there the second stop bit is the 6th commmand bit, but inverted. +This is done so it the scancodes and encoding is compatible with existing +schemes. This bit is stored in bit 6 of the scancode, inverted. This is +done to keep it compatible with plain rc-5 where there are two start bits. + +rc-5-sz (RC_PROTO_RC5_SZ) +------------------------- +This is much like rc-5 but one bit longer. The scancode is encoded +differently. + +.. flat-table:: rc-5-sz bits scancode mapping + :widths: 1 1 2 + + * - rc-5-sz bits + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 13 + + - Address bit + + * - 1 + + - none + + - Toggle bit + + * - 6 + + - 6 to 11 + + - Address + + * - 6 + + - 0 to 5 + + - Command + +rc-5x-20 (RC_PROTO_RC5X_20) +--------------------------- + +This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space +after the 8th bit. + +.. flat-table:: rc-5x-20 bits scancode mapping + :widths: 1 1 2 + + * - rc-5-sz bits + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 14 + + - Address bit + + * - 1 + + - none + + - Toggle bit + + * - 5 + + - 16 to 20 + + - Address + + * - 6 + + - 8 to 13 + + - Address + + * - 6 + + - 0 to 5 + + - Command + + +jvc (RC_PROTO_JVC) +------------------ + +The jvc protocol is much like nec, without the inverted values. It is +described here https://www.sbprojects.net/knowledge/ir/jvc.php. + +The scancode is a 16 bits value, where the address is the lower 8 bits +and the command the higher 8 bits; this is reversed from IR order. + +sony-12 (RC_PROTO_SONY12) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-12 bits scancode mapping + :widths: 1 1 2 + + * - sony-12 bits + + - scancode bit + + - description + + * - 5 + + - 16 to 20 + + - device + + * - 7 + + - 0 to 6 + + - function + +sony-15 (RC_PROTO_SONY15) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-12 bits scancode mapping + :widths: 1 1 2 + + * - sony-12 bits + + - scancode bit + + - description + + * - 8 + + - 16 to 23 + + - device + + * - 7 + + - 0 to 6 + + - function + +sony-20 (RC_PROTO_SONY20) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-20 bits scancode mapping + :widths: 1 1 2 + + * - sony-20 bits + + - scancode bit + + - description + + * - 5 + + - 16 to 20 + + - device + + * - 7 + + - 0 to 7 + + - device + + * - 8 + + - 8 to 15 + + - extended bits + +nec (RC_PROTO_NEC) +------------------ + +The nec protocol encodes an 8 bit address and an 8 bit command. It is +described here https://www.sbprojects.net/knowledge/ir/nec.php. Note +that the protocol sends least significant bit first. + +As a check, the nec protocol sends the address and command twice; the +second time it is inverted. This is done for verification. + +A plain nec IR message has 16 bits; the high 8 bits are the address +and the low 8 bits are the command. + +nec-x (RC_PROTO_NECX) +--------------------- + +Extended nec has a 16 bit address and a 8 bit command. This is encoded +as a 24 bit value as you would expect, with the lower 8 bits the command +and the upper 16 bits the address. + +nec-32 (RC_PROTO_NEC32) +----------------------- + +nec-32 does not send an inverted address or an inverted command; the +entire message, all 32 bits, are used. + +For this to be decoded correctly, the second 8 bits must not be the +inverted value of the first, and also the last 8 bits must not be the +inverted value of the third 8 bit value. + +The scancode has a somewhat unusual encoding. + +.. flat-table:: nec-32 bits scancode mapping + + * - nec-32 bits + + - scancode bit + + * - First 8 bits + + - 16 to 23 + + * - Second 8 bits + + - 24 to 31 + + * - Third 8 bits + + - 0 to 7 + + * - Fourth 8 bits + + - 8 to 15 + +sanyo (RC_PROTO_SANYO) +---------------------- + +The sanyo protocol is like the nec protocol, but with 13 bits address +rather than 8 bits. Both the address and the command are followed by +their inverted versions, but these are not present in the scancodes. + +Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8 +bits are the command. + +mcir2-kbd (RC_PROTO_MCIR2_KBD) +------------------------------ + +This protocol is generated by the Microsoft MCE keyboard for keyboard +events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. + +mcir2-mse (RC_PROTO_MCIR2_MSE) +------------------------------ + +This protocol is generated by the Microsoft MCE keyboard for pointer +events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. + +rc-6-0 (RC_PROTO_RC6_0) +----------------------- + +This is the rc-6 in mode 0. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 16 bits as in the protocol. There is also a +toggle bit. + +rc-6-6a-20 (RC_PROTO_RC6_6A_20) +------------------------------- + +This is the rc-6 in mode 6a, 20 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 20 bits +as in the protocol. There is also a toggle bit. + +rc-6-6a-24 (RC_PROTO_RC6_6A_24) +------------------------------- + +This is the rc-6 in mode 6a, 24 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 24 bits +as in the protocol. There is also a toggle bit. + +rc-6-6a-32 (RC_PROTO_RC6_6A_32) +------------------------------- + +This is the rc-6 in mode 6a, 32 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The upper 16 bits are the vendor, +and the lower 16 bits are the vendor-specific bits. This protocol is +for the non-Microsoft MCE variant (vendor != 0x800f). + + +rc-6-mce (RC_PROTO_RC6_MCE) +--------------------------- + +This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor, +and the lower 16 bits are the vendor-specific bits. This protocol is +for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the +protocol itself is ignored, and the 16th bit should be takes as the toggle +bit. + +sharp (RC_PROTO_SHARP) +---------------------- + +This is a protocol used by Sharp VCRs, is described here +https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long +(40ms) space between the normal and inverted values, and some IR receivers +cannot decode this. + +There is a 5 bit address and a 8 bit command. In the scancode the address is +in bits 8 to 12, and the command in bits 0 to 7. + +xmp (RC_PROTO_XMP) +------------------ + +This protocol has several versions and only version 1 is supported. Refer +to the decoder (ir-xmp-decoder.c) to see how it is encoded. + + +cec (RC_PROTO_CEC) +------------------ + +This is not an IR protocol, this is a protocol over CEC. The CEC +infrastructure uses rc-core for handling CEC commands, so that they +can easily be remapped. + +imon (RC_PROTO_IMON) +-------------------- + +This protocol is used by Antec Veris/SoundGraph iMON remotes. + +The protocol +describes both button presses and pointer movements. The protocol encodes +31 bits, and the scancode is simply the 31 bits with the top bit always 0. + +rc-mm-12 (RC_PROTO_RCMM12) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 12 bits. + +rc-mm-24 (RC_PROTO_RCMM24) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 24 bits. + +rc-mm-32 (RC_PROTO_RCMM32) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 32 bits. + +xbox-dvd (RC_PROTO_XBOX_DVD) +---------------------------- + +This protocol is used by XBox DVD Remote, which was made for the original +XBox. There is no in-kernel decoder or encoder for this protocol. The usb +device decodes the protocol. There is a BPF decoder available in v4l-utils. diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst index 3051f7abe11d..20e0f986df49 100644 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ b/Documentation/media/uapi/rc/remote_controllers.rst @@ -27,6 +27,7 @@ Part III - Remote Controller API rc-intro rc-sysfs-nodes + rc-protos rc-tables rc-table-change lirc-dev diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst index 8f4eb8823d82..ad2ff258afa8 100644 --- a/Documentation/media/uapi/v4l/biblio.rst +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -395,3 +395,13 @@ colimg :title: Color Imaging: Fundamentals and Applications :author: Erik Reinhard et al. + +.. _vp8: + +VP8 +=== + + +:title: RFC 6386: "VP8 Data Format and Decoding Guide" + +:author: J. Bankoski et al. diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index 71417bba028c..ef62e088ff7a 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -295,7 +295,7 @@ Control IDs Sets the alpha color component. When a capture device (or capture queue of a mem-to-mem device) produces a frame format that includes an alpha component (e.g. - :ref:`packed RGB image formats <rgb-formats>`) and the alpha value + :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value is not defined by the device or the mem-to-mem input data this control lets you select the alpha component value of all pixels. When an output device (or output queue of a mem-to-mem device) diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst new file mode 100644 index 000000000000..606b54947e10 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-decoder.rst @@ -0,0 +1,1101 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _decoder: + +************************************************* +Memory-to-Memory Stateful Video Decoder Interface +************************************************* + +A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in +display order. The decoder is expected not to require any additional information +from the client to process these buffers. + +Performing software parsing, processing etc. of the stream in the driver in +order to support this interface is strongly discouraged. In case such +operations are needed, use of the Stateless Video Decoder Interface (in +development) is strongly advised. + +Conventions and Notations Used in This Document +=============================================== + +1. The general V4L2 API rules apply if not specified in this document + otherwise. + +2. The meaning of words "must", "may", "should", etc. is as per `RFC + 2119 <https://tools.ietf.org/html/rfc2119>`_. + +3. All steps not marked "optional" are required. + +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used + interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`, + unless specified otherwise. + +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be + used interchangeably with multi-planar API, unless specified otherwise, + depending on decoder capabilities and following the general V4L2 guidelines. + +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = + [0..2]: i = 0, 1, 2. + +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE`` + queue containing data that resulted from processing buffer A. + +.. _decoder-glossary: + +Glossary +======== + +CAPTURE + the destination buffer queue; for decoders, the queue of buffers containing + decoded frames; for encoders, the queue of buffers containing an encoded + bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or + ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware + into ``CAPTURE`` buffers. + +client + the application communicating with the decoder or encoder implementing + this interface. + +coded format + encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see + also: raw format. + +coded height + height for given coded resolution. + +coded resolution + stream resolution in pixels aligned to codec and hardware requirements; + typically visible resolution rounded up to full macroblocks; + see also: visible resolution. + +coded width + width for given coded resolution. + +decode order + the order in which frames are decoded; may differ from display order if the + coded format includes a feature of frame reordering; for decoders, + ``OUTPUT`` buffers must be queued by the client in decode order; for + encoders ``CAPTURE`` buffers must be returned by the encoder in decode order. + +destination + data resulting from the decode process; see ``CAPTURE``. + +display order + the order in which frames must be displayed; for encoders, ``OUTPUT`` + buffers must be queued by the client in display order; for decoders, + ``CAPTURE`` buffers must be returned by the decoder in display order. + +DPB + Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded + raw frame available for reference in further decoding steps. + +EOS + end of stream. + +IDR + Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded + stream, which clears the list of earlier reference frames (DPBs). + +keyframe + an encoded frame that does not reference frames decoded earlier, i.e. + can be decoded fully on its own. + +macroblock + a processing unit in image and video compression formats based on linear + block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of + popular codecs the size is 16x16 samples (pixels). + +OUTPUT + the source buffer queue; for decoders, the queue of buffers containing + an encoded bytestream; for encoders, the queue of buffers containing raw + frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or + ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data + from ``OUTPUT`` buffers. + +PPS + Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream. + +raw format + uncompressed format containing raw pixel data (e.g. YUV, RGB formats). + +resume point + a point in the bytestream from which decoding may start/continue, without + any previous state/data present, e.g.: a keyframe (VP8/VP9) or + SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode + of a new stream, or to resume decoding after a seek. + +source + data fed to the decoder or encoder; see ``OUTPUT``. + +source height + height in pixels for given source resolution; relevant to encoders only. + +source resolution + resolution in pixels of source frames being source to the encoder and + subject to further cropping to the bounds of visible resolution; relevant to + encoders only. + +source width + width in pixels for given source resolution; relevant to encoders only. + +SPS + Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream. + +stream metadata + additional (non-visual) information contained inside encoded bytestream; + for example: coded resolution, visible resolution, codec profile. + +visible height + height for given visible resolution; display height. + +visible resolution + stream resolution of the visible picture, in pixels, to be used for + display purposes; must be smaller or equal to coded resolution; + display resolution. + +visible width + width for given visible resolution; display width. + +State Machine +============= + +.. kernel-render:: DOT + :alt: DOT digraph of decoder state machine + :caption: Decoder State Machine + + digraph decoder_state_machine { + node [shape = doublecircle, label="Decoding"] Decoding; + + node [shape = circle, label="Initialization"] Initialization; + node [shape = circle, label="Capture\nsetup"] CaptureSetup; + node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange; + node [shape = circle, label="Stopped"] Stopped; + node [shape = circle, label="Drain"] Drain; + node [shape = circle, label="Seek"] Seek; + node [shape = circle, label="End of Stream"] EoS; + + node [shape = point]; qi + qi -> Initialization [ label = "open()" ]; + + Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ]; + + CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ]; + + Decoding -> ResChange [ label = "Stream\nresolution\nchange" ]; + Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ]; + Decoding -> EoS [ label = "EoS mark\nin the stream" ]; + Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + Decoding -> Decoding; + + ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ]; + ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + + EoS -> Drain [ label = "Implicit\ndrain" ]; + + Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ]; + Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + + Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ]; + Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; + + Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ]; + Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + } + +Querying Capabilities +===================== + +1. To enumerate the set of coded formats supported by the decoder, the + client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. + + * The full set of supported formats will be returned, regardless of the + format set on ``CAPTURE``. + * Check the flags field of :c:type:`v4l2_fmtdesc` for more information + about the decoder's capabilities with respect to each coded format. + In particular whether or not the decoder has a full-fledged bytestream + parser and if the decoder supports dynamic resolution changes. + +2. To enumerate the set of supported raw formats, the client may call + :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. + + * Only the formats supported for the format currently active on ``OUTPUT`` + will be returned. + + * In order to enumerate raw formats supported by a given coded format, + the client must first set that coded format on ``OUTPUT`` and then + enumerate formats on ``CAPTURE``. + +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported + resolutions for a given format, passing desired pixel format in + :c:type:`v4l2_frmsizeenum` ``pixel_format``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel + format will include all possible coded resolutions supported by the + decoder for given coded pixel format. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format + will include all possible frame buffer resolutions supported by the + decoder for given raw pixel format and the coded format currently set on + ``OUTPUT``. + +4. Supported profiles and levels for the coded format currently set on + ``OUTPUT``, if applicable, may be queried using their respective controls + via :c:func:`VIDIOC_QUERYCTRL`. + +Initialization +============== + +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT` + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``pixelformat`` + a coded pixel format. + + ``width``, ``height`` + coded resolution of the stream; required only if it cannot be parsed + from the stream for the given coded format; otherwise the decoder will + use this resolution as a placeholder resolution that will likely change + as soon as it can parse the actual coded resolution from the stream. + + ``sizeimage`` + desired size of ``OUTPUT`` buffers; the decoder may adjust it to + match hardware requirements. + + other fields + follow standard semantics. + + * **Return fields:** + + ``sizeimage`` + adjusted size of ``OUTPUT`` buffers. + + * The ``CAPTURE`` format will be updated with an appropriate frame buffer + resolution instantly based on the width and height returned by + :c:func:`VIDIOC_S_FMT`. + However, for coded formats that include stream resolution information, + after the decoder is done parsing the information from the stream, it will + update the ``CAPTURE`` format with new values and signal a source change + event, regardless of whether they match the values set by the client or + not. + + .. important:: + + Changing the ``OUTPUT`` format may change the currently set ``CAPTURE`` + format. How the new ``CAPTURE`` format is determined is up to the decoder + and the client must ensure it matches its needs afterwards. + +2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on + ``OUTPUT``. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``memory`` + follows standard semantics. + + * **Return fields:** + + ``count`` + the actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be + used to have more control over buffer allocation. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``memory`` + follows standard semantics. + + ``format`` + follows standard semantics. + + * **Return fields:** + + ``count`` + adjusted to the number of allocated buffers. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + +3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`. + +4. **This step only applies to coded formats that contain resolution information + in the stream.** Continue queuing/dequeuing bytestream buffers to/from the + ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The + buffers will be processed and returned to the client in order, until + required metadata to configure the ``CAPTURE`` queue are found. This is + indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with + ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``. + + * It is not an error if the first buffer does not contain enough data for + this to occur. Processing of the buffers will continue as long as more + data is needed. + + * If data in a buffer that triggers the event is required to decode the + first frame, it will not be returned to the client, until the + initialization sequence completes and the frame is decoded. + + * If the client has not set the coded resolution of the stream on its own, + calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`, + :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE`` + queue will not return the real values for the stream until a + ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled. + + .. important:: + + Any client query issued after the decoder queues the event will return + values applying to the just parsed stream, including queue formats, + selection rectangles and controls. + + .. note:: + + A client capable of acquiring stream parameters from the bytestream on + its own may attempt to set the width and height of the ``OUTPUT`` format + to non-zero values matching the coded size of the stream, skip this step + and continue with the `Capture Setup` sequence. However, it must not + rely on any driver queries regarding stream parameters, such as + selection rectangles and controls, since the decoder has not parsed them + from the stream yet. If the values configured by the client do not match + those parsed by the decoder, a `Dynamic Resolution Change` will be + triggered to reconfigure them. + + .. note:: + + No decoded frames are produced during this phase. + +5. Continue with the `Capture Setup` sequence. + +Capture Setup +============= + +1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the + destination buffers parsed/decoded from the bytestream. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + * **Return fields:** + + ``width``, ``height`` + frame buffer resolution for the decoded frames. + + ``pixelformat`` + pixel format for decoded frames. + + ``num_planes`` (for _MPLANE ``type`` only) + number of planes for pixelformat. + + ``sizeimage``, ``bytesperline`` + as per standard semantics; matching frame buffer format. + + .. note:: + + The value of ``pixelformat`` may be any pixel format supported by the + decoder for the current stream. The decoder should choose a + preferred/optimal format for the default configuration. For example, a + YUV format may be preferred over an RGB format if an additional + conversion step would be required for the latter. + +2. **Optional.** Acquire the visible resolution via + :c:func:`VIDIOC_G_SELECTION`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``target`` + set to ``V4L2_SEL_TGT_COMPOSE``. + + * **Return fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the visible rectangle; it must fit within the frame buffer resolution + returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``. + + * The following selection targets are supported on ``CAPTURE``: + + ``V4L2_SEL_TGT_CROP_BOUNDS`` + corresponds to the coded resolution of the stream. + + ``V4L2_SEL_TGT_CROP_DEFAULT`` + the rectangle covering the part of the ``CAPTURE`` buffer that + contains meaningful picture data (visible area); width and height + will be equal to the visible resolution of the stream. + + ``V4L2_SEL_TGT_CROP`` + the rectangle within the coded resolution to be output to + ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on + hardware without additional compose/scaling capabilities. + + ``V4L2_SEL_TGT_COMPOSE_BOUNDS`` + the maximum rectangle within a ``CAPTURE`` buffer, which the cropped + frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the + hardware does not support compose/scaling. + + ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` + equal to ``V4L2_SEL_TGT_CROP``. + + ``V4L2_SEL_TGT_COMPOSE`` + the rectangle inside a ``CAPTURE`` buffer into which the cropped + frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; + read-only on hardware without additional compose/scaling capabilities. + + ``V4L2_SEL_TGT_COMPOSE_PADDED`` + the rectangle inside a ``CAPTURE`` buffer which is overwritten by the + hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not + write padding pixels. + + .. warning:: + + The values are guaranteed to be meaningful only after the decoder + successfully parses the stream metadata. The client must not rely on the + query before that happens. + +3. **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on + the ``CAPTURE`` queue. Once the stream information is parsed and known, the + client may use this ioctl to discover which raw formats are supported for + given stream and select one of them via :c:func:`VIDIOC_S_FMT`. + + .. important:: + + The decoder will return only formats supported for the currently + established coded format, as per the ``OUTPUT`` format and/or stream + metadata parsed in this initialization sequence, even if more formats + may be supported by the decoder in general. In other words, the set + returned will be a subset of the initial query mentioned in the + `Querying Capabilities` section. + + For example, a decoder may support YUV and RGB formats for resolutions + 1920x1088 and lower, but only YUV for higher resolutions (due to + hardware limitations). After parsing a resolution of 1920x1088 or lower, + :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats, + but after parsing resolution higher than 1920x1088, the decoder will not + return RGB, unsupported for this resolution. + + However, subsequent resolution change event triggered after + discovering a resolution change within the same stream may switch + the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT` + would return RGB formats again in that case. + +4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the + ``CAPTURE`` queue. The client may choose a different format than + selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``pixelformat`` + a raw pixel format. + + ``width``, ``height`` + frame buffer resolution of the decoded stream; typically unchanged from + what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different + if the hardware supports composition and/or scaling. + + * Setting the ``CAPTURE`` format will reset the compose selection rectangles + to their default values, based on the new resolution, as described in the + previous step. + +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on + the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or + scaling capabilities. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``target`` + set to ``V4L2_SEL_TGT_COMPOSE``. + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the rectangle inside a ``CAPTURE`` buffer into which the cropped + frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; + read-only on hardware without additional compose/scaling capabilities. + + * **Return fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the visible rectangle; it must fit within the frame buffer resolution + returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``. + + .. warning:: + + The decoder may adjust the compose rectangle to the nearest + supported one to meet codec and hardware requirements. The client needs + to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. + +6. If all the following conditions are met, the client may resume the decoding + instantly: + + * ``sizeimage`` of the new format (determined in previous steps) is less + than or equal to the size of currently allocated buffers, + + * the number of buffers currently allocated is greater than or equal to the + minimum number of buffers acquired in previous steps. To fulfill this + requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new + buffers. + + In that case, the remaining steps do not apply and the client may resume + the decoding by one of the following actions: + + * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD` + with the ``V4L2_DEC_CMD_START`` command, + + * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON` + on the ``CAPTURE`` queue. + + However, if the client intends to change the buffer set, to lower + memory usage or for any other reasons, it may be achieved by following + the steps below. + +7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing + buffers on the ``CAPTURE`` queue until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued. + +8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF` + on the ``CAPTURE`` queue to stop streaming. + + .. warning:: + + The ``OUTPUT`` queue must remain streaming. Calling + :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a + seek. + +9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE`` + buffers using :c:func:`VIDIOC_REQBUFS`. + + * **Required fields:** + + ``count`` + set to 0. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the + ``CAPTURE`` queue. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + + * **Return fields:** + + ``count`` + actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate more than the minimum number of buffers (for pipeline + depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` + control to get the minimum number of buffers required, and pass the + obtained value plus the number of additional buffers needed in the + ``count`` field to :c:func:`VIDIOC_REQBUFS`. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be + used to have more control over buffer allocation. For example, by + allocating buffers larger than the current ``CAPTURE`` format, future + resolution changes can be accommodated. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + + ``format`` + a format representing the maximum framebuffer resolution to be + accommodated by newly allocated buffers. + + * **Return fields:** + + ``count`` + adjusted to the number of allocated buffers. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate buffers for a format different than parsed from the stream + metadata, the client must proceed as follows, before the metadata + parsing is initiated: + + * set width and height of the ``OUTPUT`` format to desired coded resolution to + let the decoder configure the ``CAPTURE`` format appropriately, + + * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it + until this step. + + The format obtained in the query may be then used with + :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers. + +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding + frames. + +Decoding +======== + +This state is reached after the `Capture Setup` sequence finishes successfully. +In this state, the client queues and dequeues buffers to both queues via +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard +semantics. + +The content of the source ``OUTPUT`` buffers depends on the active coded pixel +format and may be affected by codec-specific extended controls, as stated in +the documentation of each format. + +Both queues operate independently, following the standard behavior of V4L2 +buffer queues and memory-to-memory devices. In addition, the order of decoded +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded +format, e.g. frame reordering. + +The client must not assume any direct relationship between ``CAPTURE`` +and ``OUTPUT`` buffers and any specific timing of buffers becoming +available to dequeue. Specifically: + +* a buffer queued to ``OUTPUT`` may result in no buffers being produced + on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only + metadata syntax structures are present in it), + +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced + on ``CAPTURE`` (if the encoded data contained more than one frame, or if + returning a decoded frame allowed the decoder to return a frame that + preceded it in decode, but succeeded it in the display order), + +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on + ``CAPTURE`` later into decode process, and/or after processing further + ``OUTPUT`` buffers, or be returned out of order, e.g. if display + reordering is used, + +* buffers may become available on the ``CAPTURE`` queue without additional + buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the + ``OUTPUT`` buffers queued in the past whose decoding results are only + available at later time, due to specifics of the decoding process. + +.. note:: + + To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they + originated from, the client can set the ``timestamp`` field of the + :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The + ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer + will have their ``timestamp`` field set to the same value when dequeued. + + In addition to the straightforward case of one ``OUTPUT`` buffer producing + one ``CAPTURE`` buffer, the following cases are defined: + + * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same + ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers. + + * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of + the ``OUTPUT`` buffer queued first will be copied. + + * the decoding order differs from the display order (i.e. the ``CAPTURE`` + buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE`` + timestamps will not retain the order of ``OUTPUT`` timestamps. + +During the decoding, the decoder may initiate one of the special sequences, as +listed below. The sequences will result in the decoder returning all the +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed +before the sequence started. Last of the buffers will have the +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client +must check if there is any pending event and: + +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution + Change` sequence needs to be followed, + +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs + to be followed. + +Some of the sequences can be intermixed with each other and need to be handled +as they happen. The exact operation is documented for each sequence. + +Should a decoding error occur, it will be reported to the client with the level +of details depending on the decoder capabilities. Specifically: + +* the CAPTURE buffer that contains the results of the failed decode operation + will be returned with the V4L2_BUF_FLAG_ERROR flag set, + +* if the decoder is able to precisely report the OUTPUT buffer that triggered + the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag + set. + +In case of a fatal failure that does not allow the decoding to continue, any +further operations on corresponding decoder file handle will return the -EIO +error code. The client may close the file handle and open a new one, or +alternatively reinitialize the instance by stopping streaming on both queues, +releasing all buffers and performing the Initialization sequence again. + +Seek +==== + +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data. +The seek does not require any specific operation on the ``CAPTURE`` queue, but +it may be affected as per normal decoder operation. + +1. Stop the ``OUTPUT`` queue to begin the seek sequence via + :c:func:`VIDIOC_STREAMOFF`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + * The decoder will drop all the pending ``OUTPUT`` buffers and they must be + treated as returned to the client (following standard semantics). + +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON` + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + * The decoder will start accepting new source bytestream buffers after the + call returns. + +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT`` + queue until a suitable resume point is found. + + .. note:: + + There is no requirement to begin queuing coded data starting exactly + from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT`` + buffers will be processed and returned to the client until a suitable + resume point is found. While looking for a resume point, the decoder + should not produce any decoded frames into ``CAPTURE`` buffers. + + Some hardware is known to mishandle seeks to a non-resume point. Such an + operation may result in an unspecified number of corrupted decoded frames + being made available on the ``CAPTURE`` queue. Drivers must ensure that + no fatal decoding errors or crashes occur, and implement any necessary + handling and workarounds for hardware issues related to seek operations. + + .. warning:: + + In case of the H.264/HEVC codec, the client must take care not to seek + over a change of SPS/PPS. Even though the target frame could be a + keyframe, the stale SPS/PPS inside decoder state would lead to undefined + results when decoding. Although the decoder must handle that case without + a crash or a fatal decode error, the client must not expect a sensible + decode output. + + If the hardware can detect such corrupted decoded frames, then + corresponding buffers will be returned to the client with the + V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further + description of decode error reporting. + +4. After a resume point is found, the decoder will start returning ``CAPTURE`` + buffers containing decoded frames. + +.. important:: + + A seek may result in the `Dynamic Resolution Change` sequence being + initiated, due to the seek target having decoding parameters different from + the part of the stream decoded before the seek. The sequence must be handled + as per normal decoder operation. + +.. warning:: + + It is not specified when the ``CAPTURE`` queue starts producing buffers + containing decoded data from the ``OUTPUT`` buffers queued after the seek, + as it operates independently from the ``OUTPUT`` queue. + + The decoder may return a number of remaining ``CAPTURE`` buffers containing + decoded frames originating from the ``OUTPUT`` buffers queued before the + seek sequence is performed. + + The ``VIDIOC_STREAMOFF`` operation discards any remaining queued + ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers + queued before the seek sequence may have matching ``CAPTURE`` buffers + produced. For example, given the sequence of operations on the + ``OUTPUT`` queue: + + QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H), + + any of the following results on the ``CAPTURE`` queue is allowed: + + {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}. + + To determine the CAPTURE buffer containing the first decoded frame after the + seek, the client may observe the timestamps to match the CAPTURE and OUTPUT + buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the + decoder. + +.. note:: + + To achieve instantaneous seek, the client may restart streaming on the + ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers. + +Dynamic Resolution Change +========================= + +Streams that include resolution metadata in the bytestream may require switching +to a different resolution during the decoding. + +.. note:: + + Not all decoders can detect resolution changes. Those that do set the + ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when + :c:func:`VIDIOC_ENUM_FMT` is called. + +The sequence starts when the decoder detects a coded frame with one or more of +the following parameters different from those previously established (and +reflected by corresponding queries): + +* coded resolution (``OUTPUT`` width and height), + +* visible resolution (selection rectangles), + +* the minimum number of buffers needed for decoding. + +Whenever that happens, the decoder must proceed as follows: + +1. After encountering a resolution change in the stream, the decoder sends a + ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION``. + + .. important:: + + Any client query issued after the decoder queues the event will return + values applying to the stream after the resolution change, including + queue formats, selection rectangles and controls. + +2. The decoder will then process and decode all remaining buffers from before + the resolution change point. + + * The last buffer from before the change must be marked with the + ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above. + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused`` + = 0) and in that case it must be ignored by the client, as it does not + contain a decoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked + with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + +The client must continue the sequence as described below to continue the +decoding process. + +1. Dequeue the source change event. + + .. important:: + + A source change triggers an implicit decoder drain, similar to the + explicit `Drain` sequence. The decoder is stopped after it completes. + The decoding process must be resumed with either a pair of calls to + :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the + ``V4L2_DEC_CMD_START`` command. + +2. Continue with the `Capture Setup` sequence. + +.. note:: + + During the resolution change sequence, the ``OUTPUT`` queue must remain + streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would + abort the sequence and initiate a seek. + + In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE`` + queue and this remains true for the duration of the entire resolution change + sequence as well. + + The client should, for best performance and simplicity, keep queuing/dequeuing + buffers to/from the ``OUTPUT`` queue even while processing this sequence. + +Drain +===== + +To ensure that all queued ``OUTPUT`` buffers have been processed and related +``CAPTURE`` buffers are given to the client, the client must follow the drain +sequence described below. After the drain sequence ends, the client has +received all decoded frames for all ``OUTPUT`` buffers queued before the +sequence was started. + +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`. + + * **Required fields:** + + ``cmd`` + set to ``V4L2_DEC_CMD_STOP``. + + ``flags`` + set to 0. + + ``pts`` + set to 0. + + .. warning:: + + The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` + queues are streaming. For compatibility reasons, the call to + :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is + not streaming, but at the same time it will not initiate the `Drain` + sequence and so the steps described below would not be applicable. + +2. Any ``OUTPUT`` buffers queued by the client before the + :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as + normal. The client must continue to handle both queues independently, + similarly to normal decode operation. This includes: + + * handling any operations triggered as a result of processing those buffers, + such as the `Dynamic Resolution Change` sequence, before continuing with + the drain sequence, + + * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued, + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` + ``bytesused`` = 0) and in that case it must be ignored by the client, + as it does not contain a decoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer + marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + + * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued + before the ``V4L2_DEC_CMD_STOP`` command are dequeued, + + * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it. + + .. note:: + + For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS`` + event when the last frame has been decoded and all frames are ready to be + dequeued. It is a deprecated behavior and the client must not rely on it. + The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. + +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call + are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is + stopped and it will accept, but not process, any newly queued ``OUTPUT`` + buffers until the client issues any of the following operations: + + * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume + operation normally, with all the state from before the drain, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue - the decoder will resume the operation normally, + however any ``CAPTURE`` buffers still in the queue will be returned to the + client, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``OUTPUT`` queue - any pending source buffers will be returned to the + client and the `Seek` sequence will be triggered. + +.. note:: + + Once the drain sequence is initiated, the client needs to drive it to + completion, as described by the steps above, unless it aborts the process by + issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` + queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or + ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they + will fail with -EBUSY error code if attempted. + + Although mandatory, the availability of decoder commands may be queried + using :c:func:`VIDIOC_TRY_DECODER_CMD`. + +End of Stream +============= + +If the decoder encounters an end of stream marking in the stream, the decoder +will initiate the `Drain` sequence, which the client must handle as described +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`. + +Commit Points +============= + +Setting formats and allocating buffers trigger changes in the behavior of the +decoder. + +1. Setting the format on the ``OUTPUT`` queue may change the set of formats + supported/advertised on the ``CAPTURE`` queue. In particular, it also means + that the ``CAPTURE`` format may be reset and the client must not rely on the + previously set format being preserved. + +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats + supported for the current ``OUTPUT`` format. + +3. Setting the format on the ``CAPTURE`` queue does not change the list of + formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE`` + format that is not supported for the currently selected ``OUTPUT`` format + will result in the decoder adjusting the requested ``CAPTURE`` format to a + supported one. + +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of + supported coded formats, irrespectively of the current ``CAPTURE`` format. + +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, + the client must not change the format on the ``OUTPUT`` queue. Drivers will + return the -EBUSY error code for any such format change attempt. + +To summarize, setting formats and allocation must always start with the +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the +set of supported formats for the ``CAPTURE`` queue. diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst index 67a980818dc8..caa05f5f6380 100644 --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst @@ -39,4 +39,10 @@ file handle is visible through another file handle). One of the most common memory-to-memory device is the codec. Codecs are more complicated than most and require additional setup for their codec parameters. This is done through codec controls. -See :ref:`mpeg-controls`. +See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory +devices are given in the following sections. + +.. toctree:: + :maxdepth: 1 + + dev-decoder diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index d6ea2ffd65c5..bc5dd8e76567 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -1748,6 +1748,14 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - ``size`` - * - __u32 + - ``start_byte_offset`` + Offset (in bytes) from the beginning of the OUTPUT buffer to the start + of the slice. If the slice starts with a start code, then this is the + offset to such start code. When operating in slice-based decoding mode + (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should + be set to 0. When operating in frame-based decoding mode, this field + should be 0 for the first slice. + * - __u32 - ``header_bit_size`` - * - __u16 @@ -1930,19 +1938,13 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - * - __u16 - ``num_slices`` - - Number of slices needed to decode the current frame + - Number of slices needed to decode the current frame/field. When + operating in slice-based decoding mode (see + :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field + should always be set to one. * - __u16 - ``nal_ref_idc`` - NAL reference ID value coming from the NAL Unit header - * - __u8 - - ``ref_pic_list_p0[32]`` - - Backward reference list used by P-frames in the original bitstream order - * - __u8 - - ``ref_pic_list_b0[32]`` - - Backward reference list used by B-frames in the original bitstream order - * - __u8 - - ``ref_pic_list_b1[32]`` - - Forward reference list used by B-frames in the original bitstream order * - __s32 - ``top_field_order_cnt`` - Picture Order Count for the coded top field @@ -2021,6 +2023,83 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - 0x00000004 - The DPB entry is a long term reference frame +``V4L2_CID_MPEG_VIDEO_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. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_h264_decode_mode + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + In this mode, ``num_slices`` field in struct + :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1, + and ``start_byte_offset`` in struct + :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + In this mode, ``num_slices`` field in struct + :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number + of slices in the frame, and ``start_byte_offset`` in struct + :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly + for each slice. For the first slice, ``start_byte_offset`` should + be zero. + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + +``V4L2_CID_MPEG_VIDEO_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 + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_h264_start_code + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. + * - ``V4L2_MPEG_VIDEO_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. + .. _v4l2-mpeg-mpeg2: ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` @@ -2234,6 +2313,329 @@ 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 diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst index 7d8e9efbeb1e..9e097f34cb74 100644 --- a/Documentation/media/uapi/v4l/hist-v4l2.rst +++ b/Documentation/media/uapi/v4l/hist-v4l2.rst @@ -900,7 +900,7 @@ V4L2 in Linux 2.6.19 :ref:`VIDIOC_ENUM_FRAMEINTERVALS` were added. -3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was +3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was added. diff --git a/Documentation/media/uapi/v4l/pixfmt-bayer.rst b/Documentation/media/uapi/v4l/pixfmt-bayer.rst new file mode 100644 index 000000000000..cfa2f4e3e114 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-bayer.rst @@ -0,0 +1,38 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _pixfmt-bayer: + +***************** +Raw Bayer Formats +***************** + +Description +=========== + +The raw Bayer formats are used by image sensors before much if any processing is +performed on the image. The formats contain green, red and blue components, with +alternating lines of red and green, and blue and green pixels in different +orders. See also `the Wikipedia article on Bayer filter +<https://en.wikipedia.org/wiki/Bayer_filter>`__. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-srggb8 + pixfmt-srggb10 + pixfmt-srggb10p + pixfmt-srggb10alaw8 + pixfmt-srggb10dpcm8 + pixfmt-srggb10-ipu3 + pixfmt-srggb12 + pixfmt-srggb12p + pixfmt-srggb14p + pixfmt-srggb16 diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index 4b701fc7653e..292fdc116c77 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -41,7 +41,12 @@ Compressed Formats - ``V4L2_PIX_FMT_H264`` - 'H264' - - H264 video elementary stream with start codes. + - H264 Access Unit. + The decoder expects one Access Unit per buffer. + The encoder generates one Access Unit per buffer. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-H264-NO-SC: - ``V4L2_PIX_FMT_H264_NO_SC`` @@ -52,16 +57,19 @@ Compressed Formats - ``V4L2_PIX_FMT_H264_MVC`` - 'M264' - H264 MVC video elementary stream. - * .. _V4L2-PIX-FMT-H264-SLICE-RAW: + * .. _V4L2-PIX-FMT-H264-SLICE: - - ``V4L2_PIX_FMT_H264_SLICE_RAW`` + - ``V4L2_PIX_FMT_H264_SLICE`` - 'S264' - H264 parsed slice data, without the start code and as extracted from the H264 bitstream. This format is adapted for stateless video decoders that implement an H264 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). - Metadata associated with the frame to decode are required to - be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, + This pixelformat has two modifiers that must be set at least once + through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE`` + and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls. + In addition, metadata associated with the frame to decode are + required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, ``V4L2_CID_MPEG_VIDEO_H264_PPS``, ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``, ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and @@ -86,12 +94,20 @@ Compressed Formats - ``V4L2_PIX_FMT_MPEG1`` - 'MPG1' - - MPEG1 video elementary stream. + - MPEG1 Picture. Each buffer starts with a Picture header, followed + by other headers as needed and ending with the Picture data. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-MPEG2: - ``V4L2_PIX_FMT_MPEG2`` - 'MPG2' - - MPEG2 video elementary stream. + - MPEG2 Picture. Each buffer starts with a Picture header, followed + by other headers as needed and ending with the Picture data. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-MPEG2-SLICE: - ``V4L2_PIX_FMT_MPEG2_SLICE`` @@ -132,17 +148,46 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8`` - 'VP80' - - VP8 video elementary stream. + - VP8 compressed video frame. The encoder generates one + compressed frame per buffer, and the decoder requires one + compressed frame per buffer. + * .. _V4L2-PIX-FMT-VP8-FRAME: + + - ``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`). + 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>`. + 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`` - 'VP90' - - VP9 video elementary stream. + - VP9 compressed video frame. The encoder generates one + compressed frame per buffer, and the decoder requires one + compressed frame per buffer. * .. _V4L2-PIX-FMT-HEVC: - ``V4L2_PIX_FMT_HEVC`` - 'HEVC' - - HEVC/H.265 video elementary stream. + - HEVC/H.265 Access Unit. + The decoder expects one Access Unit per buffer. + The encoder generates one Access Unit per buffer. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` @@ -150,6 +195,8 @@ Compressed Formats - Video elementary stream using a codec based on the Fast Walsh Hadamard Transform. This codec is implemented by the vicodec ('Virtual Codec') driver. See the codec-fwht.h header for more details. + :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + since the decoder can parse all the information from the raw bytestream. * .. _V4L2-PIX-FMT-FWHT-STATELESS: - ``V4L2_PIX_FMT_FWHT_STATELESS`` diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst deleted file mode 100644 index 738bb14c0ee2..000000000000 --- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst +++ /dev/null @@ -1,1306 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _packed-rgb: - -****************** -Packed RGB formats -****************** - -Description -=========== - -These formats are designed to match the pixel formats of typical PC -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. -These are all packed-pixel formats, meaning all the data for a pixel lie -next to each other in memory. - -.. raw:: latex - - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|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}| - - -.. _rgb-formats: - -.. flat-table:: Packed RGB Image Formats - :header-rows: 2 - :stub-columns: 0 - - * - Identifier - - Code - - :cspan:`7` Byte 0 in memory - - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - :cspan:`7` Byte 3 - * - - - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-RGB332: - - - ``V4L2_PIX_FMT_RGB332`` - - 'RGB1' - - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ARGB444: - - - ``V4L2_PIX_FMT_ARGB444`` - - 'AR12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XRGB444: - - - ``V4L2_PIX_FMT_XRGB444`` - - 'XR12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGBA444: - - - ``V4L2_PIX_FMT_RGBA444`` - - 'RA12' - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGBX444: - - - ``V4L2_PIX_FMT_RGBX444`` - - 'RX12' - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ABGR444: - - - ``V4L2_PIX_FMT_ABGR444`` - - 'AB12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XBGR444: - - - ``V4L2_PIX_FMT_XBGR444`` - - 'XB12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGRA444: - - - ``V4L2_PIX_FMT_BGRA444`` - - 'BA12' - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGRX444: - - - ``V4L2_PIX_FMT_BGRX444`` - - 'BX12' - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ARGB555: - - - ``V4L2_PIX_FMT_ARGB555`` - - 'AR15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-XRGB555: - - - ``V4L2_PIX_FMT_XRGB555`` - - 'XR15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-RGBA555: - - - ``V4L2_PIX_FMT_RGBA555`` - - 'RA15' - - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - a - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-RGBX555: - - - ``V4L2_PIX_FMT_RGBX555`` - - 'RX15' - - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-ABGR555: - - - ``V4L2_PIX_FMT_ABGR555`` - - 'AB15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-XBGR555: - - - ``V4L2_PIX_FMT_XBGR555`` - - 'XB15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-BGRA555: - - - ``V4L2_PIX_FMT_BGRA555`` - - 'BA15' - - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - a - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-BGRX555: - - - ``V4L2_PIX_FMT_BGRX555`` - - 'BX15' - - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-RGB565: - - - ``V4L2_PIX_FMT_RGB565`` - - 'RGBP' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-ARGB555X: - - - ``V4L2_PIX_FMT_ARGB555X`` - - 'AR15' | (1 << 31) - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XRGB555X: - - - ``V4L2_PIX_FMT_XRGB555X`` - - 'XR15' | (1 << 31) - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB565X: - - - ``V4L2_PIX_FMT_RGB565X`` - - 'RGBR' - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR24: - - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB24: - - - ``V4L2_PIX_FMT_RGB24`` - - 'RGB3' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR666: - - - ``V4L2_PIX_FMT_BGR666`` - - 'BGRH' - - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-ABGR32: - - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-XBGR32: - - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-BGRA32: - - - ``V4L2_PIX_FMT_BGRA32`` - - 'RA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-BGRX32: - - - ``V4L2_PIX_FMT_BGRX32`` - - 'RX24' - - - - - - - - - - - - - - - - - - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBA32: - - - ``V4L2_PIX_FMT_RGBA32`` - - 'AB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBX32: - - - ``V4L2_PIX_FMT_RGBX32`` - - 'XB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-ARGB32: - - - ``V4L2_PIX_FMT_ARGB32`` - - 'BA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - * .. _V4L2-PIX-FMT-XRGB32: - - - ``V4L2_PIX_FMT_XRGB32`` - - 'BX24' - - - - - - - - - - - - - - - - - - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - -.. raw:: latex - - \endgroup - -.. note:: Bit 7 is the most significant bit. - -The usage and value of the alpha bits (a) in the ARGB and ABGR formats -(collectively referred to as alpha formats) depend on the device type -and hardware operation. :ref:`Capture <capture>` devices (including -capture queues of mem-to-mem devices) fill the alpha component in -memory. When the device outputs an alpha channel the alpha component -will have a meaningful value. Otherwise, when the device doesn't output -an alpha channel but can set the alpha bit to a user-configurable value, -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control -is used to specify that alpha value, and the alpha component of all -pixels will be set to the value specified by that control. Otherwise a -corresponding format without an alpha component (XRGB or XBGR) must be -used instead of an alpha format. - -:ref:`Output <output>` devices (including output queues of mem-to-mem -devices and :ref:`video output overlay <osd>` devices) read the alpha -component from memory. When the device processes the alpha channel the -alpha component must be filled with meaningful values by applications. -Otherwise a corresponding format without an alpha component (XRGB or -XBGR) must be used instead of an alpha format. - -The XRGB and XBGR formats contain undefined bits (-). Applications, -devices and drivers must ignore those bits, for both -:ref:`capture` and :ref:`output` devices. - -**Byte Order.** -Each cell is one byte. - - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|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:: RGB byte order - :header-rows: 0 - :stub-columns: 0 - :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 - - * - start + 0: - - B\ :sub:`00` - - G\ :sub:`00` - - R\ :sub:`00` - - B\ :sub:`01` - - G\ :sub:`01` - - R\ :sub:`01` - - B\ :sub:`02` - - G\ :sub:`02` - - R\ :sub:`02` - - B\ :sub:`03` - - G\ :sub:`03` - - R\ :sub:`03` - * - start + 12: - - B\ :sub:`10` - - G\ :sub:`10` - - R\ :sub:`10` - - B\ :sub:`11` - - G\ :sub:`11` - - R\ :sub:`11` - - B\ :sub:`12` - - G\ :sub:`12` - - R\ :sub:`12` - - B\ :sub:`13` - - G\ :sub:`13` - - R\ :sub:`13` - * - start + 24: - - B\ :sub:`20` - - G\ :sub:`20` - - R\ :sub:`20` - - B\ :sub:`21` - - G\ :sub:`21` - - R\ :sub:`21` - - B\ :sub:`22` - - G\ :sub:`22` - - R\ :sub:`22` - - B\ :sub:`23` - - G\ :sub:`23` - - R\ :sub:`23` - * - start + 36: - - B\ :sub:`30` - - G\ :sub:`30` - - R\ :sub:`30` - - B\ :sub:`31` - - G\ :sub:`31` - - R\ :sub:`31` - - B\ :sub:`32` - - G\ :sub:`32` - - R\ :sub:`32` - - B\ :sub:`33` - - G\ :sub:`33` - - R\ :sub:`33` - -.. raw:: latex - - \normalsize - -Formats defined in :ref:`rgb-formats-deprecated` are deprecated and -must not be used by new drivers. They are documented here for reference. -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in -either the corresponding ARGB or XRGB format, depending on the driver. - - -.. raw:: latex - - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|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}| - -.. _rgb-formats-deprecated: - -.. flat-table:: Deprecated Packed RGB Image Formats - :header-rows: 2 - :stub-columns: 0 - - * - Identifier - - Code - - :cspan:`7` Byte 0 in memory - - - :cspan:`7` Byte 1 - - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-RGB444: - - - ``V4L2_PIX_FMT_RGB444`` - - 'R444' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB555: - - - ``V4L2_PIX_FMT_RGB555`` - - 'RGBO' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-RGB555X: - - - ``V4L2_PIX_FMT_RGB555X`` - - 'RGBQ' - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR32: - - - ``V4L2_PIX_FMT_BGR32`` - - 'BGR4' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGB32: - - - ``V4L2_PIX_FMT_RGB32`` - - 'RGB4' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - -.. raw:: latex - - \endgroup - -A test utility to determine which RGB formats a driver actually supports -is available from the LinuxTV v4l-dvb repository. See -`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access -instructions. diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst index 48ab80024835..4ce305cc45da 100644 --- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -13,18 +13,1292 @@ RGB Formats *********** +Description +=========== -.. toctree:: - :maxdepth: 1 - - pixfmt-packed-rgb - pixfmt-srggb8 - pixfmt-srggb10 - pixfmt-srggb10p - pixfmt-srggb10alaw8 - pixfmt-srggb10dpcm8 - pixfmt-srggb10-ipu3 - pixfmt-srggb12 - pixfmt-srggb12p - pixfmt-srggb14p - pixfmt-srggb16 +These formats are designed to match the pixel formats of typical PC +graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. +These are all packed-pixel formats, meaning all the data for a pixel lie +next to each other in memory. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|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}| + + +.. flat-table:: RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGB332: + + - ``V4L2_PIX_FMT_RGB332`` + - 'RGB1' + + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ARGB444: + + - ``V4L2_PIX_FMT_ARGB444`` + - 'AR12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XRGB444: + + - ``V4L2_PIX_FMT_XRGB444`` + - 'XR12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBA444: + + - ``V4L2_PIX_FMT_RGBA444`` + - 'RA12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBX444: + + - ``V4L2_PIX_FMT_RGBX444`` + - 'RX12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + - + - + - + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ABGR444: + + - ``V4L2_PIX_FMT_ABGR444`` + - 'AB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XBGR444: + + - ``V4L2_PIX_FMT_XBGR444`` + - 'XB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRA444: + + - ``V4L2_PIX_FMT_BGRA444`` + - 'BA12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRX444: + + - ``V4L2_PIX_FMT_BGRX444`` + - 'BX12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ARGB555: + + - ``V4L2_PIX_FMT_ARGB555`` + - 'AR15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XRGB555: + + - ``V4L2_PIX_FMT_XRGB555`` + - 'XR15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-RGBA555: + + - ``V4L2_PIX_FMT_RGBA555`` + - 'RA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGBX555: + + - ``V4L2_PIX_FMT_RGBX555`` + - 'RX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-ABGR555: + + - ``V4L2_PIX_FMT_ABGR555`` + - 'AB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XBGR555: + + - ``V4L2_PIX_FMT_XBGR555`` + - 'XB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-BGRA555: + + - ``V4L2_PIX_FMT_BGRA555`` + - 'BA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-BGRX555: + + - ``V4L2_PIX_FMT_BGRX555`` + - 'BX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGB565: + + - ``V4L2_PIX_FMT_RGB565`` + - 'RGBP' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-ARGB555X: + + - ``V4L2_PIX_FMT_ARGB555X`` + - 'AR15' | (1 << 31) + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XRGB555X: + + - ``V4L2_PIX_FMT_XRGB555X`` + - 'XR15' | (1 << 31) + + - + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB565X: + + - ``V4L2_PIX_FMT_RGB565X`` + - 'RGBR' + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR24: + + - ``V4L2_PIX_FMT_BGR24`` + - 'BGR3' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB24: + + - ``V4L2_PIX_FMT_RGB24`` + - 'RGB3' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR666: + + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + - + - + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-ABGR32: + + - ``V4L2_PIX_FMT_ABGR32`` + - 'AR24' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-BGRA32: + + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-BGRX32: + + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' + + - + - + - + - + - + - + - + - + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBA32: + + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBX32: + + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-ARGB32: + + - ``V4L2_PIX_FMT_ARGB32`` + - 'BA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _V4L2-PIX-FMT-XRGB32: + + - ``V4L2_PIX_FMT_XRGB32`` + - 'BX24' + + - + - + - + - + - + - + - + - + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + +.. note:: Bit 7 is the most significant bit. + +The usage and value of the alpha bits (a) in the ARGB and ABGR formats +(collectively referred to as alpha formats) depend on the device type +and hardware operation. :ref:`Capture <capture>` devices (including +capture queues of mem-to-mem devices) fill the alpha component in +memory. When the device outputs an alpha channel the alpha component +will have a meaningful value. Otherwise, when the device doesn't output +an alpha channel but can set the alpha bit to a user-configurable value, +the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control +is used to specify that alpha value, and the alpha component of all +pixels will be set to the value specified by that control. Otherwise a +corresponding format without an alpha component (XRGB or XBGR) must be +used instead of an alpha format. + +:ref:`Output <output>` devices (including output queues of mem-to-mem +devices and :ref:`video output overlay <osd>` devices) read the alpha +component from memory. When the device processes the alpha channel the +alpha component must be filled with meaningful values by applications. +Otherwise a corresponding format without an alpha component (XRGB or +XBGR) must be used instead of an alpha format. + +The XRGB and XBGR formats contain undefined bits (-). Applications, +devices and drivers must ignore those bits, for both +:ref:`capture` and :ref:`output` devices. + +**Byte Order.** +Each cell is one byte. + + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|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:: RGB byte order + :header-rows: 0 + :stub-columns: 0 + :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 + + * - start + 0: + - B\ :sub:`00` + - G\ :sub:`00` + - R\ :sub:`00` + - B\ :sub:`01` + - G\ :sub:`01` + - R\ :sub:`01` + - B\ :sub:`02` + - G\ :sub:`02` + - R\ :sub:`02` + - B\ :sub:`03` + - G\ :sub:`03` + - R\ :sub:`03` + * - start + 12: + - B\ :sub:`10` + - G\ :sub:`10` + - R\ :sub:`10` + - B\ :sub:`11` + - G\ :sub:`11` + - R\ :sub:`11` + - B\ :sub:`12` + - G\ :sub:`12` + - R\ :sub:`12` + - B\ :sub:`13` + - G\ :sub:`13` + - R\ :sub:`13` + * - start + 24: + - B\ :sub:`20` + - G\ :sub:`20` + - R\ :sub:`20` + - B\ :sub:`21` + - G\ :sub:`21` + - R\ :sub:`21` + - B\ :sub:`22` + - G\ :sub:`22` + - R\ :sub:`22` + - B\ :sub:`23` + - G\ :sub:`23` + - R\ :sub:`23` + * - start + 36: + - B\ :sub:`30` + - G\ :sub:`30` + - R\ :sub:`30` + - B\ :sub:`31` + - G\ :sub:`31` + - R\ :sub:`31` + - B\ :sub:`32` + - G\ :sub:`32` + - R\ :sub:`32` + - B\ :sub:`33` + - G\ :sub:`33` + - R\ :sub:`33` + +.. raw:: latex + + \normalsize + +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and +must not be used by new drivers. They are documented here for reference. +The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in +either the corresponding ARGB or XRGB format, depending on the driver. + + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|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}| + +.. _pixfmt-rgb-deprecated: + +.. flat-table:: Deprecated Packed RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + + - :cspan:`7` Byte 1 + + - :cspan:`7` Byte 2 + + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGB444: + + - ``V4L2_PIX_FMT_RGB444`` + - 'R444' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB555: + + - ``V4L2_PIX_FMT_RGB555`` + - 'RGBO' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-RGB555X: + + - ``V4L2_PIX_FMT_RGB555X`` + - 'RGBQ' + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR32: + + - ``V4L2_PIX_FMT_BGR32`` + - 'BGR4' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-RGB32: + + - ``V4L2_PIX_FMT_RGB32`` + - 'RGB4' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + +A test utility to determine which RGB formats a driver actually supports +is available from the LinuxTV v4l-dvb repository. See +`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access +instructions. diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst index da6da2ef139a..a8321c348bf8 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -39,12 +39,17 @@ Single-planar format structure to a multiple of the scale factor of any smaller planes. For example when the image format is YUV 4:2:0, ``width`` and ``height`` must be multiples of two. + + For compressed formats that contain the resolution information encoded + inside the stream, when fed to a stateful mem2mem decoder, the fields + may be zero to rely on the decoder to detect the right values. For more + details see :ref:`decoder` and format descriptions. * - __u32 - ``pixelformat`` - The pixel format or type of compression, set by the application. This is a little endian :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard - RGB formats in :ref:`rgb-formats`, YUV formats in + RGB formats in :ref:`pixfmt-rgb`, YUV formats in :ref:`yuv-formats`, and reserved codes in :ref:`reserved-formats` * - __u32 diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst index 29be001796db..a7d4cd43a298 100644 --- a/Documentation/media/uapi/v4l/pixfmt.rst +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -31,6 +31,7 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.) pixfmt-intro pixfmt-indexed pixfmt-rgb + pixfmt-bayer yuv-formats hsv-formats depth-formats diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index ab1a48a5ae80..7b8e17c7b68b 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -85,6 +85,14 @@ formats in memory (a raw Bayer image won't be magically converted to JPEG just by storing it to memory), there is no one-to-one correspondence between them. +The media bus pixel codes document parallel formats. Should the pixel data be +transported over a serial bus, the media bus pixel code that describes a +parallel format that transfers a sample on a single clock cycle is used. For +instance, both MEDIA_BUS_FMT_BGR888_1X24 and MEDIA_BUS_FMT_BGR888_3X8 are used +on parallel busses for transferring an 8 bits per sample BGR data, whereas on +serial busses the data in this format is only referred to using +MEDIA_BUS_FMT_BGR888_1X24. This is because there is effectively only a single +way to transport that format on the serial busses. Packed RGB Formats ^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst index 004ec00db6bd..97015b9b40b8 100644 --- a/Documentation/media/uapi/v4l/v4l2.rst +++ b/Documentation/media/uapi/v4l/v4l2.rst @@ -60,6 +60,10 @@ Authors, in alphabetical order: - Original author of the V4L2 API and documentation. +- Figa, Tomasz <tfiga@chromium.org> + + - Documented the memory-to-memory decoder interface. + - H Schimek, Michael <mschimek@gmx.at> - Original author of the V4L2 API and documentation. @@ -68,6 +72,10 @@ Authors, in alphabetical order: - Documented the Digital Video timings API. +- Osciak, Pawel <posciak@chromium.org> + + - Documented the memory-to-memory decoder interface. + - Osciak, Pawel <pawel@osciak.com> - Designed and documented the multi-planar API. @@ -92,7 +100,7 @@ Authors, in alphabetical order: - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API. -**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari. +**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa Except when explicitly stated as GPL, programming examples within this part can be used and distributed without restrictions. diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst index ccf83b05afa7..57f0066f4cff 100644 --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` call sends an implicit START command to the decoder if it has not been -started yet. +started yet. Applies to both queues of mem2mem decoders. A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP -command to the decoder, and all buffered data is discarded. +command to the decoder, and all buffered data is discarded. Applies to both +queues of mem2mem decoders. -These ioctls are optional, not all drivers may support them. They were -introduced in Linux 3.3. +In principle, these ioctls are optional, not all drivers may support them. They were +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}| @@ -167,26 +169,32 @@ introduced in Linux 3.3. ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be muted when playing back at a non-standard speed. + + For a device implementing the :ref:`decoder`, once the drain sequence + is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. The command may be also used to restart the + decoder in case of an implicit stop initiated by the decoder itself, + without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See + :ref:`decoder` for more details. * - ``V4L2_DEC_CMD_STOP`` - 1 - Stop the decoder. When the decoder is already stopped, this command does nothing. This command has two flags: if ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set the picture to black after it stopped decoding. Otherwise the last - image will repeat. mem2mem decoders will stop producing new frames - altogether. They will send a ``V4L2_EVENT_EOS`` event when the - last frame has been decoded and all frames are ready to be - dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on - the last buffer of the capture queue to indicate there will be no - new buffers produced to dequeue. This buffer may be empty, - indicated by the driver setting the ``bytesused`` field to 0. Once - the ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. If + image will repeat. If ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops immediately (ignoring the ``pts`` value), otherwise it will keep decoding until timestamp >= pts or until the last of the pending data from its internal buffers was decoded. + + For a device implementing the :ref:`decoder`, the command will initiate + the drain sequence as documented in :ref:`decoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. * - ``V4L2_DEC_CMD_PAUSE`` - 2 - Pause the decoder. When the decoder has not been started yet, the @@ -209,6 +217,11 @@ On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. +EBUSY + A drain sequence of a device implementing the :ref:`decoder` is still in + progress. It is not allowed to issue another decoder command until it + completes. + EINVAL The ``cmd`` field is invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst index dea9c0cc00ab..42659a3d1705 100644 --- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst +++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst @@ -389,14 +389,19 @@ call. decoder. Applications will have to query the new resolution (if any, the signal may also have been lost). + For stateful decoders follow the guidelines in :ref:`decoder`. + Video Capture devices have to query the new timings using + :ref:`VIDIOC_QUERY_DV_TIMINGS` or + :ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>`. + *Important*: even if the new video timings appear identical to the old ones, receiving this event indicates that there was an issue with the video signal and you must stop and restart streaming (:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is - that many devices are not able to recover from a temporary loss of - signal and so restarting streaming I/O is required in order for the - hardware to synchronize to the video signal. + that many Video Capture devices are not able to recover from a temporary + loss of signal and so restarting streaming I/O is required in order for + the hardware to synchronize to the video signal. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst index 822d6730e7d2..399ef1062bac 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -127,6 +127,22 @@ one until ``EINVAL`` is returned. - This format is not native to the device but emulated through software (usually libv4l2), where possible try to use a native format instead for better performance. + * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + - 0x0004 + - The hardware decoder for this compressed bytestream format (aka coded + format) is capable of parsing a continuous bytestream. Applications do + not need to parse the bytestream themselves to find the boundaries + between frames/fields. This flag can only be used in combination with + the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed + formats only. This flag is valid for stateful decoders only. + * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` + - 0x0008 + - Dynamic resolution switching is supported by the device for this + compressed bytestream format (aka coded format). It will notify the user + via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video + parameters are detected. This flag can only be used in combination + with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. It is also only applies to stateful codecs. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index dc500632095d..a3d56ffbf4cc 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -39,8 +39,8 @@ Arguments File descriptor returned by :ref:`open() <func-open>`. ``argp`` - Pointer to struct :c:type:`v4l2_queryctl`, :c:type:`v4l2_query_ext_ctrl` - or :c:type`v4l2_querymenu` (depending on the ioctl). + Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` + or :c:type:`v4l2_querymenu` (depending on the ioctl). Description diff --git a/Documentation/media/v4l-drivers/imx7.rst b/Documentation/media/v4l-drivers/imx7.rst index fe411f65c01c..1e442c97da47 100644 --- a/Documentation/media/v4l-drivers/imx7.rst +++ b/Documentation/media/v4l-drivers/imx7.rst @@ -41,7 +41,7 @@ data from MIPI CSI-2 camera sensor. It has one source pad, corresponding to the virtual channel 0. This module is compliant to previous version of Samsung D-phy, and supports two D-PHY Rx Data lanes. -csi_mux +csi-mux ------- This is the video multiplexer. It has two sink pads to select from either camera @@ -56,7 +56,7 @@ can interface directly with Parallel and MIPI CSI-2 buses. It has 256 x 64 FIFO to store received image pixel data and embedded DMA controllers to transfer data from the FIFO through AHB bus. -This entity has one sink pad that receives from the csi_mux entity and a single +This entity has one sink pad that receives from the csi-mux entity and a single source pad that routes video frames directly to memory buffers. This pad is routed to a capture device node. @@ -81,14 +81,14 @@ an output of 800x600, and BGGR 10 bit bayer format: # Setup links media-ctl -l "'ov2680 1-0036':0 -> 'imx7-mipi-csis.0':0[1]" - media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi_mux':1[1]" - media-ctl -l "'csi_mux':2 -> 'csi':0[1]" + media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi-mux':1[1]" + media-ctl -l "'csi-mux':2 -> 'csi':0[1]" media-ctl -l "'csi':1 -> 'csi capture':0[1]" # Configure pads for pipeline media-ctl -V "'ov2680 1-0036':0 [fmt:SBGGR10_1X10/800x600 field:none]" - media-ctl -V "'csi_mux':1 [fmt:SBGGR10_1X10/800x600 field:none]" - media-ctl -V "'csi_mux':2 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi-mux':1 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi-mux':2 [fmt:SBGGR10_1X10/800x600 field:none]" media-ctl -V "'imx7-mipi-csis.0':0 [fmt:SBGGR10_1X10/800x600 field:none]" media-ctl -V "'csi':0 [fmt:SBGGR10_1X10/800x600 field:none]" @@ -97,64 +97,63 @@ the resolutions supported by the sensor. .. code-block:: none - root@imx7s-warp:~# media-ctl -p - Media controller API version 4.17.0 - - Media device information - ------------------------ - driver imx-media - model imx-media - serial - bus info - hw revision 0x0 - driver version 4.17.0 - - Device topology - - entity 1: csi (2 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev0 - pad0: Sink - [fmt:SBGGR10_1X10/800x600 field:none] - <- "csi_mux":2 [ENABLED] - pad1: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "csi capture":0 [ENABLED] - - - entity 4: csi capture (1 pad, 1 link) - type Node subtype V4L flags 0 - device node name /dev/video0 - pad0: Sink - <- "csi":1 [ENABLED] - - - entity 10: csi_mux (3 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev1 - pad0: Sink - [fmt:unknown/0x0] - pad1: Sink - [fmt:unknown/800x600 field:none] - <- "imx7-mipi-csis.0":1 [ENABLED] - pad2: Source - [fmt:unknown/800x600 field:none] - -> "csi":0 [ENABLED] - - - entity 14: imx7-mipi-csis.0 (2 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev2 - pad0: Sink - [fmt:SBGGR10_1X10/800x600 field:none] - <- "ov2680 1-0036":0 [ENABLED] - pad1: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "csi_mux":1 [ENABLED] - - - entity 17: ov2680 1-0036 (1 pad, 1 link) - type V4L2 subdev subtype Sensor flags 0 - device node name /dev/v4l-subdev3 - pad0: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "imx7-mipi-csis.0":0 [ENABLED] - + # media-ctl -p + Media controller API version 5.2.0 + + Media device information + ------------------------ + driver imx7-csi + model imx-media + serial + bus info + hw revision 0x0 + driver version 5.2.0 + + Device topology + - entity 1: csi (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range] + <- "csi-mux":2 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range] + -> "csi capture":0 [ENABLED] + + - entity 4: csi capture (1 pad, 1 link) + type Node subtype V4L flags 0 + device node name /dev/video0 + pad0: Sink + <- "csi":1 [ENABLED] + + - entity 10: csi-mux (3 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev1 + pad0: Sink + [fmt:Y8_1X8/1x1 field:none] + pad1: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "imx7-mipi-csis.0":1 [ENABLED] + pad2: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi":0 [ENABLED] + + - entity 14: imx7-mipi-csis.0 (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev2 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "ov2680 1-0036":0 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi-mux":1 [ENABLED] + + - entity 17: ov2680 1-0036 (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SBGGR10_1X10/800x600@1/30 field:none colorspace:srgb] + -> "imx7-mipi-csis.0":0 [ENABLED] References ---------- diff --git a/Documentation/media/v4l-drivers/vimc.rst b/Documentation/media/v4l-drivers/vimc.rst index 4628b12d417f..406417680db5 100644 --- a/Documentation/media/v4l-drivers/vimc.rst +++ b/Documentation/media/v4l-drivers/vimc.rst @@ -15,7 +15,7 @@ recompile the driver to achieve your own topology. This is the default topology: .. _vimc_topology_graph: .. kernel-figure:: vimc.dot - :alt: vimc.dot + :alt: Diagram of the default media pipeline topology :align: center Media pipeline graph on vimc @@ -96,3 +96,14 @@ those arguments to each subdevice, not to the vimc module. For example:: Window size to calculate the mean. Note: the window size needs to be an odd number, as the main pixel stays in the center of the window, otherwise the next odd number is considered (the default value is 3). + +Source code documentation +------------------------- + +vimc-streamer +~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.h + :internal: + +.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.c diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index 55cbe324b9fc..adeb6b7a15cb 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -180,15 +180,17 @@ replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA reserved-formats # V4L2 format flags replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags +replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags +replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags -# V4L2 tymecode types +# V4L2 timecode types replace define V4L2_TC_TYPE_24FPS timecode-type replace define V4L2_TC_TYPE_25FPS timecode-type replace define V4L2_TC_TYPE_30FPS timecode-type replace define V4L2_TC_TYPE_50FPS timecode-type replace define V4L2_TC_TYPE_60FPS timecode-type -# V4L2 tymecode flags +# V4L2 timecode flags replace define V4L2_TC_FLAG_DROPFRAME timecode-flags replace define V4L2_TC_FLAG_COLORFRAME timecode-flags replace define V4L2_TC_USERBITS_field timecode-flags diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst index ff675a1b1422..2f9c2cff6738 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/au1xxx_ide.rst @@ -1,7 +1,14 @@ -README for MIPS AU1XXX IDE driver - Released 2005-07-15 +.. include:: <isonum.txt> + +====================== +MIPS AU1XXX IDE driver +====================== + +Released 2005-07-15 + +About +===== -ABOUT ------ This file describes the 'drivers/ide/au1xxx-ide.c', related files and the services they provide. @@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST' section. -LICENSE -------- +License +======= -Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions +:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR @@ -35,31 +42,35 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE +Note: + for more information, please refer "AMD Alchemy Au1200/Au1550 IDE Interface and Linux Device Driver" Application Note. -FILES, CONFIGS AND COMPATIBILITY --------------------------------- +Files, Configs and Compatibility +================================ Two files are introduced: a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h' contains : struct _auide_hwif - timing parameters for PIO mode 0/1/2/3/4 - timing parameters for MWDMA 0/1/2 + + - timing parameters for PIO mode 0/1/2/3/4 + - timing parameters for MWDMA 0/1/2 b) 'drivers/ide/mips/au1xxx-ide.c' contains the functionality of the AU1XXX IDE driver Following extra configs variables are introduced: - CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode - CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode + CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA + - enable the PIO+DBDMA mode + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA + - enable the MWDMA mode -SUPPORTED IDE MODES -------------------- +Supported IDE Modes +=================== The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode. @@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g. -X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0. -PERFORMANCE CONFIGURATIONS --------------------------- +Performance Configurations +========================== -If the used system doesn't need USB support enable the following kernel configs: +If the used system doesn't need USB support enable the following kernel +configs:: -CONFIG_IDE=y -CONFIG_BLK_DEV_IDE=y -CONFIG_IDE_GENERIC=y -CONFIG_BLK_DEV_IDEPCI=y -CONFIG_BLK_DEV_GENERIC=y -CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_BLK_DEV_IDE_AU1XXX=y -CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y -CONFIG_BLK_DEV_IDEDMA=y + CONFIG_IDE=y + CONFIG_BLK_DEV_IDE=y + CONFIG_IDE_GENERIC=y + CONFIG_BLK_DEV_IDEPCI=y + CONFIG_BLK_DEV_GENERIC=y + CONFIG_BLK_DEV_IDEDMA_PCI=y + CONFIG_BLK_DEV_IDE_AU1XXX=y + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y + CONFIG_BLK_DEV_IDEDMA=y Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable the burst support on DBDMA controller. @@ -90,20 +102,22 @@ the burst support on DBDMA controller. If the used system need the USB support enable the following kernel configs for high IDE to USB throughput. -CONFIG_IDE_GENERIC=y -CONFIG_BLK_DEV_IDEPCI=y -CONFIG_BLK_DEV_GENERIC=y -CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_BLK_DEV_IDE_AU1XXX=y -CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y -CONFIG_BLK_DEV_IDEDMA=y +:: + + CONFIG_IDE_GENERIC=y + CONFIG_BLK_DEV_IDEPCI=y + CONFIG_BLK_DEV_GENERIC=y + CONFIG_BLK_DEV_IDEDMA_PCI=y + CONFIG_BLK_DEV_IDE_AU1XXX=y + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y + CONFIG_BLK_DEV_IDEDMA=y Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to disable the burst support on DBDMA controller. -ACKNOWLEDGMENTS ---------------- +Acknowledgments +=============== These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX IDE driver from AMD. @@ -112,4 +126,5 @@ Additional input also from: Matthias Lenk <matthias.lenk@amd.com> Happy hacking! + Enrico Walther <enrico.walther@amd.com> diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst new file mode 100644 index 000000000000..fd9023c8a89f --- /dev/null +++ b/Documentation/mips/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +MIPS architecture +================= + +.. toctree:: + :maxdepth: 2 + + au1xxx_ide + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index a57f92dfe49a..f11c5daeada5 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -20,3 +20,4 @@ fit into other categories. isl29003 lis3lv02d max6875 + xilinx_sdfec diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index eeedc2e826aa..83f7ae5fc045 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -153,10 +153,12 @@ an example, if the UMEM is 64k and each chunk is 4k, then the UMEM has Frames passed to the kernel are used for the ingress path (RX rings). -The user application produces UMEM addrs to this ring. Note that the -kernel will mask the incoming addr. E.g. for a chunk size of 2k, the -log2(2048) LSB of the addr will be masked off, meaning that 2048, 2050 -and 3000 refers to the same chunk. +The user application produces UMEM addrs to this ring. Note that, if +running the application with aligned chunk mode, the kernel will mask +the incoming addr. E.g. for a chunk size of 2k, the log2(2048) LSB of +the addr will be masked off, meaning that 2048, 2050 and 3000 refers +to the same chunk. If the user application is run in the unaligned +chunks mode, then the incoming addr will be left untouched. UMEM Completion Ring diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst index 757ccfaa1385..07afc8063d4d 100644 --- a/Documentation/networking/caif/README +++ b/Documentation/networking/caif/caif.rst @@ -1,18 +1,31 @@ -Copyright (C) ST-Ericsson AB 2010 -Author: Sjur Brendeland/ sjur.brandeland@stericsson.com -License terms: GNU General Public License (GPL) version 2 ---------------------------------------------------------- +:orphan: -=== Start === -If you have compiled CAIF for modules do: +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> -$modprobe crc_ccitt -$modprobe caif -$modprobe caif_socket -$modprobe chnl_net +================ +Using Linux CAIF +================ -=== Preparing the setup with a STE modem === + +:Copyright: |copy| ST-Ericsson AB 2010 + +:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com + +Start +===== + +If you have compiled CAIF for modules do:: + + $modprobe crc_ccitt + $modprobe caif + $modprobe caif_socket + $modprobe chnl_net + + +Preparing the setup with a STE modem +==================================== If you are working on integration of CAIF you should make sure that the kernel is built with module support. @@ -32,24 +45,30 @@ module parameter "ser_use_stx". Normally Frame Checksum is always used on UART, but this is also provided as a module parameter "ser_use_fcs". -$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes -$ ifconfig caif_ttyS0 up +:: + + $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes + $ ifconfig caif_ttyS0 up -PLEASE NOTE: There is a limitation in Android shell. +PLEASE NOTE: + There is a limitation in Android shell. It only accepts one argument to insmod/modprobe! -=== Trouble shooting === +Trouble shooting +================ There are debugfs parameters provided for serial communication. /sys/kernel/debug/caif_serial/<tty-name>/ * ser_state: Prints the bit-mask status where + - 0x02 means SENDING, this is a transient state. - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent - and is blocking further send operation. Flow OFF has been propagated - to all CAIF Channels using this TTY. + and is blocking further send operation. Flow OFF has been propagated + to all CAIF Channels using this TTY. * tty_status: Prints the bit-mask tty status information + - 0x01 - tty->warned is on. - 0x02 - tty->low_latency is on. - 0x04 - tty->packed is on. @@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication. - 0x20 - tty->stopped is on. * last_tx_msg: Binary blob Prints the last transmitted frame. - This can be printed with + + This can be printed with:: + $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg. - The first two tx messages sent look like this. Note: The initial - byte 02 is start of frame extension (STX) used for re-syncing - upon errors. - - Enumeration: + The first two tx messages sent look like this. Note: The initial + byte 02 is start of frame extension (STX) used for re-syncing + upon errors. + + - Enumeration:: + 0000000 02 05 00 00 03 01 d2 02 | | | | | | STX(1) | | | | @@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication. Command:Enumeration(1) Link-ID(1) Checksum(2) - - Channel Setup: + + - Channel Setup:: + 0000000 02 07 00 00 00 21 a1 00 48 df | | | | | | | | STX(1) | | | | | | @@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication. Checksum(2) * last_rx_msg: Prints the last transmitted frame. - The RX messages for LinkSetup look almost identical but they have the - bit 0x20 set in the command bit, and Channel Setup has added one byte - before Checksum containing Channel ID. - NOTE: Several CAIF Messages might be concatenated. The maximum debug + + The RX messages for LinkSetup look almost identical but they have the + bit 0x20 set in the command bit, and Channel Setup has added one byte + before Checksum containing Channel ID. + + NOTE: + Several CAIF Messages might be concatenated. The maximum debug buffer size is 128 bytes. -== Error Scenarios: +Error Scenarios +=============== + - last_tx_msg contains channel setup message and last_rx_msg is empty -> The host seems to be able to send over the UART, at least the CAIF ldisc get notified that sending is completed. @@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication. - if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there might be problems transmitting over UART. + E.g. host and modem wiring is not correct you will typically see tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT). + You will probably see the enumeration message in last_tx_message and empty last_rx_message. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 2b7fefe72351..f51f92571e39 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -23,8 +23,9 @@ Contents: intel/ice google/gve mellanox/mlx5 + pensando/ionic -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst index 2d0c3baa1752..cfc08842e32c 100644 --- a/Documentation/networking/device_drivers/intel/iavf.rst +++ b/Documentation/networking/device_drivers/intel/iavf.rst @@ -10,11 +10,15 @@ Copyright(c) 2013-2018 Intel Corporation. Contents ======== +- Overview - Identifying Your Adapter - Additional Configurations - Known Issues/Troubleshooting - Support +Overview +======== + This file describes the iavf Linux* Base Driver. This driver was formerly called i40evf. @@ -27,6 +31,7 @@ The guest OS loading the iavf driver must support MSI-X interrupts. Identifying Your Adapter ======================== + The driver in this kernel is compatible with devices based on the following: * Intel(R) XL710 X710 Virtual Function * Intel(R) X722 Virtual Function @@ -50,9 +55,10 @@ Link messages will not be displayed to the console if the distribution is restricting system messages. In order to see network driver link messages on your console, set dmesg to eight by entering the following:: - dmesg -n 8 + # dmesg -n 8 -NOTE: This setting is not saved across reboots. +NOTE: + This setting is not saved across reboots. ethtool ------- @@ -72,11 +78,11 @@ then requests from that VF to set VLAN tag stripping will be ignored. To enable/disable VLAN tag stripping for a VF, issue the following command from inside the VM in which you are running the VF:: - ethtool -K <if_name> rxvlan on/off + # ethtool -K <if_name> rxvlan on/off or alternatively:: - ethtool --offload <if_name> rxvlan on/off + # ethtool --offload <if_name> rxvlan on/off Adaptive Virtual Function ------------------------- @@ -91,21 +97,21 @@ additional features depending on what features are available in the PF with which the AVF is associated. The following are base mode features: - 4 Queue Pairs (QP) and associated Configuration Status Registers (CSRs) - for Tx/Rx. -- i40e descriptors and ring format. -- Descriptor write-back completion. -- 1 control queue, with i40e descriptors, CSRs and ring format. -- 5 MSI-X interrupt vectors and corresponding i40e CSRs. -- 1 Interrupt Throttle Rate (ITR) index. -- 1 Virtual Station Interface (VSI) per VF. + for Tx/Rx +- i40e descriptors and ring format +- Descriptor write-back completion +- 1 control queue, with i40e descriptors, CSRs and ring format +- 5 MSI-X interrupt vectors and corresponding i40e CSRs +- 1 Interrupt Throttle Rate (ITR) index +- 1 Virtual Station Interface (VSI) per VF - 1 Traffic Class (TC), TC0 - Receive Side Scaling (RSS) with 64 entry indirection table and key, - configured through the PF. -- 1 unicast MAC address reserved per VF. -- 16 MAC address filters for each VF. -- Stateless offloads - non-tunneled checksums. -- AVF device ID. -- HW mailbox is used for VF to PF communications (including on Windows). + configured through the PF +- 1 unicast MAC address reserved per VF +- 16 MAC address filters for each VF +- Stateless offloads - non-tunneled checksums +- AVF device ID +- HW mailbox is used for VF to PF communications (including on Windows) IEEE 802.1ad (QinQ) Support --------------------------- @@ -117,8 +123,8 @@ VLAN ID, among other uses. The following are examples of how to configure 802.1ad (QinQ):: - ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24 - ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371 + # ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24 + # ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371 Where "24" and "371" are example VLAN IDs. @@ -133,6 +139,19 @@ specific application. This can reduce latency for the specified application, and allow Tx traffic to be rate limited per application. Follow the steps below to set ADq. +Requirements: + +- The sch_mqprio, act_mirred and cls_flower modules must be loaded +- The latest version of iproute2 +- If another driver (for example, DPDK) has set cloud filters, you cannot + enable ADQ +- Depending on the underlying PF device, ADQ cannot be enabled when the + following features are enabled: + + + Data Center Bridging (DCB) + + Multiple Functions per Port (MFP) + + Sideband Filters + 1. Create traffic classes (TCs). Maximum of 8 TCs can be created per interface. The shaper bw_rlimit parameter is optional. @@ -141,9 +160,9 @@ to 1Gbit for tc0 and 3Gbit for tc1. :: - # tc qdisc add dev <interface> root mqprio num_tc 2 map 0 0 0 0 1 1 1 1 - queues 16@0 16@16 hw 1 mode channel shaper bw_rlimit min_rate 1Gbit 2Gbit - max_rate 1Gbit 3Gbit + tc qdisc add dev <interface> root mqprio num_tc 2 map 0 0 0 0 1 1 1 1 + queues 16@0 16@16 hw 1 mode channel shaper bw_rlimit min_rate 1Gbit 2Gbit + max_rate 1Gbit 3Gbit map: priority mapping for up to 16 priorities to tcs (e.g. map 0 0 0 0 1 1 1 1 sets priorities 0-3 to use tc0 and 4-7 to use tc1) @@ -162,6 +181,10 @@ 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] +NOTE: + Setting up channels via ethtool (ethtool -L) is not supported when the + TCs are configured using mqprio. + 2. Enable HW TC offload on interface:: # ethtool -K <interface> hw-tc-offload on @@ -171,16 +194,16 @@ monitoring tools such as ifstat or sar –n DEV [interval] [number of samples] # tc qdisc add dev <interface> ingress NOTES: - - Run all tc commands from the iproute2 <pathtoiproute2>/tc/ directory. - - ADq is not compatible with cloud filters. + - Run all tc commands from the iproute2 <pathtoiproute2>/tc/ directory + - ADq is not compatible with cloud filters - Setting up channels via ethtool (ethtool -L) is not supported when the TCs - are configured using mqprio. + are configured using mqprio - You must have iproute2 latest version - - NVM version 6.01 or later is required. + - NVM version 6.01 or later is required - ADq cannot be enabled when any the following features are enabled: Data - Center Bridging (DCB), Multiple Functions per Port (MFP), or Sideband Filters. + Center Bridging (DCB), Multiple Functions per Port (MFP), or Sideband Filters - If another driver (for example, DPDK) has set cloud filters, you cannot - enable ADq. + enable ADq - Tunnel filters are not supported in ADq. If encapsulated packets do arrive in non-tunnel mode, filtering will be done on the inner headers. For example, for VXLAN traffic in non-tunnel mode, PCTYPE is identified as a VXLAN @@ -198,6 +221,16 @@ NOTES: Known Issues/Troubleshooting ============================ +Bonding fails with VFs bound to an Intel(R) Ethernet Controller 700 series device +--------------------------------------------------------------------------------- +If you bind Virtual Functions (VFs) to an Intel(R) Ethernet Controller 700 +series based device, the VF slaves may fail when they become the active slave. +If the MAC address of the VF is set by the PF (Physical Function) of the +device, when you add a slave, or change the active-backup slave, Linux bonding +tries to sync the backup slave's MAC address to the same MAC address as the +active slave. Linux bonding will fail at this point. This issue will not occur +if the VF's MAC address is not set by the PF. + Traffic Is Not Being Passed Between VM and Client ------------------------------------------------- You may not be able to pass traffic between a client system and a @@ -215,13 +248,28 @@ Do not unload a port's driver if a Virtual Function (VF) with an active Virtual Machine (VM) is bound to it. Doing so will cause the port to appear to hang. Once the VM shuts down, or otherwise releases the VF, the command will complete. +Using four traffic classes fails +-------------------------------- +Do not try to reserve more than three traffic classes in the iavf driver. Doing +so will fail to set any traffic classes and will cause the driver to write +errors to stdout. Use a maximum of three queues to avoid this issue. + +Multiple log error messages on iavf driver removal +-------------------------------------------------- +If you have several VFs and you remove the iavf driver, several instances of +the following log errors are written to the log:: + + Unable to send opcode 2 to PF, err I40E_ERR_QUEUE_EMPTY, aq_err ok + Unable to send the message to VF 2 aq_err 12 + ARQ Overflow Error detected + Virtual machine does not get link --------------------------------- If the virtual machine has more than one virtual port assigned to it, and those virtual ports are bound to different physical ports, you may not get link on all of the virtual ports. The following command may work around the issue:: - ethtool -r <PF> + # ethtool -r <PF> Where <PF> is the PF interface in the host, for example: p5p1. You may need to run the command more than once to get link on all virtual ports. @@ -251,12 +299,13 @@ traffic. If you have multiple interfaces in a server, either turn on ARP filtering by entering:: - echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter + # echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter -NOTE: This setting is not saved across reboots. The configuration change can be -made permanent by adding the following line to the file /etc/sysctl.conf:: +NOTE: + This setting is not saved across reboots. The configuration change can be + made permanent by adding the following line to the file /etc/sysctl.conf:: - net.ipv4.conf.all.arp_filter = 1 + net.ipv4.conf.all.arp_filter = 1 Another alternative is to install the interfaces in separate broadcast domains (either in different switches or in a switch partitioned to VLANs). diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/mellanox/mlx5.rst index 214325897732..d071c6b49e1f 100644 --- a/Documentation/networking/device_drivers/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/mellanox/mlx5.rst @@ -11,7 +11,9 @@ Contents - `Enabling the driver and kconfig options`_ - `Devlink info`_ +- `Devlink parameters`_ - `Devlink health reporters`_ +- `mlx5 tracepoints`_ Enabling the driver and kconfig options ================================================ @@ -121,12 +123,44 @@ User command example:: stored: fw.version 16.26.0100 +Devlink parameters +================== + +flow_steering_mode: Device flow steering mode +--------------------------------------------- +The flow steering mode parameter controls the flow steering mode of the driver. +Two modes are supported: +1. 'dmfs' - Device managed flow steering. +2. 'smfs - Software/Driver managed flow steering. + +In DMFS mode, the HW steering entities are created and managed through the +Firmware. +In SMFS mode, the HW steering entities are created and managed though by +the driver directly into Hardware without firmware intervention. + +SMFS mode is faster and provides better rule inserstion rate compared to default DMFS mode. + +User command examples: + +- Set SMFS flow steering mode:: + + $ devlink dev param set pci/0000:06:00.0 name flow_steering_mode value "smfs" cmode runtime + +- Read device flow steering mode:: + + $ devlink dev param show pci/0000:06:00.0 name flow_steering_mode + pci/0000:06:00.0: + name flow_steering_mode type driver-specific + values: + cmode runtime value smfs + + Devlink health reporters ======================== tx reporter ----------- -The tx reporter is responsible of two error scenarios: +The tx reporter is responsible for reporting and recovering of the following two error scenarios: - TX timeout Report on kernel tx timeout detection. @@ -135,7 +169,7 @@ The tx reporter is responsible of two error scenarios: Report on error tx completion. Recover by flushing the TX queue and reset it. -TX reporter also support Diagnose callback, on which it provides +TX reporter also support on demand diagnose callback, on which it provides real time information of its send queues status. User commands examples: @@ -144,11 +178,40 @@ User commands examples: $ devlink health diagnose pci/0000:82:00.0 reporter tx +NOTE: This command has valid output only when interface is up, otherwise the command has empty output. + - Show number of tx errors indicated, number of recover flows ended successfully, is autorecover enabled and graceful period from last recover:: $ devlink health show pci/0000:82:00.0 reporter tx +rx reporter +----------- +The rx reporter is responsible for reporting and recovering of the following two error scenarios: + +- RX queues initialization (population) timeout + RX queues descriptors population on ring initialization is done in + napi context via triggering an irq, in case of a failure to get + the minimum amount of descriptors, a timeout would occur and it + could be recoverable by polling the EQ (Event Queue). +- RX completions with errors (reported by HW on interrupt context) + Report on rx completion error. + Recover (if needed) by flushing the related queue and reset it. + +RX reporter also supports on demand diagnose callback, on which it +provides real time information of its receive queues status. + +- Diagnose rx queues status, and corresponding completion queue:: + + $ devlink health diagnose pci/0000:82:00.0 reporter rx + +NOTE: This command has valid output only when interface is up, otherwise the command has empty output. + +- Show number of rx errors indicated, number of recover flows ended successfully, + is autorecover enabled and graceful period from last recover:: + + $ devlink health show pci/0000:82:00.0 reporter rx + fw reporter ----------- The fw reporter implements diagnose and dump callbacks. @@ -190,3 +253,48 @@ User commands examples: $ devlink health dump show pci/0000:82:00.1 reporter fw_fatal NOTE: This command can run only on PF. + +mlx5 tracepoints +================ + +mlx5 driver provides internal trace points for tracking and debugging using +kernel tracepoints interfaces (refer to Documentation/trace/ftrase.rst). + +For the list of support mlx5 events check /sys/kernel/debug/tracing/events/mlx5/ + +tc and eswitch offloads tracepoints: + +- mlx5e_configure_flower: trace flower filter actions and cookies offloaded to mlx5:: + + $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + tc-6535 [019] ...1 2672.404466: mlx5e_configure_flower: cookie=0000000067874a55 actions= REDIRECT + +- mlx5e_delete_flower: trace flower filter actions and cookies deleted from mlx5:: + + $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + tc-6569 [010] .N.1 2686.379075: mlx5e_delete_flower: cookie=0000000067874a55 actions= NULL + +- mlx5e_stats_flower: trace flower stats request:: + + $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + tc-6546 [010] ...1 2679.704889: mlx5e_stats_flower: cookie=0000000060eb3d6a bytes=0 packets=0 lastused=4295560217 + +- mlx5e_tc_update_neigh_used_value: trace tunnel rule neigh update value offloaded to mlx5:: + + $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + kworker/u48:4-8806 [009] ...1 55117.882428: mlx5e_tc_update_neigh_used_value: netdev: ens1f0 IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_used=1 + +- mlx5e_rep_neigh_update: trace neigh update tasks scheduled due to neigh state change events:: + + $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace + ... + kworker/u48:7-2221 [009] ...1 1475.387435: mlx5e_rep_neigh_update: netdev: ens1f0 MAC: 24:8a:07:9a:17:9a IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_connected=1 diff --git a/Documentation/networking/device_drivers/netronome/nfp.rst b/Documentation/networking/device_drivers/netronome/nfp.rst new file mode 100644 index 000000000000..6c08ac8b5147 --- /dev/null +++ b/Documentation/networking/device_drivers/netronome/nfp.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +============================================= +Netronome Flow Processor (NFP) Kernel Drivers +============================================= + +Copyright (c) 2019, Netronome Systems, Inc. + +Contents +======== + +- `Overview`_ +- `Acquiring Firmware`_ + +Overview +======== + +This driver supports Netronome's line of Flow Processor devices, +including the NFP4000, NFP5000, and NFP6000 models, which are also +incorporated in the company's family of Agilio SmartNICs. The SR-IOV +physical and virtual functions for these devices are supported by +the driver. + +Acquiring Firmware +================== + +The NFP4000 and NFP6000 devices require application specific firmware +to function. Application firmware can be located either on the host file system +or in the device flash (if supported by management firmware). + +Firmware files on the host filesystem contain card type (`AMDA-*` string), media +config etc. They should be placed in `/lib/firmware/netronome` directory to +load firmware from the host file system. + +Firmware for basic NIC operation is available in the upstream +`linux-firmware.git` repository. + +Firmware in NVRAM +----------------- + +Recent versions of management firmware supports loading application +firmware from flash when the host driver gets probed. The firmware loading +policy configuration may be used to configure this feature appropriately. + +Devlink or ethtool can be used to update the application firmware on the device +flash by providing the appropriate `nic_AMDA*.nffw` file to the respective +command. Users need to take care to write the correct firmware image for the +card and media configuration to flash. + +Available storage space in flash depends on the card being used. + +Dealing with multiple projects +------------------------------ + +NFP hardware is fully programmable therefore there can be different +firmware images targeting different applications. + +When using application firmware from host, we recommend placing +actual firmware files in application-named subdirectories in +`/lib/firmware/netronome` and linking the desired files, e.g.:: + + $ tree /lib/firmware/netronome/ + /lib/firmware/netronome/ + ├── bpf + │ ├── nic_AMDA0081-0001_1x40.nffw + │ └── nic_AMDA0081-0001_4x10.nffw + ├── flower + │ ├── nic_AMDA0081-0001_1x40.nffw + │ └── nic_AMDA0081-0001_4x10.nffw + ├── nic + │ ├── nic_AMDA0081-0001_1x40.nffw + │ └── nic_AMDA0081-0001_4x10.nffw + ├── nic_AMDA0081-0001_1x40.nffw -> bpf/nic_AMDA0081-0001_1x40.nffw + └── nic_AMDA0081-0001_4x10.nffw -> bpf/nic_AMDA0081-0001_4x10.nffw + + 3 directories, 8 files + +You may need to use hard instead of symbolic links on distributions +which use old `mkinitrd` command instead of `dracut` (e.g. Ubuntu). + +After changing firmware files you may need to regenerate the initramfs +image. Initramfs contains drivers and firmware files your system may +need to boot. Refer to the documentation of your distribution to find +out how to update initramfs. Good indication of stale initramfs +is system loading wrong driver or firmware on boot, but when driver is +later reloaded manually everything works correctly. + +Selecting firmware per device +----------------------------- + +Most commonly all cards on the system use the same type of firmware. +If you want to load specific firmware image for a specific card, you +can use either the PCI bus address or serial number. Driver will print +which files it's looking for when it recognizes a NFP device:: + + nfp: Looking for firmware file in order of priority: + nfp: netronome/serial-00-12-34-aa-bb-cc-10-ff.nffw: not found + nfp: netronome/pci-0000:02:00.0.nffw: not found + nfp: netronome/nic_AMDA0081-0001_1x40.nffw: found, loading... + +In this case if file (or link) called *serial-00-12-34-aa-bb-5d-10-ff.nffw* +or *pci-0000:02:00.0.nffw* is present in `/lib/firmware/netronome` this +firmware file will take precedence over `nic_AMDA*` files. + +Note that `serial-*` and `pci-*` files are **not** automatically included +in initramfs, you will have to refer to documentation of appropriate tools +to find out how to include them. + +Firmware loading policy +----------------------- + +Firmware loading policy is controlled via three HWinfo parameters +stored as key value pairs in the device flash: + +app_fw_from_flash + Defines which firmware should take precedence, 'Disk' (0), 'Flash' (1) or + the 'Preferred' (2) firmware. When 'Preferred' is selected, the management + firmware makes the decision over which firmware will be loaded by comparing + versions of the flash firmware and the host supplied firmware. + This variable is configurable using the 'fw_load_policy' + devlink parameter. + +abi_drv_reset + Defines if the driver should reset the firmware when + the driver is probed, either 'Disk' (0) if firmware was found on disk, + 'Always' (1) reset or 'Never' (2) reset. Note that the device is always + reset on driver unload if firmware was loaded when the driver was probed. + This variable is configurable using the 'reset_dev_on_drv_probe' + devlink parameter. + +abi_drv_load_ifc + Defines a list of PF devices allowed to load FW on the device. + This variable is not currently user configurable. diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/pensando/ionic.rst new file mode 100644 index 000000000000..67b6839d516b --- /dev/null +++ b/Documentation/networking/device_drivers/pensando/ionic.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================================================== +Linux* Driver for the Pensando(R) Ethernet adapter family +========================================================== + +Pensando Linux Ethernet driver. +Copyright(c) 2019 Pensando Systems, Inc + +Contents +======== + +- Identifying the Adapter +- Support + +Identifying the Adapter +======================= + +To find if one or more Pensando PCI Ethernet devices are installed on the +host, check for the PCI devices:: + + $ lspci -d 1dd8: + b5:00.0 Ethernet controller: Device 1dd8:1002 + b6:00.0 Ethernet controller: Device 1dd8:1002 + +If such devices are listed as above, then the ionic.ko driver should find +and configure them for use. There should be log entries in the kernel +messages such as these:: + + $ dmesg | grep ionic + ionic Pensando Ethernet NIC Driver, ver 0.15.0-k + ionic 0000:b5:00.0 enp181s0: renamed from eth0 + ionic 0000:b6:00.0 enp182s0: renamed from eth0 + +Support +======= +For general Linux networking support, please use the netdev mailing +list, which is monitored by Pensando personnel:: + netdev@vger.kernel.org + +For more specific support needs, please use the Pensando driver support +email:: + drivers@pensando.io diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink-info-versions.rst index 4316342b7746..4914f581b1fd 100644 --- a/Documentation/networking/devlink-info-versions.rst +++ b/Documentation/networking/devlink-info-versions.rst @@ -14,11 +14,27 @@ board.rev Board design revision. +asic.id +======= + +ASIC design identifier. + +asic.rev +======== + +ASIC design revision. + board.manufacture ================= An identifier of the company or the facility which produced the part. +fw +== + +Overall firmware version, often representing the collection of +fw.mgmt, fw.app, etc. + fw.mgmt ======= diff --git a/Documentation/networking/devlink-params-nfp.txt b/Documentation/networking/devlink-params-nfp.txt new file mode 100644 index 000000000000..43e4d4034865 --- /dev/null +++ b/Documentation/networking/devlink-params-nfp.txt @@ -0,0 +1,5 @@ +fw_load_policy [DEVICE, GENERIC] + Configuration mode: permanent + +reset_dev_on_drv_probe [DEVICE, GENERIC] + Configuration mode: permanent diff --git a/Documentation/networking/devlink-params.txt b/Documentation/networking/devlink-params.txt index 2d26434ddcf8..ddba3e9b55b1 100644 --- a/Documentation/networking/devlink-params.txt +++ b/Documentation/networking/devlink-params.txt @@ -48,4 +48,20 @@ fw_load_policy [DEVICE, GENERIC] Load firmware version preferred by the driver. * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH (1) Load firmware currently stored in flash. + * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DISK (2) + Load firmware currently available on host's disk. + Type: u8 + +reset_dev_on_drv_probe [DEVICE, GENERIC] + Controls the device's reset policy on driver probe. + Valid values: + * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_UNKNOWN (0) + Unknown or invalid value. + * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_ALWAYS (1) + Always reset device on driver probe. + * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_NEVER (2) + Never reset device on driver probe. + * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_DISK (3) + Reset only if device firmware can be found in the + filesystem. Type: u8 diff --git a/Documentation/networking/devlink-trap-netdevsim.rst b/Documentation/networking/devlink-trap-netdevsim.rst new file mode 100644 index 000000000000..b721c9415473 --- /dev/null +++ b/Documentation/networking/devlink-trap-netdevsim.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +Devlink Trap netdevsim +====================== + +Driver-specific Traps +===================== + +.. list-table:: List of Driver-specific Traps Registered by ``netdevsim`` + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fid_miss`` + - ``exception`` + - When a packet enters the device it is classified to a filtering + indentifier (FID) based on the ingress port and VLAN. This trap is used + to trap packets for which a FID could not be found diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink-trap.rst new file mode 100644 index 000000000000..c20c7c483664 --- /dev/null +++ b/Documentation/networking/devlink-trap.rst @@ -0,0 +1,208 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Devlink Trap +============ + +Background +========== + +Devices capable of offloading the kernel's datapath and perform functions such +as bridging and routing must also be able to send specific packets to the +kernel (i.e., the CPU) for processing. + +For example, a device acting as a multicast-aware bridge must be able to send +IGMP membership reports to the kernel for processing by the bridge module. +Without processing such packets, the bridge module could never populate its +MDB. + +As another example, consider a device acting as router which has received an IP +packet with a TTL of 1. Upon routing the packet the device must send it to the +kernel so that it will route it as well and generate an ICMP Time Exceeded +error datagram. Without letting the kernel route such packets itself, utilities +such as ``traceroute`` could never work. + +The fundamental ability of sending certain packets to the kernel for processing +is called "packet trapping". + +Overview +======== + +The ``devlink-trap`` mechanism allows capable device drivers to register their +supported packet traps with ``devlink`` and report trapped packets to +``devlink`` for further analysis. + +Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and +bytes accounting and potentially report the packet to user space via a netlink +event along with all the provided metadata (e.g., trap reason, timestamp, input +port). This is especially useful for drop traps (see :ref:`Trap-Types`) +as it allows users to obtain further visibility into packet drops that would +otherwise be invisible. + +The following diagram provides a general overview of ``devlink-trap``:: + + Netlink event: Packet w/ metadata + Or a summary of recent drops + ^ + | + Userspace | + +---------------------------------------------------+ + Kernel | + | + +-------+--------+ + | | + | drop_monitor | + | | + +-------^--------+ + | + | + | + +----+----+ + | | Kernel's Rx path + | devlink | (non-drop traps) + | | + +----^----+ ^ + | | + +-----------+ + | + +-------+-------+ + | | + | Device driver | + | | + +-------^-------+ + Kernel | + +---------------------------------------------------+ + Hardware | + | Trapped packet + | + +--+---+ + | | + | ASIC | + | | + +------+ + +.. _Trap-Types: + +Trap Types +========== + +The ``devlink-trap`` mechanism supports the following packet trap types: + + * ``drop``: Trapped packets were dropped by the underlying device. Packets + are only processed by ``devlink`` and not injected to the kernel's Rx path. + The trap action (see :ref:`Trap-Actions`) can be changed. + * ``exception``: Trapped packets were not forwarded as intended by the + underlying device due to an exception (e.g., TTL error, missing neighbour + entry) and trapped to the control plane for resolution. Packets are + processed by ``devlink`` and injected to the kernel's Rx path. Changing the + action of such traps is not allowed, as it can easily break the control + plane. + +.. _Trap-Actions: + +Trap Actions +============ + +The ``devlink-trap`` mechanism supports the following packet trap actions: + + * ``trap``: The sole copy of the packet is sent to the CPU. + * ``drop``: The packet is dropped by the underlying device and a copy is not + sent to the CPU. + +Generic Packet Traps +==================== + +Generic packet traps are used to describe traps that trap well-defined packets +or packets that are trapped due to well-defined conditions (e.g., TTL error). +Such traps can be shared by multiple device drivers and their description must +be added to the following table: + +.. list-table:: List of Generic Packet Traps + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``source_mac_is_multicast`` + - ``drop`` + - Traps incoming packets that the device decided to drop because of a + multicast source MAC + * - ``vlan_tag_mismatch`` + - ``drop`` + - Traps incoming packets that the device decided to drop in case of VLAN + tag mismatch: The ingress bridge port is not configured with a PVID and + the packet is untagged or prio-tagged + * - ``ingress_vlan_filter`` + - ``drop`` + - Traps incoming packets that the device decided to drop in case they are + tagged with a VLAN that is not configured on the ingress bridge port + * - ``ingress_spanning_tree_filter`` + - ``drop`` + - Traps incoming packets that the device decided to drop in case the STP + state of the ingress bridge port is not "forwarding" + * - ``port_list_is_empty`` + - ``drop`` + - Traps packets that the device decided to drop in case they need to be + flooded and the flood list is empty + * - ``port_loopback_filter`` + - ``drop`` + - Traps packets that the device decided to drop in case after layer 2 + forwarding the only port from which they should be transmitted through + is the port from which they were received + * - ``blackhole_route`` + - ``drop`` + - Traps packets that the device decided to drop in case they hit a + blackhole route + * - ``ttl_value_is_too_small`` + - ``exception`` + - Traps unicast packets that should be forwarded by the device whose TTL + was decremented to 0 or less + * - ``tail_drop`` + - ``drop`` + - Traps packets that the device decided to drop because they could not be + enqueued to a transmission queue which is full + +Driver-specific Packet Traps +============================ + +Device drivers can register driver-specific packet traps, but these must be +clearly documented. Such traps can correspond to device-specific exceptions and +help debug packet drops caused by these exceptions. The following list includes +links to the description of driver-specific traps registered by various device +drivers: + + * :doc:`/devlink-trap-netdevsim` + +Generic Packet Trap Groups +========================== + +Generic packet trap groups are used to aggregate logically related packet +traps. These groups allow the user to batch operations such as setting the trap +action of all member traps. In addition, ``devlink-trap`` can report aggregated +per-group packets and bytes statistics, in case per-trap statistics are too +narrow. The description of these groups must be added to the following table: + +.. list-table:: List of Generic Packet Trap Groups + :widths: 10 90 + + * - Name + - Description + * - ``l2_drops`` + - Contains packet traps for packets that were dropped by the device during + layer 2 forwarding (i.e., bridge) + * - ``l3_drops`` + - Contains packet traps for packets that were dropped by the device or hit + an exception (e.g., TTL error) during layer 3 forwarding + * - ``buffer_drops`` + - Contains packet traps for packets that were dropped by the device due to + an enqueue decision + +Testing +======= + +See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a +test covering the core infrastructure. Test cases should be added for any new +functionality. + +Device drivers should focus their tests on device-specific functionality, such +as the triggering of supported packet traps. diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst index cb2858dece93..eef20d0bcf7c 100644 --- a/Documentation/networking/dsa/sja1105.rst +++ b/Documentation/networking/dsa/sja1105.rst @@ -146,6 +146,96 @@ enslaves eth0 and eth1 (the DSA master of the switch ports). This is because in this mode, the switch ports beneath br0 are not capable of regular traffic, and are only used as a conduit for switchdev operations. +Offloads +======== + +Time-aware scheduling +--------------------- + +The switch supports a variation of the enhancements for scheduled traffic +specified in IEEE 802.1Q-2018 (formerly 802.1Qbv). This means it can be used to +ensure deterministic latency for priority traffic that is sent in-band with its +gate-open event in the network schedule. + +This capability can be managed through the tc-taprio offload ('flags 2'). The +difference compared to the software implementation of taprio is that the latter +would only be able to shape traffic originated from the CPU, but not +autonomously forwarded flows. + +The device has 8 traffic classes, and maps incoming frames to one of them based +on the VLAN PCP bits (if no VLAN is present, the port-based default is used). +As described in the previous sections, depending on the value of +``vlan_filtering``, the EtherType recognized by the switch as being VLAN can +either be the typical 0x8100 or a custom value used internally by the driver +for tagging. Therefore, the switch ignores the VLAN PCP if used in standalone +or bridge mode with ``vlan_filtering=0``, as it will not recognize the 0x8100 +EtherType. In these modes, injecting into a particular TX queue can only be +done by the DSA net devices, which populate the PCP field of the tagging header +on egress. Using ``vlan_filtering=1``, the behavior is the other way around: +offloaded flows can be steered to TX queues based on the VLAN PCP, but the DSA +net devices are no longer able to do that. To inject frames into a hardware TX +queue with VLAN awareness active, it is necessary to create a VLAN +sub-interface on the DSA master port, and send normal (0x8100) VLAN-tagged +towards the switch, with the VLAN PCP bits set appropriately. + +Management traffic (having DMAC 01-80-C2-xx-xx-xx or 01-19-1B-xx-xx-xx) is the +notable exception: the switch always treats it with a fixed priority and +disregards any VLAN PCP bits even if present. The traffic class for management +traffic has a value of 7 (highest priority) at the moment, which is not +configurable in the driver. + +Below is an example of configuring a 500 us cyclic schedule on egress port +``swp5``. The traffic class gate for management traffic (7) is open for 100 us, +and the gates for all other traffic classes are open for 400 us:: + + #!/bin/bash + + set -e -u -o pipefail + + NSEC_PER_SEC="1000000000" + + gatemask() { + local tc_list="$1" + local mask=0 + + for tc in ${tc_list}; do + mask=$((${mask} | (1 << ${tc}))) + done + + printf "%02x" ${mask} + } + + if ! systemctl is-active --quiet ptp4l; then + echo "Please start the ptp4l service" + exit + fi + + now=$(phc_ctl /dev/ptp1 get | gawk '/clock time is/ { print $5; }') + # Phase-align the base time to the start of the next second. + sec=$(echo "${now}" | gawk -F. '{ print $1; }') + base_time="$(((${sec} + 1) * ${NSEC_PER_SEC}))" + + tc qdisc add dev swp5 parent root handle 100 taprio \ + num_tc 8 \ + map 0 1 2 3 5 6 7 \ + queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \ + base-time ${base_time} \ + sched-entry S $(gatemask 7) 100000 \ + sched-entry S $(gatemask "0 1 2 3 4 5 6") 400000 \ + flags 2 + +It is possible to apply the tc-taprio offload on multiple egress ports. There +are hardware restrictions related to the fact that no gate event may trigger +simultaneously on two ports. The driver checks the consistency of the schedules +against this restriction and errors out when appropriate. Schedule analysis is +needed to avoid this, which is outside the scope of the document. + +At the moment, the time-aware scheduler can only be triggered based on a +standalone clock and not based on PTP time. This means the base-time argument +from tc-taprio is ignored and the schedule starts right away. It also means it +is more difficult to phase-align the scheduler with the other devices in the +network. + Device Tree bindings and board design ===================================== diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index a46fca264bee..d4dca42910d0 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -14,7 +14,10 @@ Contents: device_drivers/index dsa/index devlink-info-versions + devlink-trap + devlink-trap-netdevsim ieee802154 + j1939 kapi z8530book msg_zerocopy @@ -31,7 +34,7 @@ Contents: tls tls-offload -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index df33674799b5..49e95f438ed7 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -256,6 +256,12 @@ tcp_base_mss - INTEGER Path MTU discovery (MTU probing). If MTU probing is enabled, this is the initial MSS used by the connection. +tcp_mtu_probe_floor - INTEGER + If MTU probing is enabled this caps the minimum MSS used for search_low + for the connection. + + Default : 48 + tcp_min_snd_mss - INTEGER TCP SYN and SYNACK messages usually advertise an ADVMSS option, as described in RFC 1122 and RFC 6691. diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst new file mode 100644 index 000000000000..ce7e7a044e08 --- /dev/null +++ b/Documentation/networking/j1939.rst @@ -0,0 +1,422 @@ +.. SPDX-License-Identifier: (GPL-2.0 OR MIT) + +=================== +J1939 Documentation +=================== + +Overview / What Is J1939 +======================== + +SAE J1939 defines a higher layer protocol on CAN. It implements a more +sophisticated addressing scheme and extends the maximum packet size above 8 +bytes. Several derived specifications exist, which differ from the original +J1939 on the application level, like MilCAN A, NMEA2000 and especially +ISO-11783 (ISOBUS). This last one specifies the so-called ETP (Extended +Transport Protocol) which is has been included in this implementation. This +results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB. + +Specifications used +------------------- + +* SAE J1939-21 : data link layer +* SAE J1939-81 : network management +* ISO 11783-6 : Virtual Terminal (Extended Transport Protocol) + +.. _j1939-motivation: + +Motivation +========== + +Given the fact there's something like SocketCAN with an API similar to BSD +sockets, we found some reasons to justify a kernel implementation for the +addressing and transport methods used by J1939. + +* **Addressing:** when a process on an ECU communicates via J1939, it should + not necessarily know its source address. Although at least one process per + ECU should know the source address. Other processes should be able to reuse + that address. This way, address parameters for different processes + cooperating for the same ECU, are not duplicated. This way of working is + closely related to the UNIX concept where programs do just one thing, and do + it well. + +* **Dynamic addressing:** Address Claiming in J1939 is time critical. + Furthermore data transport should be handled properly during the address + negotiation. Putting this functionality in the kernel eliminates it as a + requirement for _every_ user space process that communicates via J1939. This + results in a consistent J1939 bus with proper addressing. + +* **Transport:** both TP & ETP reuse some PGNs to relay big packets over them. + Different processes may thus use the same TP & ETP PGNs without actually + knowing it. The individual TP & ETP sessions _must_ be serialized + (synchronized) between different processes. The kernel solves this problem + properly and eliminates the serialization (synchronization) as a requirement + for _every_ user space process that communicates via J1939. + +J1939 defines some other features (relaying, gateway, fast packet transport, +...). In-kernel code for these would not contribute to protocol stability. +Therefore, these parts are left to user space. + +The J1939 sockets operate on CAN network devices (see SocketCAN). Any J1939 +user space library operating on CAN raw sockets will still operate properly. +Since such library does not communicate with the in-kernel implementation, care +must be taken that these two do not interfere. In practice, this means they +cannot share ECU addresses. A single ECU (or virtual ECU) address is used by +the library exclusively, or by the in-kernel system exclusively. + +J1939 concepts +============== + +PGN +--- + +The PGN (Parameter Group Number) is a number to identify a packet. The PGN +is composed as follows: +1 bit : Reserved Bit +1 bit : Data Page +8 bits : PF (PDU Format) +8 bits : PS (PDU Specific) + +In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2 +format (where PF >= 240). Furthermore, when using PDU2 format, the PS-field +contains a so-called Group Extension, which is part of the PGN. When using PDU2 +format, the Group Extension is set in the PS-field. + +On the other hand, when using PDU1 format, the PS-field contains a so-called +Destination Address, which is _not_ part of the PGN. When communicating a PGN +from user space to kernel (or visa versa) and PDU2 format is used, the PS-field +of the PGN shall be set to zero. The Destination Address shall be set +elsewhere. + +Regarding PGN mapping to 29-bit CAN identifier, the Destination Address shall +be get/set from/to the appropriate bits of the identifier by the kernel. + + +Addressing +---------- + +Both static and dynamic addressing methods can be used. + +For static addresses, no extra checks are made by the kernel, and provided +addresses are considered right. This responsibility is for the OEM or system +integrator. + +For dynamic addressing, so-called Address Claiming, extra support is foreseen +in the kernel. In J1939 any ECU is known by it's 64-bit NAME. At the moment of +a successful address claim, the kernel keeps track of both NAME and source +address being claimed. This serves as a base for filter schemes. By default, +packets with a destination that is not locally, will be rejected. + +Mixed mode packets (from a static to a dynamic address or vice versa) are +allowed. The BSD sockets define separate API calls for getting/setting the +local & remote address and are applicable for J1939 sockets. + +Filtering +--------- + +J1939 defines white list filters per socket that a user can set in order to +receive a subset of the J1939 traffic. Filtering can be based on: + +* SA +* SOURCE_NAME +* PGN + +When multiple filters are in place for a single socket, and a packet comes in +that matches several of those filters, the packet is only received once for +that socket. + +How to Use J1939 +================ + +API Calls +--------- + +On CAN, you first need to open a socket for communicating over a CAN network. +To use J1939, #include <linux/can/j1939.h>. From there, <linux/can.h> will be +included too. To open a socket, use: + +.. code-block:: C + + s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939); + +J1939 does use SOCK_DGRAM sockets. In the J1939 specification, connections are +mentioned in the context of transport protocol sessions. These still deliver +packets to the other end (using several CAN packets). SOCK_STREAM is not +supported. + +After the successful creation of the socket, you would normally use the bind(2) +and/or connect(2) system call to bind the socket to a CAN interface. After +binding and/or connecting the socket, you can read(2) and write(2) from/to the +socket or use send(2), sendto(2), sendmsg(2) and the recv*() counterpart +operations on the socket as usual. There are also J1939 specific socket options +described below. + +In order to send data, a bind(2) must have been successful. bind(2) assigns a +local address to a socket. + +Different from CAN is that the payload data is just the data that get send, +without it's header info. The header info is derived from the sockaddr supplied +to bind(2), connect(2), sendto(2) and recvfrom(2). A write(2) with size 4 will +result in a packet with 4 bytes. + +The sockaddr structure has extensions for use with J1939 as specified below: + +.. code-block:: C + + struct sockaddr_can { + sa_family_t can_family; + int can_ifindex; + union { + struct { + __u64 name; + /* pgn: + * 8 bit: PS in PDU2 case, else 0 + * 8 bit: PF + * 1 bit: DP + * 1 bit: reserved + */ + __u32 pgn; + __u8 addr; + } j1939; + } can_addr; + } + +can_family & can_ifindex serve the same purpose as for other SocketCAN sockets. + +can_addr.j1939.pgn specifies the PGN (max 0x3ffff). Individual bits are +specified above. + +can_addr.j1939.name contains the 64-bit J1939 NAME. + +can_addr.j1939.addr contains the address. + +The bind(2) system call assigns the local address, i.e. the source address when +sending packages. If a PGN during bind(2) is set, it's used as a RX filter. +I.e. only packets with a matching PGN are received. If an ADDR or NAME is set +it is used as a receive filter, too. It will match the destination NAME or ADDR +of the incoming packet. The NAME filter will work only if appropriate Address +Claiming for this name was done on the CAN bus and registered/cached by the +kernel. + +On the other hand connect(2) assigns the remote address, i.e. the destination +address. The PGN from connect(2) is used as the default PGN when sending +packets. If ADDR or NAME is set it will be used as the default destination ADDR +or NAME. Further a set ADDR or NAME during connect(2) is used as a receive +filter. It will match the source NAME or ADDR of the incoming packet. + +Both write(2) and send(2) will send a packet with local address from bind(2) and +the remote address from connect(2). Use sendto(2) to overwrite the destination +address. + +If can_addr.j1939.name is set (!= 0) the NAME is looked up by the kernel and +the corresponding ADDR is used. If can_addr.j1939.name is not set (== 0), +can_addr.j1939.addr is used. + +When creating a socket, reasonable defaults are set. Some options can be +modified with setsockopt(2) & getsockopt(2). + +RX path related options: + +- SO_J1939_FILTER - configure array of filters +- SO_J1939_PROMISC - disable filters set by bind(2) and connect(2) + +By default no broadcast packets can be send or received. To enable sending or +receiving broadcast packets use the socket option SO_BROADCAST: + +.. code-block:: C + + int value = 1; + setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)); + +The following diagram illustrates the RX path: + +.. code:: + + +--------------------+ + | incoming packet | + +--------------------+ + | + V + +--------------------+ + | SO_J1939_PROMISC? | + +--------------------+ + | | + no | | yes + | | + .---------' `---------. + | | + +---------------------------+ | + | bind() + connect() + | | + | SOCK_BROADCAST filter | | + +---------------------------+ | + | | + |<---------------------' + V + +---------------------------+ + | SO_J1939_FILTER | + +---------------------------+ + | + V + +---------------------------+ + | socket recv() | + +---------------------------+ + +TX path related options: +SO_J1939_SEND_PRIO - change default send priority for the socket + +Message Flags during send() and Related System Calls +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +send(2), sendto(2) and sendmsg(2) take a 'flags' argument. Currently +supported flags are: + +* MSG_DONTWAIT, i.e. non-blocking operation. + +recvmsg(2) +^^^^^^^^^ + +In most cases recvmsg(2) is needed if you want to extract more information than +recvfrom(2) can provide. For example package priority and timestamp. The +Destination Address, name and packet priority (if applicable) are attached to +the msghdr in the recvmsg(2) call. They can be extracted using cmsg(3) macros, +with cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR, +SCM_J1939_DEST_NAME or SCM_J1939_PRIO. The returned data is a uint8_t for +priority and dst_addr, and uint64_t for dst_name. + +.. code-block:: C + + uint8_t priority, dst_addr; + uint64_t dst_name; + + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) { + switch (cmsg->cmsg_level) { + case SOL_CAN_J1939: + if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR) + dst_addr = *CMSG_DATA(cmsg); + else if (cmsg->cmsg_type == SCM_J1939_DEST_NAME) + memcpy(&dst_name, CMSG_DATA(cmsg), cmsg->cmsg_len - CMSG_LEN(0)); + else if (cmsg->cmsg_type == SCM_J1939_PRIO) + priority = *CMSG_DATA(cmsg); + break; + } + } + +Dynamic Addressing +------------------ + +Distinction has to be made between using the claimed address and doing an +address claim. To use an already claimed address, one has to fill in the +j1939.name member and provide it to bind(2). If the name had claimed an address +earlier, all further messages being sent will use that address. And the +j1939.addr member will be ignored. + +An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim +Address" message and the kernel will use the j1939.addr member for that PGN if +necessary. + +To claim an address following code example can be used: + +.. code-block:: C + + struct sockaddr_can baddr = { + .can_family = AF_CAN, + .can_addr.j1939 = { + .name = name, + .addr = J1939_IDLE_ADDR, + .pgn = J1939_NO_PGN, /* to disable bind() rx filter for PGN */ + }, + .can_ifindex = if_nametoindex("can0"), + }; + + bind(sock, (struct sockaddr *)&baddr, sizeof(baddr)); + + /* for Address Claiming broadcast must be allowed */ + int value = 1; + setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)); + + /* configured advanced RX filter with PGN needed for Address Claiming */ + const struct j1939_filter filt[] = { + { + .pgn = J1939_PGN_ADDRESS_CLAIMED, + .pgn_mask = J1939_PGN_PDU1_MAX, + }, { + .pgn = J1939_PGN_ADDRESS_REQUEST, + .pgn_mask = J1939_PGN_PDU1_MAX, + }, { + .pgn = J1939_PGN_ADDRESS_COMMANDED, + .pgn_mask = J1939_PGN_MAX, + }, + }; + + setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, &filt, sizeof(filt)); + + uint64_t dat = htole64(name); + const struct sockaddr_can saddr = { + .can_family = AF_CAN, + .can_addr.j1939 = { + .pgn = J1939_PGN_ADDRESS_CLAIMED, + .addr = J1939_NO_ADDR, + }, + }; + + /* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the + * NAME provided, does not match the j1939.name provided to bind(2), EPROTO + * will be returned. + */ + sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr)); + +If no-one else contests the address claim within 250ms after transmission, the +kernel marks the NAME-SA assignment as valid. The valid assignment will be kept +among other valid NAME-SA assignments. From that point, any socket bound to the +NAME can send packets. + +If another ECU claims the address, the kernel will mark the NAME-SA expired. +No socket bound to the NAME can send packets (other than address claims). To +claim another address, some socket bound to NAME, must bind(2) again, but with +only j1939.addr changed to the new SA, and must then send a valid address claim +packet. This restarts the state machine in the kernel (and any other +participant on the bus) for this NAME. + +can-utils also include the jacd tool, so it can be used as code example or as +default Address Claiming daemon. + +Send Examples +------------- + +Static Addressing +^^^^^^^^^^^^^^^^^ + +This example will send a PGN (0x12300) from SA 0x20 to DA 0x30. + +Bind: + +.. code-block:: C + + struct sockaddr_can baddr = { + .can_family = AF_CAN, + .can_addr.j1939 = { + .name = J1939_NO_NAME, + .addr = 0x20, + .pgn = J1939_NO_PGN, + }, + .can_ifindex = if_nametoindex("can0"), + }; + + bind(sock, (struct sockaddr *)&baddr, sizeof(baddr)); + +Now, the socket 'sock' is bound to the SA 0x20. Since no connect(2) was called, +at this point we can use only sendto(2) or sendmsg(2). + +Send: + +.. code-block:: C + + const struct sockaddr_can saddr = { + .can_family = AF_CAN, + .can_addr.j1939 = { + .name = J1939_NO_NAME; + .pgn = 0x30, + .addr = 0x12300, + }, + }; + + sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr)); diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst index 3566a725d19c..d2266ce5534e 100644 --- a/Documentation/networking/mac80211_hwsim/README +++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst @@ -1,5 +1,13 @@ +:orphan: + +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=================================================================== mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211 -Copyright (c) 2008, Jouni Malinen <j@w1.fi> +=================================================================== + +:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as @@ -7,6 +15,7 @@ published by the Free Software Foundation. Introduction +============ mac80211_hwsim is a Linux kernel module that can be used to simulate arbitrary number of IEEE 802.11 radios for mac80211. It can be used to @@ -43,6 +52,7 @@ regardless of channel. Simple example +============== This example shows how to use mac80211_hwsim to simulate two radios: one to act as an access point and the other as a station that @@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take care of WPA2-PSK authentication. In addition, hostapd is also processing access point side of association. +:: + -# Build mac80211_hwsim as part of kernel configuration + # Build mac80211_hwsim as part of kernel configuration -# Load the module -modprobe mac80211_hwsim + # Load the module + modprobe mac80211_hwsim -# Run hostapd (AP) for wlan0 -hostapd hostapd.conf + # Run hostapd (AP) for wlan0 + hostapd hostapd.conf -# Run wpa_supplicant (station) for wlan1 -wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf + # Run wpa_supplicant (station) for wlan1 + wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf More test cases are available in hostap.git: diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst index 91446b431b70..a5e00a159d21 100644 --- a/Documentation/networking/sfp-phylink.rst +++ b/Documentation/networking/sfp-phylink.rst @@ -8,7 +8,8 @@ Overview ======== phylink is a mechanism to support hot-pluggable networking modules -without needing to re-initialise the adapter on hot-plug events. +directly connected to a MAC without needing to re-initialise the +adapter on hot-plug events. phylink supports conventional phylib-based setups, fixed link setups and SFP (Small Formfactor Pluggable) modules at present. diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst index 048e5ca44824..0dd3f748239f 100644 --- a/Documentation/networking/tls-offload.rst +++ b/Documentation/networking/tls-offload.rst @@ -424,13 +424,24 @@ Statistics Following minimum set of TLS-related statistics should be reported by the driver: - * ``rx_tls_decrypted`` - number of successfully decrypted TLS segments - * ``tx_tls_encrypted`` - number of in-order TLS segments passed to device - for encryption + * ``rx_tls_decrypted_packets`` - number of successfully decrypted RX packets + which were part of a TLS stream. + * ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets + which were successfully decrypted. + * ``tx_tls_encrypted_packets`` - number of TX packets passed to the device + for encryption of their TLS payload. + * ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets + passed to the device for encryption. + * ``tx_tls_ctx`` - number of TLS TX HW offload contexts added to device for + encryption. * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream - but did not arrive in the expected order - * ``tx_tls_drop_no_sync_data`` - number of TX packets dropped because - they arrived out of order and associated record could not be found + but did not arrive in the expected order. + * ``tx_tls_drop_no_sync_data`` - number of TX packets which were part of + a TLS stream dropped, because they arrived out of order and associated + record could not be found. + * ``tx_tls_drop_bypass_req`` - number of TX packets which were part of a TLS + stream dropped, because they contain both data that has been encrypted by + software and data that expects hardware crypto offload. Notable corner cases, exceptions and additional requirements ============================================================ @@ -495,21 +506,3 @@ Drivers should ignore the changes to TLS the device feature flags. These flags will be acted upon accordingly by the core ``ktls`` code. TLS device feature flags only control adding of new TLS connection offloads, old connections will remain active after flags are cleared. - -Known bugs -========== - -skb_orphan() leaks clear text ------------------------------ - -Currently drivers depend on the :c:member:`sk` member of -:c:type:`struct sk_buff <sk_buff>` to identify segments requiring -encryption. Any operation which removes or does not preserve the socket -association such as :c:func:`skb_orphan` or :c:func:`skb_clone` -will cause the driver to miss the packets and lead to clear text leaks. - -Redirects leak clear text -------------------------- - -In the RX direction, if segment has already been decrypted by the device -and it gets redirected or mirrored - clear text will be transmitted out. diff --git a/Documentation/networking/tuntap.txt b/Documentation/networking/tuntap.txt index 949d5dcdd9a3..0104830d5075 100644 --- a/Documentation/networking/tuntap.txt +++ b/Documentation/networking/tuntap.txt @@ -204,8 +204,8 @@ Ethernet device, which instead of receiving packets from a physical media, receives them from user space program and instead of sending packets via physical media sends them to the user space program. -Let's say that you configured IPX on the tap0, then whenever -the kernel sends an IPX packet to tap0, it is passed to the application +Let's say that you configured IPv6 on the tap0, then whenever +the kernel sends an IPv6 packet to tap0, it is passed to the application (VTun for example). The application encrypts, compresses and sends it to the other side over TCP or UDP. The application on the other side decompresses and decrypts the data received and writes the packet to the TAP device, diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst index 054a67d55563..43da3f7cee76 100644 --- a/Documentation/nios2/README +++ b/Documentation/nios2/nios2.rst @@ -1,3 +1,4 @@ +================================= Linux on the Nios II architecture ================================= diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst new file mode 100644 index 000000000000..748b3eea1707 --- /dev/null +++ b/Documentation/openrisc/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +OpenRISC Architecture +===================== + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst index 777a893d533d..a18747a8d191 100644 --- a/Documentation/openrisc/README +++ b/Documentation/openrisc/openrisc_port.rst @@ -1,3 +1,4 @@ +============== OpenRISC Linux ============== @@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k). For information about OpenRISC processors and ongoing development: + ======= ============================= website http://openrisc.io email openrisc@lists.librecores.org + ======= ============================= --------------------------------------------------------------------- @@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page. Instructions for building the different toolchains can be found on openrisc.io or Stafford's toolchain build and release scripts. + ========== ================================================= binaries https://github.com/openrisc/or1k-gcc/releases toolchains https://openrisc.io/software building https://github.com/stffrdhrn/or1k-toolchain-build + ========== ================================================= 2) Building -Build the Linux kernel as usual +Build the Linux kernel as usual:: make ARCH=openrisc defconfig make ARCH=openrisc @@ -43,6 +48,8 @@ development board with the OpenRISC SoC. During the build FPGA RTL is code downloaded from the FuseSoC IP cores repository and built using the FPGA vendor tools. Binaries are loaded onto the board with openocd. +:: + git clone https://github.com/olofk/fusesoc cd fusesoc sudo pip install -e . @@ -65,7 +72,9 @@ platform. Please follow the OpenRISC instructions on the QEMU website to get Linux running on QEMU. You can build QEMU yourself, but your Linux distribution likely provides binary packages to support OpenRISC. + ============= ====================================================== qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== --------------------------------------------------------------------- @@ -75,36 +84,38 @@ Terminology In the code, the following particles are used on symbols to limit the scope to more or less specific processor implementations: +========= ======================================= openrisc: the OpenRISC class of processors or1k: the OpenRISC 1000 family of processors or1200: the OpenRISC 1200 processor +========= ======================================= --------------------------------------------------------------------- History ======== -18. 11. 2003 Matjaz Breskvar (phoenix@bsemi.com) +18-11-2003 Matjaz Breskvar (phoenix@bsemi.com) initial port of linux to OpenRISC/or32 architecture. all the core stuff is implemented and seams usable. -08. 12. 2003 Matjaz Breskvar (phoenix@bsemi.com) +08-12-2003 Matjaz Breskvar (phoenix@bsemi.com) complete change of TLB miss handling. rewrite of exceptions handling. fully functional sash-3.6 in default initrd. a much improved version with changes all around. -10. 04. 2004 Matjaz Breskvar (phoenix@bsemi.com) +10-04-2004 Matjaz Breskvar (phoenix@bsemi.com) alot of bugfixes all over. ethernet support, functional http and telnet servers. running many standard linux apps. -26. 06. 2004 Matjaz Breskvar (phoenix@bsemi.com) +26-06-2004 Matjaz Breskvar (phoenix@bsemi.com) port to 2.6.x -30. 11. 2004 Matjaz Breskvar (phoenix@bsemi.com) +30-11-2004 Matjaz Breskvar (phoenix@bsemi.com) lots of bugfixes and enhancments. added opencores framebuffer driver. -09. 10. 2010 Jonas Bonn (jonas@southpole.se) +09-10-2010 Jonas Bonn (jonas@southpole.se) major rewrite to bring up to par with upstream Linux 2.6.36 diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst index c43d4e1d14eb..420b18b87eda 100644 --- a/Documentation/openrisc/TODO +++ b/Documentation/openrisc/todo.rst @@ -1,12 +1,15 @@ +==== +TODO +==== + The OpenRISC Linux port is fully functional and has been tracking upstream since 2.6.35. There are, however, remaining items to be completed within the coming months. Here's a list of known-to-be-less-than-stellar items that are due for investigation shortly, i.e. our TODO list: --- Implement the rest of the DMA API... dma_map_sg, etc. +- Implement the rest of the DMA API... dma_map_sg, etc. --- Finish the renaming cleanup... there are references to or32 in the code +- Finish the renaming cleanup... there are references to or32 in the code which was an older name for the architecture. The name we've settled on is or1k and this change is slowly trickling through the stack. For the time being, or32 is equivalent to or1k. - diff --git a/Documentation/padata.txt b/Documentation/padata.txt index b103d0c82000..b37ba1eaace3 100644 --- a/Documentation/padata.txt +++ b/Documentation/padata.txt @@ -16,10 +16,12 @@ overall control of how tasks are to be run:: #include <linux/padata.h> - struct padata_instance *padata_alloc(struct workqueue_struct *wq, + struct padata_instance *padata_alloc(const char *name, const struct cpumask *pcpumask, const struct cpumask *cbcpumask); +'name' simply identifies the instance. + The pcpumask describes which processors will be used to execute work submitted to this instance in parallel. The cbcpumask defines which processors are allowed to be used as the serialization callback processor. @@ -128,8 +130,7 @@ in that CPU mask or about a not running instance. Each task submitted to padata_do_parallel() will, in turn, be passed to exactly one call to the above-mentioned parallel() function, on one CPU, so -true parallelism is achieved by submitting multiple tasks. Despite the -fact that the workqueue is used to make these calls, parallel() is run with +true parallelism is achieved by submitting multiple tasks. parallel() runs with software interrupts disabled and thus cannot sleep. The parallel() function gets the padata_priv structure pointer as its lone parameter; information about the actual work to be done is probably obtained by using @@ -148,7 +149,7 @@ fact with a call to:: At some point in the future, padata_do_serial() will trigger a call to the serial() function in the padata_priv structure. That call will happen on the CPU requested in the initial call to padata_do_parallel(); it, too, is -done through the workqueue, but with local software interrupts disabled. +run with local software interrupts disabled. Note that this call may be deferred for a while since the padata code takes pains to ensure that tasks are completed in the order in which they were submitted. @@ -159,5 +160,4 @@ when a padata instance is no longer needed:: void padata_free(struct padata_instance *pinst); This function will busy-wait while any remaining tasks are completed, so it -might be best not to call it while there is work outstanding. Shutting -down the workqueue, if necessary, should be done separately. +might be best not to call it while there is work outstanding. diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst index 7d75223fa18d..de1b60402c5b 100644 --- a/Documentation/parisc/debugging +++ b/Documentation/parisc/debugging.rst @@ -1,8 +1,13 @@ +================= +PA-RISC Debugging +================= + okay, here are some hints for debugging the lower-level parts of linux/parisc. 1. Absolute addresses +===================== A lot of the assembly code currently runs in real mode, which means absolute addresses are used instead of virtual addresses as in the @@ -12,6 +17,7 @@ currently). 2. HPMCs +======== When real-mode code tries to access non-existent memory, you'll get an HPMC instead of a kernel oops. To debug an HPMC, try to find @@ -27,6 +33,7 @@ access it. 3. Q bit fun +============ Certain, very critical code has to clear the Q bit in the PSW. What happens when the Q bit is cleared is the CPU does not update the diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst new file mode 100644 index 000000000000..aa3ee0470425 --- /dev/null +++ b/Documentation/parisc/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +PA-RISC Architecture +==================== + +.. toctree:: + :maxdepth: 2 + + debugging + registers + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst index 10c7d1730f5d..59c8ecf3e856 100644 --- a/Documentation/parisc/registers +++ b/Documentation/parisc/registers.rst @@ -1,11 +1,16 @@ +================================ Register Usage for Linux/PA-RISC +================================ [ an asterisk is used for planned usage which is currently unimplemented ] - General Registers as specified by ABI +General Registers as specified by ABI +===================================== - Control Registers +Control Registers +----------------- +=============================== =============================================== CR 0 (Recovery Counter) used for ptrace CR 1-CR 7(undefined) unused CR 8 (Protection ID) per-process value* @@ -29,26 +34,35 @@ CR28 (TR 4) not used CR29 (TR 5) not used CR30 (TR 6) current / 0 CR31 (TR 7) Temporary register, used in various places +=============================== =============================================== - Space Registers (kernel mode) +Space Registers (kernel mode) +----------------------------- +=============================== =============================================== SR0 temporary space register SR4-SR7 set to 0 SR1 temporary space register SR2 kernel should not clobber this SR3 used for userspace accesses (current process) +=============================== =============================================== - Space Registers (user mode) +Space Registers (user mode) +--------------------------- +=============================== =============================================== SR0 temporary space register SR1 temporary space register SR2 holds space of linux gateway page SR3 holds user address space value while in kernel SR4-SR7 Defines short address space for user/kernel +=============================== =============================================== - Processor Status Word +Processor Status Word +--------------------- +=============================== =============================================== W (64-bit addresses) 0 E (Little-endian) 0 S (Secure Interval Timer) 0 @@ -69,15 +83,19 @@ Q (collect interruption state) 1 (0 in code directly preceding an rfi) P (Protection Identifiers) 1* D (Data address translation) 1, 0 while executing real-mode code I (external interrupt mask) used by cli()/sti() macros +=============================== =============================================== - "Invisible" Registers +"Invisible" Registers +--------------------- +=============================== =============================================== PSW default W value 0 PSW default E value 0 Shadow Registers used by interruption handler code TOC enable bit 1 +=============================== =============================================== -========================================================================= +------------------------------------------------------------------------- The PA-RISC architecture defines 7 registers as "shadow registers". Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce @@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register (GR) saves and restores in interruption handlers. Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25. -========================================================================= +------------------------------------------------------------------------- + Register usage notes, originally from John Marvin, with some additional notes from Randolph Chung. @@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling another procedure. Some of the above registers do have special meanings that you should be aware of: - r1: The addil instruction is hardwired to place its result in r1, + r1: + The addil instruction is hardwired to place its result in r1, so if you use that instruction be aware of that. - r2: This is the return pointer. In general you don't want to + r2: + This is the return pointer. In general you don't want to use this, since you need the pointer to get back to your caller. However, it is grouped with this set of registers since the caller can't rely on the value being the same @@ -107,23 +128,27 @@ that you should be aware of: and return through that register after trashing r2, and that should not cause a problem for the calling routine. - r19-r22: these are generally regarded as temporary registers. + r19-r22: + these are generally regarded as temporary registers. Note that in 64 bit they are arg7-arg4. - r23-r26: these are arg3-arg0, i.e. you can use them if you + r23-r26: + these are arg3-arg0, i.e. you can use them if you don't care about the values that were passed in anymore. - r28,r29: are ret0 and ret1. They are what you pass return values + r28,r29: + are ret0 and ret1. They are what you pass return values in. r28 is the primary return. When returning small structures r29 may also be used to pass data back to the caller. - r30: stack pointer + r30: + stack pointer - r31: the ble instruction puts the return pointer in here. + r31: + the ble instruction puts the return pointer in here. -r3-r18,r27,r30 need to be saved and restored. r3-r18 are just + r3-r18,r27,r30 need to be saved and restored. r3-r18 are just general purpose registers. r27 is the data pointer, and is used to make references to global variables easier. r30 is the stack pointer. - diff --git a/Documentation/power/opp.rst b/Documentation/power/opp.rst index b3cf1def9dee..209c7613f5a4 100644 --- a/Documentation/power/opp.rst +++ b/Documentation/power/opp.rst @@ -46,7 +46,7 @@ We can represent these as three OPPs as the following {Hz, uV} tuples: ---------------------------------------- OPP library provides a set of helper functions to organize and query the OPP -information. The library is located in drivers/base/power/opp.c and the header +information. The library is located in drivers/opp/ directory and the header is located in include/linux/pm_opp.h. OPP library can be enabled by enabling CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to diff --git a/Documentation/power/pm_qos_interface.rst b/Documentation/power/pm_qos_interface.rst index 69921f072ce1..3097694fba69 100644 --- a/Documentation/power/pm_qos_interface.rst +++ b/Documentation/power/pm_qos_interface.rst @@ -7,8 +7,7 @@ performance expectations by drivers, subsystems and user space applications on one of the parameters. Two different PM QoS frameworks are available: -1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput, -memory_bandwidth. +1. PM QoS classes for cpu_dma_latency 2. the per-device PM QoS framework provides the API to manage the per-device latency constraints and PM QoS flags. @@ -79,7 +78,7 @@ cleanup of a process, the interface requires the process to register its parameter requests in the following way: To register the default pm_qos target for the specific parameter, the process -must open one of /dev/[cpu_dma_latency, network_latency, network_throughput] +must open /dev/cpu_dma_latency As long as the device node is held open that process has a registered request on the parameter. diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 07faa5457bcb..5273d06c8ff6 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -40,7 +40,7 @@ Emailed patches should be in ASCII or UTF-8 encoding only. If you configure your email client to send emails with UTF-8 encoding, you avoid some possible charset problems. -Email clients should generate and maintain References: or In-Reply-To: +Email clients should generate and maintain "References:" or "In-Reply-To:" headers so that mail threading is not broken. Copy-and-paste (or cut-and-paste) usually does not work for patches @@ -89,7 +89,7 @@ Claws Mail (GUI) Works. Some people use this successfully for patches. -To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) or an external editor. If the inserted patch has to be edited in the Claws composition window @@ -132,8 +132,8 @@ wrapping. At the bottom of your email, put the commonly-used patch delimiter before inserting your patch: three hyphens (``---``). -Then from the :menuselection:`Message` menu item, select insert file and -choose your patch. +Then from the :menuselection:`Message` menu item, select +:menuselection:`insert file` and choose your patch. As an added bonus you can customise the message creation toolbar menu and put the :menuselection:`insert file` icon there. @@ -149,18 +149,16 @@ patches so do not GPG sign them. Signing patches that have been inserted as inlined text will make them tricky to extract from their 7-bit encoding. If you absolutely must send patches as attachments instead of inlining -them as text, right click on the attachment and select properties, and -highlight :menuselection:`Suggest automatic display` to make the attachment +them as text, right click on the attachment and select :menuselection:`properties`, +and highlight :menuselection:`Suggest automatic display` to make the attachment inlined to make it more viewable. When saving patches that are sent as inlined text, select the email that contains the patch from the message list pane, right click and select :menuselection:`save as`. You can use the whole email unmodified as a patch -if it was properly composed. There is no option currently to save the email -when you are actually viewing it in its own window -- there has been a request -filed at kmail's bugzilla and hopefully this will be addressed. Emails are -saved as read-write for user only so you will have to chmod them to make them -group and world readable if you copy them elsewhere. +if it was properly composed. Emails are saved as read-write for user only so +you will have to chmod them to make them group and world readable if you copy +them elsewhere. Lotus Notes (GUI) ***************** diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..402636356fbe --- /dev/null +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -0,0 +1,279 @@ +Embargoed hardware issues +========================= + +Scope +----- + +Hardware issues which result in security problems are a different category +of security bugs than pure software bugs which only affect the Linux +kernel. + +Hardware issues like Meltdown, Spectre, L1TF etc. must be treated +differently because they usually affect all Operating Systems ("OS") and +therefore need coordination across different OS vendors, distributions, +hardware vendors and other parties. For some of the issues, software +mitigations can depend on microcode or firmware updates, which need further +coordination. + +.. _Contact: + +Contact +------- + +The Linux kernel hardware security team is separate from the regular Linux +kernel security team. + +The team only handles the coordination of embargoed hardware security +issues. Reports of pure software security bugs in the Linux kernel are not +handled by this team and the reporter will be guided to contact the regular +Linux kernel security team (:ref:`Documentation/admin-guide/ +<securitybugs>`) instead. + +The team can be contacted by email at <hardware-security@kernel.org>. This +is a private list of security officers who will help you to coordinate an +issue according to our documented process. + +The list is encrypted and email to the list can be sent by either PGP or +S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME +certificate. The list's PGP key and S/MIME certificate are available from +https://www.kernel.org/.... + +While hardware security issues are often handled by the affected hardware +vendor, we welcome contact from researchers or individuals who have +identified a potential hardware flaw. + +Hardware security officers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The current team of hardware security officers: + + - Linus Torvalds (Linux Foundation Fellow) + - Greg Kroah-Hartman (Linux Foundation Fellow) + - Thomas Gleixner (Linux Foundation Fellow) + +Operation of mailing-lists +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The encrypted mailing-lists which are used in our process are hosted on +Linux Foundation's IT infrastructure. By providing this service Linux +Foundation's director of IT Infrastructure security technically has the +ability to access the embargoed information, but is obliged to +confidentiality by his employment contract. Linux Foundation's director of +IT Infrastructure security is also responsible for the kernel.org +infrastructure. + +The Linux Foundation's current director of IT Infrastructure security is +Konstantin Ryabitsev. + + +Non-disclosure agreements +------------------------- + +The Linux kernel hardware security team is not a formal body and therefore +unable to enter into any non-disclosure agreements. The kernel community +is aware of the sensitive nature of such issues and offers a Memorandum of +Understanding instead. + + +Memorandum of Understanding +--------------------------- + +The Linux kernel community has a deep understanding of the requirement to +keep hardware security issues under embargo for coordination between +different OS vendors, distributors, hardware vendors and other parties. + +The Linux kernel community has successfully handled hardware security +issues in the past and has the necessary mechanisms in place to allow +community compliant development under embargo restrictions. + +The Linux kernel community has a dedicated hardware security team for +initial contact, which oversees the process of handling such issues under +embargo rules. + +The hardware security team identifies the developers (domain experts) who +will form the initial response team for a particular issue. The initial +response team can bring in further developers (domain experts) to address +the issue in the best technical way. + +All involved developers pledge to adhere to the embargo rules and to keep +the received information confidential. Violation of the pledge will lead to +immediate exclusion from the current issue and removal from all related +mailing-lists. In addition, the hardware security team will also exclude +the offender from future issues. The impact of this consequence is a highly +effective deterrent in our community. In case a violation happens the +hardware security team will inform the involved parties immediately. If you +or anyone becomes aware of a potential violation, please report it +immediately to the Hardware security officers. + + +Process +^^^^^^^ + +Due to the globally distributed nature of Linux kernel development, +face-to-face meetings are almost impossible to address hardware security +issues. Phone conferences are hard to coordinate due to time zones and +other factors and should be only used when absolutely necessary. Encrypted +email has been proven to be the most effective and secure communication +method for these types of issues. + +Start of Disclosure +""""""""""""""""""" + +Disclosure starts by contacting the Linux kernel hardware security team by +email. This initial contact should contain a description of the problem and +a list of any known affected hardware. If your organization builds or +distributes the affected hardware, we encourage you to also consider what +other hardware could be affected. + +The hardware security team will provide an incident-specific encrypted +mailing-list which will be used for initial discussion with the reporter, +further disclosure and coordination. + +The hardware security team will provide the disclosing party a list of +developers (domain experts) who should be informed initially about the +issue after confirming with the developers that they will adhere to this +Memorandum of Understanding and the documented process. These developers +form the initial response team and will be responsible for handling the +issue after initial contact. The hardware security team is supporting the +response team, but is not necessarily involved in the mitigation +development process. + +While individual developers might be covered by a non-disclosure agreement +via their employer, they cannot enter individual non-disclosure agreements +in their role as Linux kernel developers. They will, however, agree to +adhere to this documented process and the Memorandum of Understanding. + + +Disclosure +"""""""""" + +The disclosing party provides detailed information to the initial response +team via the specific encrypted mailing-list. + +From our experience the technical documentation of these issues is usually +a sufficient starting point and further technical clarification is best +done via email. + +Mitigation development +"""""""""""""""""""""" + +The initial response team sets up an encrypted mailing-list or repurposes +an existing one if appropriate. The disclosing party should provide a list +of contacts for all other parties who have already been, or should be, +informed about the issue. The response team contacts these parties so they +can name experts who should be subscribed to the mailing-list. + +Using a mailing-list is close to the normal Linux development process and +has been successfully used in developing mitigations for various hardware +security issues in the past. + +The mailing-list operates in the same way as normal Linux development. +Patches are posted, discussed and reviewed and if agreed on applied to a +non-public git repository which is only accessible to the participating +developers via a secure connection. The repository contains the main +development branch against the mainline kernel and backport branches for +stable kernel versions as necessary. + +The initial response team will identify further experts from the Linux +kernel developer community as needed and inform the disclosing party about +their participation. Bringing in experts can happen at any time of the +development process and often needs to be handled in a timely manner. + +Coordinated release +""""""""""""""""""" + +The involved parties will negotiate the date and time where the embargo +ends. At that point the prepared mitigations are integrated into the +relevant kernel trees and published. + +While we understand that hardware security issues need coordinated embargo +time, the embargo time should be constrained to the minimum time which is +required for all involved parties to develop, test and prepare the +mitigations. Extending embargo time artificially to meet conference talk +dates or other non-technical reasons is creating more work and burden for +the involved developers and response teams as the patches need to be kept +up to date in order to follow the ongoing upstream kernel development, +which might create conflicting changes. + +CVE assignment +"""""""""""""" + +Neither the hardware security team nor the initial response team assign +CVEs, nor are CVEs required for the development process. If CVEs are +provided by the disclosing party they can be used for documentation +purposes. + +Process ambassadors +------------------- + +For assistance with this process we have established ambassadors in various +organizations, who can answer questions about or provide guidance on the +reporting process and further handling. Ambassadors are not involved in the +disclosure of a particular issue, unless requested by a response team or by +an involved disclosed party. The current ambassadors list: + + ============= ======================================================== + ARM + AMD + IBM + Intel + Qualcomm Trilok Soni <tsoni@codeaurora.org> + + Microsoft Sasha Levin <sashal@kernel.org> + VMware + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical Tyler Hicks <tyhicks@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Amazon + Google Kees Cook <keescook@chromium.org> + ============= ======================================================== + +If you want your organization to be added to the ambassadors list, please +contact the hardware security team. The nominated ambassador has to +understand and support our process fully and is ideally well connected in +the Linux kernel community. + +Encrypted mailing-lists +----------------------- + +We use encrypted mailing-lists for communication. The operating principle +of these lists is that email sent to the list is encrypted either with the +list's PGP key or with the list's S/MIME certificate. The mailing-list +software decrypts the email and re-encrypts it individually for each +subscriber with the subscriber's PGP key or S/MIME certificate. Details +about the mailing-list software and the setup which is used to ensure the +security of the lists and protection of the data can be found here: +https://www.kernel.org/.... + +List keys +^^^^^^^^^ + +For initial contact see :ref:`Contact`. For incident specific mailing-lists +the key and S/MIME certificate are conveyed to the subscribers by email +sent from the specific list. + +Subscription to incident specific lists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Subscription is handled by the response teams. Disclosed parties who want +to participate in the communication send a list of potential subscribers to +the response team so the response team can validate subscription requests. + +Each subscriber needs to send a subscription request to the response team +by email. The email must be signed with the subscriber's PGP key or S/MIME +certificate. If a PGP key is used, it must be available from a public key +server and is ideally connected to the Linux kernel's PGP web of trust. See +also: https://www.kernel.org/signature.html. + +The response team verifies that the subscriber request is valid and adds +the subscriber to the list. After subscription the subscriber will receive +email from the mailing-list which is signed either with the list's PGP key +or the list's S/MIME certificate. The subscriber's email client can extract +the PGP key or the S/MIME certificate from the signature so the subscriber +can send encrypted email to the list. + diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6ab75c11d2c3..b6f5a379ad6c 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -123,7 +123,7 @@ required reading: https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` This file describes the rationale behind the conscious decision to diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 878ebfda7eef..e2c9ffc682c5 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -45,6 +45,7 @@ Other guides to the community that are of interest to most developers are: submit-checklist kernel-docs deprecated + embargoed-hardware-issues These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 9c4299293c72..fb56297f70dc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -844,7 +844,7 @@ Andrew Morton, "The perfect patch" (tpp). <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". - <http://linux.yyz.us/patch-format.html> + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer.html> diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.rst index 1b73fea23b39..7b4d1d747585 100644 --- a/Documentation/riscv/boot-image-header.txt +++ b/Documentation/riscv/boot-image-header.rst @@ -1,50 +1,62 @@ - Boot image header in RISC-V Linux - ============================================= +================================= +Boot image header in RISC-V Linux +================================= -Author: Atish Patra <atish.patra@wdc.com> -Date : 20 May 2019 +:Author: Atish Patra <atish.patra@wdc.com> +:Date: 20 May 2019 This document only describes the boot image header details for RISC-V Linux. -The complete booting guide will be available at Documentation/riscv/booting.txt. -The following 64-byte header is present in decompressed Linux kernel image. +TODO: + Write a complete booting guide. + +The following 64-byte header is present in decompressed Linux kernel image:: u32 code0; /* Executable code */ - u32 code1; /* 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 */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ - u32 res3; /* Reserved for additional RISC-V specific header */ + u32 magic2 = 0x56534905; /* Magic number 2, little endian, "RSC\x05" */ u32 res4; /* Reserved for PE COFF offset */ This header format is compliant with PE/COFF header and largely inspired from ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common header in future. -Notes: +Notes +===== + - This header can also be reused to support EFI stub for RISC-V in future. EFI specification needs PE/COFF image header in the beginning of the kernel image in order to load it as an EFI application. In order to support EFI stub, code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should point to the rest of the PE/COFF header. -- version field indicate header version number. - Bits 0:15 - Minor version - Bits 16:31 - Major version +- version field indicate header version number + + ========== ============= + Bits 0:15 Minor version + Bits 16:31 Major version + ========== ============= This preserves compatibility across newer and older version of the header. - The current version is defined as 0.1. + The current version is defined as 0.2. + +- The "magic" field is deprecated as of version 0.2. In a future + release, it may be removed. This originally should have matched up + with the ARM64 header "magic" field, but unfortunately does not. + The "magic2" field replaces it, matching up with the ARM64 header. -- res3 is reserved for offset to any other additional fields. This makes the - header extendible in future. One example would be to accommodate ISA - extension for RISC-V in future. For current version, it is set to be zero. +- In current header, the flags field has only one field. -- In current header, the flag field has only one field. - Bit 0: Kernel endianness. 1 if BE, 0 if LE. + ===== ==================================== + Bit 0 Kernel endianness. 1 if BE, 0 if LE. + ===== ==================================== - Image size is mandatory for boot loader to load kernel image. Booting will fail otherwise. diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst index e3ca0922a8c2..215fd3c1f2d5 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/riscv/index.rst @@ -5,6 +5,7 @@ RISC-V architecture .. toctree:: :maxdepth: 1 + boot-image-header pmu .. only:: subproject and html diff --git a/Documentation/s390/dasd.rst b/Documentation/s390/dasd.rst deleted file mode 100644 index 9e22247285c8..000000000000 --- a/Documentation/s390/dasd.rst +++ /dev/null @@ -1,84 +0,0 @@ -================== -DASD device driver -================== - -S/390's disk devices (DASDs) are managed by Linux via the DASD device -driver. It is valid for all types of DASDs and represents them to -Linux as block devices, namely "dd". Currently the DASD driver uses a -single major number (254) and 4 minor numbers per volume (1 for the -physical volume and 3 for partitions). With respect to partitions see -below. Thus you may have up to 64 DASD devices in your system. - -The kernel parameter 'dasd=from-to,...' may be issued arbitrary times -in the kernel's parameter line or not at all. The 'from' and 'to' -parameters are to be given in hexadecimal notation without a leading -0x. -If you supply kernel parameters the different instances are processed -in order of appearance and a minor number is reserved for any device -covered by the supplied range up to 64 volumes. Additional DASDs are -ignored. If you do not supply the 'dasd=' kernel parameter at all, the -DASD driver registers all supported DASDs of your system to a minor -number in ascending order of the subchannel number. - -The driver currently supports ECKD-devices and there are stubs for -support of the FBA and CKD architectures. For the FBA architecture -only some smart data structures are missing to make the support -complete. -We performed our testing on 3380 and 3390 type disks of different -sizes, under VM and on the bare hardware (LPAR), using internal disks -of the multiprise as well as a RAMAC virtual array. Disks exported by -an Enterprise Storage Server (Seascape) should work fine as well. - -We currently implement one partition per volume, which is the whole -volume, skipping the first blocks up to the volume label. These are -reserved for IPL records and IBM's volume label to assure -accessibility of the DASD from other OSs. In a later stage we will -provide support of partitions, maybe VTOC oriented or using a kind of -partition table in the label record. - -Usage -===== - --Low-level format (?CKD only) -For using an ECKD-DASD as a Linux harddisk you have to low-level -format the tracks by issuing the BLKDASDFORMAT-ioctl on that -device. This will erase any data on that volume including IBM volume -labels, VTOCs etc. The ioctl may take a `struct format_data *` or -'NULL' as an argument:: - - typedef struct { - int start_unit; - int stop_unit; - int blksize; - } format_data_t; - -When a NULL argument is passed to the BLKDASDFORMAT ioctl the whole -disk is formatted to a blocksize of 1024 bytes. Otherwise start_unit -and stop_unit are the first and last track to be formatted. If -stop_unit is -1 it implies that the DASD is formatted from start_unit -up to the last track. blksize can be any power of two between 512 and -4096. We recommend no blksize lower than 1024 because the ext2fs uses -1kB blocks anyway and you gain approx. 50% of capacity increasing your -blksize from 512 byte to 1kB. - -Make a filesystem -================= - -Then you can mk??fs the filesystem of your choice on that volume or -partition. For reasons of sanity you should build your filesystem on -the partition /dev/dd?1 instead of the whole volume. You only lose 3kB -but may be sure that you can reuse your data after introduction of a -real partition table. - -Bugs -==== - -- Performance sometimes is rather low because we don't fully exploit clustering - -TODO-List -========= - -- Add IBM'S Disk layout to genhd -- Enhance driver to use more than one major number -- Enable usage as a module -- Support Cache fast write and DASD fast write (ECKD) diff --git a/Documentation/s390/debugging390.rst b/Documentation/s390/debugging390.rst deleted file mode 100644 index 73ad0b06c666..000000000000 --- a/Documentation/s390/debugging390.rst +++ /dev/null @@ -1,2613 +0,0 @@ -============================================= -Debugging on Linux for s/390 & z/Architecture -============================================= - -Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com) - -Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation - -.. Best viewed with fixed width fonts - -Overview of Document: -===================== -This document is intended to give a good overview of how to debug Linux for -s/390 and z/Architecture. It is not intended as a complete reference and not a -tutorial on the fundamentals of C & assembly. It doesn't go into -390 IO in any detail. It is intended to complement the documents in the -reference section below & any other worthwhile references you get. - -It is intended like the Enterprise Systems Architecture/390 Reference Summary -to be printed out & used as a quick cheat sheet self help style reference when -problems occur. - -.. Contents - ======== - Register Set - Address Spaces on Intel Linux - Address Spaces on Linux for s/390 & z/Architecture - The Linux for s/390 & z/Architecture Kernel Task Structure - Register Usage & Stackframes on Linux for s/390 & z/Architecture - A sample program with comments - Compiling programs for debugging on Linux for s/390 & z/Architecture - Debugging under VM - s/390 & z/Architecture IO Overview - Debugging IO on s/390 & z/Architecture under VM - GDB on s/390 & z/Architecture - Stack chaining in gdb by hand - Examining core dumps - ldd - Debugging modules - The proc file system - SysRq - References - Special Thanks - -Register Set -============ -The current architectures have the following registers. - -16 General propose registers, 32 bit on s/390 and 64 bit on z/Architecture, -r0-r15 (or gpr0-gpr15), used for arithmetic and addressing. - -16 Control registers, 32 bit on s/390 and 64 bit on z/Architecture, cr0-cr15, -kernel usage only, used for memory management, interrupt control, debugging -control etc. - -16 Access registers (ar0-ar15), 32 bit on both s/390 and z/Architecture, -normally not used by normal programs but potentially could be used as -temporary storage. These registers have a 1:1 association with general -purpose registers and are designed to be used in the so-called access -register mode to select different address spaces. -Access register 0 (and access register 1 on z/Architecture, which needs a -64 bit pointer) is currently used by the pthread library as a pointer to -the current running threads private area. - -16 64-bit floating point registers (fp0-fp15 ) IEEE & HFP floating -point format compliant on G5 upwards & a Floating point control reg (FPC) - -4 64-bit registers (fp0,fp2,fp4 & fp6) HFP only on older machines. - -Note: - Linux (currently) always uses IEEE & emulates G5 IEEE format on older - machines, ( provided the kernel is configured for this ). - - -The PSW is the most important register on the machine it -is 64 bit on s/390 & 128 bit on z/Architecture & serves the roles of -a program counter (pc), condition code register,memory space designator. -In IBM standard notation I am counting bit 0 as the MSB. -It has several advantages over a normal program counter -in that you can change address translation & program counter -in a single instruction. To change address translation, -e.g. switching address translation off requires that you -have a logical=physical mapping for the address you are -currently running at. - -+-------------------------+-------------------------------------------------+ -| Bit | | -+--------+----------------+ Value | -| s/390 | z/Architecture | | -+========+================+=================================================+ -| 0 | 0 | Reserved (must be 0) otherwise specification | -| | | exception occurs. | -+--------+----------------+-------------------------------------------------+ -| 1 | 1 | Program Event Recording 1 PER enabled, | -| | | PER is used to facilitate debugging e.g. | -| | | single stepping. | -+--------+----------------+-------------------------------------------------+ -| 2-4 | 2-4 | Reserved (must be 0). | -+--------+----------------+-------------------------------------------------+ -| 5 | 5 | Dynamic address translation 1=DAT on. | -+--------+----------------+-------------------------------------------------+ -| 6 | 6 | Input/Output interrupt Mask | -+--------+----------------+-------------------------------------------------+ -| 7 | 7 | External interrupt Mask used primarily for | -| | | interprocessor signalling and clock interrupts. | -+--------+----------------+-------------------------------------------------+ -| 8-11 | 8-11 | PSW Key used for complex memory protection | -| | | mechanism (not used under linux) | -+--------+----------------+-------------------------------------------------+ -| 12 | 12 | 1 on s/390 0 on z/Architecture | -+--------+----------------+-------------------------------------------------+ -| 13 | 13 | Machine Check Mask 1=enable machine check | -| | | interrupts | -+--------+----------------+-------------------------------------------------+ -| 14 | 14 | Wait State. Set this to 1 to stop the processor | -| | | except for interrupts and give time to other | -| | | LPARS. Used in CPU idle in the kernel to | -| | | increase overall usage of processor resources. | -+--------+----------------+-------------------------------------------------+ -| 15 | 15 | Problem state (if set to 1 certain instructions | -| | | are disabled). All linux user programs run with | -| | | this bit 1 (useful info for debugging under VM).| -+--------+----------------+-------------------------------------------------+ -| 16-17 | 16-17 | Address Space Control | -| | | | -| | | 00 Primary Space Mode: | -| | | | -| | | The register CR1 contains the primary | -| | | address-space control element (PASCE), which | -| | | points to the primary space region/segment | -| | | table origin. | -| | | | -| | | 01 Access register mode | -| | | | -| | | 10 Secondary Space Mode: | -| | | | -| | | The register CR7 contains the secondary | -| | | address-space control element (SASCE), which | -| | | points to the secondary space region or | -| | | segment table origin. | -| | | | -| | | 11 Home Space Mode: | -| | | | -| | | The register CR13 contains the home space | -| | | address-space control element (HASCE), which | -| | | points to the home space region/segment | -| | | table origin. | -| | | | -| | | See "Address Spaces on Linux for s/390 & | -| | | z/Architecture" below for more information | -| | | about address space usage in Linux. | -+--------+----------------+-------------------------------------------------+ -| 18-19 | 18-19 | Condition codes (CC) | -+--------+----------------+-------------------------------------------------+ -| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions | -| | | for this event occur (normally 0) | -+--------+----------------+-------------------------------------------------+ -| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for | -| | | this event occur (normally 0) | -+--------+----------------+-------------------------------------------------+ -| 22 | 22 | Exponent underflow mask if 1=FPU exceptions | -| | | for this event occur (normally 0) | -+--------+----------------+-------------------------------------------------+ -| 23 | 23 | Significance Mask if 1=FPU exceptions for this | -| | | event occur (normally 0) | -+--------+----------------+-------------------------------------------------+ -| 24-31 | 24-30 | Reserved Must be 0. | -| +----------------+-------------------------------------------------+ -| | 31 | Extended Addressing Mode | -| +----------------+-------------------------------------------------+ -| | 32 | Basic Addressing Mode | -| | | | -| | | Used to set addressing mode:: | -| | | | -| | | +---------+----------+----------+ | -| | | | PSW 31 | PSW 32 | | | -| | | +---------+----------+----------+ | -| | | | 0 | 0 | 24 bit | | -| | | +---------+----------+----------+ | -| | | | 0 | 1 | 31 bit | | -| | | +---------+----------+----------+ | -| | | | 1 | 1 | 64 bit | | -| | | +---------+----------+----------+ | -+--------+----------------+-------------------------------------------------+ -| 32 | | 1=31 bit addressing mode 0=24 bit addressing | -| | | mode (for backward compatibility), linux | -| | | always runs with this bit set to 1 | -+--------+----------------+-------------------------------------------------+ -| 33-64 | | Instruction address. | -| +----------------+-------------------------------------------------+ -| | 33-63 | Reserved must be 0 | -| +----------------+-------------------------------------------------+ -| | 64-127 | Address | -| | | | -| | | - In 24 bits mode bits 64-103=0 bits 104-127 | -| | | Address | -| | | - In 31 bits mode bits 64-96=0 bits 97-127 | -| | | Address | -| | | | -| | | Note: | -| | | unlike 31 bit mode on s/390 bit 96 must be | -| | | zero when loading the address with LPSWE | -| | | otherwise a specification exception occurs, | -| | | LPSW is fully backward compatible. | -+--------+----------------+-------------------------------------------------+ - -Prefix Page(s) --------------- -This per cpu memory area is too intimately tied to the processor not to mention. -It exists between the real addresses 0-4096 on s/390 and between 0-8192 on -z/Architecture and is exchanged with one page on s/390 or two pages on -z/Architecture in absolute storage by the set prefix instruction during Linux -startup. - -This page is mapped to a different prefix for each processor in an SMP -configuration (assuming the OS designer is sane of course). - -Bytes 0-512 (200 hex) on s/390 and 0-512, 4096-4544, 4604-5119 currently on -z/Architecture are used by the processor itself for holding such information -as exception indications and entry points for exceptions. - -Bytes after 0xc00 hex are used by linux for per processor globals on s/390 and -z/Architecture (there is a gap on z/Architecture currently between 0xc00 and -0x1000, too, which is used by Linux). - -The closest thing to this on traditional architectures is the interrupt -vector table. This is a good thing & does simplify some of the kernel coding -however it means that we now cannot catch stray NULL pointers in the -kernel without hard coded checks. - - - -Address Spaces on Intel Linux -============================= - -The traditional Intel Linux is approximately mapped as follows forgive -the ascii art:: - - 0xFFFFFFFF 4GB Himem ***************** - * * - * Kernel Space * - * * - ***************** **************** - User Space Himem * User Stack * * * - (typically 0xC0000000 3GB ) ***************** * * - * Shared Libs * * Next Process * - ***************** * to * - * * <== * Run * <== - * User Program * * * - * Data BSS * * * - * Text * * * - * Sections * * * - 0x00000000 ***************** **************** - -Now it is easy to see that on Intel it is quite easy to recognise a kernel -address as being one greater than user space himem (in this case 0xC0000000), -and addresses of less than this are the ones in the current running program on -this processor (if an smp box). - -If using the virtual machine ( VM ) as a debugger it is quite difficult to -know which user process is running as the address space you are looking at -could be from any process in the run queue. - -The limitation of Intels addressing technique is that the linux -kernel uses a very simple real address to virtual addressing technique -of Real Address=Virtual Address-User Space Himem. -This means that on Intel the kernel linux can typically only address -Himem=0xFFFFFFFF-0xC0000000=1GB & this is all the RAM these machines -can typically use. - -They can lower User Himem to 2GB or lower & thus be -able to use 2GB of RAM however this shrinks the maximum size -of User Space from 3GB to 2GB they have a no win limit of 4GB unless -they go to 64 Bit. - - -On 390 our limitations & strengths make us slightly different. -For backward compatibility we are only allowed use 31 bits (2GB) -of our 32 bit addresses, however, we use entirely separate address -spaces for the user & kernel. - -This means we can support 2GB of non Extended RAM on s/390, & more -with the Extended memory management swap device & -currently 4TB of physical memory currently on z/Architecture. - - -Address Spaces on Linux for s/390 & z/Architecture -================================================== - -Our addressing scheme is basically as follows:: - - Primary Space Home Space - Himem 0x7fffffff 2GB on s/390 ***************** **************** - currently 0x3ffffffffff (2^42)-1 * User Stack * * * - on z/Architecture. ***************** * * - * Shared Libs * * * - ***************** * * - * * * Kernel * - * User Program * * * - * Data BSS * * * - * Text * * * - * Sections * * * - 0x00000000 ***************** **************** - -This also means that we need to look at the PSW problem state bit and the -addressing mode to decide whether we are looking at user or kernel space. - -User space runs in primary address mode (or access register mode within -the vdso code). - -The kernel usually also runs in home space mode, however when accessing -user space the kernel switches to primary or secondary address mode if -the mvcos instruction is not available or if a compare-and-swap (futex) -instruction on a user space address is performed. - -When also looking at the ASCE control registers, this means: - -User space: - -- runs in primary or access register mode -- cr1 contains the user asce -- cr7 contains the user asce -- cr13 contains the kernel asce - -Kernel space: - -- runs in home space mode -- cr1 contains the user or kernel asce - - - the kernel asce is loaded when a uaccess requires primary or - secondary address mode - -- cr7 contains the user or kernel asce, (changed with set_fs()) -- cr13 contains the kernel asce - -In case of uaccess the kernel changes to: - -- primary space mode in case of a uaccess (copy_to_user) and uses - e.g. the mvcp instruction to access user space. However the kernel - will stay in home space mode if the mvcos instruction is available -- secondary space mode in case of futex atomic operations, so that the - instructions come from primary address space and data from secondary - space - -In case of KVM, the kernel runs in home space mode, but cr1 gets switched -to contain the gmap asce before the SIE instruction gets executed. When -the SIE instruction is finished, cr1 will be switched back to contain the -user asce. - - -Virtual Addresses on s/390 & z/Architecture -=========================================== - -A virtual address on s/390 is made up of 3 parts -The SX (segment index, roughly corresponding to the PGD & PMD in Linux -terminology) being bits 1-11. - -The PX (page index, corresponding to the page table entry (pte) in Linux -terminology) being bits 12-19. - -The remaining bits BX (the byte index are the offset in the page ) -i.e. bits 20 to 31. - -On z/Architecture in linux we currently make up an address from 4 parts. - -- The region index bits (RX) 0-32 we currently use bits 22-32 -- The segment index (SX) being bits 33-43 -- The page index (PX) being bits 44-51 -- The byte index (BX) being bits 52-63 - -Notes: - 1) s/390 has no PMD so the PMD is really the PGD also. - A lot of this stuff is defined in pgtable.h. - - 2) Also seeing as s/390's page indexes are only 1k in size - (bits 12-19 x 4 bytes per pte ) we use 1 ( page 4k ) - to make the best use of memory by updating 4 segment indices - entries each time we mess with a PMD & use offsets - 0,1024,2048 & 3072 in this page as for our segment indexes. - On z/Architecture our page indexes are now 2k in size - ( bits 12-19 x 8 bytes per pte ) we do a similar trick - but only mess with 2 segment indices each time we mess with - a PMD. - - 3) As z/Architecture supports up to a massive 5-level page table lookup we - can only use 3 currently on Linux ( as this is all the generic kernel - currently supports ) however this may change in future - this allows us to access ( according to my sums ) - 4TB of virtual storage per process i.e. - 4096*512(PTES)*1024(PMDS)*2048(PGD) = 4398046511104 bytes, - enough for another 2 or 3 of years I think :-). - to do this we use a region-third-table designation type in - our address space control registers. - - -The Linux for s/390 & z/Architecture Kernel Task Structure -========================================================== -Each process/thread under Linux for S390 has its own kernel task_struct -defined in linux/include/linux/sched.h -The S390 on initialisation & resuming of a process on a cpu sets -the __LC_KERNEL_STACK variable in the spare prefix area for this cpu -(which we use for per-processor globals). - -The kernel stack pointer is intimately tied with the task structure for -each processor as follows:: - - s/390 - ************************ - * 1 page kernel stack * - * ( 4K ) * - ************************ - * 1 page task_struct * - * ( 4K ) * - 8K aligned ************************ - - z/Architecture - ************************ - * 2 page kernel stack * - * ( 8K ) * - ************************ - * 2 page task_struct * - * ( 8K ) * - 16K aligned ************************ - -What this means is that we don't need to dedicate any register or global -variable to point to the current running process & can retrieve it with the -following very simple construct for s/390 & one very similar for -z/Architecture:: - - static inline struct task_struct * get_current(void) - { - struct task_struct *current; - __asm__("lhi %0,-8192\n\t" - "nr %0,15" - : "=r" (current) ); - return current; - } - -i.e. just anding the current kernel stack pointer with the mask -8192. -Thankfully because Linux doesn't have support for nested IO interrupts -& our devices have large buffers can survive interrupts being shut for -short amounts of time we don't need a separate stack for interrupts. - - - - -Register Usage & Stackframes on Linux for s/390 & z/Architecture -================================================================= -Overview: ---------- -This is the code that gcc produces at the top & the bottom of -each function. It usually is fairly consistent & similar from -function to function & if you know its layout you can probably -make some headway in finding the ultimate cause of a problem -after a crash without a source level debugger. - -Note: To follow stackframes requires a knowledge of C or Pascal & -limited knowledge of one assembly language. - -It should be noted that there are some differences between the -s/390 and z/Architecture stack layouts as the z/Architecture stack layout -didn't have to maintain compatibility with older linkage formats. - -Glossary: ---------- -alloca: - This is a built in compiler function for runtime allocation - of extra space on the callers stack which is obviously freed - up on function exit ( e.g. the caller may choose to allocate nothing - of a buffer of 4k if required for temporary purposes ), it generates - very efficient code ( a few cycles ) when compared to alternatives - like malloc. - -automatics: - These are local variables on the stack, i.e they aren't in registers & - they aren't static. - -back-chain: - This is a pointer to the stack pointer before entering a - framed functions ( see frameless function ) prologue got by - dereferencing the address of the current stack pointer, - i.e. got by accessing the 32 bit value at the stack pointers - current location. - -base-pointer: - This is a pointer to the back of the literal pool which - is an area just behind each procedure used to store constants - in each function. - -call-clobbered: - The caller probably needs to save these registers if there - is something of value in them, on the stack or elsewhere before making a - call to another procedure so that it can restore it later. - -epilogue: - The code generated by the compiler to return to the caller. - -frameless-function: - A frameless function in Linux for s390 & z/Architecture is one which doesn't - need more than the register save area (96 bytes on s/390, 160 on z/Architecture) - given to it by the caller. - - A frameless function never: - - 1) Sets up a back chain. - 2) Calls alloca. - 3) Calls other normal functions - 4) Has automatics. - -GOT-pointer: - This is a pointer to the global-offset-table in ELF - ( Executable Linkable Format, Linux'es most common executable format ), - all globals & shared library objects are found using this pointer. - -lazy-binding - ELF shared libraries are typically only loaded when routines in the shared - library are actually first called at runtime. This is lazy binding. - -procedure-linkage-table - This is a table found from the GOT which contains pointers to routines - in other shared libraries which can't be called to by easier means. - -prologue: - The code generated by the compiler to set up the stack frame. - -outgoing-args: - This is extra area allocated on the stack of the calling function if the - parameters for the callee's cannot all be put in registers, the same - area can be reused by each function the caller calls. - -routine-descriptor: - A COFF executable format based concept of a procedure reference - actually being 8 bytes or more as opposed to a simple pointer to the routine. - This is typically defined as follows: - - - Routine Descriptor offset 0=Pointer to Function - - Routine Descriptor offset 4=Pointer to Table of Contents - - The table of contents/TOC is roughly equivalent to a GOT pointer. - & it means that shared libraries etc. can be shared between several - environments each with their own TOC. - -static-chain: - This is used in nested functions a concept adopted from pascal - by gcc not used in ansi C or C++ ( although quite useful ), basically it - is a pointer used to reference local variables of enclosing functions. - You might come across this stuff once or twice in your lifetime. - - e.g. - - The function below should return 11 though gcc may get upset & toss warnings - about unused variables:: - - int FunctionA(int a) - { - int b; - FunctionC(int c) - { - b=c+1; - } - FunctionC(10); - return(b); - } - - -s/390 & z/Architecture Register usage -===================================== - -======== ========================================== =============== -r0 used by syscalls/assembly call-clobbered -r1 used by syscalls/assembly call-clobbered -r2 argument 0 / return value 0 call-clobbered -r3 argument 1 / return value 1 (if long long) call-clobbered -r4 argument 2 call-clobbered -r5 argument 3 call-clobbered -r6 argument 4 saved -r7 pointer-to arguments 5 to ... saved -r8 this & that saved -r9 this & that saved -r10 static-chain ( if nested function ) saved -r11 frame-pointer ( if function used alloca ) saved -r12 got-pointer saved -r13 base-pointer saved -r14 return-address saved -r15 stack-pointer saved - -f0 argument 0 / return value ( float/double ) call-clobbered -f2 argument 1 call-clobbered -f4 z/Architecture argument 2 saved -f6 z/Architecture argument 3 saved -======== ========================================== =============== - -The remaining floating points -f1,f3,f5 f7-f15 are call-clobbered. - -Notes: ------- -1) The only requirement is that registers which are used - by the callee are saved, e.g. the compiler is perfectly - capable of using r11 for purposes other than a frame a - frame pointer if a frame pointer is not needed. -2) In functions with variable arguments e.g. printf the calling procedure - is identical to one without variable arguments & the same number of - parameters. However, the prologue of this function is somewhat more - hairy owing to it having to move these parameters to the stack to - get va_start, va_arg & va_end to work. -3) Access registers are currently unused by gcc but are used in - the kernel. Possibilities exist to use them at the moment for - temporary storage but it isn't recommended. -4) Only 4 of the floating point registers are used for - parameter passing as older machines such as G3 only have only 4 - & it keeps the stack frame compatible with other compilers. - However with IEEE floating point emulation under linux on the - older machines you are free to use the other 12. -5) A long long or double parameter cannot be have the - first 4 bytes in a register & the second four bytes in the - outgoing args area. It must be purely in the outgoing args - area if crossing this boundary. -6) Floating point parameters are mixed with outgoing args - on the outgoing args area in the order the are passed in as parameters. -7) Floating point arguments 2 & 3 are saved in the outgoing args area for - z/Architecture - - -Stack Frame Layout ------------------- - -========= ============== ====================================================== -s/390 z/Architecture -========= ============== ====================================================== -0 0 back chain ( a 0 here signifies end of back chain ) -4 8 eos ( end of stack, not used on Linux for S390 used - in other linkage formats ) -8 16 glue used in other s/390 linkage formats for saved - routine descriptors etc. -12 24 glue used in other s/390 linkage formats for saved - routine descriptors etc. -16 32 scratch area -20 40 scratch area -24 48 saved r6 of caller function -28 56 saved r7 of caller function -32 64 saved r8 of caller function -36 72 saved r9 of caller function -40 80 saved r10 of caller function -44 88 saved r11 of caller function -48 96 saved r12 of caller function -52 104 saved r13 of caller function -56 112 saved r14 of caller function -60 120 saved r15 of caller function -64 128 saved f4 of caller function -72 132 saved f6 of caller function -80 undefined -96 160 outgoing args passed from caller to callee -96+x 160+x possible stack alignment ( 8 bytes desirable ) -96+x+y 160+x+y alloca space of caller ( if used ) -96+x+y+z 160+x+y+z automatics of caller ( if used ) -0 back-chain -========= ============== ====================================================== - -A sample program with comments. -=============================== - -Comments on the function test ------------------------------ -1) It didn't need to set up a pointer to the constant pool gpr13 as it is not - used ( :-( ). -2) This is a frameless function & no stack is bought. -3) The compiler was clever enough to recognise that it could return the - value in r2 as well as use it for the passed in parameter ( :-) ). -4) The basr ( branch relative & save ) trick works as follows the instruction - has a special case with r0,r0 with some instruction operands is understood as - the literal value 0, some risc architectures also do this ). So now - we are branching to the next address & the address new program counter is - in r13,so now we subtract the size of the function prologue we have executed - the size of the literal pool to get to the top of the literal pool:: - - - 0040037c int test(int b) - { # Function prologue below - 40037c: 90 de f0 34 stm %r13,%r14,52(%r15) # Save registers r13 & r14 - 400380: 0d d0 basr %r13,%r0 # Set up pointer to constant pool using - 400382: a7 da ff fa ahi %r13,-6 # basr trick - return(5+b); - # Huge main program - 400386: a7 2a 00 05 ahi %r2,5 # add 5 to r2 - - # Function epilogue below - 40038a: 98 de f0 34 lm %r13,%r14,52(%r15) # restore registers r13 & 14 - 40038e: 07 fe br %r14 # return - } - -Comments on the function main ------------------------------ -1) The compiler did this function optimally ( 8-) ):: - - Literal pool for main. - 400390: ff ff ff ec .long 0xffffffec - main(int argc,char *argv[]) - { # Function prologue below - 400394: 90 bf f0 2c stm %r11,%r15,44(%r15) # Save necessary registers - 400398: 18 0f lr %r0,%r15 # copy stack pointer to r0 - 40039a: a7 fa ff a0 ahi %r15,-96 # Make area for callee saving - 40039e: 0d d0 basr %r13,%r0 # Set up r13 to point to - 4003a0: a7 da ff f0 ahi %r13,-16 # literal pool - 4003a4: 50 00 f0 00 st %r0,0(%r15) # Save backchain - - return(test(5)); # Main Program Below - 4003a8: 58 e0 d0 00 l %r14,0(%r13) # load relative address of test from - # literal pool - 4003ac: a7 28 00 05 lhi %r2,5 # Set first parameter to 5 - 4003b0: 4d ee d0 00 bas %r14,0(%r14,%r13) # jump to test setting r14 as return - # address using branch & save instruction. - - # Function Epilogue below - 4003b4: 98 bf f0 8c lm %r11,%r15,140(%r15)# Restore necessary registers. - 4003b8: 07 fe br %r14 # return to do program exit - } - - -Compiler updates ----------------- - -:: - - main(int argc,char *argv[]) - { - 4004fc: 90 7f f0 1c stm %r7,%r15,28(%r15) - 400500: a7 d5 00 04 bras %r13,400508 <main+0xc> - 400504: 00 40 04 f4 .long 0x004004f4 - # compiler now puts constant pool in code to so it saves an instruction - 400508: 18 0f lr %r0,%r15 - 40050a: a7 fa ff a0 ahi %r15,-96 - 40050e: 50 00 f0 00 st %r0,0(%r15) - return(test(5)); - 400512: 58 10 d0 00 l %r1,0(%r13) - 400516: a7 28 00 05 lhi %r2,5 - 40051a: 0d e1 basr %r14,%r1 - # compiler adds 1 extra instruction to epilogue this is done to - # avoid processor pipeline stalls owing to data dependencies on g5 & - # above as register 14 in the old code was needed directly after being loaded - # by the lm %r11,%r15,140(%r15) for the br %14. - 40051c: 58 40 f0 98 l %r4,152(%r15) - 400520: 98 7f f0 7c lm %r7,%r15,124(%r15) - 400524: 07 f4 br %r4 - } - - -Hartmut ( our compiler developer ) also has been threatening to take out the -stack backchain in optimised code as this also causes pipeline stalls, you -have been warned. - -64 bit z/Architecture code disassembly --------------------------------------- - -If you understand the stuff above you'll understand the stuff -below too so I'll avoid repeating myself & just say that -some of the instructions have g's on the end of them to indicate -they are 64 bit & the stack offsets are a bigger, -the only other difference you'll find between 32 & 64 bit is that -we now use f4 & f6 for floating point arguments on 64 bit:: - - 00000000800005b0 <test>: - int test(int b) - { - return(5+b); - 800005b0: a7 2a 00 05 ahi %r2,5 - 800005b4: b9 14 00 22 lgfr %r2,%r2 # downcast to integer - 800005b8: 07 fe br %r14 - 800005ba: 07 07 bcr 0,%r7 - - - } - - 00000000800005bc <main>: - main(int argc,char *argv[]) - { - 800005bc: eb bf f0 58 00 24 stmg %r11,%r15,88(%r15) - 800005c2: b9 04 00 1f lgr %r1,%r15 - 800005c6: a7 fb ff 60 aghi %r15,-160 - 800005ca: e3 10 f0 00 00 24 stg %r1,0(%r15) - return(test(5)); - 800005d0: a7 29 00 05 lghi %r2,5 - # brasl allows jumps > 64k & is overkill here bras would do fune - 800005d4: c0 e5 ff ff ff ee brasl %r14,800005b0 <test> - 800005da: e3 40 f1 10 00 04 lg %r4,272(%r15) - 800005e0: eb bf f0 f8 00 04 lmg %r11,%r15,248(%r15) - 800005e6: 07 f4 br %r4 - } - - - -Compiling programs for debugging on Linux for s/390 & z/Architecture -==================================================================== --gdwarf-2 now works it should be considered the default debugging -format for s/390 & z/Architecture as it is more reliable for debugging -shared libraries, normal -g debugging works much better now -Thanks to the IBM java compiler developers bug reports. - -This is typically done adding/appending the flags -g or -gdwarf-2 to the -CFLAGS & LDFLAGS variables Makefile of the program concerned. - -If using gdb & you would like accurate displays of registers & -stack traces compile without optimisation i.e make sure -that there is no -O2 or similar on the CFLAGS line of the Makefile & -the emitted gcc commands, obviously this will produce worse code -( not advisable for shipment ) but it is an aid to the debugging process. - -This aids debugging because the compiler will copy parameters passed in -in registers onto the stack so backtracing & looking at passed in -parameters will work, however some larger programs which use inline functions -will not compile without optimisation. - -Debugging with optimisation has since much improved after fixing -some bugs, please make sure you are using gdb-5.0 or later developed -after Nov'2000. - - - -Debugging under VM -================== - -Notes ------ -Addresses & values in the VM debugger are always hex never decimal -Address ranges are of the format <HexValue1>-<HexValue2> or -<HexValue1>.<HexValue2> -For example, the address range 0x2000 to 0x3000 can be described as 2000-3000 -or 2000.1000 - -The VM Debugger is case insensitive. - -VM's strengths are usually other debuggers weaknesses you can get at any -resource no matter how sensitive e.g. memory management resources, change -address translation in the PSW. For kernel hacking you will reap dividends if -you get good at it. - -The VM Debugger displays operators but not operands, and also the debugger -displays useful information on the same line as the author of the code probably -felt that it was a good idea not to go over the 80 columns on the screen. -This isn't as unintuitive as it may seem as the s/390 instructions are easy to -decode mentally and you can make a good guess at a lot of them as all the -operands are nibble (half byte aligned). -So if you have an objdump listing by hand, it is quite easy to follow, and if -you don't have an objdump listing keep a copy of the s/390 Reference Summary -or alternatively the s/390 principles of operation next to you. -e.g. even I can guess that -0001AFF8' LR 180F CC 0 -is a ( load register ) lr r0,r15 - -Also it is very easy to tell the length of a 390 instruction from the 2 most -significant bits in the instruction (not that this info is really useful except -if you are trying to make sense of a hexdump of code). -Here is a table - -======================= ================== -Bits Instruction Length -======================= ================== -00 2 Bytes -01 4 Bytes -10 4 Bytes -11 6 Bytes -======================= ================== - -The debugger also displays other useful info on the same line such as the -addresses being operated on destination addresses of branches & condition codes. -e.g.:: - - 00019736' AHI A7DAFF0E CC 1 - 000198BA' BRC A7840004 -> 000198C2' CC 0 - 000198CE' STM 900EF068 >> 0FA95E78 CC 2 - - - -Useful VM debugger commands ---------------------------- - -I suppose I'd better mention this before I start -to list the current active traces do:: - - Q TR - -there can be a maximum of 255 of these per set -( more about trace sets later ). - -To stop traces issue a:: - - TR END. - -To delete a particular breakpoint issue:: - - TR DEL <breakpoint number> - -The PA1 key drops to CP mode so you can issue debugger commands, -Doing alt c (on my 3270 console at least ) clears the screen. - -hitting b <enter> comes back to the running operating system -from cp mode ( in our case linux ). - -It is typically useful to add shortcuts to your profile.exec file -if you have one ( this is roughly equivalent to autoexec.bat in DOS ). -file here are a few from mine:: - - /* this gives me command history on issuing f12 */ - set pf12 retrieve - /* this continues */ - set pf8 imm b - /* goes to trace set a */ - set pf1 imm tr goto a - /* goes to trace set b */ - set pf2 imm tr goto b - /* goes to trace set c */ - set pf3 imm tr goto c - - - -Instruction Tracing -------------------- -Setting a simple breakpoint:: - - TR I PSWA <address> - -To debug a particular function try:: - - TR I R <function address range> - TR I on its own will single step. - TR I DATA <MNEMONIC> <OPTIONAL RANGE> will trace for particular mnemonics - -e.g.:: - - TR I DATA 4D R 0197BC.4000 - -will trace for BAS'es ( opcode 4D ) in the range 0197BC.4000 - -if you were inclined you could add traces for all branch instructions & -suffix them with the run prefix so you would have a backtrace on screen -when a program crashes:: - - TR BR <INTO OR FROM> will trace branches into or out of an address. - -e.g.:: - - TR BR INTO 0 - -is often quite useful if a program is getting awkward & deciding -to branch to 0 & crashing as this will stop at the address before in jumps to 0. - -:: - - TR I R <address range> RUN cmd d g - -single steps a range of addresses but stays running & -displays the gprs on each step. - - - -Displaying & modifying Registers --------------------------------- -D G - will display all the gprs - -Adding a extra G to all the commands is necessary to access the full 64 bit -content in VM on z/Architecture. Obviously this isn't required for access -registers as these are still 32 bit. - -e.g. - -DGG - instead of DG - -D X - will display all the control registers -D AR - will display all the access registers -D AR4-7 - will display access registers 4 to 7 -CPU ALL D G - will display the GRPS of all CPUS in the configuration -D PSW - will display the current PSW -st PSW 2000 - will put the value 2000 into the PSW & cause crash your machine. -D PREFIX - displays the prefix offset - - -Displaying Memory ------------------ -To display memory mapped using the current PSW's mapping try:: - - D <range> - -To make VM display a message each time it hits a particular address and -continue try: - -D I<range> - will disassemble/display a range of instructions. - -ST addr 32 bit word - will store a 32 bit aligned address -D T<range> - will display the EBCDIC in an address (if you are that way inclined) -D R<range> - will display real addresses ( without DAT ) but with prefixing. - -There are other complex options to display if you need to get at say home space -but are in primary space the easiest thing to do is to temporarily -modify the PSW to the other addressing mode, display the stuff & then -restore it. - - - -Hints ------ -If you want to issue a debugger command without halting your virtual machine -with the PA1 key try prefixing the command with #CP e.g.:: - - #cp tr i pswa 2000 - -also suffixing most debugger commands with RUN will cause them not -to stop just display the mnemonic at the current instruction on the console. - -If you have several breakpoints you want to put into your program & -you get fed up of cross referencing with System.map -you can do the following trick for several symbols. - -:: - - grep do_signal System.map - -which emits the following among other things:: - - 0001f4e0 T do_signal - -now you can do:: - - TR I PSWA 0001f4e0 cmd msg * do_signal - -This sends a message to your own console each time do_signal is entered. -( As an aside I wrote a perl script once which automatically generated a REXX -script with breakpoints on every kernel procedure, this isn't a good idea -because there are thousands of these routines & VM can only set 255 breakpoints -at a time so you nearly had to spend as long pruning the file down as you would -entering the msgs by hand), however, the trick might be useful for a single -object file. In the 3270 terminal emulator x3270 there is a very useful option -in the file menu called "Save Screen In File" - this is very good for keeping a -copy of traces. - -From CMS help <command name> will give you online help on a particular command. -e.g.:: - - HELP DISPLAY - -Also CP has a file called profile.exec which automatically gets called -on startup of CMS ( like autoexec.bat ), keeping on a DOS analogy session -CP has a feature similar to doskey, it may be useful for you to -use profile.exec to define some keystrokes. - -SET PF9 IMM B - This does a single step in VM on pressing F8. - -SET PF10 ^ - This sets up the ^ key. - which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed - directly into some 3270 consoles. - -SET PF11 ^- - This types the starting keystrokes for a sysrq see SysRq below. -SET PF12 RETRIEVE - This retrieves command history on pressing F12. - - -Sometimes in VM the display is set up to scroll automatically this -can be very annoying if there are messages you wish to look at -to stop this do - -TERM MORE 255 255 - This will nearly stop automatic screen updates, however it will - cause a denial of service if lots of messages go to the 3270 console, - so it would be foolish to use this as the default on a production machine. - - -Tracing particular processes ----------------------------- -The kernel's text segment is intentionally at an address in memory that it will -very seldom collide with text segments of user programs ( thanks Martin ), -this simplifies debugging the kernel. -However it is quite common for user processes to have addresses which collide -this can make debugging a particular process under VM painful under normal -circumstances as the process may change when doing a:: - - TR I R <address range>. - -Thankfully after reading VM's online help I figured out how to debug -I particular process. - -Your first problem is to find the STD ( segment table designation ) -of the program you wish to debug. -There are several ways you can do this here are a few - -Run:: - - objdump --syms <program to be debugged> | grep main - -To get the address of main in the program. Then:: - - tr i pswa <address of main> - -Start the program, if VM drops to CP on what looks like the entry -point of the main function this is most likely the process you wish to debug. -Now do a D X13 or D XG13 on z/Architecture. - -On 31 bit the STD is bits 1-19 ( the STO segment table origin ) -& 25-31 ( the STL segment table length ) of CR13. - -now type:: - - TR I R STD <CR13's value> 0.7fffffff - -e.g.:: - - TR I R STD 8F32E1FF 0.7fffffff - -Another very useful variation is:: - - TR STORE INTO STD <CR13's value> <address range> - -for finding out when a particular variable changes. - -An alternative way of finding the STD of a currently running process -is to do the following, ( this method is more complex but -could be quite convenient if you aren't updating the kernel much & -so your kernel structures will stay constant for a reasonable period of -time ). - -:: - - grep task /proc/<pid>/status - -from this you should see something like:: - - task: 0f160000 ksp: 0f161de8 pt_regs: 0f161f68 - -This now gives you a pointer to the task structure. - -Now make:: - - CC:="s390-gcc -g" kernel/sched.s - -To get the task_struct stabinfo. - -( task_struct is defined in include/linux/sched.h ). - -Now we want to look at -task->active_mm->pgd - -on my machine the active_mm in the task structure stab is -active_mm:(4,12),672,32 - -its offset is 672/8=84=0x54 - -the pgd member in the mm_struct stab is -pgd:(4,6)=*(29,5),96,32 -so its offset is 96/8=12=0xc - -so we'll:: - - hexdump -s 0xf160054 /dev/mem | more - -i.e. task_struct+active_mm offset -to look at the active_mm member:: - - f160054 0fee cc60 0019 e334 0000 0000 0000 0011 - -:: - - hexdump -s 0x0feecc6c /dev/mem | more - -i.e. active_mm+pgd offset:: - - feecc6c 0f2c 0000 0000 0001 0000 0001 0000 0010 - -we get something like -now do:: - - TR I R STD <pgd|0x7f> 0.7fffffff - -i.e. the 0x7f is added because the pgd only -gives the page table origin & we need to set the low bits -to the maximum possible segment table length. - -:: - - TR I R STD 0f2c007f 0.7fffffff - -on z/Architecture you'll probably need to do:: - - TR I R STD <pgd|0x7> 0.ffffffffffffffff - -to set the TableType to 0x1 & the Table length to 3. - - - -Tracing Program Exceptions --------------------------- -If you get a crash which says something like -illegal operation or specification exception followed by a register dump -You can restart linux & trace these using the tr prog <range or value> trace -option. - - -The most common ones you will normally be tracing for is: - -- 1=operation exception -- 2=privileged operation exception -- 4=protection exception -- 5=addressing exception -- 6=specification exception -- 10=segment translation exception -- 11=page translation exception - -The full list of these is on page 22 of the current s/390 Reference Summary. -e.g. - -tr prog 10 will trace segment translation exceptions. - -tr prog on its own will trace all program interruption codes. - -Trace Sets ----------- -On starting VM you are initially in the INITIAL trace set. -You can do a Q TR to verify this. -If you have a complex tracing situation where you wish to wait for instance -till a driver is open before you start tracing IO, but know in your -heart that you are going to have to make several runs through the code till you -have a clue whats going on. - -What you can do is:: - - TR I PSWA <Driver open address> - -hit b to continue till breakpoint - -reach the breakpoint - -now do your:: - - TR GOTO B - TR IO 7c08-7c09 inst int run - -or whatever the IO channels you wish to trace are & hit b - -To got back to the initial trace set do:: - - TR GOTO INITIAL - -& the TR I PSWA <Driver open address> will be the only active breakpoint again. - - -Tracing linux syscalls under VM -------------------------------- -Syscalls are implemented on Linux for S390 by the Supervisor call instruction -(SVC). There 256 possibilities of these as the instruction is made up of a 0xA -opcode and the second byte being the syscall number. They are traced using the -simple command:: - - TR SVC <Optional value or range> - -the syscalls are defined in linux/arch/s390/include/asm/unistd.h -e.g. to trace all file opens just do:: - - TR SVC 5 ( as this is the syscall number of open ) - - -SMP Specific commands ---------------------- -To find out how many cpus you have -Q CPUS displays all the CPU's available to your virtual machine -To find the cpu that the current cpu VM debugger commands are being directed at -do Q CPU to change the current cpu VM debugger commands are being directed at -do:: - - CPU <desired cpu no> - -On a SMP guest issue a command to all CPUs try prefixing the command with cpu -all. To issue a command to a particular cpu try cpu <cpu number> e.g.:: - - CPU 01 TR I R 2000.3000 - -If you are running on a guest with several cpus & you have a IO related problem -& cannot follow the flow of code but you know it isn't smp related. - -from the bash prompt issue:: - - shutdown -h now or halt. - -do a:: - - Q CPUS - -to find out how many cpus you have detach each one of them from cp except -cpu 0 by issuing a:: - - DETACH CPU 01-(number of cpus in configuration) - -& boot linux again. - -TR SIGP - will trace inter processor signal processor instructions. - -DEFINE CPU 01-(number in configuration) - will get your guests cpus back. - - -Help for displaying ascii textstrings -------------------------------------- -On the very latest VM Nucleus'es VM can now display ascii -( thanks Neale for the hint ) by doing:: - - D TX<lowaddr>.<len> - -e.g.:: - - D TX0.100 - -Alternatively -============= -Under older VM debuggers (I love EBDIC too) you can use following little -program which converts a command line of hex digits to ascii text. It can be -compiled under linux and you can copy the hex digits from your x3270 terminal -to your xterm if you are debugging from a linuxbox. - -This is quite useful when looking at a parameter passed in as a text string -under VM ( unless you are good at decoding ASCII in your head ). - -e.g. consider tracing an open syscall:: - - TR SVC 5 - -We have stopped at a breakpoint:: - - 000151B0' SVC 0A05 -> 0001909A' CC 0 - -D 20.8 to check the SVC old psw in the prefix area and see was it from userspace -(for the layout of the prefix area consult the "Fixed Storage Locations" -chapter of the s/390 Reference Summary if you have it available). - -:: - - V00000020 070C2000 800151B2 - -The problem state bit wasn't set & it's also too early in the boot sequence -for it to be a userspace SVC if it was we would have to temporarily switch the -psw to user space addressing so we could get at the first parameter of the open -in gpr2. - -Next do a:: - - D G2 - GPR 2 = 00014CB4 - -Now display what gpr2 is pointing to:: - - D 00014CB4.20 - V00014CB4 2F646576 2F636F6E 736F6C65 00001BF5 - V00014CC4 FC00014C B4001001 E0001000 B8070707 - -Now copy the text till the first 00 hex ( which is the end of the string -to an xterm & do hex2ascii on it:: - - hex2ascii 2F646576 2F636F6E 736F6C65 00 - -outputs:: - - Decoded Hex:=/ d e v / c o n s o l e 0x00 - -We were opening the console device, - -You can compile the code below yourself for practice :-), - -:: - - /* - * hex2ascii.c - * a useful little tool for converting a hexadecimal command line to ascii - * - * Author(s): Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com) - * (C) 2000 IBM Deutschland Entwicklung GmbH, IBM Corporation. - */ - #include <stdio.h> - - int main(int argc,char *argv[]) - { - int cnt1,cnt2,len,toggle=0; - int startcnt=1; - unsigned char c,hex; - - if(argc>1&&(strcmp(argv[1],"-a")==0)) - startcnt=2; - printf("Decoded Hex:="); - for(cnt1=startcnt;cnt1<argc;cnt1++) - { - len=strlen(argv[cnt1]); - for(cnt2=0;cnt2<len;cnt2++) - { - c=argv[cnt1][cnt2]; - if(c>='0'&&c<='9') - c=c-'0'; - if(c>='A'&&c<='F') - c=c-'A'+10; - if(c>='a'&&c<='f') - c=c-'a'+10; - switch(toggle) - { - case 0: - hex=c<<4; - toggle=1; - break; - case 1: - hex+=c; - if(hex<32||hex>127) - { - if(startcnt==1) - printf("0x%02X ",(int)hex); - else - printf("."); - } - else - { - printf("%c",hex); - if(startcnt==1) - printf(" "); - } - toggle=0; - break; - } - } - } - printf("\n"); - } - - - - -Stack tracing under VM ----------------------- -A basic backtrace ------------------ - -Here are the tricks I use 9 out of 10 times it works pretty well, - -When your backchain reaches a dead end --------------------------------------- -This can happen when an exception happens in the kernel and the kernel is -entered twice. If you reach the NULL pointer at the end of the back chain you -should be able to sniff further back if you follow the following tricks. -1) A kernel address should be easy to recognise since it is in -primary space & the problem state bit isn't set & also -The Hi bit of the address is set. -2) Another backchain should also be easy to recognise since it is an -address pointing to another address approximately 100 bytes or 0x70 hex -behind the current stackpointer. - - -Here is some practice. - -boot the kernel & hit PA1 at some random time - -d g to display the gprs, this should display something like:: - - GPR 0 = 00000001 00156018 0014359C 00000000 - GPR 4 = 00000001 001B8888 000003E0 00000000 - GPR 8 = 00100080 00100084 00000000 000FE000 - GPR 12 = 00010400 8001B2DC 8001B36A 000FFED8 - -Note that GPR14 is a return address but as we are real men we are going to -trace the stack. -display 0x40 bytes after the stack pointer:: - - V000FFED8 000FFF38 8001B838 80014C8E 000FFF38 - V000FFEE8 00000000 00000000 000003E0 00000000 - V000FFEF8 00100080 00100084 00000000 000FE000 - V000FFF08 00010400 8001B2DC 8001B36A 000FFED8 - - -Ah now look at whats in sp+56 (sp+0x38) this is 8001B36A our saved r14 if -you look above at our stackframe & also agrees with GPR14. - -now backchain:: - - d 000FFF38.40 - -we now are taking the contents of SP to get our first backchain:: - - V000FFF38 000FFFA0 00000000 00014995 00147094 - V000FFF48 00147090 001470A0 000003E0 00000000 - V000FFF58 00100080 00100084 00000000 001BF1D0 - V000FFF68 00010400 800149BA 80014CA6 000FFF38 - -This displays a 2nd return address of 80014CA6 - -now do:: - - d 000FFFA0.40 - -for our 3rd backchain:: - - V000FFFA0 04B52002 0001107F 00000000 00000000 - V000FFFB0 00000000 00000000 FF000000 0001107F - V000FFFC0 00000000 00000000 00000000 00000000 - V000FFFD0 00010400 80010802 8001085A 000FFFA0 - - -our 3rd return address is 8001085A - -as the 04B52002 looks suspiciously like rubbish it is fair to assume that the -kernel entry routines for the sake of optimisation don't set up a backchain. - -now look at System.map to see if the addresses make any sense:: - - grep -i 0001b3 System.map - -outputs among other things:: - - 0001b304 T cpu_idle - -so 8001B36A -is cpu_idle+0x66 ( quiet the cpu is asleep, don't wake it ) - -:: - - grep -i 00014 System.map - -produces among other things:: - - 00014a78 T start_kernel - -so 0014CA6 is start_kernel+some hex number I can't add in my head. - -:: - - grep -i 00108 System.map - -this produces:: - - 00010800 T _stext - -so 8001085A is _stext+0x5a - -Congrats you've done your first backchain. - - - -s/390 & z/Architecture IO Overview -================================== - -I am not going to give a course in 390 IO architecture as this would take me -quite a while and I'm no expert. Instead I'll give a 390 IO architecture -summary for Dummies. If you have the s/390 principles of operation available -read this instead. If nothing else you may find a few useful keywords in here -and be able to use them on a web search engine to find more useful information. - -Unlike other bus architectures modern 390 systems do their IO using mostly -fibre optics and devices such as tapes and disks can be shared between several -mainframes. Also S390 can support up to 65536 devices while a high end PC based -system might be choking with around 64. - -Here is some of the common IO terminology: - -Subchannel: - This is the logical number most IO commands use to talk to an IO device. There - can be up to 0x10000 (65536) of these in a configuration, typically there are a - few hundred. Under VM for simplicity they are allocated contiguously, however - on the native hardware they are not. They typically stay consistent between - boots provided no new hardware is inserted or removed. - - Under Linux for s390 we use these as IRQ's and also when issuing an IO command - (CLEAR SUBCHANNEL, HALT SUBCHANNEL, MODIFY SUBCHANNEL, RESUME SUBCHANNEL, - START SUBCHANNEL, STORE SUBCHANNEL and TEST SUBCHANNEL). We use this as the ID - of the device we wish to talk to. The most important of these instructions are - START SUBCHANNEL (to start IO), TEST SUBCHANNEL (to check whether the IO - completed successfully) and HALT SUBCHANNEL (to kill IO). A subchannel can have - up to 8 channel paths to a device, this offers redundancy if one is not - available. - -Device Number: - This number remains static and is closely tied to the hardware. There are 65536 - of these, made up of a CHPID (Channel Path ID, the most significant 8 bits) and - another lsb 8 bits. These remain static even if more devices are inserted or - removed from the hardware. There is a 1 to 1 mapping between subchannels and - device numbers, provided devices aren't inserted or removed. - -Channel Control Words: - CCWs are linked lists of instructions initially pointed to by an operation - request block (ORB), which is initially given to Start Subchannel (SSCH) - command along with the subchannel number for the IO subsystem to process - while the CPU continues executing normal code. - CCWs come in two flavours, Format 0 (24 bit for backward compatibility) and - Format 1 (31 bit). These are typically used to issue read and write (and many - other) instructions. They consist of a length field and an absolute address - field. - - Each IO typically gets 1 or 2 interrupts, one for channel end (primary status) - when the channel is idle, and the second for device end (secondary status). - Sometimes you get both concurrently. You check how the IO went on by issuing a - TEST SUBCHANNEL at each interrupt, from which you receive an Interruption - response block (IRB). If you get channel and device end status in the IRB - without channel checks etc. your IO probably went okay. If you didn't you - probably need to examine the IRB, extended status word etc. - If an error occurs, more sophisticated control units have a facility known as - concurrent sense. This means that if an error occurs Extended sense information - will be presented in the Extended status word in the IRB. If not you have to - issue a subsequent SENSE CCW command after the test subchannel. - - -TPI (Test pending interrupt) can also be used for polled IO, but in -multitasking multiprocessor systems it isn't recommended except for -checking special cases (i.e. non looping checks for pending IO etc.). - -Store Subchannel and Modify Subchannel can be used to examine and modify -operating characteristics of a subchannel (e.g. channel paths). - -Other IO related Terms: - -Sysplex: - S390's Clustering Technology -QDIO: - S390's new high speed IO architecture to support devices such as gigabit - ethernet, this architecture is also designed to be forward compatible with - upcoming 64 bit machines. - - -General Concepts ----------------- - -Input Output Processors (IOP's) are responsible for communicating between -the mainframe CPU's & the channel & relieve the mainframe CPU's from the -burden of communicating with IO devices directly, this allows the CPU's to -concentrate on data processing. - -IOP's can use one or more links ( known as channel paths ) to talk to each -IO device. It first checks for path availability & chooses an available one, -then starts ( & sometimes terminates IO ). -There are two types of channel path: ESCON & the Parallel IO interface. - -IO devices are attached to control units, control units provide the -logic to interface the channel paths & channel path IO protocols to -the IO devices, they can be integrated with the devices or housed separately -& often talk to several similar devices ( typical examples would be raid -controllers or a control unit which connects to 1000 3270 terminals ):: - - - +---------------------------------------------------------------+ - | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ | - | | CPU | | CPU | | CPU | | CPU | | Main | | Expanded | | - | | | | | | | | | | Memory | | Storage | | - | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ | - |---------------------------------------------------------------+ - | IOP | IOP | IOP | - |--------------------------------------------------------------- - | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C | - ---------------------------------------------------------------- - || || - || Bus & Tag Channel Path || ESCON - || ====================== || Channel - || || || || Path - +----------+ +----------+ +----------+ - | | | | | | - | CU | | CU | | CU | - | | | | | | - +----------+ +----------+ +----------+ - | | | | | - +----------+ +----------+ +----------+ +----------+ +----------+ - |I/O Device| |I/O Device| |I/O Device| |I/O Device| |I/O Device| - +----------+ +----------+ +----------+ +----------+ +----------+ - CPU = Central Processing Unit - C = Channel - IOP = IP Processor - CU = Control Unit - -The 390 IO systems come in 2 flavours the current 390 machines support both - -The Older 360 & 370 Interface,sometimes called the Parallel I/O interface, -sometimes called Bus-and Tag & sometimes Original Equipment Manufacturers -Interface (OEMI). - -This byte wide Parallel channel path/bus has parity & data on the "Bus" cable -and control lines on the "Tag" cable. These can operate in byte multiplex mode -for sharing between several slow devices or burst mode and monopolize the -channel for the whole burst. Up to 256 devices can be addressed on one of these -cables. These cables are about one inch in diameter. The maximum unextended -length supported by these cables is 125 Meters but this can be extended up to -2km with a fibre optic channel extended such as a 3044. The maximum burst speed -supported is 4.5 megabytes per second. However, some really old processors -support only transfer rates of 3.0, 2.0 & 1.0 MB/sec. -One of these paths can be daisy chained to up to 8 control units. - - -ESCON if fibre optic it is also called FICON -Was introduced by IBM in 1990. Has 2 fibre optic cables and uses either leds or -lasers for communication at a signaling rate of up to 200 megabits/sec. As -10bits are transferred for every 8 bits info this drops to 160 megabits/sec -and to 18.6 Megabytes/sec once control info and CRC are added. ESCON only -operates in burst mode. - -ESCONs typical max cable length is 3km for the led version and 20km for the -laser version known as XDF (extended distance facility). This can be further -extended by using an ESCON director which triples the above mentioned ranges. -Unlike Bus & Tag as ESCON is serial it uses a packet switching architecture, -the standard Bus & Tag control protocol is however present within the packets. -Up to 256 devices can be attached to each control unit that uses one of these -interfaces. - -Common 390 Devices include: -Network adapters typically OSA2,3172's,2116's & OSA-E gigabit ethernet adapters, -Consoles 3270 & 3215 (a teletype emulated under linux for a line mode console). -DASD's direct access storage devices ( otherwise known as hard disks ). -Tape Drives. -CTC ( Channel to Channel Adapters ), -ESCON or Parallel Cables used as a very high speed serial link -between 2 machines. - - -Debugging IO on s/390 & z/Architecture under VM -=============================================== - -Now we are ready to go on with IO tracing commands under VM - -A few self explanatory queries:: - - Q OSA - Q CTC - Q DISK ( This command is CMS specific ) - Q DASD - -Q OSA on my machine returns:: - - OSA 7C08 ON OSA 7C08 SUBCHANNEL = 0000 - OSA 7C09 ON OSA 7C09 SUBCHANNEL = 0001 - OSA 7C14 ON OSA 7C14 SUBCHANNEL = 0002 - OSA 7C15 ON OSA 7C15 SUBCHANNEL = 0003 - -If you have a guest with certain privileges you may be able to see devices -which don't belong to you. To avoid this, add the option V. -e.g.:: - - Q V OSA - -Now using the device numbers returned by this command we will -Trace the io starting up on the first device 7c08 & 7c09 -In our simplest case we can trace the -start subchannels -like TR SSCH 7C08-7C09 -or the halt subchannels -or TR HSCH 7C08-7C09 -MSCH's ,STSCH's I think you can guess the rest - -A good trick is tracing all the IO's and CCWS and spooling them into the reader -of another VM guest so he can ftp the logfile back to his own machine. I'll do -a small bit of this and give you a look at the output. - -1) Spool stdout to VM reader:: - - SP PRT TO (another vm guest ) or * for the local vm guest - -2) Fill the reader with the trace:: - - TR IO 7c08-7c09 INST INT CCW PRT RUN - -3) Start up linux:: - - i 00c -4) Finish the trace:: - - TR END - -5) close the reader:: - - C PRT - -6) list reader contents:: - - RDRLIST - -7) copy it to linux4's minidisk:: - - RECEIVE / LOG TXT A1 ( replace - -8) -filel & press F11 to look at it -You should see something like:: - - 00020942' SSCH B2334000 0048813C CC 0 SCH 0000 DEV 7C08 - CPA 000FFDF0 PARM 00E2C9C4 KEY 0 FPI C0 LPM 80 - CCW 000FFDF0 E4200100 00487FE8 0000 E4240100 ........ - IDAL 43D8AFE8 - IDAL 0FB76000 - 00020B0A' I/O DEV 7C08 -> 000197BC' SCH 0000 PARM 00E2C9C4 - 00021628' TSCH B2354000 >> 00488164 CC 0 SCH 0000 DEV 7C08 - CCWA 000FFDF8 DEV STS 0C SCH STS 00 CNT 00EC - KEY 0 FPI C0 CC 0 CTLS 4007 - 00022238' STSCH B2344000 >> 00488108 CC 0 SCH 0000 DEV 7C08 - -If you don't like messing up your readed ( because you possibly booted from it ) -you can alternatively spool it to another readers guest. - - -Other common VM device related commands ---------------------------------------------- -These commands are listed only because they have -been of use to me in the past & may be of use to -you too. For more complete info on each of the commands -use type HELP <command> from CMS. - -detaching devices:: - - DET <devno range> - ATT <devno range> <guest> - -attach a device to guest * for your own guest - -READY <devno> - cause VM to issue a fake interrupt. - -The VARY command is normally only available to VM administrators:: - - VARY ON PATH <path> TO <devno range> - VARY OFF PATH <PATH> FROM <devno range> - -This is used to switch on or off channel paths to devices. - -Q CHPID <channel path ID> - This displays state of devices using this channel path - -D SCHIB <subchannel> - This displays the subchannel information SCHIB block for the device. - this I believe is also only available to administrators. - -DEFINE CTC <devno> - defines a virtual CTC channel to channel connection - 2 need to be defined on each guest for the CTC driver to use. - -COUPLE devno userid remote devno - Joins a local virtual device to a remote virtual device - ( commonly used for the CTC driver ). - -Building a VM ramdisk under CMS which linux can use:: - - def vfb-<blocksize> <subchannel> <number blocks> - -blocksize is commonly 4096 for linux. - -Formatting it:: - - format <subchannel> <driver letter e.g. x> (blksize <blocksize> - -Sharing a disk between multiple guests:: - - LINK userid devno1 devno2 mode password - - - -GDB on S390 -=========== -N.B. if compiling for debugging gdb works better without optimisation -( see Compiling programs for debugging ) - -invocation ----------- -gdb <victim program> <optional corefile> - -Online help ------------ -help: gives help on commands - -e.g.:: - - help - help display - -Note gdb's online help is very good use it. - - -Assembly --------- -info registers: - displays registers other than floating point. - -info all-registers: - displays floating points as well. - -disassemble: - disassembles - -e.g.:: - - disassemble without parameters will disassemble the current function - disassemble $pc $pc+10 - -Viewing & modifying variables ------------------------------ -print or p: - displays variable or register - -e.g. p/x $sp will display the stack pointer - -display: - prints variable or register each time program stops - -e.g.:: - - display/x $pc will display the program counter - display argc - -undisplay: - undo's display's - -info breakpoints: - shows all current breakpoints - -info stack: - shows stack back trace (if this doesn't work too well, I'll show - you the stacktrace by hand below). - -info locals: - displays local variables. - -info args: - display current procedure arguments. - -set args: - will set argc & argv each time the victim program is invoked - -e.g.:: - - set <variable>=value - set argc=100 - set $pc=0 - - - -Modifying execution -------------------- -step: - steps n lines of sourcecode - -step - steps 1 line. - -step 100 - steps 100 lines of code. - -next: - like step except this will not step into subroutines - -stepi: - steps a single machine code instruction. - -e.g.:: - - stepi 100 - -nexti: - steps a single machine code instruction but will not step into - subroutines. - -finish: - will run until exit of the current routine - -run: - (re)starts a program - -cont: - continues a program - -quit: - exits gdb. - - -breakpoints ------------- - -break - sets a breakpoint - -e.g.:: - - break main - break *$pc - break *0x400618 - -Here's a really useful one for large programs - -rbr - Set a breakpoint for all functions matching REGEXP - -e.g.:: - - rbr 390 - -will set a breakpoint with all functions with 390 in their name. - -info breakpoints - lists all breakpoints - -delete: - delete breakpoint by number or delete them all - -e.g. - -delete 1 - will delete the first breakpoint - - -delete - will delete them all - -watch: - This will set a watchpoint ( usually hardware assisted ), - -This will watch a variable till it changes - -e.g. - -watch cnt - will watch the variable cnt till it changes. - -As an aside unfortunately gdb's, architecture independent watchpoint code -is inconsistent & not very good, watchpoints usually work but not always. - -info watchpoints: - Display currently active watchpoints - -condition: ( another useful one ) - Specify breakpoint number N to break only if COND is true. - -Usage is `condition N COND`, where N is an integer and COND is an -expression to be evaluated whenever breakpoint N is reached. - - - -User defined functions/macros ------------------------------ -define: ( Note this is very very useful,simple & powerful ) - -usage define <name> <list of commands> end - -examples which you should consider putting into .gdbinit in your home -directory:: - - define d - stepi - disassemble $pc $pc+10 - end - define e - nexti - disassemble $pc $pc+10 - end - - -Other hard to classify stuff ----------------------------- -signal n: - sends the victim program a signal. - -e.g. `signal 3` will send a SIGQUIT. - -info signals: - what gdb does when the victim receives certain signals. - -list: - -e.g.: - -list - lists current function source -list 1,10 - list first 10 lines of current file. - -list test.c:1,10 - - -directory: - Adds directories to be searched for source if gdb cannot find the source. - (note it is a bit sensitive about slashes) - -e.g. To add the root of the filesystem to the searchpath do:: - - directory // - - -call <function> -This calls a function in the victim program, this is pretty powerful -e.g. -(gdb) call printf("hello world") -outputs: -$1 = 11 - -You might now be thinking that the line above didn't work, something extra had -to be done. -(gdb) call fflush(stdout) -hello world$2 = 0 -As an aside the debugger also calls malloc & free under the hood -to make space for the "hello world" string. - - - -hints ------ -1) command completion works just like bash - ( if you are a bad typist like me this really helps ) - -e.g. hit br <TAB> & cursor up & down :-). - -2) if you have a debugging problem that takes a few steps to recreate -put the steps into a file called .gdbinit in your current working directory -if you have defined a few extra useful user defined commands put these in -your home directory & they will be read each time gdb is launched. - -A typical .gdbinit file might be.:: - - break main - run - break runtime_exception - cont - - -stack chaining in gdb by hand ------------------------------ -This is done using a the same trick described for VM:: - - p/x (*($sp+56))&0x7fffffff - -get the first backchain. - -For z/Architecture -Replace 56 with 112 & ignore the &0x7fffffff -in the macros below & do nasty casts to longs like the following -as gdb unfortunately deals with printed arguments as ints which -messes up everything. - -i.e. here is a 3rd backchain dereference:: - - p/x *(long *)(***(long ***)$sp+112) - - -this outputs:: - - $5 = 0x528f18 - -on my machine. - -Now you can use:: - - info symbol (*($sp+56))&0x7fffffff - -you might see something like:: - - rl_getc + 36 in section .text - -telling you what is located at address 0x528f18 -Now do:: - - p/x (*(*$sp+56))&0x7fffffff - -This outputs:: - - $6 = 0x528ed0 - -Now do:: - - info symbol (*(*$sp+56))&0x7fffffff - rl_read_key + 180 in section .text - -now do:: - - p/x (*(**$sp+56))&0x7fffffff - -& so on. - -Disassembling instructions without debug info ---------------------------------------------- -gdb typically complains if there is a lack of debugging -symbols in the disassemble command with -"No function contains specified address." To get around -this do:: - - x/<number lines to disassemble>xi <address> - -e.g.:: - - x/20xi 0x400730 - - - -Note: - Remember gdb has history just like bash you don't need to retype the - whole line just use the up & down arrows. - - - -For more info -------------- -From your linuxbox do:: - - man gdb - -or:: - - info gdb. - -core dumps ----------- - -What a core dump ? -^^^^^^^^^^^^^^^^^^ - -A core dump is a file generated by the kernel (if allowed) which contains the -registers and all active pages of the program which has crashed. - -From this file gdb will allow you to look at the registers, stack trace and -memory of the program as if it just crashed on your system. It is usually -called core and created in the current working directory. - -This is very useful in that a customer can mail a core dump to a technical -support department and the technical support department can reconstruct what -happened. Provided they have an identical copy of this program with debugging -symbols compiled in and the source base of this build is available. - -In short it is far more useful than something like a crash log could ever hope -to be. - -Why have I never seen one ? -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Probably because you haven't used the command:: - - ulimit -c unlimited in bash - -to allow core dumps, now do:: - - ulimit -a - -to verify that the limit was accepted. - -A sample core dump - To create this I'm going to do:: - - ulimit -c unlimited - gdb - -to launch gdb (my victim app. ) now be bad & do the following from another -telnet/xterm session to the same machine:: - - ps -aux | grep gdb - kill -SIGSEGV <gdb's pid> - -or alternatively use `killall -SIGSEGV gdb` if you have the killall command. - -Now look at the core dump:: - - ./gdb core - -Displays the following:: - - GNU gdb 4.18 - Copyright 1998 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, and you are - welcome to change it and/or distribute copies of it under certain conditions. - Type "show copying" to see the conditions. - There is absolutely no warranty for GDB. Type "show warranty" for details. - This GDB was configured as "s390-ibm-linux"... - Core was generated by `./gdb'. - Program terminated with signal 11, Segmentation fault. - Reading symbols from /usr/lib/libncurses.so.4...done. - Reading symbols from /lib/libm.so.6...done. - Reading symbols from /lib/libc.so.6...done. - Reading symbols from /lib/ld-linux.so.2...done. - #0 0x40126d1a in read () from /lib/libc.so.6 - Setting up the environment for debugging gdb. - Breakpoint 1 at 0x4dc6f8: file utils.c, line 471. - Breakpoint 2 at 0x4d87a4: file top.c, line 2609. - (top-gdb) info stack - #0 0x40126d1a in read () from /lib/libc.so.6 - #1 0x528f26 in rl_getc (stream=0x7ffffde8) at input.c:402 - #2 0x528ed0 in rl_read_key () at input.c:381 - #3 0x5167e6 in readline_internal_char () at readline.c:454 - #4 0x5168ee in readline_internal_charloop () at readline.c:507 - #5 0x51692c in readline_internal () at readline.c:521 - #6 0x5164fe in readline (prompt=0x7ffff810) - at readline.c:349 - #7 0x4d7a8a in command_line_input (prompt=0x564420 "(gdb) ", repeat=1, - annotation_suffix=0x4d6b44 "prompt") at top.c:2091 - #8 0x4d6cf0 in command_loop () at top.c:1345 - #9 0x4e25bc in main (argc=1, argv=0x7ffffdf4) at main.c:635 - - -LDD -=== -This is a program which lists the shared libraries which a library needs, -Note you also get the relocations of the shared library text segments which -help when using objdump --source. - -e.g.:: - - ldd ./gdb - -outputs:: - - libncurses.so.4 => /usr/lib/libncurses.so.4 (0x40018000) - libm.so.6 => /lib/libm.so.6 (0x4005e000) - libc.so.6 => /lib/libc.so.6 (0x40084000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) - - -Debugging shared libraries -========================== -Most programs use shared libraries, however it can be very painful -when you single step instruction into a function like printf for the -first time & you end up in functions like _dl_runtime_resolve this is -the ld.so doing lazy binding, lazy binding is a concept in ELF where -shared library functions are not loaded into memory unless they are -actually used, great for saving memory but a pain to debug. - -To get around this either relink the program -static or exit gdb type -export LD_BIND_NOW=true this will stop lazy binding & restart the gdb'ing -the program in question. - - - -Debugging modules -================= -As modules are dynamically loaded into the kernel their address can be -anywhere to get around this use the -m option with insmod to emit a load -map which can be piped into a file if required. - -The proc file system -==================== -What is it ?. -It is a filesystem created by the kernel with files which are created on demand -by the kernel if read, or can be used to modify kernel parameters, -it is a powerful concept. - -e.g.:: - - cat /proc/sys/net/ipv4/ip_forward - -On my machine outputs:: - - 0 - -telling me ip_forwarding is not on to switch it on I can do:: - - echo 1 > /proc/sys/net/ipv4/ip_forward - -cat it again:: - - cat /proc/sys/net/ipv4/ip_forward - -On my machine now outputs:: - - 1 - -IP forwarding is on. - -There is a lot of useful info in here best found by going in and having a look -around, so I'll take you through some entries I consider important. - -All the processes running on the machine have their own entry defined by -/proc/<pid> - -So lets have a look at the init process:: - - cd /proc/1 - cat cmdline - -emits:: - - init [2] - -:: - - cd /proc/1/fd - -This contains numerical entries of all the open files, -some of these you can cat e.g. stdout (2):: - - cat /proc/29/maps - -on my machine emits:: - - 00400000-00478000 r-xp 00000000 5f:00 4103 /bin/bash - 00478000-0047e000 rw-p 00077000 5f:00 4103 /bin/bash - 0047e000-00492000 rwxp 00000000 00:00 0 - 40000000-40015000 r-xp 00000000 5f:00 14382 /lib/ld-2.1.2.so - 40015000-40016000 rw-p 00014000 5f:00 14382 /lib/ld-2.1.2.so - 40016000-40017000 rwxp 00000000 00:00 0 - 40017000-40018000 rw-p 00000000 00:00 0 - 40018000-4001b000 r-xp 00000000 5f:00 14435 /lib/libtermcap.so.2.0.8 - 4001b000-4001c000 rw-p 00002000 5f:00 14435 /lib/libtermcap.so.2.0.8 - 4001c000-4010d000 r-xp 00000000 5f:00 14387 /lib/libc-2.1.2.so - 4010d000-40111000 rw-p 000f0000 5f:00 14387 /lib/libc-2.1.2.so - 40111000-40114000 rw-p 00000000 00:00 0 - 40114000-4011e000 r-xp 00000000 5f:00 14408 /lib/libnss_files-2.1.2.so - 4011e000-4011f000 rw-p 00009000 5f:00 14408 /lib/libnss_files-2.1.2.so - 7fffd000-80000000 rwxp ffffe000 00:00 0 - - -Showing us the shared libraries init uses where they are in memory -& memory access permissions for each virtual memory area. - -/proc/1/cwd is a softlink to the current working directory. - -/proc/1/root is the root of the filesystem for this process. - -/proc/1/mem is the current running processes memory which you -can read & write to like a file. - -strace uses this sometimes as it is a bit faster than the -rather inefficient ptrace interface for peeking at DATA. - -:: - - cat status - - Name: init - State: S (sleeping) - Pid: 1 - PPid: 0 - Uid: 0 0 0 0 - Gid: 0 0 0 0 - Groups: - VmSize: 408 kB - VmLck: 0 kB - VmRSS: 208 kB - VmData: 24 kB - VmStk: 8 kB - VmExe: 368 kB - VmLib: 0 kB - SigPnd: 0000000000000000 - SigBlk: 0000000000000000 - SigIgn: 7fffffffd7f0d8fc - SigCgt: 00000000280b2603 - CapInh: 00000000fffffeff - CapPrm: 00000000ffffffff - CapEff: 00000000fffffeff - - User PSW: 070de000 80414146 - task: 004b6000 tss: 004b62d8 ksp: 004b7ca8 pt_regs: 004b7f68 - User GPRS: - 00000400 00000000 0000000b 7ffffa90 - 00000000 00000000 00000000 0045d9f4 - 0045cafc 7ffffa90 7fffff18 0045cb08 - 00010400 804039e8 80403af8 7ffff8b0 - User ACRS: - 00000000 00000000 00000000 00000000 - 00000001 00000000 00000000 00000000 - 00000000 00000000 00000000 00000000 - 00000000 00000000 00000000 00000000 - Kernel BackChain CallChain BackChain CallChain - 004b7ca8 8002bd0c 004b7d18 8002b92c - 004b7db8 8005cd50 004b7e38 8005d12a - 004b7f08 80019114 - -Showing among other things memory usage & status of some signals & -the processes'es registers from the kernel task_structure -as well as a backchain which may be useful if a process crashes -in the kernel for some unknown reason. - -Some driver debugging techniques -================================ -debug feature -------------- -Some of our drivers now support a "debug feature" in -/proc/s390dbf see s390dbf.txt in the linux/Documentation directory -for more info. - -e.g. -to switch on the lcs "debug feature":: - - echo 5 > /proc/s390dbf/lcs/level - -& then after the error occurred:: - - cat /proc/s390dbf/lcs/sprintf >/logfile - -the logfile now contains some information which may help -tech support resolve a problem in the field. - - - -high level debugging network drivers ------------------------------------- -ifconfig is a quite useful command -it gives the current state of network drivers. - -If you suspect your network device driver is dead -one way to check is type:: - - ifconfig <network device> - -e.g. tr0 - -You should see something like:: - - ifconfig tr0 - tr0 Link encap:16/4 Mbps Token Ring (New) HWaddr 00:04:AC:20:8E:48 - inet addr:9.164.185.132 Bcast:9.164.191.255 Mask:255.255.224.0 - UP BROADCAST RUNNING MULTICAST MTU:2000 Metric:1 - RX packets:246134 errors:0 dropped:0 overruns:0 frame:0 - TX packets:5 errors:0 dropped:0 overruns:0 carrier:0 - collisions:0 txqueuelen:100 - -if the device doesn't say up -try:: - - /etc/rc.d/init.d/network start - -( this starts the network stack & hopefully calls ifconfig tr0 up ). -ifconfig looks at the output of /proc/net/dev and presents it in a more -presentable form. - -Now ping the device from a machine in the same subnet. - -if the RX packets count & TX packets counts don't increment you probably -have problems. - -next:: - - cat /proc/net/arp - -Do you see any hardware addresses in the cache if not you may have problems. -Next try:: - - ping -c 5 <broadcast_addr> - -i.e. the Bcast field above in the output of -ifconfig. Do you see any replies from machines other than the local machine -if not you may have problems. also if the TX packets count in ifconfig -hasn't incremented either you have serious problems in your driver -(e.g. the txbusy field of the network device being stuck on ) -or you may have multiple network devices connected. - - -chandev -------- -There is a new device layer for channel devices, some -drivers e.g. lcs are registered with this layer. - -If the device uses the channel device layer you'll be -able to find what interrupts it uses & the current state -of the device. - -See the manpage chandev.8 &type cat /proc/chandev for more info. - - -SysRq -===== -This is now supported by linux for s/390 & z/Architecture. - -To enable it do compile the kernel with:: - - Kernel Hacking -> Magic SysRq Key Enabled - -Then:: - - echo "1" > /proc/sys/kernel/sysrq - -also type:: - - echo "8" >/proc/sys/kernel/printk - -To make printk output go to console. - -On 390 all commands are prefixed with:: - - ^- - -e.g.:: - - ^-t will show tasks. - ^-? or some unknown command will display help. - -The sysrq key reading is very picky ( I have to type the keys in an -xterm session & paste them into the x3270 console ) -& it may be wise to predefine the keys as described in the VM hints above - -This is particularly useful for syncing disks unmounting & rebooting -if the machine gets partially hung. - -Read Documentation/admin-guide/sysrq.rst for more info - -References: -=========== -- Enterprise Systems Architecture Reference Summary -- Enterprise Systems Architecture Principles of Operation -- Hartmut Penners s390 stack frame sheet. -- IBM Mainframe Channel Attachment a technology brief from a CISCO webpage -- Various bits of man & info pages of Linux. -- Linux & GDB source. -- Various info & man pages. -- CMS Help on tracing commands. -- Linux for s/390 Elf Application Binary Interface -- Linux for z/Series Elf Application Binary Interface ( Both Highly Recommended ) -- z/Architecture Principles of Operation SA22-7832-00 -- Enterprise Systems Architecture/390 Reference Summary SA22-7209-01 & the -- Enterprise Systems Architecture/390 Principles of Operation SA22-7201-05 - -Special Thanks -============== -Special thanks to Neale Ferguson who maintains a much -prettier HTML version of this page at -http://linuxvm.org/penguinvm/ -Bob Grainger Stefan Bader & others for reporting bugs diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst index 4602312909d3..f7af2061e406 100644 --- a/Documentation/s390/index.rst +++ b/Documentation/s390/index.rst @@ -7,7 +7,6 @@ s390 Architecture cds 3270 - debugging390 driver-model monreader qeth @@ -15,7 +14,6 @@ s390 Architecture vfio-ap vfio-ccw zfcpdump - dasd common_io text_files diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index 3a9064219656..9801d6b284b1 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -9,15 +9,16 @@ CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the specification of the maximum CPU bandwidth available to a group or hierarchy. The bandwidth allowed for a group is specified using a quota and period. Within -each given "period" (microseconds), a group is allowed to consume only up to -"quota" microseconds of CPU time. When the CPU bandwidth consumption of a -group exceeds this limit (for that period), the tasks belonging to its -hierarchy will be throttled and are not allowed to run again until the next -period. - -A group's unused runtime is globally tracked, being refreshed with quota units -above at each period boundary. As threads consume this bandwidth it is -transferred to cpu-local "silos" on a demand basis. The amount transferred +each given "period" (microseconds), a task group is allocated up to "quota" +microseconds of CPU time. That quota is assigned to per-cpu run queues in +slices as threads in the cgroup become runnable. Once all quota has been +assigned any additional requests for quota will result in those threads being +throttled. Throttled threads will not be able to run again until the next +period when the quota is replenished. + +A group's unassigned quota is globally tracked, being refreshed back to +cfs_quota units at each period boundary. As threads consume this bandwidth it +is transferred to cpu-local "silos" on a demand basis. The amount transferred within each of these updates is tunable and described as the "slice". Management @@ -35,12 +36,12 @@ The default values are:: A value of -1 for cpu.cfs_quota_us indicates that the group does not have any bandwidth restriction in place, such a group is described as an unconstrained -bandwidth group. This represents the traditional work-conserving behavior for +bandwidth group. This represents the traditional work-conserving behavior for CFS. Writing any (valid) positive value(s) will enact the specified bandwidth limit. -The minimum quota allowed for the quota or period is 1ms. There is also an -upper bound on the period length of 1s. Additional restrictions exist when +The minimum quota allowed for the quota or period is 1ms. There is also an +upper bound on the period length of 1s. Additional restrictions exist when bandwidth limits are used in a hierarchical fashion, these are explained in more detail below. @@ -53,8 +54,8 @@ unthrottled if it is in a constrained state. System wide settings -------------------- For efficiency run-time is transferred between the global pool and CPU local -"silos" in a batch fashion. This greatly reduces global accounting pressure -on large systems. The amount transferred each time such an update is required +"silos" in a batch fashion. This greatly reduces global accounting pressure +on large systems. The amount transferred each time such an update is required is described as the "slice". This is tunable via procfs:: @@ -97,6 +98,51 @@ There are two ways in which a group may become throttled: In case b) above, even though the child may have runtime remaining it will not be allowed to until the parent's runtime is refreshed. +CFS Bandwidth Quota Caveats +--------------------------- +Once a slice is assigned to a cpu it does not expire. However all but 1ms of +the slice may be returned to the global pool if all threads on that cpu become +unrunnable. This is configured at compile time by the min_cfs_rq_runtime +variable. This is a performance tweak that helps prevent added contention on +the global lock. + +The fact that cpu-local slices do not expire results in some interesting corner +cases that should be understood. + +For cgroup cpu constrained applications that are cpu limited this is a +relatively moot point because they will naturally consume the entirety of their +quota as well as the entirety of each cpu-local slice in each period. As a +result it is expected that nr_periods roughly equal nr_throttled, and that +cpuacct.usage will increase roughly equal to cfs_quota_us in each period. + +For highly-threaded, non-cpu bound applications this non-expiration nuance +allows applications to briefly burst past their quota limits by the amount of +unused slice on each cpu that the task group is running on (typically at most +1ms per cpu or as defined by min_cfs_rq_runtime). This slight burst only +applies if quota had been assigned to a cpu and then not fully used or returned +in previous periods. This burst amount will not be transferred between cores. +As a result, this mechanism still strictly limits the task group to quota +average usage, albeit over a longer time window than a single period. This +also limits the burst ability to no more than 1ms per cpu. This provides +better more predictable user experience for highly threaded applications with +small quota limits on high core count machines. It also eliminates the +propensity to throttle these applications while simultanously using less than +quota amounts of cpu. Another way to say this, is that by allowing the unused +portion of a slice to remain valid across periods we have decreased the +possibility of wastefully expiring quota on cpu-local silos that don't need a +full slice's amount of cpu time. + +The interaction between cpu-bound and non-cpu-bound-interactive applications +should also be considered, especially when single core usage hits 100%. If you +gave each of these applications half of a cpu-core and they both got scheduled +on the same CPU it is theoretically possible that the non-cpu bound application +will use up to 1ms additional quota in some periods, thereby preventing the +cpu-bound application from fully using its quota by that same amount. In these +instances it will be up to the CFS algorithm (see sched-design-CFS.rst) to +decide which application is chosen to run, as they will both be runnable and +have remaining quota. This runtime discrepancy will be made up in the following +periods when the interactive application idles. + Examples -------- 1. Limit a group to 1 CPU worth of runtime:: diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst index 3296533e54cf..fc40e9f23c85 100644 --- a/Documentation/security/tpm/index.rst +++ b/Documentation/security/tpm/index.rst @@ -4,5 +4,7 @@ Trusted Platform Module documentation .. toctree:: + tpm_event_log tpm_vtpm_proxy xen-tpmfront + tpm_ftpm_tee diff --git a/Documentation/security/tpm/tpm_event_log.rst b/Documentation/security/tpm/tpm_event_log.rst new file mode 100644 index 000000000000..f00f7a1d5e92 --- /dev/null +++ b/Documentation/security/tpm/tpm_event_log.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +TPM Event Log +============= + +This document briefly describes what TPM log is and how it is handed +over from the preboot firmware to the operating system. + +Introduction +============ + +The preboot firmware maintains an event log that gets new entries every +time something gets hashed by it to any of the PCR registers. The events +are segregated by their type and contain the value of the hashed PCR +register. Typically, the preboot firmware will hash the components to +who execution is to be handed over or actions relevant to the boot +process. + +The main application for this is remote attestation and the reason why +it is useful is nicely put in the very first section of [1]: + +"Attestation is used to provide information about the platform’s state +to a challenger. However, PCR contents are difficult to interpret; +therefore, attestation is typically more useful when the PCR contents +are accompanied by a measurement log. While not trusted on their own, +the measurement log contains a richer set of information than do the PCR +contents. The PCR contents are used to provide the validation of the +measurement log." + +UEFI event log +============== + +UEFI provided event log has a few somewhat weird quirks. + +Before calling ExitBootServices() Linux EFI stub copies the event log to +a custom configuration table defined by the stub itself. Unfortunately, +the events generated by ExitBootServices() don't end up in the table. + +The firmware provides so called final events configuration table to sort +out this issue. Events gets mirrored to this table after the first time +EFI_TCG2_PROTOCOL.GetEventLog() gets called. + +This introduces another problem: nothing guarantees that it is not called +before the Linux EFI stub gets to run. Thus, it needs to calculate and save the +final events table size while the stub is still running to the custom +configuration table so that the TPM driver can later on skip these events when +concatenating two halves of the event log from the custom configuration table +and the final events table. + +References +========== + +- [1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ +- [2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c diff --git a/Documentation/security/tpm/tpm_ftpm_tee.rst b/Documentation/security/tpm/tpm_ftpm_tee.rst new file mode 100644 index 000000000000..8c2bae16e3d9 --- /dev/null +++ b/Documentation/security/tpm/tpm_ftpm_tee.rst @@ -0,0 +1,27 @@ +============================================= +Firmware TPM Driver +============================================= + +This document describes the firmware Trusted Platform Module (fTPM) +device driver. + +Introduction +============ + +This driver is a shim for firmware implemented in ARM's TrustZone +environment. The driver allows programs to interact with the TPM in the same +way they would interact with a hardware TPM. + +Design +====== + +The driver acts as a thin layer that passes commands to and from a TPM +implemented in firmware. The driver itself doesn't contain much logic and is +used more like a dumb pipe between firmware and kernel/userspace. + +The firmware itself is based on the following paper: +https://www.microsoft.com/en-us/research/wp-content/uploads/2017/06/ftpm1.pdf + +When the driver is loaded it will expose ``/dev/tpmX`` character devices to +userspace which will enable userspace to communicate with the firmware TPM +through this device. diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index 4a3cecc8ad38..02aacd69ab96 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -1001,6 +1001,8 @@ position_fix 2 = POSBUF: use position buffer, 3 = VIACOMBO: VIA-specific workaround for capture, 4 = COMBO: use LPIB for playback, auto for capture stream + 5 = SKL+: apply the delay calculation available on recent Intel chips + 6 = FIFO: correct the position with the fixed FIFO size, for recent AMD chips probe_mask Bitmask to probe codecs (default = -1, meaning all slots); When the bit 8 (0x100) is set, the lower 8 bits are used diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst index 7d7c191102a7..11298f0ce44d 100644 --- a/Documentation/sound/hd-audio/models.rst +++ b/Documentation/sound/hd-audio/models.rst @@ -260,6 +260,9 @@ alc295-hp-x360 HP Spectre X360 fixups alc-sense-combo Headset button support for Chrome platform +huawei-mbx-stereo + Enable initialization verbs for Huawei MBX stereo speakers; + might be risky, try this at your own risk ALC66x/67x/892 ============== diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 9f7347830ba4..0f3109d9abc8 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -66,6 +66,11 @@ by comparing both LPIB and position-buffer values. ``position_fix=4`` is another combination available for all controllers, and uses LPIB for the playback and the position-buffer for the capture streams. +``position_fix=5`` is specific to Intel platforms, so far, for Skylake +and onward. It applies the delay calculation for the precise position +reporting. +``position_fix=6`` is to correct the position with the fixed FIFO +size, mainly targeted for the recent AMD controllers. 0 is the default value for all other controllers, the automatic check and fallback to LPIB as described in the above. If you get a problem of repeated sounds, this option might diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 47b89f014e69..4d7d42acf6df 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation hd-audio/index cards/index -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 77e89c1956d7..5b6119ff69f4 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -25,8 +25,9 @@ RE_function = re.compile(r'([\w_][\w\d_]+\(\))') # to the creation of incorrect and confusing cross references. So # just don't even try with these names. # -Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap' - 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl'] +Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', + 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', + 'socket' ] # # Find all occurrences of function() and try to replace them with diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst index 9927af7a629c..e614a589547c 100644 --- a/Documentation/spi/butterfly +++ b/Documentation/spi/butterfly.rst @@ -1,3 +1,4 @@ +=================================================== spi_butterfly - parport-to-butterfly adapter driver =================================================== @@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP" connector pins (used also on non-Butterfly AVR boards). On the parport side this is like "sp12" programming cables. + ====== ============= =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PB1/SCK = pin 2/D0 - RESET = J403.nRST = pin 3/D1 - VCC = J403.VCC_EXT = pin 8/D6 - MOSI = J403.PB2/MOSI = pin 9/D7 - MISO = J403.PB3/MISO = pin 11/S7,nBUSY - GND = J403.GND = pin 23/GND + ====== ============= =================== + SCK J403.PB1/SCK pin 2/D0 + RESET J403.nRST pin 3/D1 + VCC J403.VCC_EXT pin 8/D6 + MOSI J403.PB2/MOSI pin 9/D7 + MISO J403.PB3/MISO pin 11/S7,nBUSY + GND J403.GND pin 23/GND + ====== ============= =================== Then to let Linux master that bus to talk to the DataFlash chip, you must (a) flash new firmware that disables SPI (set PRR.2, and disable pullups by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and (c) cable in the chipselect. + ====== ============ =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - VCC = J400.VCC_EXT = pin 7/D5 - SELECT = J400.PB0/nSS = pin 17/C3,nSELECT - GND = J400.GND = pin 24/GND + ====== ============ =================== + VCC J400.VCC_EXT pin 7/D5 + SELECT J400.PB0/nSS pin 17/C3,nSELECT + GND J400.GND pin 24/GND + ====== ============ =================== Or you could flash firmware making the AVR into an SPI slave (keeping the DataFlash in reset) and tweak the spi_butterfly driver to make it bind to @@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware, while letting either Linux or the AVR use the DataFlash. There are plenty of spare parport pins to wire this one up, such as: + ====== ============= =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PE4/USCK = pin 5/D3 - MOSI = J403.PE5/DI = pin 6/D4 - MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT - GND = J403.GND = pin 22/GND - - IRQ = J402.PF4 = pin 10/S6,ACK - GND = J402.GND(P2) = pin 25/GND + ====== ============= =================== + SCK J403.PE4/USCK pin 5/D3 + MOSI J403.PE5/DI pin 6/D4 + MISO J403.PE6/DO pin 12/S5,nPAPEROUT + GND J403.GND pin 22/GND + IRQ J402.PF4 pin 10/S6,ACK + GND J402.GND(P2) pin 25/GND + ====== ============= =================== diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst new file mode 100644 index 000000000000..06c34ea11bcf --- /dev/null +++ b/Documentation/spi/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +Serial Peripheral Interface (SPI) +================================= + +.. toctree:: + :maxdepth: 1 + + spi-summary + spidev + butterfly + pxa2xx + spi-lm70llp + spi-sc18is602 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst index 551325b66b23..882d3cc72cc2 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx.rst @@ -1,8 +1,10 @@ +============================== PXA2xx SPI on SSP driver HOWTO -=================================================== +============================== + This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx synchronous serial port into a SPI master controller -(see Documentation/spi/spi-summary). The driver has the following features +(see Documentation/spi/spi-summary.rst). The driver has the following features - Support for any PXA2xx SSP - SSP PIO and SSP DMA data transfers. @@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers ----------------------------------- Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a "platform device". The master configuration is passed to the driver via a table -found in include/linux/spi/pxa2xx_spi.h: +found in include/linux/spi/pxa2xx_spi.h:: -struct pxa2xx_spi_controller { + struct pxa2xx_spi_controller { u16 num_chipselect; u8 enable_dma; -}; + }; The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of slave device (chips) attached to this SPI master. @@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller". NSSP MASTER SAMPLE ------------------ -Below is a sample configuration using the PXA255 NSSP. +Below is a sample configuration using the PXA255 NSSP:: -static struct resource pxa_spi_nssp_resources[] = { + static struct resource pxa_spi_nssp_resources[] = { [0] = { .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */ .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */ @@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = { .end = IRQ_NSSP, .flags = IORESOURCE_IRQ, }, -}; + }; -static struct pxa2xx_spi_controller pxa_nssp_master_info = { + static struct pxa2xx_spi_controller pxa_nssp_master_info = { .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ -}; + }; -static struct platform_device pxa_spi_nssp = { + static struct platform_device pxa_spi_nssp = { .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */ .id = 2, /* Bus number, MUST MATCH SSP number 1..n */ .resource = pxa_spi_nssp_resources, @@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = { .dev = { .platform_data = &pxa_nssp_master_info, /* Passed to driver */ }, -}; + }; -static struct platform_device *devices[] __initdata = { + static struct platform_device *devices[] __initdata = { &pxa_spi_nssp, -}; + }; -static void __init board_init(void) -{ + static void __init board_init(void) + { (void)platform_add_device(devices, ARRAY_SIZE(devices)); -} + } Declaring Slave Devices ----------------------- Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c using the "spi_board_info" structure found in "linux/spi/spi.h". See -"Documentation/spi/spi-summary" for additional information. +"Documentation/spi/spi-summary.rst" for additional information. Each slave device attached to the PXA must provide slave specific configuration information via the structure "pxa2xx_spi_chip" found in @@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in will uses the configuration whenever the driver communicates with the slave device. All fields are optional. -struct pxa2xx_spi_chip { +:: + + struct pxa2xx_spi_chip { u8 tx_threshold; u8 rx_threshold; u8 dma_burst_size; u32 timeout; u8 enable_loopback; void (*cs_control)(u32 command); -}; + }; The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are used to configure the SSP hardware fifo. These fields are critical to the performance of pxa2xx_spi driver and misconfiguration will result in rx -fifo overruns (especially in PIO mode transfers). Good default values are +fifo overruns (especially in PIO mode transfers). Good default values are:: .tx_threshold = 8, .rx_threshold = 8, @@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" field. Below is a sample configuration using the PXA255 NSSP. -/* Chip Select control for the CS8415A SPI slave device */ -static void cs8415a_cs_control(u32 command) -{ +:: + + /* Chip Select control for the CS8415A SPI slave device */ + static void cs8415a_cs_control(u32 command) + { if (command & PXA2XX_CS_ASSERT) GPCR(2) = GPIO_bit(2); else GPSR(2) = GPIO_bit(2); -} + } -/* Chip Select control for the CS8405A SPI slave device */ -static void cs8405a_cs_control(u32 command) -{ + /* Chip Select control for the CS8405A SPI slave device */ + static void cs8405a_cs_control(u32 command) + { if (command & PXA2XX_CS_ASSERT) GPCR(3) = GPIO_bit(3); else GPSR(3) = GPIO_bit(3); -} + } -static struct pxa2xx_spi_chip cs8415a_chip_info = { + static struct pxa2xx_spi_chip cs8415a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ .cs_control = cs8415a_cs_control, /* Use external chip select */ -}; + }; -static struct pxa2xx_spi_chip cs8405a_chip_info = { + static struct pxa2xx_spi_chip cs8405a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ .cs_control = cs8405a_cs_control, /* Use external chip select */ -}; + }; -static struct spi_board_info streetracer_spi_board_info[] __initdata = { + static struct spi_board_info streetracer_spi_board_info[] __initdata = { { .modalias = "cs8415a", /* Name of spi_driver for this device */ .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ @@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = { .controller_data = &cs8405a_chip_info, /* Master chip config */ .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ }, -}; + }; -static void __init streetracer_init(void) -{ + static void __init streetracer_init(void) + { spi_register_board_info(streetracer_spi_board_info, ARRAY_SIZE(streetracer_spi_board_info)); -} + } DMA and PIO I/O Support @@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on -a per "spi_transfer" basis: +a per "spi_transfer" basis:: -if !enable_dma then + if !enable_dma then always use PIO transfers -if spi_message.len > 8191 then + if spi_message.len > 8191 then print "rate limited" warning use PIO transfers -if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then use coherent DMA mode -if rx_buf and tx_buf are aligned on 8 byte boundary then + if rx_buf and tx_buf are aligned on 8 byte boundary then use streaming DMA mode -otherwise + otherwise use PIO transfer THANKS TO --------- David Brownell and others for mentoring the development of this driver. - diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst index 463f6d01fa15..07631aef4343 100644 --- a/Documentation/spi/spi-lm70llp +++ b/Documentation/spi/spi-lm70llp.rst @@ -1,8 +1,11 @@ +============================================== spi_lm70llp : LM70-LLP parport-to-SPI adapter ============================================== Supported board/chip: + * National Semiconductor LM70 LLP evaluation board + Datasheet: http://www.national.com/pf/LM/LM70.html Author: @@ -29,9 +32,10 @@ available (on page 4) here: The hardware interfacing on the LM70 LLP eval board is as follows: + ======== == ========= ========== Parallel LM70 LLP - Port Direction JP2 Header - ----------- --------- ---------------- + Port . Direction JP2 Header + ======== == ========= ========== D0 2 - - D1 3 --> V+ 5 D2 4 --> V+ 5 @@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows: D7 9 --> SI/O 5 GND 25 - GND 7 Select 13 <-- SI/O 1 - ----------- --------- ---------------- + ======== == ========= ========== Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin is connected to both pin D7 (as Master Out) and Select (as Master In) @@ -74,6 +78,7 @@ inverting the value read at pin 13. Thanks to --------- -o David Brownell for mentoring the SPI-side driver development. -o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. -o Nadir Billimoria for help interpreting the circuit schematic. + +- David Brownell for mentoring the SPI-side driver development. +- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. +- Nadir Billimoria for help interpreting the circuit schematic. diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst index a45702865a38..2a31dc722321 100644 --- a/Documentation/spi/spi-sc18is602 +++ b/Documentation/spi/spi-sc18is602.rst @@ -1,8 +1,11 @@ +=========================== Kernel driver spi-sc18is602 =========================== Supported chips: + * NXP SI18IS602/602B/603 + Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf Author: @@ -17,7 +20,7 @@ kernel's SPI core subsystem. The driver does not probe for supported chips, since the SI18IS602/603 does not support Chip ID registers. You will have to instantiate the devices explicitly. -Please see Documentation/i2c/instantiating-devices for details. +Please see Documentation/i2c/instantiating-devices.rst for details. Usage Notes diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst index 1a63194b74d7..f1daffe10d78 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary.rst @@ -1,3 +1,4 @@ +==================================== Overview of Linux kernel SPI support ==================================== @@ -139,12 +140,14 @@ a command and then reading its response. There are two types of SPI driver, here called: - Controller drivers ... controllers may be built into System-On-Chip + Controller drivers ... + controllers may be built into System-On-Chip processors, and often support both Master and Slave roles. These drivers touch hardware registers and may use DMA. Or they can be PIO bitbangers, needing just GPIO pins. - Protocol drivers ... these pass messages through the controller + Protocol drivers ... + these pass messages through the controller driver to communicate with a Slave or Master device on the other side of an SPI link. @@ -160,7 +163,7 @@ those two types of drivers. There is a minimal core of SPI programming interfaces, focussing on using the driver model to connect controller and protocol drivers using device tables provided by board specific initialization code. SPI -shows up in sysfs in several locations: +shows up in sysfs in several locations:: /sys/devices/.../CTLR ... physical node for a given SPI controller @@ -168,7 +171,7 @@ shows up in sysfs in several locations: chipselect C, accessed through CTLR. /sys/bus/spi/devices/spiB.C ... symlink to that physical - .../CTLR/spiB.C device + .../CTLR/spiB.C device /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver that should be used with this device (for hotplug/coldplug) @@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices. That information is normally provided by board-specific code, even for chips that do support some of automated discovery/enumeration. -DECLARE CONTROLLERS +Declare Controllers +^^^^^^^^^^^^^^^^^^^ The first kind of information is a list of what SPI controllers exist. For System-on-Chip (SOC) based boards, these will usually be platform @@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several SPI-capable controllers, and only the ones actually usable on a given board should normally be set up and registered. -So for example arch/.../mach-*/board-*.c files might have code like: +So for example arch/.../mach-*/board-*.c files might have code like:: #include <mach/spi.h> /* for mysoc_spi_data */ @@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like: ... } -And SOC-specific utility code might look something like: +And SOC-specific utility code might look something like:: #include <mach/spi.h> @@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use an external clock, where another derives the SPI clock from current settings of some master clock. - -DECLARE SLAVE DEVICES +Declare Slave Devices +^^^^^^^^^^^^^^^^^^^^^ The second kind of information is a list of what SPI slave devices exist on the target board, often with some board-specific data needed for the @@ -278,7 +282,7 @@ driver to work correctly. Normally your arch/.../mach-*/board-*.c files would provide a small table listing the SPI devices on each board. (This would typically be only a -small handful.) That might look like: +small handful.) That might look like:: static struct ads7846_platform_data ads_info = { .vref_delay_usecs = 100, @@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it. Then your board initialization code would register that table with the SPI infrastructure, so that it's available later when the SPI master controller -driver is registered: +driver is registered:: spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); @@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those. The widely used "card" style computers bundle memory, cpu, and little else onto a card that's maybe just thirty square centimeters. On such systems, -your arch/.../mach-.../board-*.c file would primarily provide information +your ``arch/.../mach-.../board-*.c`` file would primarily provide information about the devices on the mainboard into which such a card is plugged. That certainly includes SPI devices hooked up through the card connectors! -NON-STATIC CONFIGURATIONS +Non-static Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^ Developer boards often play by different rules than product boards, and one example is the potential need to hotplug SPI devices and/or controllers. @@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"? Most SPI drivers are currently kernel drivers, but there's also support for userspace drivers. Here we talk only about kernel drivers. -SPI protocol drivers somewhat resemble platform device drivers: +SPI protocol drivers somewhat resemble platform device drivers:: static struct spi_driver CHIP_driver = { .driver = { @@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code might look like this unless you're creating a device which is managing a bus (appearing under /sys/class/spi_master). +:: + static int CHIP_probe(struct spi_device *spi) { struct CHIP *chip; @@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master". Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() to get the driver-private data allocated for that device. +:: + struct spi_master *master; struct CONTROLLER *c; @@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master() will reverse the effect of spi_register_master(). -BUS NUMBERING +Bus Numbering +^^^^^^^^^^^^^ Bus numbering is important, since that's how Linux identifies a given SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On @@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat this as a non-static configuration (see above). -SPI MASTER METHODS +SPI Master Methods +^^^^^^^^^^^^^^^^^^ - master->setup(struct spi_device *spi) +``master->setup(struct spi_device *spi)`` This sets up the device clock rate, SPI mode, and word sizes. Drivers may change the defaults provided by board_info, and then call spi_setup(spi) to invoke this routine. It may sleep. @@ -528,37 +539,37 @@ SPI MASTER METHODS change them right away ... otherwise drivers could corrupt I/O that's in progress for other SPI devices. - ** BUG ALERT: for some reason the first version of - ** many spi_master drivers seems to get this wrong. - ** When you code setup(), ASSUME that the controller - ** is actively processing transfers for another device. + .. note:: + + BUG ALERT: for some reason the first version of + many spi_master drivers seems to get this wrong. + When you code setup(), ASSUME that the controller + is actively processing transfers for another device. - master->cleanup(struct spi_device *spi) +``master->cleanup(struct spi_device *spi)`` Your controller driver may use spi_device.controller_state to hold state it dynamically associates with that device. If you do that, be sure to provide the cleanup() method to free that state. - master->prepare_transfer_hardware(struct spi_master *master) +``master->prepare_transfer_hardware(struct spi_master *master)`` This will be called by the queue mechanism to signal to the driver that a message is coming in soon, so the subsystem requests the driver to prepare the transfer hardware by issuing this call. This may sleep. - master->unprepare_transfer_hardware(struct spi_master *master) +``master->unprepare_transfer_hardware(struct spi_master *master)`` This will be called by the queue mechanism to signal to the driver that there are no more messages pending in the queue and it may relax the hardware (e.g. by power management calls). This may sleep. - master->transfer_one_message(struct spi_master *master, - struct spi_message *mesg) +``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)`` The subsystem calls the driver to transfer a single message while queuing transfers that arrive in the meantime. When the driver is finished with this message, it must call spi_finalize_current_message() so the subsystem can issue the next message. This may sleep. - master->transfer_one(struct spi_master *master, struct spi_device *spi, - struct spi_transfer *transfer) +``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)`` The subsystem calls the driver to transfer a single transfer while queuing transfers that arrive in the meantime. When the driver is finished with this transfer, it must call @@ -568,19 +579,20 @@ SPI MASTER METHODS not call your transfer_one callback. Return values: - negative errno: error - 0: transfer is finished - 1: transfer is still in progress - master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, - u8 hold_clk_cycles, u8 inactive_clk_cycles) + * negative errno: error + * 0: transfer is finished + * 1: transfer is still in progress + +``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` This method allows SPI client drivers to request SPI master controller for configuring device specific CS setup, hold and inactive timing requirements. - DEPRECATED METHODS +Deprecated Methods +^^^^^^^^^^^^^^^^^^ - master->transfer(struct spi_device *spi, struct spi_message *message) +``master->transfer(struct spi_device *spi, struct spi_message *message)`` This must not sleep. Its responsibility is to arrange that the transfer happens and its complete() callback is issued. The two will normally happen later, after other transfers complete, and @@ -590,7 +602,8 @@ SPI MASTER METHODS implemented. -SPI MESSAGE QUEUE +SPI Message Queue +^^^^^^^^^^^^^^^^^ If you are happy with the standard queueing mechanism provided by the SPI subsystem, just implement the queued methods specified above. Using @@ -619,13 +632,13 @@ THANKS TO Contributors to Linux-SPI discussions include (in alphabetical order, by last name): -Mark Brown -David Brownell -Russell King -Grant Likely -Dmitry Pervushin -Stephen Street -Mark Underwood -Andrew Victor -Linus Walleij -Vitaly Wool +- Mark Brown +- David Brownell +- Russell King +- Grant Likely +- Dmitry Pervushin +- Stephen Street +- Mark Underwood +- Andrew Victor +- Linus Walleij +- Vitaly Wool diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst index 3d14035b1766..f05dbc5ccdbc 100644 --- a/Documentation/spi/spidev +++ b/Documentation/spi/spidev.rst @@ -1,7 +1,13 @@ +================= +SPI userspace API +================= + SPI devices have a limited userspace API, supporting basic half-duplex read() and write() access to SPI slave devices. Using ioctl() requests, full duplex transfers and device I/O configuration are also available. +:: + #include <fcntl.h> #include <unistd.h> #include <sys/ioctl.h> @@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev. busybox; it's less featureful, but often enough.) For a SPI device with chipselect C on bus B, you should see: - /dev/spidevB.C ... character special device, major number 153 with + /dev/spidevB.C ... + character special device, major number 153 with a dynamically chosen minor device number. This is the node that userspace programs will open, created by "udev" or "mdev". - /sys/devices/.../spiB.C ... as usual, the SPI device node will + /sys/devices/.../spiB.C ... + as usual, the SPI device node will be a child of its SPI master controller. - /sys/class/spidev/spidevB.C ... created when the "spidev" driver + /sys/class/spidev/spidevB.C ... + created when the "spidev" driver binds to that device. (Directory or symlink, based on whether or not you enabled the "deprecated sysfs files" Kconfig option.) @@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request. Several ioctl() requests let your driver read or override the device's current settings for data transfer parameters: - SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will + SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... + pass a pointer to a byte which will return (RD) or assign (WR) the SPI transfer mode. Use the constants SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, @@ -88,22 +98,26 @@ settings for data transfer parameters: Note that this request is limited to SPI mode flags that fit in a single byte. - SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t + SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... + pass a pointer to a uin32_t which will return (RD) or assign (WR) the full SPI transfer mode, not limited to the bits that fit in one byte. - SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte + SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... + pass a pointer to a byte which will return (RD) or assign (WR) the bit justification used to transfer SPI words. Zero indicates MSB-first; other values indicate the less common LSB-first encoding. In both cases the specified value is right-justified in each word, so that unused (TX) or undefined (RX) bits are in the MSBs. - SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to + SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... + pass a pointer to a byte which will return (RD) or assign (WR) the number of bits in each SPI transfer word. The value zero signifies eight bits. - SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a + SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... + pass a pointer to a u32 which will return (RD) or assign (WR) the maximum SPI transfer speed, in Hz. The controller can't necessarily assign that specific clock speed. diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst index 1a660a39e3c0..993dd294b81b 100644 --- a/Documentation/trace/coresight-cpu-debug.txt +++ b/Documentation/trace/coresight-cpu-debug.rst @@ -1,8 +1,9 @@ - Coresight CPU Debug Module - ========================== +========================== +Coresight CPU Debug Module +========================== - Author: Leo Yan <leo.yan@linaro.org> - Date: April 5th, 2017 + :Author: Leo Yan <leo.yan@linaro.org> + :Date: April 5th, 2017 Introduction ------------ @@ -69,6 +70,7 @@ Before accessing debug registers, we should ensure the clock and power domain have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1 Debug registers', the debug registers are spread into two domains: the debug domain and the CPU domain. +:: +---------------+ | | @@ -125,18 +127,21 @@ If you want to enable debugging functionality at boot time, you can add "coresight_cpu_debug.enable=1" to the kernel command line parameter. The driver also can work as module, so can enable the debugging when insmod -module: -# insmod coresight_cpu_debug.ko debug=1 +module:: + + # insmod coresight_cpu_debug.ko debug=1 When boot time or insmod module you have not enabled the debugging, the driver uses the debugfs file system to provide a knob to dynamically enable or disable debugging: -To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable: -# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable +To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:: + + # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable + +To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:: -To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable: -# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable As explained in chapter "Clock and power domain", if you are working on one platform which has idle states to power off debug logic and the power @@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency" interface (see Documentation/power/pm_qos_interface.rst for more details). As specified in the PM QoS documentation the requested parameter will stay in effect until the file descriptor is released. -For example: +For example:: -# exec 3<> /dev/cpu_dma_latency; echo 0 >&3 -... -Do some work... -... -# exec 3<>- + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3 + ... + Do some work... + ... + # exec 3<>- The same can also be done from an application program. Disable specific CPU's specific idle state from cpuidle sysfs (see -Documentation/admin-guide/pm/cpuidle.rst): -# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable +Documentation/admin-guide/pm/cpuidle.rst):: + # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable Output format ------------- -Here is an example of the debugging output format: - -ARM external debug module: -coresight-cpu-debug 850000.debug: CPU[0]: -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) -coresight-cpu-debug 852000.debug: CPU[1]: -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) +Here is an example of the debugging output format:: + + ARM external debug module: + coresight-cpu-debug 850000.debug: CPU[0]: + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) + coresight-cpu-debug 852000.debug: CPU[1]: + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst index b027d61b27a6..72f4b7ef1bad 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.rst @@ -1,8 +1,9 @@ - Coresight - HW Assisted Tracing on ARM - ====================================== +====================================== +Coresight - HW Assisted Tracing on ARM +====================================== - Author: Mathieu Poirier <mathieu.poirier@linaro.org> - Date: September 11th, 2014 + :Author: Mathieu Poirier <mathieu.poirier@linaro.org> + :Date: September 11th, 2014 Introduction ------------ @@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a memory buffer or creating an interface to the outside world where data can be transferred to a host without fear of filling up the onboard coresight memory buffer. -At typical coresight system would look like this: +At typical coresight system would look like this:: ***************************************************************** **************************** AMBA AXI ****************************===|| @@ -95,15 +96,24 @@ Acronyms and Classification Acronyms: -PTM: Program Trace Macrocell -ETM: Embedded Trace Macrocell -STM: System trace Macrocell -ETB: Embedded Trace Buffer -ITM: Instrumentation Trace Macrocell -TPIU: Trace Port Interface Unit -TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router -TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO -CTI: Cross Trigger Interface +PTM: + Program Trace Macrocell +ETM: + Embedded Trace Macrocell +STM: + System trace Macrocell +ETB: + Embedded Trace Buffer +ITM: + Instrumentation Trace Macrocell +TPIU: + Trace Port Interface Unit +TMC-ETR: + Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: + Trace Memory Controller, configured as Embedded Trace FIFO +CTI: + Cross Trigger Interface Classification: @@ -118,7 +128,7 @@ Misc: Device Tree Bindings ----------------------- +-------------------- See Documentation/devicetree/bindings/arm/coresight.txt for details. @@ -133,79 +143,79 @@ The coresight framework provides a central point to represent, configure and manage coresight devices on a platform. Any coresight compliant device can register with the framework for as long as they use the right APIs: -struct coresight_device *coresight_register(struct coresight_desc *desc); -void coresight_unregister(struct coresight_device *csdev); +.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc); +.. c:function:: void coresight_unregister(struct coresight_device *csdev); -The registering function is taking a "struct coresight_device *csdev" and -register the device with the core framework. The unregister function takes -a reference to a "struct coresight_device", obtained at registration time. +The registering function is taking a ``struct coresight_desc *desc`` and +register the device with the core framework. The unregister function takes +a reference to a ``struct coresight_device *csdev`` obtained at registration time. If everything goes well during the registration process the new devices will -show up under /sys/bus/coresight/devices, as showns here for a TC2 platform: +show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:: -root:~# ls /sys/bus/coresight/devices/ -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm -root:~# + root:~# ls /sys/bus/coresight/devices/ + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:~# -The functions take a "struct coresight_device", which looks like this: +The functions take a ``struct coresight_device``, which looks like this:: -struct coresight_desc { - enum coresight_dev_type type; - struct coresight_dev_subtype subtype; - const struct coresight_ops *ops; - struct coresight_platform_data *pdata; - struct device *dev; - const struct attribute_group **groups; -}; + struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct attribute_group **groups; + }; The "coresight_dev_type" identifies what the device is, i.e, source link or sink while the "coresight_dev_subtype" will characterise that type further. -The "struct coresight_ops" is mandatory and will tell the framework how to +The ``struct coresight_ops`` is mandatory and will tell the framework how to perform base operations related to the components, each component having -a different set of requirement. For that "struct coresight_ops_sink", -"struct coresight_ops_link" and "struct coresight_ops_source" have been +a different set of requirement. For that ``struct coresight_ops_sink``, +``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been provided. -The next field, "struct coresight_platform_data *pdata" is acquired by calling -"of_get_coresight_platform_data()", as part of the driver's _probe routine and -"struct device *dev" gets the device reference embedded in the "amba_device": +The next field ``struct coresight_platform_data *pdata`` is acquired by calling +``of_get_coresight_platform_data()``, as part of the driver's _probe routine and +``struct device *dev`` gets the device reference embedded in the ``amba_device``:: -static int etm_probe(struct amba_device *adev, const struct amba_id *id) -{ - ... - ... - drvdata->dev = &adev->dev; - ... -} + static int etm_probe(struct amba_device *adev, const struct amba_id *id) + { + ... + ... + drvdata->dev = &adev->dev; + ... + } Specific class of device (source, link, or sink) have generic operations -that can be performed on them (see "struct coresight_ops"). The -"**groups" is a list of sysfs entries pertaining to operations +that can be performed on them (see ``struct coresight_ops``). The ``**groups`` +is a list of sysfs entries pertaining to operations specific to that component only. "Implementation defined" customisations are expected to be accessed and controlled using those entries. - Device Naming scheme ------------------------- +-------------------- + The devices that appear on the "coresight" bus were named the same as their parent devices, i.e, the real devices that appears on AMBA bus or the platform bus. Thus the names were based on the Linux Open Firmware layer naming convention, which follows the base physical address of the device followed by the device -type. e.g: +type. e.g:: -root:~# ls /sys/bus/coresight/devices/ - 20010000.etf 20040000.funnel 20100000.stm 22040000.etm - 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu - 20070000.etr 20120000.replicator 220c0000.funnel - 23040000.etm 23140000.etm 23340000.etm + root:~# ls /sys/bus/coresight/devices/ + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu + 20070000.etr 20120000.replicator 220c0000.funnel + 23040000.etm 23140000.etm 23340000.etm However, with the introduction of ACPI support, the names of the real devices are a bit cryptic and non-obvious. Thus, a new naming scheme was introduced to use more generic names based on the type of the device. The -following rules apply: +following rules apply:: 1) Devices that are bound to CPUs, are named based on the CPU logical number. @@ -220,11 +230,11 @@ following rules apply: e.g, tmc_etf0, tmc_etr0, funnel0, funnel1 -Thus, with the new scheme the devices could appear as : +Thus, with the new scheme the devices could appear as :: -root:~# ls /sys/bus/coresight/devices/ - etm0 etm1 etm2 etm3 etm4 etm5 funnel0 - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 + root:~# ls /sys/bus/coresight/devices/ + etm0 etm1 etm2 etm3 etm4 etm5 funnel0 + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 Some of the examples below might refer to old naming scheme and some to the newer scheme, to give a confirmation that what you see on your @@ -234,9 +244,12 @@ the system under specified locations. How to use the tracer modules ----------------------------- -There are two ways to use the Coresight framework: 1) using the perf cmd line -tools and 2) interacting directly with the Coresight devices using the sysFS -interface. Preference is given to the former as using the sysFS interface +There are two ways to use the Coresight framework: + +1. using the perf cmd line tools. +2. interacting directly with the Coresight devices using the sysFS interface. + +Preference is given to the former as using the sysFS interface requires a deep understanding of the Coresight HW. The following sections provide details on using both methods. @@ -245,107 +258,107 @@ provide details on using both methods. Before trace collection can start, a coresight sink needs to be identified. There is no limit on the amount of sinks (nor sources) that can be enabled at any given moment. As a generic operation, all device pertaining to the sink -class will have an "active" entry in sysfs: - -root:/sys/bus/coresight/devices# ls -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm -root:/sys/bus/coresight/devices# ls 20010000.etb -enable_sink status trigger_cntr -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink -1 -root:/sys/bus/coresight/devices# +class will have an "active" entry in sysfs:: + + root:/sys/bus/coresight/devices# ls + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:/sys/bus/coresight/devices# ls 20010000.etb + enable_sink status trigger_cntr + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink + 1 + root:/sys/bus/coresight/devices# At boot time the current etm3x driver will configure the first address comparator with "_stext" and "_etext", essentially tracing any instruction that falls within that range. As such "enabling" a source will immediately -trigger a trace capture: - -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source -1 -root:/sys/bus/coresight/devices# cat 20010000.etb/status -Depth: 0x2000 -Status: 0x1 -RAM read ptr: 0x0 -RAM wrt ptr: 0x19d3 <----- The write pointer is moving -Trigger cnt: 0x0 -Control: 0x1 -Flush status: 0x0 -Flush ctrl: 0x2001 -root:/sys/bus/coresight/devices# - -Trace collection is stopped the same way: - -root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source -root:/sys/bus/coresight/devices# - -The content of the ETB buffer can be harvested directly from /dev: - -root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ -of=~/cstrace.bin - -64+0 records in -64+0 records out -32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s -root:/sys/bus/coresight/devices# +trigger a trace capture:: + + root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source + 1 + root:/sys/bus/coresight/devices# cat 20010000.etb/status + Depth: 0x2000 + Status: 0x1 + RAM read ptr: 0x0 + RAM wrt ptr: 0x19d3 <----- The write pointer is moving + Trigger cnt: 0x0 + Control: 0x1 + Flush status: 0x0 + Flush ctrl: 0x2001 + root:/sys/bus/coresight/devices# + +Trace collection is stopped the same way:: + + root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# + +The content of the ETB buffer can be harvested directly from /dev:: + + root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ + of=~/cstrace.bin + 64+0 records in + 64+0 records out + 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s + root:/sys/bus/coresight/devices# The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. Following is a DS-5 output of an experimental loop that increments a variable up to a certain value. The example is simple and yet provides a glimpse of the wealth of possibilities that coresight provides. - -Info Tracing enabled -Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Timestamp Timestamp: 17106715833 -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 -Info Tracing enabled -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} -Timestamp Timestamp: 17107041535 +:: + + Info Tracing enabled + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Timestamp Timestamp: 17106715833 + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 + Info Tracing enabled + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} + Timestamp Timestamp: 17107041535 2) Using perf framework: @@ -370,19 +383,18 @@ A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is listed along with configuration options within forward slashes '/'. Since a Coresight system will typically have more than one sink, the name of the sink to work with needs to be specified as an event option. -On newer kernels the available sinks are listed in sysFS under: -($SYSFS)/bus/event_source/devices/cs_etm/sinks/ +On newer kernels the available sinks are listed in sysFS under +($SYSFS)/bus/event_source/devices/cs_etm/sinks/:: root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls tmc_etf0 tmc_etr0 tpiu0 On older kernels, this may need to be found from the list of coresight devices, -available under ($SYSFS)/bus/coresight/devices/: +available under ($SYSFS)/bus/coresight/devices/:: root:~# ls /sys/bus/coresight/devices/ etm0 etm1 etm2 etm3 etm4 etm5 funnel0 funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 - root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program As mentioned above in section "Device Naming scheme", the names of the devices could @@ -395,14 +407,14 @@ to use for the trace session. More information on the above and other example on how to use Coresight with the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub -repository [3]. +repository [#third]_. 2.1) AutoFDO analysis using the perf tools: perf can be used to record and analyze trace of programs. Execution can be recorded using 'perf record' with the cs_etm event, -specifying the name of the sink to record to, e.g: +specifying the name of the sink to record to, e.g:: perf record -e cs_etm/@tmc_etr0/u --per-thread @@ -421,12 +433,14 @@ Generating coverage files for Feedback Directed Optimization: AutoFDO 'perf inject' accepts the --itrace option in which case tracing data is removed and replaced with the synthesized events. e.g. +:: perf inject --itrace --strip -i perf.data -o perf.data.new Below is an example of using ARM ETM for autoFDO. It requires autofdo (https://github.com/google/autofdo) and gcc version 5. The bubble sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial). +:: $ gcc-5 -O3 sort.c -o sort $ taskset -c 2 ./sort @@ -455,28 +469,30 @@ difference is that clients are driving the trace capture rather than the program flow through the code. As with any other CoreSight component, specifics about the STM tracer can be -found in sysfs with more information on each entry being found in [1]: +found in sysfs with more information on each entry being found in [#first]_:: -root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 -enable_source hwevent_select port_enable subsystem uevent -hwevent_enable mgmt port_select traceid -root@genericarmv8:~# + root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 + enable_source hwevent_select port_enable subsystem uevent + hwevent_enable mgmt port_select traceid + root@genericarmv8:~# Like any other source a sink needs to be identified and the STM enabled before -being used: +being used:: -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source From there user space applications can request and use channels using the devfs -interface provided for that purpose by the generic STM API: +interface provided for that purpose by the generic STM API:: + + root@genericarmv8:~# ls -l /dev/stm0 + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 + root@genericarmv8:~# + +Details on how to use the generic STM API can be found here [#second]_. -root@genericarmv8:~# ls -l /dev/stm0 -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 -root@genericarmv8:~# +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm -Details on how to use the generic STM API can be found here [2]. +.. [#second] Documentation/trace/stm.rst -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm -[2]. Documentation/trace/stm.rst -[3]. https://github.com/Linaro/perf-opencsd +.. [#third] https://github.com/Linaro/perf-opencsd diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index f60079259669..e3060eedb22d 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -125,7 +125,8 @@ of ftrace. Here is a list of some of the key files: This file holds the output of the trace in a human readable format (described below). Note, tracing is temporarily - disabled while this file is being read (opened). + disabled when the file is open for reading. Once all readers + are closed, tracing is re-enabled. trace_pipe: @@ -139,8 +140,9 @@ of ftrace. Here is a list of some of the key files: will not be read again with a sequential read. The "trace" file is static, and if the tracer is not adding more data, it will display the same - information every time it is read. This file will not - disable tracing while being read. + information every time it is read. Unlike the + "trace" file, opening this file for reading will not + temporarily disable tracing. trace_options: @@ -3153,7 +3155,10 @@ different. The trace is live. Note, reading the trace_pipe file will block until more input is -added. +added. This is contrary to the trace file. If any process opened +the trace file for reading, it will actually disable tracing and +prevent new entries from being added. The trace_pipe file does +not have this limitation. trace entries ------------- diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 6b4107cf4b98..b7891cb1ab4d 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -23,3 +23,5 @@ Linux Tracing Technologies intel_th stm sys-t + coresight + coresight-cpu-debug diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index d0874327f301..94a6499742ac 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -26,16 +26,15 @@ Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi usando, il comando indicato dovrebbe dirvelo. Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta, -non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete un -modem ISDN, per esempio, probabilmente non dovreste preoccuparvi di -isdn4k-utils. +non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una +PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== Programma Versione minima Comando per verificare la versione ====================== ================= ======================================== GNU C 4.6 gcc --version GNU make 3.81 make --version -binutils 2.20 ld -v +binutils 2.21 ld -v flex 2.5.35 flex --version bison 2.0 bison --version util-linux 2.10o fdformat --version @@ -49,7 +48,6 @@ btrfs-progs 0.18 btrfsck pcmciautils 004 pccardctl -V quota-tools 3.09 quota -V PPP 2.4.0 pppd --version -isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version oprofile 0.9 oprofiled --version @@ -81,10 +79,7 @@ Per compilare il kernel vi servirà GNU make 3.81 o successivo. Binutils -------- -Il sistema di compilazione, dalla versione 4.13, per la produzione dei passi -intermedi, si è convertito all'uso di *thin archive* (`ar T`) piuttosto che -all'uso del *linking* incrementale (`ld -r`). Questo richiede binutils 2.20 o -successivo. +Per generare il kernel è necessario avere Binutils 2.21 o superiore. pkg-config ---------- @@ -286,11 +281,6 @@ col seguente comando:: mknod /dev/ppp c 108 0 -Isdn4k-utils ------------- - -Per via della modifica del campo per il numero di telefono, il pacchetto -isdn4k-utils dev'essere ricompilato o (preferibilmente) aggiornato. NFS-utils --------- @@ -456,10 +446,6 @@ PPP - <ftp://ftp.samba.org/pub/ppp/> -Isdn4k-utils ------------- - -- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> NFS-utils --------- diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 44e6077730e8..1db5a1082389 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -129,7 +129,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/translations/it_IT/process/stable-api-nonsense.rst <it_stable_api_nonsense>` diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 7d7ea92c5c5a..cba1f8cb61ed 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -868,7 +868,7 @@ Andrew Morton, "La patch perfetta" (tpp). <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux" - <http://linux.yyz.us/patch-format.html> + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema" <http://www.kroah.com/log/linux/maintainer.html> diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index ad979c3c06a6..dd0c3280ba5a 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -693,7 +693,7 @@ Andrew Morton, "The perfect patch" (tpp). <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". - <http://linux.yyz.us/patch-format.html> + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/2005/03/31/> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index 2621b770a745..73ebdab4ced7 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -139,7 +139,7 @@ linux-api@vger.kernel.org に送ることを勧めます。 "The Perfect Patch" http://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` このファイルはカーネルの中に不変の API を持たないことにした意識的 diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index bcd63731b80a..b3f51b19de7c 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -135,7 +135,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt index 4e373d128d98..5b0164132c71 100644 --- a/Documentation/translations/zh_CN/arm64/booting.txt +++ b/Documentation/translations/zh_CN/arm64/booting.txt @@ -67,8 +67,8 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装 必要性: 强制 设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树 -数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意 -特定属性被映射的 2MB 区域内。 +数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于必须以特定 +属性映射的2M区域内。 注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下 text_offset 字节处算起第一个 512MB 内。 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 5b671178b17b..a8e6ab818983 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -113,7 +113,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst <cn_stable_api_nonsense>` 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 @@ -146,14 +146,18 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 :ref:`Documentation/process/applying-patches.rst <applying_patches>` 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 -内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 -妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内 -核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 -页等不同格式的文档:: +内核还拥有大量从代码自动生成或者从 ReStructuredText(ReST) 标记生成的文档， +比如这个文档，它包含内核内部API的全面介绍以及如何妥善处理加锁的规则。所有 +这些文档都可以通过运行以下命令从内核代码中生成为PDF或HTML文档:: make pdfdocs make htmldocs +ReST格式的文档会生成在 Documentation/output. 目录中。 +它们也可以用下列命令生成 LaTeX 和 ePub 格式文档:: + + make latexdocs + make epubdocs 如何成为内核开发者 ------------------ diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 437c23b367bb..1bb4271ab420 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -652,7 +652,7 @@ Andrew Morton, "The perfect patch" (tpp). <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". - <http://linux.yyz.us/patch-format.html> + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer.html> diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf deleted file mode 100644 index 8b3d43efce90..000000000000 --- a/Documentation/usb/wusb-cbaf +++ /dev/null @@ -1,130 +0,0 @@ -#! /bin/bash -# - -set -e - -progname=$(basename $0) -function help -{ - cat <<EOF -Usage: $progname COMMAND DEVICEs [ARGS] - -Command for manipulating the pairing/authentication credentials of a -Wireless USB device that supports wired-mode Cable-Based-Association. - -Works in conjunction with the wusb-cba.ko driver from http://linuxuwb.org. - - -DEVICE - - sysfs path to the device to authenticate; for example, both this - guys are the same: - - /sys/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4.4/1-4.4:1.1 - /sys/bus/usb/drivers/wusb-cbaf/1-4.4:1.1 - -COMMAND/ARGS are - - start - - Start a WUSB host controller (by setting up a CHID) - - set-chid DEVICE HOST-CHID HOST-BANDGROUP HOST-NAME - - Sets host information in the device; after this you can call the - get-cdid to see how does this device report itself to us. - - get-cdid DEVICE - - Get the device ID associated to the HOST-CHID we sent with - 'set-chid'. We might not know about it. - - set-cc DEVICE - - If we allow the device to connect, set a random new CDID and CK - (connection key). Device saves them for the next time it wants to - connect wireless. We save them for that next time also so we can - authenticate the device (when we see the CDID he uses to id - itself) and the CK to crypto talk to it. - -CHID is always 16 hex bytes in 'XX YY ZZ...' form -BANDGROUP is almost always 0001 - -Examples: - - You can default most arguments to '' to get a sane value: - - $ $progname set-chid '' '' '' "My host name" - - A full sequence: - - $ $progname set-chid '' '' '' "My host name" - $ $progname get-cdid '' - $ $progname set-cc '' - -EOF -} - - -# Defaults -# FIXME: CHID should come from a database :), band group from the host -host_CHID="00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff" -host_band_group="0001" -host_name=$(hostname) - -devs="$(echo /sys/bus/usb/drivers/wusb-cbaf/[0-9]*)" -hdevs="$(for h in /sys/class/uwb_rc/*/wusbhc; do readlink -f $h; done)" - -result=0 -case $1 in - start) - for dev in ${2:-$hdevs} - do - echo $host_CHID > $dev/wusb_chid - echo I: started host $(basename $dev) >&2 - done - ;; - stop) - for dev in ${2:-$hdevs} - do - echo 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 > $dev/wusb_chid - echo I: stopped host $(basename $dev) >&2 - done - ;; - set-chid) - shift - for dev in ${2:-$devs}; do - echo "${4:-$host_name}" > $dev/wusb_host_name - echo "${3:-$host_band_group}" > $dev/wusb_host_band_groups - echo ${2:-$host_CHID} > $dev/wusb_chid - done - ;; - get-cdid) - for dev in ${2:-$devs} - do - cat $dev/wusb_cdid - done - ;; - set-cc) - for dev in ${2:-$devs}; do - shift - CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)" - CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)" - echo "$CDID" > $dev/wusb_cdid - echo "$CK" > $dev/wusb_ck - - echo I: CC set >&2 - echo "CHID: $(cat $dev/wusb_chid)" - echo "CDID:$CDID" - echo "CK: $CK" - done - ;; - help|h|--help|-h) - help - ;; - *) - echo "E: Unknown usage" 1>&2 - help 1>&2 - result=1 -esac -exit $result diff --git a/Documentation/usb/wusb-design-overview.rst b/Documentation/usb/wusb-design-overview.rst deleted file mode 100644 index dc5e21609bb5..000000000000 --- a/Documentation/usb/wusb-design-overview.rst +++ /dev/null @@ -1,457 +0,0 @@ -================================ -Linux UWB + Wireless USB + WiNET -================================ - - Copyright (C) 2005-2006 Intel Corporation - - Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License version - 2 as published by the Free Software Foundation. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA. - - -Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for -updated content. - - * Design-overview.txt-1.8 - -This code implements a Ultra Wide Band stack for Linux, as well as -drivers for the USB based UWB radio controllers defined in the -Wireless USB 1.0 specification (including Wireless USB host controller -and an Intel WiNET controller). - -.. Contents - 1. Introduction - 1. HWA: Host Wire adapters, your Wireless USB dongle - - 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired - devices - 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host - adapter - 2. The UWB stack - 1. Devices and hosts: the basic structure - - 2. Host Controller life cycle - - 3. On the air: beacons and enumerating the radio neighborhood - - 4. Device lists - 5. Bandwidth allocation - - 3. Wireless USB Host Controller drivers - - 4. Glossary - - -Introduction -============ - -UWB is a wide-band communication protocol that is to serve also as the -low-level protocol for others (much like TCP sits on IP). Currently -these others are Wireless USB and TCP/IP, but seems Bluetooth and -Firewire/1394 are coming along. - -UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of -~-41dB (or 0.074 uW/MHz--geography specific data is still being -negotiated w/ regulators, so watch for changes). That band is divided in -a bunch of ~1.5 GHz wide channels (or band groups) composed of three -subbands/subchannels (528 MHz each). Each channel is independent of each -other, so you could consider them different "busses". Initially this -driver considers them all a single one. - -Radio time is divided in 65536 us long /superframes/, each one divided -in 256 256us long /MASs/ (Media Allocation Slots), which are the basic -time/media allocation units for transferring data. At the beginning of -each superframe there is a Beacon Period (BP), where every device -transmit its beacon on a single MAS. The length of the BP depends on how -many devices are present and the length of their beacons. - -Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 -bit address) and send periodic beacons to advertise themselves and pass -info on what they are and do. They advertise their capabilities and a -bunch of other stuff. - -The different logical parts of this driver are: - - * - - *UWB*: the Ultra-Wide-Band stack -- manages the radio and - associated spectrum to allow for devices sharing it. Allows to - control bandwidth assignment, beaconing, scanning, etc - - * - - *WUSB*: the layer that sits on top of UWB to provide Wireless USB. - The Wireless USB spec defines means to control a UWB radio and to - do the actual WUSB. - - -HWA: Host Wire adapters, your Wireless USB dongle -------------------------------------------------- - -WUSB also defines a device called a Host Wire Adaptor (HWA), which in -mere terms is a USB dongle that enables your PC to have UWB and Wireless -USB. The Wireless USB Host Controller in a HWA looks to the host like a -[Wireless] USB controller connected via USB (!) - -The HWA itself is broken in two or three main interfaces: - - * - - *RC*: Radio control -- this implements an interface to the - Ultra-Wide-Band radio controller. The driver for this implements a - USB-based UWB Radio Controller to the UWB stack. - - * - - *HC*: the wireless USB host controller. It looks like a USB host - whose root port is the radio and the WUSB devices connect to it. - To the system it looks like a separate USB host. The driver (will) - implement a USB host controller (similar to UHCI, OHCI or EHCI) - for which the root hub is the radio...To reiterate: it is a USB - controller that is connected via USB instead of PCI. - - * - - *WINET*: some HW provide a WiNET interface (IP over UWB). This - package provides a driver for it (it looks like a network - interface, winetX). The driver detects when there is a link up for - their type and kick into gear. - - -DWA: Device Wired Adaptor, a Wireless USB hub for wired devices ---------------------------------------------------------------- - -These are the complement to HWAs. They are a USB host for connecting -wired devices, but it is connected to your PC connected via Wireless -USB. To the system it looks like yet another USB host. To the untrained -eye, it looks like a hub that connects upstream wirelessly. - -We still offer no support for this; however, it should share a lot of -code with the HWA-RC driver; there is a bunch of factorization work that -has been done to support that in upcoming releases. - - -WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter -------------------------------------------------------------------- - -This is your usual PCI device that implements WHCI. Similar in concept -to EHCI, it allows your wireless USB devices (including DWAs) to connect -to your host via a PCI interface. As in the case of the HWA, it has a -Radio Control interface and the WUSB Host Controller interface per se. - -There is still no driver support for this, but will be in upcoming -releases. - - -The UWB stack -============= - -The main mission of the UWB stack is to keep a tally of which devices -are in radio proximity to allow drivers to connect to them. As well, it -provides an API for controlling the local radio controllers (RCs from -now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. - - -Devices and hosts: the basic structure --------------------------------------- - -The main building block here is the UWB device (struct uwb_dev). For -each device that pops up in radio presence (ie: the UWB host receives a -beacon from it) you get a struct uwb_dev that will show up in -/sys/bus/uwb/devices. - -For each RC that is detected, a new struct uwb_rc and struct uwb_dev are -created. An entry is also created in /sys/class/uwb_rc for each RC. - -Each RC driver is implemented by a separate driver that plugs into the -interface that the UWB stack provides through a struct uwb_rc_ops. The -spec creators have been nice enough to make the message format the same -for HWA and WHCI RCs, so the driver is really a very thin transport that -moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] -and sends the replies and notifications back to the API -[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that -is chartered, among other things, to keep the tab of how the UWB radio -neighborhood looks, creating and destroying devices as they show up or -disappear. - -Command execution is very simple: a command block is sent and a event -block or reply is expected back. For sending/receiving command/events, a -handle called /neh/ (Notification/Event Handle) is opened with -/uwb_rc_neh_open()/. - -The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for -the USB connected HWA. Eventually, drivers/whci-rc.c will do the same -for the PCI connected WHCI controller. - - -Host Controller life cycle --------------------------- - -So let's say we connect a dongle to the system: it is detected and -firmware uploaded if needed [for Intel's i1480 -/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. -Now we have a real HWA device connected and -/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the -Wire-Adaptor environment and then suck it into the UWB stack's vision of -the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. - - * - - [*] The stack should put a new RC to scan for devices - [/uwb_rc_scan()/] so it finds what's available around and tries to - connect to them, but this is policy stuff and should be driven - from user space. As of now, the operator is expected to do it - manually; see the release notes for documentation on the procedure. - -When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ -takes time of tearing everything down safely (or not...). - - -On the air: beacons and enumerating the radio neighborhood ----------------------------------------------------------- - -So assuming we have devices and we have agreed for a channel to connect -on (let's say 9), we put the new RC to beacon: - - * - - $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon - -Now it is visible. If there were other devices in the same radio channel -and beacon group (that's what the zero is for), the dongle's radio -control interface will send beacon notifications on its -notification/event endpoint (NEEP). The beacon notifications are part of -the event stream that is funneled into the API with -/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB -daemon through a notification list. - -UWBD wakes up and scans the event list; finds a beacon and adds it to -the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from -the same device, he considers it to be 'onair' and creates a new device -[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons -are received in some time, the device is considered gone and wiped out -[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge -the beacon cache of dead devices]. - - -Device lists ------------- - -All UWB devices are kept in the list of the struct bus_type uwb_bus_type. - - -Bandwidth allocation --------------------- - -The UWB stack maintains a local copy of DRP availability through -processing of incoming *DRP Availability Change* notifications. This -local copy is currently used to present the current bandwidth -availability to the user through the sysfs file -/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth -availability information will be used by the bandwidth reservation -routines. - -The bandwidth reservation routines are in progress and are thus not -present in the current release. When completed they will enable a user -to initiate DRP reservation requests through interaction with sysfs. DRP -reservation requests from remote UWB devices will also be handled. The -bandwidth management done by the UWB stack will include callbacks to the -higher layers will enable the higher layers to use the reservations upon -completion. [Note: The bandwidth reservation work is in progress and -subject to change.] - - -Wireless USB Host Controller drivers -==================================== - -*WARNING* This section needs a lot of work! - -As explained above, there are three different types of HCs in the WUSB -world: HWA-HC, DWA-HC and WHCI-HC. - -HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB -connected controllers), and their transfer management system is almost -identical. So is their notification delivery system. - -HWA-HC and WHCI-HC share that they are both WUSB host controllers, so -they have to deal with WUSB device life cycle and maintenance, wireless -root-hub - -HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has -three endpoints (Notifications, Data Transfer In and Data Transfer -Out--known as NEP, DTI and DTO in the code). - -We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster -ID and tell the HC to use all that. Then we start it. This means the HC -starts sending MMCs. - - * - - The MMCs are blocks of data defined somewhere in the WUSB1.0 spec - that define a stream in the UWB channel time allocated for sending - WUSB IEs (host to device commands/notifications) and Device - Notifications (device initiated to host). Each host defines a - unique Wireless USB cluster through MMCs. Devices can connect to a - single cluster at the time. The IEs are Information Elements, and - among them are the bandwidth allocations that tell each device - when can they transmit or receive. - -Now it all depends on external stimuli. - -New device connection ---------------------- - -A new device pops up, it scans the radio looking for MMCs that give out -the existence of Wireless USB channels. Once one (or more) are found, -selects which one to connect to. Sends a /DN_Connect/ (device -notification connect) during the DNTS (Device Notification Time -Slot--announced in the MMCs - -HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery -into /devconnect/). This process starts the authentication process for -the device. First we allocate a /fake port/ and assign an -unauthenticated address (128 to 255--what we really do is -0x80 | fake_port_idx). We fiddle with the fake port status and /hub_wq/ -sees a new connection, so he moves on to enable the fake port with a reset. - -So now we are in the reset path -- we know we have a non-yet enumerated -device with an unauthorized address; we ask user space to authenticate -(FIXME: not yet done, similar to bluetooth pairing), then we do the key -exchange (FIXME: not yet done) and issue a /set address 0/ to bring the -device to the default state. Device is authenticated. - -From here, the USB stack takes control through the usb_hcd ops. hub_wq -has seen the port status changes, as we have been toggling them. It will -start enumerating and doing transfers through usb_hcd->urb_enqueue() to -read descriptors and move our data. - -Device life cycle and keep alives ---------------------------------- - -Every time there is a successful transfer to/from a device, we update a -per-device activity timestamp. If not, every now and then we check and -if the activity timestamp gets old, we ping the device by sending it a -Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this -arrives to us as a notification through -devconnect.c:wusb_handle_dn_alive(). If a device times out, we -disconnect it from the system (cleaning up internal information and -toggling the bits in the fake hub port, which kicks hub_wq into removing -the rest of the stuff). - -This is done through devconnect:__wusb_check_devs(), which will scan the -device list looking for whom needs refreshing. - -If the device wants to disconnect, it will either die (ugly) or send a -/DN_Disconnect/ that will prompt a disconnection from the system. - -Sending and receiving data --------------------------- - -Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is -/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and -DWAs. - -Each HC has a number of rpipes and buffers that can be assigned to them; -when doing a data transfer (xfer), first the rpipe has to be aimed and -prepared (buffers assigned), then we can start queueing requests for -data in or out. - -Data buffers have to be segmented out before sending--so we send first a -header (segment request) and then if there is any data, a data buffer -immediately after to the DTI interface (yep, even the request). If our -buffer is bigger than the max segment size, then we just do multiple -requests. - -[This sucks, because doing USB scatter gatter in Linux is resource -intensive, if any...not that the current approach is not. It just has to -be cleaned up a lot :)]. - -If reading, we don't send data buffers, just the segment headers saying -we want to read segments. - -When the xfer is executed, we receive a notification that says data is -ready in the DTI endpoint (handled through -xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a -descriptor that gives us the status of the transfer, its identification -(given when we issued it) and the segment number. If it was a data read, -we issue another URB to read into the destination buffer the chunk of -data coming out of the remote endpoint. Done, wait for the next guy. The -callbacks for the URBs issued from here are the ones that will declare -the xfer complete at some point and call its callback. - -Seems simple, but the implementation is not trivial. - - * - - *WARNING* Old!! - -The main xfer descriptor, wa_xfer (equivalent to a URB) contains an -array of segments, tallys on segments and buffers and callback -information. Buried in there is a lot of URBs for executing the segments -and buffer transfers. - -For OUT xfers, there is an array of segments, one URB for each, another -one of buffer URB. When submitting, we submit URBs for segment request -1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer -result data; when all the segments are complete, we call the callback to -finalize the transfer. - -For IN xfers, we only issue URBs for the segments we want to read and -then wait for the xfer result data. - -URB mapping into xfers -^^^^^^^^^^^^^^^^^^^^^^ - -This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an -rpipe to the endpoint where we have to transmit, create a transfer -context (wa_xfer) and submit it. When the xfer is done, our callback is -called and we assign the status bits and release the xfer resources. - -In dequeue() we are basically cancelling/aborting the transfer. We issue -a xfer abort request to the HC, cancel all the URBs we had submitted -and not yet done and when all that is done, the xfer callback will be -called--this will call the URB callback. - - -Glossary -======== - -*DWA* -- Device Wire Adapter - -USB host, wired for downstream devices, upstream connects wirelessly -with Wireless USB. - -*EVENT* -- Response to a command on the NEEP - -*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB - -*NEH* -- Notification/Event Handle - -Handle/file descriptor for receiving notifications or events. The WA -code requires you to get one of this to listen for notifications or -events on the NEEP. - -*NEEP* -- Notification/Event EndPoint - -Stuff related to the management of the first endpoint of a HWA USB -dongle that is used to deliver an stream of events and notifications to -the host. - -*NOTIFICATION* -- Message coming in the NEEP as response to something. - -*RC* -- Radio Control - -Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by -InakyPerezGonzalez) diff --git a/Documentation/virt/kvm/api.txt b/Documentation/virt/kvm/api.txt index 2d067767b617..136f1eef3712 100644 --- a/Documentation/virt/kvm/api.txt +++ b/Documentation/virt/kvm/api.txt @@ -586,7 +586,7 @@ Capability: basic Architectures: x86 Type: vcpu ioctl Parameters: struct kvm_msrs (in) -Returns: 0 on success, -1 on error +Returns: number of msrs successfully set (see below), -1 on error Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the data structures. @@ -595,6 +595,11 @@ Application code should set the 'nmsrs' member (which indicates the size of the entries array), and the 'index' and 'data' members of each array entry. +It tries to set the MSRs in array entries[] one by one. If setting an MSR +fails, e.g., due to setting reserved bits, the MSR isn't supported/emulated +by KVM, etc..., it stops processing the MSR list and returns the number of +MSRs that have been set successfully. + 4.20 KVM_SET_CPUID @@ -753,8 +758,8 @@ in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to use PPIs designated for specific cpus. The irq field is interpreted like this: - bits: | 31 ... 24 | 23 ... 16 | 15 ... 0 | - field: | irq_type | vcpu_index | irq_id | + bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 | + field: | vcpu2_index | irq_type | vcpu_index | irq_id | The irq_type field has the following values: - irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ @@ -766,6 +771,14 @@ The irq_type field has the following values: In both cases, level is used to assert/deassert the line. +When KVM_CAP_ARM_IRQ_LINE_LAYOUT_2 is supported, the target vcpu is +identified as (256 * vcpu2_index + vcpu_index). Otherwise, vcpu2_index +must be zero. + +Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditions +injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always +be used for a userspace interrupt controller. + struct kvm_irq_level { union { __u32 irq; /* GSI */ @@ -3079,12 +3092,14 @@ This exception is also raised directly at the corresponding VCPU if the flag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the "flags" field. The start address of the memory region has to be specified in the "gaddr" -field, and the length of the region in the "size" field. "buf" is the buffer -supplied by the userspace application where the read data should be written -to for KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written -is stored for a KVM_S390_MEMOP_LOGICAL_WRITE. "buf" is unused and can be NULL -when KVM_S390_MEMOP_F_CHECK_ONLY is specified. "ar" designates the access -register number to be used. +field, and the length of the region in the "size" field (which must not +be 0). The maximum value for "size" can be obtained by checking the +KVM_CAP_S390_MEM_OP capability. "buf" is the buffer supplied by the +userspace application where the read data should be written to for +KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written is +stored for a KVM_S390_MEMOP_LOGICAL_WRITE. When KVM_S390_MEMOP_F_CHECK_ONLY +is specified, "buf" is unused and can be NULL. "ar" designates the access +register number to be used; the valid range is 0..15. The "reserved" field is meant for future extensions. It is not used by KVM with the currently defined set of flags. diff --git a/Documentation/virt/kvm/mmu.txt b/Documentation/virt/kvm/mmu.txt index 1b9880dfba0a..dadb29e8738f 100644 --- a/Documentation/virt/kvm/mmu.txt +++ b/Documentation/virt/kvm/mmu.txt @@ -294,7 +294,7 @@ Handling a page fault is performed as follows: - walk shadow page table - check for valid generation number in the spte (see "Fast invalidation of MMIO sptes" below) - - cache the information to vcpu->arch.mmio_gva, vcpu->arch.access and + - cache the information to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn, and call the emulator - If both P bit and R/W bit of error code are set, this could possibly be handled as a "fast page fault" (fixed without taking the MMU lock). See @@ -304,7 +304,7 @@ Handling a page fault is performed as follows: - if permissions are insufficient, reflect the fault back to the guest - determine the host page - if this is an mmio request, there is no host page; cache the info to - vcpu->arch.mmio_gva, vcpu->arch.access and vcpu->arch.mmio_gfn + vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn - walk the shadow page table to find the spte for the translation, instantiating missing intermediate page tables as necessary - If this is an mmio request, cache the mmio info to the spte and set some diff --git a/Documentation/virtual/guest-halt-polling.txt b/Documentation/virtual/guest-halt-polling.txt new file mode 100644 index 000000000000..b3a2a294532d --- /dev/null +++ b/Documentation/virtual/guest-halt-polling.txt @@ -0,0 +1,78 @@ +Guest halt polling +================== + +The cpuidle_haltpoll driver, with the haltpoll governor, allows +the guest vcpus to poll for a specified amount of time before +halting. +This provides the following benefits to host side polling: + + 1) The POLL flag is set while polling is performed, which allows + a remote vCPU to avoid sending an IPI (and the associated + cost of handling the IPI) when performing a wakeup. + + 2) The VM-exit cost can be avoided. + +The downside of guest side polling is that polling is performed +even with other runnable tasks in the host. + +The basic logic as follows: A global value, guest_halt_poll_ns, +is configured by the user, indicating the maximum amount of +time polling is allowed. This value is fixed. + +Each vcpu has an adjustable guest_halt_poll_ns +("per-cpu guest_halt_poll_ns"), which is adjusted by the algorithm +in response to events (explained below). + +Module Parameters +================= + +The haltpoll governor has 5 tunable module parameters: + +1) guest_halt_poll_ns: +Maximum amount of time, in nanoseconds, that polling is +performed before halting. + +Default: 200000 + +2) guest_halt_poll_shrink: +Division factor used to shrink per-cpu guest_halt_poll_ns when +wakeup event occurs after the global guest_halt_poll_ns. + +Default: 2 + +3) guest_halt_poll_grow: +Multiplication factor used to grow per-cpu guest_halt_poll_ns +when event occurs after per-cpu guest_halt_poll_ns +but before global guest_halt_poll_ns. + +Default: 2 + +4) guest_halt_poll_grow_start: +The per-cpu guest_halt_poll_ns eventually reaches zero +in case of an idle system. This value sets the initial +per-cpu guest_halt_poll_ns when growing. This can +be increased from 10000, to avoid misses during the initial +growth stage: + +10k, 20k, 40k, ... (example assumes guest_halt_poll_grow=2). + +Default: 50000 + +5) guest_halt_poll_allow_shrink: + +Bool parameter which allows shrinking. Set to N +to avoid it (per-cpu guest_halt_poll_ns will remain +high once achieves global guest_halt_poll_ns value). + +Default: Y + +The module parameters can be set from the debugfs files in: + + /sys/module/haltpoll/parameters/ + +Further Notes +============= + +- Care should be taken when setting the guest_halt_poll_ns parameter as a +large value has the potential to drive the cpu usage to 100% on a machine which +would be almost entirely idle otherwise. diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index 7d90964abbb0..710ce1c701bf 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -237,7 +237,7 @@ The usage pattern is:: ret = hmm_range_snapshot(&range); if (ret) { up_read(&mm->mmap_sem); - if (ret == -EAGAIN) { + if (ret == -EBUSY) { /* * No need to check hmm_range_wait_until_valid() return value * on retry we will get proper error with hmm_range_snapshot() diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst new file mode 100644 index 000000000000..57cba81865e2 --- /dev/null +++ b/Documentation/w1/index.rst @@ -0,0 +1,21 @@ +. SPDX-License-Identifier: GPL-2.0 + +================ +1-Wire Subsystem +================ + +.. toctree:: + :maxdepth: 1 + + + w1-generic.rst + w1-netlink.rst + masters/index + slaves/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst index 56f8edace6ac..17ebe8f660cd 100644 --- a/Documentation/w1/masters/ds2482 +++ b/Documentation/w1/masters/ds2482.rst @@ -1,13 +1,19 @@ +==================== Kernel driver ds2482 ==================== Supported chips: + * Maxim DS2482-100, Maxim DS2482-800 + Prefix: 'ds2482' + Addresses scanned: None + Datasheets: - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf + + - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf + - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf Author: Ben Gardner <bgardner@wabtec.com> @@ -23,9 +29,11 @@ General Remarks --------------- Valid addresses are 0x18, 0x19, 0x1a, and 0x1b. + However, the device cannot be detected without writing to the i2c bus, so no detection is done. You should instantiate the device explicitly. -$ modprobe ds2482 -$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device +:: + $ modprobe ds2482 + $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst index 3e091151dd80..7e5b50f9c0f5 100644 --- a/Documentation/w1/masters/ds2490 +++ b/Documentation/w1/masters/ds2490.rst @@ -1,7 +1,9 @@ +==================== Kernel driver ds2490 ==================== Supported chips: + * Maxim DS2490 based Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru> @@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490 low-level operational chip. Notes and limitations. + - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA. - The 5V strong pullup is supported with a minimum of 5.9mA and a maximum of 30.4 mA. (From DS2490.pdf) @@ -65,4 +68,5 @@ Notes and limitations. reattaching would clear the problem. usbmon output in the guest and host did not explain the problem. My guess is a bug in either qemu or the host OS and more likely the host OS. --- 03-06-2008 David Fries <David@Fries.net> + +03-06-2008 David Fries <David@Fries.net> diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst new file mode 100644 index 000000000000..4442a98850ad --- /dev/null +++ b/Documentation/w1/masters/index.rst @@ -0,0 +1,14 @@ +. SPDX-License-Identifier: GPL-2.0 + +===================== +1-wire Master Drivers +===================== + +.. toctree:: + :maxdepth: 1 + + ds2482 + ds2490 + mxc-w1 + omap-hdq + w1-gpio diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1 deleted file mode 100644 index 38be1ad65532..000000000000 --- a/Documentation/w1/masters/mxc-w1 +++ /dev/null @@ -1,12 +0,0 @@ -Kernel driver mxc_w1 -==================== - -Supported chips: - * Freescale MX27, MX31 and probably other i.MX SoCs - Datasheets: - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1 - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE= - Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation - -Author: Originally based on Freescale code, prepared for mainline by - Sascha Hauer <s.hauer@pengutronix.de> diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst new file mode 100644 index 000000000000..334f9893103f --- /dev/null +++ b/Documentation/w1/masters/mxc-w1.rst @@ -0,0 +1,17 @@ +==================== +Kernel driver mxc_w1 +==================== + +Supported chips: + + * Freescale MX27, MX31 and probably other i.MX SoCs + + Datasheets: + + - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1 + - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation + +Author: + + Originally based on Freescale code, prepared for mainline by + Sascha Hauer <s.hauer@pengutronix.de> diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst index 234522709a5f..345298a59e50 100644 --- a/Documentation/w1/masters/omap-hdq +++ b/Documentation/w1/masters/omap-hdq.rst @@ -1,9 +1,10 @@ -Kernel driver for omap HDQ/1-wire module. +======================================== +Kernel driver for omap HDQ/1-wire module ======================================== Supported chips: ================ - HDQ/1-wire controller on the TI OMAP 2430/3430 platforms. +HDQ/1-wire controller on the TI OMAP 2430/3430 platforms. A useful link about HDQ basics: =============================== @@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1. Please note to load both the modules with a different ID if required, but note that the ID used should be same for both master and slave driver loading. -e.g: -insmod omap_hdq.ko W1_ID=2 -inamod w1_bq27000.ko F_ID=2 +e.g:: + + insmod omap_hdq.ko W1_ID=2 + inamod w1_bq27000.ko F_ID=2 The driver also supports 1-wire mode. In this mode, there is no need to pass slave ID as parameter. The driver will auto-detect slaves connected diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst index 623961d9e83f..18fdb7366372 100644 --- a/Documentation/w1/masters/w1-gpio +++ b/Documentation/w1/masters/w1-gpio.rst @@ -1,3 +1,4 @@ +===================== Kernel driver w1-gpio ===================== @@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt Example (mach-at91) ------------------- -#include <linux/gpio/machine.h> -#include <linux/w1-gpio.h> +:: + + #include <linux/gpio/machine.h> + #include <linux/w1-gpio.h> -static struct gpiod_lookup_table foo_w1_gpiod_table = { + static struct gpiod_lookup_table foo_w1_gpiod_table = { .dev_id = "w1-gpio", .table = { GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0, GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN), }, -}; + }; -static struct w1_gpio_platform_data foo_w1_gpio_pdata = { + static struct w1_gpio_platform_data foo_w1_gpio_pdata = { .ext_pullup_enable_pin = -EINVAL, -}; + }; -static struct platform_device foo_w1_device = { + static struct platform_device foo_w1_device = { .name = "w1-gpio", .id = -1, .dev.platform_data = &foo_w1_gpio_pdata, -}; + }; -... + ... at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); gpiod_add_lookup_table(&foo_w1_gpiod_table); diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst new file mode 100644 index 000000000000..d0697b202f09 --- /dev/null +++ b/Documentation/w1/slaves/index.rst @@ -0,0 +1,16 @@ +. SPDX-License-Identifier: GPL-2.0 + +==================== +1-wire Slave Drivers +==================== + +.. toctree:: + :maxdepth: 1 + + w1_ds2406 + w1_ds2413 + w1_ds2423 + w1_ds2438 + w1_ds28e04 + w1_ds28e17 + w1_therm diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst index 8137fe6f6c3d..d3e68266084f 100644 --- a/Documentation/w1/slaves/w1_ds2406 +++ b/Documentation/w1/slaves/w1_ds2406.rst @@ -1,7 +1,9 @@ +======================= w1_ds2406 kernel driver ======================= Supported chips: + * Maxim DS2406 (and other family 0x12) addressable switches Author: Scott Alfter <scott@alfter.us> @@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us> Description ----------- -The w1_ds2406 driver allows connected devices to be switched on and off. +The w1_ds2406 driver allows connected devices to be switched on and off. These chips also provide 128 bytes of OTP EPROM, but reading/writing it is not supported. In TSOC-6 form, the DS2406 provides two switch outputs and can be provided with power on a dedicated input. In TO-92 form, it provides diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst index 936263a8ccb4..c15bb5b919b7 100644 --- a/Documentation/w1/slaves/w1_ds2413 +++ b/Documentation/w1/slaves/w1_ds2413.rst @@ -1,11 +1,16 @@ +======================= Kernel driver w1_ds2413 ======================= Supported chips: + * Maxim DS2413 1-Wire Dual Channel Addressable Switch supported family codes: + + ================ ==== W1_FAMILY_DS2413 0x3A + ================ ==== Author: Mariusz Bialonczyk <manio@skyboo.net> @@ -20,11 +25,13 @@ Reading state The "state" file provides one-byte value which is in the same format as for the chip PIO_ACCESS_READ command (refer the datasheet for details): +======== ============================================================= Bit 0: PIOA Pin State Bit 1: PIOA Output Latch State Bit 2: PIOB Pin State Bit 3: PIOB Output Latch State Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module) +======== ============================================================= This file is readonly. @@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file. It is writable, you can write one-byte value to this sysfs file. Similarly the byte format is the same as for the PIO_ACCESS_WRITE command: +======== ====================================== Bit 0: PIOA Bit 1: PIOB Bit 2-7: No matter (driver will set it to "1"s) +======== ====================================== The chip has some kind of basic protection against transmission errors. diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423 deleted file mode 100644 index 3f98b505a0ee..000000000000 --- a/Documentation/w1/slaves/w1_ds2423 +++ /dev/null @@ -1,47 +0,0 @@ -Kernel driver w1_ds2423 -======================= - -Supported chips: - * Maxim DS2423 based counter devices. - -supported family codes: - W1_THERM_DS2423 0x1D - -Author: Mika Laitio <lamikr@pilppa.org> - -Description ------------ - -Support is provided through the sysfs w1_slave file. Each opening and -read sequence of w1_slave file initiates the read of counters and ram -available in DS2423 pages 12 - 15. - -Result of each page is provided as an ASCII output where each counter -value and associated ram buffer is outpputed to own line. - -Each lines will contain the values of 42 bytes read from the counter and -memory page along the crc=YES or NO for indicating whether the read operation -was successful and CRC matched. -If the operation was successful, there is also in the end of each line -a counter value expressed as an integer after c= - -Meaning of 42 bytes represented is following: - - 1 byte from ram page - - 4 bytes for the counter value - - 4 zero bytes - - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes - - 31 remaining bytes from the ram page - - crc=YES/NO indicating whether read was ok and crc matched - - c=<int> current counter value - -example from the successful read: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 -00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 - -example from the read with crc errors: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst new file mode 100644 index 000000000000..755d659ad997 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2423.rst @@ -0,0 +1,54 @@ +Kernel driver w1_ds2423 +======================= + +Supported chips: + + * Maxim DS2423 based counter devices. + +supported family codes: + + =============== ==== + W1_THERM_DS2423 0x1D + =============== ==== + +Author: Mika Laitio <lamikr@pilppa.org> + +Description +----------- + +Support is provided through the sysfs w1_slave file. Each opening and +read sequence of w1_slave file initiates the read of counters and ram +available in DS2423 pages 12 - 15. + +Result of each page is provided as an ASCII output where each counter +value and associated ram buffer is outpputed to own line. + +Each lines will contain the values of 42 bytes read from the counter and +memory page along the crc=YES or NO for indicating whether the read operation +was successful and CRC matched. +If the operation was successful, there is also in the end of each line +a counter value expressed as an integer after c= + +Meaning of 42 bytes represented is following: + + - 1 byte from ram page + - 4 bytes for the counter value + - 4 zero bytes + - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes + - 31 remaining bytes from the ram page + - crc=YES/NO indicating whether read was ok and crc matched + - c=<int> current counter value + +example from the successful read:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 + 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 + +example from the read with crc errors:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst index e64f65a09387..a29309a3f8e5 100644 --- a/Documentation/w1/slaves/w1_ds2438 +++ b/Documentation/w1/slaves/w1_ds2438.rst @@ -2,10 +2,13 @@ Kernel driver w1_ds2438 ======================= Supported chips: + * Maxim DS2438 Smart Battery Monitor supported family codes: + ================ ==== W1_FAMILY_DS2438 0x26 + ================ ==== Author: Mariusz Bialonczyk <manio@skyboo.net> @@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion) command of the chip. Depending on a sysfs filename a different input for the A/D will be selected: -vad: general purpose A/D input (VAD) -vdd: battery input (VDD) + +vad: + general purpose A/D input (VAD) +vdd: + battery input (VDD) After the voltage conversion the value is returned as decimal ASCII. Note: To get a volts the value has to be divided by 100. diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst index 7819b65cfa48..b12b118890d3 100644 --- a/Documentation/w1/slaves/w1_ds28e04 +++ b/Documentation/w1/slaves/w1_ds28e04.rst @@ -1,11 +1,16 @@ +======================== Kernel driver w1_ds28e04 ======================== Supported chips: + * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO supported family codes: + + ================= ==== W1_FAMILY_DS28E04 0x1C + ================= ==== Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de> diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst index 7fcfad5b4a37..e2d9f96d8f2c 100644 --- a/Documentation/w1/slaves/w1_ds28e17 +++ b/Documentation/w1/slaves/w1_ds28e17.rst @@ -1,11 +1,16 @@ +======================== Kernel driver w1_ds28e17 ======================== Supported chips: + * Maxim DS28E17 1-Wire-to-I2C Master Bridge supported family codes: + + ================= ==== W1_FAMILY_DS28E17 0x19 + ================= ==== Author: Jan Kandziora <jjj@gmx.de> @@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were connected to a "native" I2C bus master. -An udev rule like the following -------------------------------------------------------------------------------- -SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ - SYMLINK+="i2c-$attr{name}" -------------------------------------------------------------------------------- +An udev rule like the following:: + + SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ + SYMLINK+="i2c-$attr{name}" + may be used to create stable /dev/i2c- entries based on the unique id of the DS28E17 chip. @@ -65,4 +70,3 @@ structure is created. See https://github.com/ianka/w1_ds28e17 for even more information. - diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst index d1f93af36f38..90531c340a07 100644 --- a/Documentation/w1/slaves/w1_therm +++ b/Documentation/w1/slaves/w1_therm.rst @@ -1,7 +1,9 @@ +====================== Kernel driver w1_therm -==================== +====================== Supported chips: + * Maxim ds18*20 based temperature sensors. * Maxim ds1825 based temperature sensors. @@ -13,12 +15,16 @@ Description w1_therm provides basic temperature conversion for ds18*20 devices, and the ds28ea00 device. -supported family codes: + +Supported family codes: + +==================== ==== W1_THERM_DS18S20 0x10 W1_THERM_DS1822 0x22 W1_THERM_DS18B20 0x28 W1_THERM_DS1825 0x3B W1_THERM_DS28EA00 0x42 +==================== ==== Support is provided through the sysfs w1_slave file. Each open and read sequence will initiate a temperature conversion then provide two @@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup. In case the detection of parasite devices using this command fails (seems to be the case with some DS18S20) the strong pullup can be force-enabled. + If the strong pullup is enabled, the master's strong pullup will be driven when the conversion is taking place, provided the master driver does support the strong pullup (or it falls back to a pullup diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst index c51b1ab012d0..da4e8b4e9b01 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1-generic.rst @@ -1,5 +1,7 @@ -The 1-wire (w1) subsystem ------------------------------------------------------------------- +========================================= +Introduction to the 1-wire (w1) subsystem +========================================= + The 1-wire bus is a simple master-slave bus that communicates via a single signal wire (plus ground, so two wires). @@ -12,14 +14,16 @@ communication with slaves. All w1 slave devices must be connected to a w1 bus master device. Example w1 master devices: - DS9490 usb device - W1-over-GPIO - DS2482 (i2c to w1 bridge) - Emulated devices, such as a RS232 converter, parallel port adapter, etc + + - DS9490 usb device + - W1-over-GPIO + - DS2482 (i2c to w1 bridge) + - Emulated devices, such as a RS232 converter, parallel port adapter, etc What does the w1 subsystem do? ------------------------------------------------------------------- +------------------------------ + When a w1 master driver registers with the w1 subsystem, the following occurs: - sysfs entries for that w1 master are created @@ -43,24 +47,28 @@ be read, since no device was selected. W1 device families ------------------------------------------------------------------- +------------------ + Slave devices are handled by a driver written for a family of w1 devices. A family driver populates a struct w1_family_ops (see w1_family.h) and registers with the w1 subsystem. Current family drivers: -w1_therm - (ds18?20 thermal sensor family driver) + +w1_therm + - (ds18?20 thermal sensor family driver) provides temperature reading function which is bound to ->rbin() method of the above w1_family_ops structure. -w1_smem - driver for simple 64bit memory cell provides ID reading method. +w1_smem + - driver for simple 64bit memory cell provides ID reading method. You can call above methods by reading appropriate sysfs files. What does a w1 master driver need to implement? ------------------------------------------------------------------- +----------------------------------------------- The driver for w1 bus master must provide at minimum two functions. @@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details. w1 master sysfs interface ------------------------------------------------------------------- -<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial -bus - (standard) symlink to the w1 bus -driver - (standard) symlink to the w1 driver -w1_master_add - (rw) manually register a slave device -w1_master_attempts - (ro) the number of times a search was attempted -w1_master_max_slave_count - - (rw) maximum number of slaves to search for at a time -w1_master_name - (ro) the name of the device (w1_bus_masterX) -w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled -w1_master_remove - (rw) manually remove a slave device -w1_master_search - (rw) the number of searches left to do, - -1=continual (default) -w1_master_slave_count - - (ro) the number of slaves found -w1_master_slaves - (ro) the names of the slaves, one per line -w1_master_timeout - (ro) the delay in seconds between searches -w1_master_timeout_us - - (ro) the delay in microseconds beetwen searches +------------------------- + +========================= ===================================================== +<xx-xxxxxxxxxxxx> A directory for a found device. The format is + family-serial +bus (standard) symlink to the w1 bus +driver (standard) symlink to the w1 driver +w1_master_add (rw) manually register a slave device +w1_master_attempts (ro) the number of times a search was attempted +w1_master_max_slave_count (rw) maximum number of slaves to search for at a time +w1_master_name (ro) the name of the device (w1_bus_masterX) +w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled +w1_master_remove (rw) manually remove a slave device +w1_master_search (rw) the number of searches left to do, + -1=continual (default) +w1_master_slave_count (ro) the number of slaves found +w1_master_slaves (ro) the names of the slaves, one per line +w1_master_timeout (ro) the delay in seconds between searches +w1_master_timeout_us (ro) the delay in microseconds beetwen searches +========================= ===================================================== If you have a w1 bus that never changes (you don't add or remove devices), you can set the module parameter search_count to a small positive number @@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments w1_master_attempts by 1. w1 slave sysfs interface ------------------------------------------------------------------- -bus - (standard) symlink to the w1 bus -driver - (standard) symlink to the w1 driver -name - the device name, usually the same as the directory name -w1_slave - (optional) a binary file whose meaning depends on the - family driver -rw - (optional) created for slave devices which do not have - appropriate family driver. Allows to read/write binary data. +------------------------ + +=================== ============================================================ +bus (standard) symlink to the w1 bus +driver (standard) symlink to the w1 driver +name the device name, usually the same as the directory name +w1_slave (optional) a binary file whose meaning depends on the + family driver +rw (optional) created for slave devices which do not have + appropriate family driver. Allows to read/write binary data. +=================== ============================================================ diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst index 94ad4c420828..aaa13243a5e4 100644 --- a/Documentation/w1/w1.netlink +++ b/Documentation/w1/w1-netlink.rst @@ -1,22 +1,26 @@ -Userspace communication protocol over connector [1]. +=============================================== +Userspace communication protocol over connector +=============================================== - -Message types. +Message types ============= There are three types of messages between w1 core and userspace: + 1. Events. They are generated each time a new master or slave device - is found either due to automatic or requested search. + is found either due to automatic or requested search. 2. Userspace commands. 3. Replies to userspace commands. -Protocol. +Protocol ======== -[struct cn_msg] - connector header. +:: + + [struct cn_msg] - connector header. Its length field is equal to size of the attached data -[struct w1_netlink_msg] - w1 netlink header. + [struct w1_netlink_msg] - w1 netlink header. __u8 type - message type. W1_LIST_MASTERS list current bus masters @@ -40,7 +44,7 @@ Protocol. } mst; } id; -[struct w1_netlink_cmd] - command for given master or slave device. + [struct w1_netlink_cmd] - command for given master or slave device. __u8 cmd - command opcode. W1_CMD_READ - read command W1_CMD_WRITE - write command @@ -71,18 +75,18 @@ when it is added to w1 core. Currently replies to userspace commands are only generated for read command request. One reply is generated exactly for one w1_netlink_cmd read request. Replies are not combined when sent - i.e. typical reply -messages looks like the following: +messages looks like the following:: -[cn_msg][w1_netlink_msg][w1_netlink_cmd] -cn_msg.len = sizeof(struct w1_netlink_msg) + + [cn_msg][w1_netlink_msg][w1_netlink_cmd] + cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len; -w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; -w1_netlink_cmd.len = cmd->len; + w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; + w1_netlink_cmd.len = cmd->len; Replies to W1_LIST_MASTERS should send a message back to the userspace which will contain list of all registered master ids in the following -format: +format:: cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct w1_netlink_msg) plus number of masters multiplied by 4) @@ -90,39 +94,47 @@ format: number of masters multiplied by 4 (u32 size)) id0 ... idN - Each message is at most 4k in size, so if number of master devices - exceeds this, it will be split into several messages. +Each message is at most 4k in size, so if number of master devices +exceeds this, it will be split into several messages. W1 search and alarm search commands. -request: -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] -reply: +request:: + + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] + +reply:: + [cn_msg, ack = 1 and increasing, 0 means the last message, - seq is equal to the request seq] + seq is equal to the request seq] [w1_netlink_msg type = W1_MASTER_CMD] [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH len is equal to number of IDs multiplied by 8] [64bit-id0 ... 64bit-idN] + Length in each header corresponds to the size of the data behind it, so w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. - Can be zero. -w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; -cn_msg->len = sizeof(struct w1_netlink_msg) + +Can be zero. + +:: + + w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; + cn_msg->len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + N*8; -W1 reset command. -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_RESET] +W1 reset command:: + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_RESET] -Command status replies. + +Command status replies ====================== Each command (either root, master or slave with or without w1_netlink_cmd @@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg, even if there were errors, only length mismatch interrupts message processing. -Operation steps in w1 core when new command is received. +Operation steps in w1 core when new command is received ======================================================= When new message (w1_netlink_msg) is received w1 core detects if it is @@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked and next w1_netlink_msg header processing started. -Connector [1] specific documentation. +Connector [1] specific documentation ==================================== Each connector message includes two u32 fields as "address". @@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and acknowledge number is set to seq+1. -Additional documantion, source code examples. -============================================ +Additional documentation, source code examples +============================================== 1. Documentation/driver-api/connector.rst 2. http://www.ioremap.net/archive/w1 -This archive includes userspace application w1d.c which uses -read/write/search commands for all master/slave devices found on the bus. + + This archive includes userspace application w1d.c which uses + read/write/search commands for all master/slave devices found on the bus. |