diff options
Diffstat (limited to 'Documentation')
571 files changed, 12185 insertions, 8249 deletions
diff --git a/Documentation/ABI/README b/Documentation/ABI/README index 3121029dce21..8bac9cb09a6d 100644 --- a/Documentation/ABI/README +++ b/Documentation/ABI/README @@ -32,7 +32,7 @@ The different levels of stability are: layout of the files below for details on how to do this.) obsolete/ - This directory documents interfaces that are still remaining in + This directory documents interfaces that are still remaining in the kernel, but are marked to be removed at some later point in time. The description of the interface will document the reason why it is obsolete and when it can be expected to be removed. @@ -58,6 +58,14 @@ Users: All users of this interface who wish to be notified when be changed further. +Note: + The fields should be use a simple notation, compatible with ReST markup. + Also, the file **should not** have a top-level index, like:: + + === + foo + === + How things move between levels: Interfaces in stable may move to obsolete, as long as the proper diff --git a/Documentation/ABI/obsolete/sysfs-class-dax b/Documentation/ABI/obsolete/sysfs-class-dax index 2cb9fc5e8bd1..0faf1354cd05 100644 --- a/Documentation/ABI/obsolete/sysfs-class-dax +++ b/Documentation/ABI/obsolete/sysfs-class-dax @@ -8,11 +8,11 @@ Description: Device DAX is the device-centric analogue of Filesystem system. Device DAX is strict, precise and predictable. Specifically this interface: - 1/ Guarantees fault granularity with respect to a given - page size (pte, pmd, or pud) set at configuration time. + 1. Guarantees fault granularity with respect to a given + page size (pte, pmd, or pud) set at configuration time. - 2/ Enforces deterministic behavior by being strict about - what fault scenarios are supported. + 2. Enforces deterministic behavior by being strict about + what fault scenarios are supported. The /sys/class/dax/ interface enumerates all the device-dax instances in the system. The ABI is diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra index 5d41ebadf15e..66545c587a64 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra @@ -7,10 +7,13 @@ Description: It is possible to switch the cpi setting of the mouse with the setting reported by the mouse. This number has to be further processed to receive the real dpi value: + ===== ==== VALUE DPI + ===== ==== 1 400 2 800 4 1600 + ===== ==== This file is readonly. Has never been used. If bookkeeping is done, it's done in userland tools. diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio index e0d4e5e2dd90..b8b0fd341c17 100644 --- a/Documentation/ABI/obsolete/sysfs-gpio +++ b/Documentation/ABI/obsolete/sysfs-gpio @@ -13,6 +13,8 @@ Description: GPIOs are identified as they are inside the kernel, using integers in the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information. + :: + /sys/class/gpio /export ... asks the kernel to export a GPIO to userspace /unexport ... to return a GPIO to the kernel diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs index 0020c49933c4..24fb35adf277 100644 --- a/Documentation/ABI/removed/devfs +++ b/Documentation/ABI/removed/devfs @@ -5,6 +5,7 @@ Description: devfs has been unmaintained for a number of years, has unfixable races, contains a naming policy within the kernel that is against the LSB, and can be replaced by using udev. + The files fs/devfs/*, include/linux/devfs_fs*.h were removed, along with the assorted devfs function calls throughout the kernel tree. diff --git a/Documentation/ABI/removed/raw1394 b/Documentation/ABI/removed/raw1394 index ec333e676322..9ec7ec493920 100644 --- a/Documentation/ABI/removed/raw1394 +++ b/Documentation/ABI/removed/raw1394 @@ -7,6 +7,7 @@ Description: to implement sensible device security policies, and its low level of abstraction that required userspace clients to duplicate much of the kernel's ieee1394 core functionality. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of firewire-core. diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill index 9c08c7f98ffb..f25174eafd55 100644 --- a/Documentation/ABI/removed/sysfs-class-rfkill +++ b/Documentation/ABI/removed/sysfs-class-rfkill @@ -10,4 +10,4 @@ Description: This file was deprecated because there no longer was a way to claim just control over a single rfkill instance. This file was scheduled to be removed in 2012, and was removed in 2016. -Values: 0: Kernel handles events +Values: 0: Kernel handles events diff --git a/Documentation/ABI/removed/video1394 b/Documentation/ABI/removed/video1394 index c39c25aee77b..1905d35a6619 100644 --- a/Documentation/ABI/removed/video1394 +++ b/Documentation/ABI/removed/video1394 @@ -8,6 +8,7 @@ Description: performance issues in its first generation. Any video1394 user had to use raw1394 + libraw1394 too because video1394 did not provide asynchronous I/O for device discovery and configuration. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of firewire-core. diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev index f72ed653878a..261f85b13154 100644 --- a/Documentation/ABI/stable/firewire-cdev +++ b/Documentation/ABI/stable/firewire-cdev @@ -14,13 +14,17 @@ Description: Each /dev/fw* is associated with one IEEE 1394 node, which can be remote or local nodes. Operations on a /dev/fw* file have different scope: + - The 1394 node which is associated with the file: + - Asynchronous request transmission - Get the Configuration ROM - Query node ID - Query maximum speed of the path between this node and local node + - The 1394 bus (i.e. "card") to which the node is attached to: + - Isochronous stream transmission and reception - Asynchronous stream transmission and reception - Asynchronous broadcast request transmission @@ -31,7 +35,9 @@ Description: manager - Query cycle time - Bus reset initiation, bus reset event reception + - All 1394 buses: + - Allocation of IEEE 1212 address ranges on the local link layers, reception of inbound requests to such an address range, asynchronous response transmission @@ -43,6 +49,7 @@ Description: userland implement different access permission models, some operations are restricted to /dev/fw* files that are associated with a local node: + - Addition of descriptors or directories to the local nodes' Configuration ROM - PHY packet transmission and reception @@ -55,50 +62,50 @@ Description: The following file operations are supported: open(2) - Currently the only useful flags are O_RDWR. + Currently the only useful flags are O_RDWR. ioctl(2) - Initiate various actions. Some take immediate effect, others - are performed asynchronously while or after the ioctl returns. - See the inline documentation in <linux/firewire-cdev.h> for - descriptions of all ioctls. + Initiate various actions. Some take immediate effect, others + are performed asynchronously while or after the ioctl returns. + See the inline documentation in <linux/firewire-cdev.h> for + descriptions of all ioctls. poll(2), select(2), epoll_wait(2) etc. - Watch for events to become available to be read. + Watch for events to become available to be read. read(2) - Receive various events. There are solicited events like - outbound asynchronous transaction completion or isochronous - buffer completion, and unsolicited events such as bus resets, - request reception, or PHY packet reception. Always use a read - buffer which is large enough to receive the largest event that - could ever arrive. See <linux/firewire-cdev.h> for descriptions - of all event types and for which ioctls affect reception of - events. + Receive various events. There are solicited events like + outbound asynchronous transaction completion or isochronous + buffer completion, and unsolicited events such as bus resets, + request reception, or PHY packet reception. Always use a read + buffer which is large enough to receive the largest event that + could ever arrive. See <linux/firewire-cdev.h> for descriptions + of all event types and for which ioctls affect reception of + events. mmap(2) - Allocate a DMA buffer for isochronous reception or transmission - and map it into the process address space. The arguments should - be used as follows: addr = NULL, length = the desired buffer - size, i.e. number of packets times size of largest packet, - prot = at least PROT_READ for reception and at least PROT_WRITE - for transmission, flags = MAP_SHARED, fd = the handle to the - /dev/fw*, offset = 0. + Allocate a DMA buffer for isochronous reception or transmission + and map it into the process address space. The arguments should + be used as follows: addr = NULL, length = the desired buffer + size, i.e. number of packets times size of largest packet, + prot = at least PROT_READ for reception and at least PROT_WRITE + for transmission, flags = MAP_SHARED, fd = the handle to the + /dev/fw*, offset = 0. Isochronous reception works in packet-per-buffer fashion except for multichannel reception which works in buffer-fill mode. munmap(2) - Unmap the isochronous I/O buffer from the process address space. + Unmap the isochronous I/O buffer from the process address space. close(2) - Besides stopping and freeing I/O contexts that were associated - with the file descriptor, back out any changes to the local - nodes' Configuration ROM. Deallocate isochronous channels and - bandwidth at the IRM that were marked for kernel-assisted - re- and deallocation. - -Users: libraw1394 - libdc1394 - libhinawa + Besides stopping and freeing I/O contexts that were associated + with the file descriptor, back out any changes to the local + nodes' Configuration ROM. Deallocate isochronous channels and + bandwidth at the IRM that were marked for kernel-assisted + re- and deallocation. + +Users: libraw1394; + libdc1394; + libhinawa; tools like linux-firewire-utils, fwhack, ... diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile index 964c7a8afb26..2d6314f0e4e4 100644 --- a/Documentation/ABI/stable/sysfs-acpi-pmprofile +++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile @@ -1,22 +1,26 @@ -What: /sys/firmware/acpi/pm_profile +What: /sys/firmware/acpi/pm_profile Date: 03-Nov-2011 KernelVersion: v3.2 Contact: linux-acpi@vger.kernel.org -Description: The ACPI pm_profile sysfs interface exports the platform +Description: The ACPI pm_profile sysfs interface exports the platform power management (and performance) requirement expectations as provided by BIOS. The integer value is directly passed as retrieved from the FADT ACPI table. -Values: For possible values see ACPI specification: + +Values: For possible values see ACPI specification: 5.2.9 Fixed ACPI Description Table (FADT) Field: Preferred_PM_Profile Currently these values are defined by spec: - 0 Unspecified - 1 Desktop - 2 Mobile - 3 Workstation - 4 Enterprise Server - 5 SOHO Server - 6 Appliance PC - 7 Performance Server + + == ================= + 0 Unspecified + 1 Desktop + 2 Mobile + 3 Workstation + 4 Enterprise Server + 5 SOHO Server + 6 Appliance PC + 7 Performance Server >7 Reserved + == ================= diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire index 41e5a0cd1e3e..9ac9eddb82ef 100644 --- a/Documentation/ABI/stable/sysfs-bus-firewire +++ b/Documentation/ABI/stable/sysfs-bus-firewire @@ -47,6 +47,7 @@ Description: IEEE 1394 node device attribute. Read-only and immutable. Values: 1: The sysfs entry represents a local node (a controller card). + 0: The sysfs entry represents a remote node. @@ -125,7 +126,9 @@ Description: Read-only attribute, immutable during the target's lifetime. Format, as exposed by firewire-sbp2 since 2.6.22, May 2007: Colon-separated hexadecimal string representations of + u64 EUI-64 : u24 directory_ID : u16 LUN + without 0x prefixes, without whitespace. The former sbp2 driver (removed in 2.6.37 after being superseded by firewire-sbp2) used a somewhat shorter format which was not as close to SAM. diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem index 9ffba8576f7b..c399323f37de 100644 --- a/Documentation/ABI/stable/sysfs-bus-nvmem +++ b/Documentation/ABI/stable/sysfs-bus-nvmem @@ -9,13 +9,14 @@ Description: Note: This file is only present if CONFIG_NVMEM_SYSFS is enabled - ex: - hexdump /sys/bus/nvmem/devices/qfprom0/nvmem + ex:: - 0000000 0000 0000 0000 0000 0000 0000 0000 0000 - * - 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 - 0000000 0000 0000 0000 0000 0000 0000 0000 0000 - ... - * - 0001000 + hexdump /sys/bus/nvmem/devices/qfprom0/nvmem + + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + * + 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + ... + * + 0001000 diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb index b832eeff9999..cad4bc232520 100644 --- a/Documentation/ABI/stable/sysfs-bus-usb +++ b/Documentation/ABI/stable/sysfs-bus-usb @@ -50,8 +50,10 @@ Description: Tools can use this file and the connected_duration file to compute the percentage of time that a device has been active. - For example, - echo $((100 * `cat active_duration` / `cat connected_duration`)) + For example:: + + echo $((100 * `cat active_duration` / `cat connected_duration`)) + will give an integer percentage. Note that this does not account for counter wrap. Users: diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index 8e8d167eca31..c27b7b89477c 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -63,13 +63,6 @@ Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: VCPU (sub)channel is affinitized to Users: tools/hv/lsvmbus and other debugging tools -What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu -Date: September. 2017 -KernelVersion: 4.14 -Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: VCPU (sub)channel is affinitized to -Users: tools/hv/lsvmbus and other debugging tools - What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/in_mask Date: September. 2017 KernelVersion: 4.14 diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1 index 992dfb183ed0..5cd5e872bcae 100644 --- a/Documentation/ABI/stable/sysfs-bus-w1 +++ b/Documentation/ABI/stable/sysfs-bus-w1 @@ -6,6 +6,7 @@ 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.rst for detailed information. Users: any user space application which wants to know bus scanning interval diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight index 70302f370e7e..023fb52645f8 100644 --- a/Documentation/ABI/stable/sysfs-class-backlight +++ b/Documentation/ABI/stable/sysfs-class-backlight @@ -4,6 +4,7 @@ KernelVersion: 2.6.12 Contact: Richard Purdie <rpurdie@rpsys.net> Description: Control BACKLIGHT power, values are FB_BLANK_* from fb.h + - FB_BLANK_UNBLANK (0) : power on. - FB_BLANK_POWERDOWN (4) : power off Users: HAL diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband index 87b11f91b425..348c4ac803ad 100644 --- a/Documentation/ABI/stable/sysfs-class-infiniband +++ b/Documentation/ABI/stable/sysfs-class-infiniband @@ -8,12 +8,14 @@ Date: Apr, 2005 KernelVersion: v2.6.12 Contact: linux-rdma@vger.kernel.org Description: + =============== =========================================== node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP, switch or router) node_guid: (RO) Node GUID sys_image_guid: (RO) System image GUID + =============== =========================================== What: /sys/class/infiniband/<device>/node_desc @@ -47,6 +49,7 @@ KernelVersion: v2.6.12 Contact: linux-rdma@vger.kernel.org Description: + =============== =============================================== lid: (RO) Port LID rate: (RO) Port data rate (active width * active @@ -66,8 +69,9 @@ Description: cap_mask: (RO) Port capability mask. 2 bits here are settable- IsCommunicationManagementSupported - (set when CM module is loaded) and IsSM (set via - open of issmN file). + (set when CM module is loaded) and IsSM (set + via open of issmN file). + =============== =============================================== What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer @@ -103,8 +107,7 @@ Date: Apr, 2005 KernelVersion: v2.6.12 Contact: linux-rdma@vger.kernel.org Description: - Errors info: - ----------- + **Errors info**: symbol_error: (RO) Total number of minor link errors detected on one or more physical lanes. @@ -142,8 +145,7 @@ Description: intervention. It can also indicate hardware issues or extremely poor link signal integrity - Data info: - --------- + **Data info**: port_xmit_data: (RO) Total number of data octets, divided by 4 (lanes), transmitted on all VLs. This is 64 bit counter @@ -176,8 +178,7 @@ Description: transmitted on all VLs from the port. This may include multicast packets with errors. - Misc info: - --------- + **Misc info**: port_xmit_discards: (RO) Total number of outbound packets discarded by the port because the port is down or congested. @@ -244,9 +245,11 @@ Description: two umad devices and two issm devices, while a switch will have one device of each type (for switch port 0). + ======= ===================================== ibdev: (RO) Show Infiniband (IB) device name port: (RO) Display port number + ======= ===================================== What: /sys/class/infiniband_mad/abi_version @@ -264,10 +267,12 @@ Date: Sept, 2005 KernelVersion: v2.6.14 Contact: linux-rdma@vger.kernel.org Description: + =============== =========================================== ibdev: (RO) Display Infiniband (IB) device name abi_version: (RO) Show ABI version of IB device specific interfaces. + =============== =========================================== What: /sys/class/infiniband_verbs/abi_version @@ -289,12 +294,14 @@ Date: Apr, 2005 KernelVersion: v2.6.12 Contact: linux-rdma@vger.kernel.org Description: + =============== ================================================ hw_rev: (RO) Hardware revision number hca_type: (RO) Host Channel Adapter type: MT23108, MT25208 (MT23108 compat mode), MT25208 or MT25204 board_id: (RO) Manufacturing board ID + =============== ================================================ sysfs interface for Mellanox ConnectX HCA IB driver (mlx4) @@ -307,11 +314,13 @@ Date: Sep, 2007 KernelVersion: v2.6.24 Contact: linux-rdma@vger.kernel.org Description: + =============== =============================== hw_rev: (RO) Hardware revision number hca_type: (RO) Host channel adapter type board_id: (RO) Manufacturing board ID + =============== =============================== What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n> @@ -337,6 +346,7 @@ Description: example, ports/1/pkeys/10 contains the value at index 10 in port 1's P_Key table. + ======================= ========================================== gids/<n>: (RO) The physical port gids n = 0..127 admin_guids/<n>: (RW) Allows examining or changing the @@ -365,6 +375,7 @@ Description: guest, whenever it uses its pkey index 1, will actually be using the real pkey index 10. + ======================= ========================================== What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled @@ -376,12 +387,14 @@ Description: Enabling QP0 on VFs for selected VF/port. By default, no VFs are enabled for QP0 operation. - smi_enabled: (RO) Indicates whether smi is currently enabled - for the indicated VF/port + ================= ==== =========================================== + smi_enabled: (RO) Indicates whether smi is currently enabled + for the indicated VF/port - enable_smi_admin:(RW) Used by the admin to request that smi - capability be enabled or disabled for the - indicated VF/port. 0 = disable, 1 = enable. + enable_smi_admin: (RW) Used by the admin to request that smi + capability be enabled or disabled for the + indicated VF/port. 0 = disable, 1 = enable. + ================= ==== =========================================== The requested enablement will occur at the next reset of the VF (e.g. driver restart on the VM which owns the VF). @@ -398,6 +411,7 @@ KernelVersion: v2.6.35 Contact: linux-rdma@vger.kernel.org Description: + =============== ============================================= hw_rev: (RO) Hardware revision number hca_type: (RO) Driver short name. Should normally match @@ -406,6 +420,7 @@ Description: board_id: (RO) Manufacturing board id. (Vendor + device information) + =============== ============================================= sysfs interface for Intel IB driver qib @@ -426,6 +441,7 @@ Date: May, 2010 KernelVersion: v2.6.35 Contact: linux-rdma@vger.kernel.org Description: + =============== ====================================================== version: (RO) Display version information of installed software and drivers. @@ -452,6 +468,7 @@ Description: chip_reset: (WO) Reset the chip if possible by writing "reset" to this file. Only allowed if no user contexts are open that use chip resources. + =============== ====================================================== What: /sys/class/infiniband/qibX/ports/N/sl2vl/[0-15] @@ -471,14 +488,16 @@ Contact: linux-rdma@vger.kernel.org Description: Per-port congestion control. Both are binary attributes. - cc_table_bin: (RO) Congestion control table size followed by + =============== ================================================ + cc_table_bin (RO) Congestion control table size followed by table entries. - cc_settings_bin:(RO) Congestion settings: port control, control + cc_settings_bin (RO) Congestion settings: port control, control map and an array of 16 entries for the congestion entries - increase, timer, event log trigger threshold and the minimum injection rate delay. + =============== ================================================ What: /sys/class/infiniband/qibX/ports/N/linkstate/loopback What: /sys/class/infiniband/qibX/ports/N/linkstate/led_override @@ -491,6 +510,7 @@ Contact: linux-rdma@vger.kernel.org Description: [to be documented] + =============== =============================================== loopback: (WO) led_override: (WO) hrtbt_enable: (RW) @@ -501,6 +521,7 @@ Description: errors. Possible states are- "Initted", "Present", "IB_link_up", "IB_configured" or "Fatal_Hardware_Error". + =============== =============================================== What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends What: /sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks @@ -549,6 +570,7 @@ Contact: Christian Benvenuti <benve@cisco.com>, linux-rdma@vger.kernel.org Description: + =============== =============================================== board_id: (RO) Manufacturing board id config: (RO) Report the configuration for this PF @@ -561,6 +583,7 @@ Description: iface: (RO) Shows which network interface this usNIC entry is associated to (visible with ifconfig). + =============== =============================================== What: /sys/class/infiniband/usnic_X/qpn/summary What: /sys/class/infiniband/usnic_X/qpn/context @@ -605,6 +628,7 @@ Date: May, 2016 KernelVersion: v4.6 Contact: linux-rdma@vger.kernel.org Description: + =============== ============================================= hw_rev: (RO) Hardware revision number board_id: (RO) Manufacturing board id @@ -623,6 +647,7 @@ Description: available. tempsense: (RO) Thermal sense information + =============== ============================================= What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin @@ -634,19 +659,21 @@ Contact: linux-rdma@vger.kernel.org Description: Per-port congestion control. - cc_table_bin: (RO) CCA tables used by PSM2 Congestion control + =============== ================================================ + cc_table_bin (RO) CCA tables used by PSM2 Congestion control table size followed by table entries. Binary attribute. - cc_settings_bin:(RO) Congestion settings: port control, control + cc_settings_bin (RO) Congestion settings: port control, control map and an array of 16 entries for the congestion entries - increase, timer, event log trigger threshold and the minimum injection rate delay. Binary attribute. - cc_prescan: (RW) enable prescanning for faster BECN + cc_prescan (RW) enable prescanning for faster BECN response. Write "on" to enable and "off" to disable. + =============== ================================================ What: /sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31] What: /sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31] @@ -655,11 +682,13 @@ Date: May, 2016 KernelVersion: v4.6 Contact: linux-rdma@vger.kernel.org Description: + =============== =================================================== sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl + =============== =================================================== What: /sys/class/infiniband/hfi1_X/sdma_N/cpu_list @@ -670,26 +699,28 @@ Contact: linux-rdma@vger.kernel.org Description: sdma<N>/ contains one directory per sdma engine (0 - 15) + =============== ============================================== cpu_list: (RW) List of cpus for user-process to sdma engine assignment. vl: (RO) Displays the virtual lane (vl) the sdma engine maps to. + =============== ============================================== This interface gives the user control on the affinity settings for the device. As an example, to set an sdma engine irq affinity and thread affinity of a user processes to use the sdma engine, which is "near" in terms of NUMA configuration, or - physical cpu location, the user will do: + physical cpu location, the user will do:: - echo "3" > /proc/irq/<N>/smp_affinity_list - echo "4-7" > /sys/devices/.../sdma3/cpu_list - cat /sys/devices/.../sdma3/vl - 0 - echo "8" > /proc/irq/<M>/smp_affinity_list - echo "9-12" > /sys/devices/.../sdma4/cpu_list - cat /sys/devices/.../sdma4/vl - 1 + echo "3" > /proc/irq/<N>/smp_affinity_list + echo "4-7" > /sys/devices/.../sdma3/cpu_list + cat /sys/devices/.../sdma3/vl + 0 + echo "8" > /proc/irq/<M>/smp_affinity_list + echo "9-12" > /sys/devices/.../sdma4/cpu_list + cat /sys/devices/.../sdma4/vl + 1 to make sure that when a process runs on cpus 4,5,6, or 7, and uses vl=0, then sdma engine 3 is selected by the driver, and @@ -711,11 +742,13 @@ Date: Jan, 2016 KernelVersion: v4.10 Contact: linux-rdma@vger.kernel.org Description: + =============== ==== ======================== hw_rev: (RO) Hardware revision number hca_type: (RO) Show HCA type (I40IW) board_id: (RO) I40IW board ID + =============== ==== ======================== sysfs interface for QLogic qedr NIC Driver @@ -728,9 +761,11 @@ KernelVersion: v4.10 Contact: linux-rdma@vger.kernel.org Description: + =============== ==== ======================== hw_rev: (RO) Hardware revision number hca_type: (RO) Display HCA type + =============== ==== ======================== sysfs interface for VMware Paravirtual RDMA driver @@ -744,11 +779,13 @@ KernelVersion: v4.10 Contact: linux-rdma@vger.kernel.org Description: + =============== ==== ===================================== hw_rev: (RO) Hardware revision number hca_type: (RO) Host channel adapter type board_id: (RO) Display PVRDMA manufacturing board ID + =============== ==== ===================================== sysfs interface for Broadcom NetXtreme-E RoCE driver @@ -760,6 +797,8 @@ Date: Feb, 2017 KernelVersion: v4.11 Contact: linux-rdma@vger.kernel.org Description: + =============== ==== ========================= hw_rev: (RO) Hardware revision number hca_type: (RO) Host channel adapter type + =============== ==== ========================= diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill index 5b154f922643..037979f7dc4b 100644 --- a/Documentation/ABI/stable/sysfs-class-rfkill +++ b/Documentation/ABI/stable/sysfs-class-rfkill @@ -2,7 +2,7 @@ rfkill - radio frequency (RF) connector kill switch support For details to this subsystem look at Documentation/driver-api/rfkill.rst. -For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in +For the deprecated ``/sys/class/rfkill/*/claim`` knobs of this interface look in Documentation/ABI/removed/sysfs-class-rfkill. What: /sys/class/rfkill @@ -36,9 +36,10 @@ KernelVersion v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Whether the soft blocked state is initialised from non-volatile storage at startup. -Values: A numeric value. - 0: false - 1: true +Values: A numeric value: + + - 0: false + - 1: true What: /sys/class/rfkill/rfkill[0-9]+/state @@ -54,6 +55,7 @@ Description: Current state of the transmitter. through this interface. There will likely be another attempt to remove it in the future. Values: A numeric value. + 0: RFKILL_STATE_SOFT_BLOCKED transmitter is turned off by software 1: RFKILL_STATE_UNBLOCKED @@ -69,6 +71,7 @@ KernelVersion v2.6.34 Contact: linux-wireless@vger.kernel.org Description: Current hardblock state. This file is read only. Values: A numeric value. + 0: inactive The transmitter is (potentially) active. 1: active @@ -82,7 +85,9 @@ KernelVersion v2.6.34 Contact: linux-wireless@vger.kernel.org Description: Current softblock state. This file is read and write. Values: A numeric value. + 0: inactive The transmitter is (potentially) active. + 1: active The transmitter is turned off by software. diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm index 58e94e7d55be..91ca63ec7581 100644 --- a/Documentation/ABI/stable/sysfs-class-tpm +++ b/Documentation/ABI/stable/sysfs-class-tpm @@ -32,11 +32,11 @@ KernelVersion: 2.6.12 Contact: linux-integrity@vger.kernel.org Description: The "caps" property contains TPM manufacturer and version info. - Example output: + Example output:: - Manufacturer: 0x53544d20 - TCG version: 1.2 - Firmware version: 8.16 + Manufacturer: 0x53544d20 + TCG version: 1.2 + Firmware version: 8.16 Manufacturer is a hex dump of the 4 byte manufacturer info space in a TPM. TCG version shows the TCG TPM spec level that @@ -54,9 +54,9 @@ Description: The "durations" property shows the 3 vendor-specific values any longer than necessary before starting to poll for a result. - Example output: + Example output:: - 3015000 4508000 180995000 [original] + 3015000 4508000 180995000 [original] Here the short, medium and long durations are displayed in usecs. "[original]" indicates that the values are displayed @@ -92,14 +92,14 @@ Description: The "pcrs" property will dump the current value of all Platform values may be constantly changing, the output is only valid for a snapshot in time. - Example output: + Example output:: - PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 - PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 - PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 - PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 - PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 - ... + PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + ... The number of PCRs and hex bytes needed to represent a PCR value will vary depending on TPM chip version. For TPM 1.1 and @@ -119,44 +119,44 @@ Description: The "pubek" property will return the TPM's public endorsement ated at TPM manufacture time and exists for the life of the chip. - Example output: - - Algorithm: 00 00 00 01 - Encscheme: 00 03 - Sigscheme: 00 01 - Parameters: 00 00 08 00 00 00 00 02 00 00 00 00 - Modulus length: 256 - Modulus: - B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C - 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6 - 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB - 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3 - D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B - 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26 - 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E - 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D - 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0 - A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6 - 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6 - 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70 - E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A - F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6 - F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B - C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B - - Possible values: - - Algorithm: TPM_ALG_RSA (1) - Encscheme: TPM_ES_RSAESPKCSv15 (2) + Example output:: + + Algorithm: 00 00 00 01 + Encscheme: 00 03 + Sigscheme: 00 01 + Parameters: 00 00 08 00 00 00 00 02 00 00 00 00 + Modulus length: 256 + Modulus: + B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C + 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6 + 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB + 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3 + D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B + 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26 + 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E + 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D + 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0 + A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6 + 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6 + 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70 + E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A + F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6 + F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B + C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B + + Possible values:: + + Algorithm: TPM_ALG_RSA (1) + Encscheme: TPM_ES_RSAESPKCSv15 (2) TPM_ES_RSAESOAEP_SHA1_MGF1 (3) - Sigscheme: TPM_SS_NONE (1) - Parameters, a byte string of 3 u32 values: + Sigscheme: TPM_SS_NONE (1) + Parameters, a byte string of 3 u32 values: Key Length (bits): 00 00 08 00 (2048) Num primes: 00 00 00 02 (2) Exponent Size: 00 00 00 00 (0 means the default exp) - Modulus Length: 256 (bytes) - Modulus: The 256 byte Endorsement Key modulus + Modulus Length: 256 (bytes) + Modulus: The 256 byte Endorsement Key modulus What: /sys/class/tpm/tpmX/device/temp_deactivated Date: April 2006 @@ -176,9 +176,9 @@ Description: The "timeouts" property shows the 4 vendor-specific values timeouts is defined by the TPM interface spec that the chip conforms to. - Example output: + Example output:: - 750000 750000 750000 750000 [original] + 750000 750000 750000 750000 [original] The four timeout values are shown in usecs, with a trailing "[original]" or "[adjusted]" depending on whether the values @@ -191,6 +191,6 @@ Contact: linux-integrity@vger.kernel.org Description: The "tpm_version_major" property shows the TCG spec major version implemented by the TPM device. - Example output: + Example output:: - 2 + 2 diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices index 4404bd9b96c1..42bf1eab5677 100644 --- a/Documentation/ABI/stable/sysfs-devices +++ b/Documentation/ABI/stable/sysfs-devices @@ -1,5 +1,6 @@ -# Note: This documents additional properties of any device beyond what -# is documented in Documentation/admin-guide/sysfs-rules.rst +Note: + This documents additional properties of any device beyond what + is documented in Documentation/admin-guide/sysfs-rules.rst What: /sys/devices/*/of_node Date: February 2015 diff --git a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma index 420c1d09e42f..3a4e2cd0ddcc 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma +++ b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma @@ -1,29 +1,29 @@ -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/cap +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/cap Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Capabilities the DMA supports.Currently there are DMA_PQ, DMA_PQ_VAL, DMA_XOR,DMA_XOR_VAL,DMA_INTERRUPT. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_active +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_active Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: The number of descriptors active in the ring. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_size +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_size Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Descriptor ring size, total number of descriptors available. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/version +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/version Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Version of ioatdma device. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/intr_coalesce +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/intr_coalesce Date: August 8, 2017 KernelVersion: 4.14 Contact: dmaengine@vger.kernel.org diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp index 00fa04c76ff3..f5724bb5b462 100644 --- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp +++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp @@ -12,13 +12,15 @@ Description: resets. Three registers are used by the FSBL and other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}. - Usage: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 - # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 + Usage:: + + # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 + # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 + + Example:: - Example: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 - # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 + # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 + # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0 Users: Xilinx @@ -39,13 +41,15 @@ Description: software products: PERS_GLOB_GEN_STORAGE{4:7}. Register is reset only by a POR reset. - Usage: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 - # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 + Usage:: + + # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 + # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 + + Example:: - Example: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 - # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 + # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 + # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0 Users: Xilinx @@ -61,23 +65,28 @@ Description: Following are available shutdown scopes(subtypes): - subsystem: Only the APU along with all of its peripherals + subsystem: + Only the APU along with all of its peripherals not used by other processing units will be shut down. This may result in the FPD power domain being shut down provided that no other processing unit uses FPD peripherals or DRAM. - ps_only: The complete PS will be shut down, including the + ps_only: + The complete PS will be shut down, including the RPU, PMU, etc. Only the PL domain (FPGA) remains untouched. - system: The complete system/device is shut down. + system: + The complete system/device is shut down. - Usage: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope - # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope + Usage:: + + # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope + # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope + + Example:: - Example: - # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope - # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope + # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope + # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope Users: Xilinx @@ -94,10 +103,13 @@ Description: system restart. Usage: - Set healthy bit - # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status - Unset healthy bit - # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status + Set healthy bit:: + + # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status + + Unset healthy bit:: + + # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status Users: Xilinx diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp index 84972a57caae..bada15a329f7 100644 --- a/Documentation/ABI/stable/sysfs-driver-ib_srp +++ b/Documentation/ABI/stable/sysfs-driver-ib_srp @@ -6,6 +6,7 @@ Description: Interface for making ib_srp connect to a new target. One can request ib_srp to connect to a new target by writing a comma-separated list of login parameters to this sysfs attribute. The supported parameters are: + * id_ext, a 16-digit hexadecimal number specifying the eight byte identifier extension in the 16-byte SRP target port identifier. The target port identifier is sent by ib_srp diff --git a/Documentation/ABI/stable/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup index c6a32c434ce9..792f58ba327d 100644 --- a/Documentation/ABI/stable/sysfs-driver-speakup +++ b/Documentation/ABI/stable/sysfs-driver-speakup @@ -69,6 +69,7 @@ Description: Controls if typing interrupts output from speakup. With speakup if for example the say screen command is used before the entire screen is read. + With no_interrupt set to one, if the say screen command is used, and one then types on the keyboard, speakup will continue to say the whole screen regardless until @@ -215,8 +216,10 @@ Description: This file contains names for key states. Again, these are part of the help system. For instance, if you had pressed speakup + keypad 3, you would hear: "speakup keypad 3 is go to bottom edge." + The speakup key is depressed, so the name of the key state is speakup. + This part of the message comes from the states collection. What: /sys/accessibility/speakup/i18n/characters @@ -297,6 +300,7 @@ KernelVersion: 2.6 Contact: speakup@linux-speakup.org Description: Controls if punctuation is spoken by speakup, or by the synthesizer. + For example, speakup speaks ">" as "greater", while the espeak synthesizer used by the soft driver speaks "greater than". Zero lets speakup speak the punctuation. One lets the diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars index 5def20b9019e..46ccd233e359 100644 --- a/Documentation/ABI/stable/sysfs-firmware-efi-vars +++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars @@ -17,6 +17,7 @@ Description: directory has a name of the form "<key>-<vendor guid>" and contains the following files: + =============== ======================================== attributes: A read-only text file enumerating the EFI variable flags. Potential values include: @@ -59,12 +60,14 @@ Description: size: As ASCII representation of the size of the variable's value. + =============== ======================================== In addition, two other magic binary files are provided in the top-level directory and are used for adding and removing variables: + =============== ======================================== new_var: Takes a "struct efi_variable" and instructs the EFI firmware to create a new variable. @@ -73,3 +76,4 @@ Description: instructs the EFI firmware to remove any variable that has a matching vendor GUID and variable key name. + =============== ======================================== diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump index 32fe7f5c4880..1f74f45327ba 100644 --- a/Documentation/ABI/stable/sysfs-firmware-opal-dump +++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump @@ -7,6 +7,7 @@ Description: This is only for the powerpc/powernv platform. + =============== =============================================== initiate_dump: When '1' is written to it, we will initiate a dump. Read this file for supported commands. @@ -19,8 +20,11 @@ Description: and ID of the dump, use the id and type files. Do not rely on any particular size of dump type or dump id. + =============== =============================================== Each dump has the following files: + + =============== =============================================== id: An ASCII representation of the dump ID in hex (e.g. '0x01') type: An ASCII representation of the type of @@ -39,3 +43,4 @@ Description: inaccessible. Reading this file will get a list of supported actions. + =============== =============================================== diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog index 2536434d49d0..7c8a61a2d005 100644 --- a/Documentation/ABI/stable/sysfs-firmware-opal-elog +++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog @@ -38,6 +38,7 @@ Description: For each log entry (directory), there are the following files: + ============== ================================================ id: An ASCII representation of the ID of the error log, in hex - e.g. "0x01". @@ -58,3 +59,4 @@ Description: entry will be removed from sysfs. Reading this file will list the supported operations (currently just acknowledge). + ============== ================================================ diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen index 3cf5cdfcd9a8..748593c64568 100644 --- a/Documentation/ABI/stable/sysfs-hypervisor-xen +++ b/Documentation/ABI/stable/sysfs-hypervisor-xen @@ -33,6 +33,8 @@ Description: If running under Xen: Space separated list of supported guest system types. Each type is in the format: <class>-<major>.<minor>-<arch> With: + + ======== ============================================ <class>: "xen" -- x86: paravirtualized, arm: standard "hvm" -- x86 only: fully virtualized <major>: major guest interface version @@ -43,6 +45,7 @@ Description: If running under Xen: "x86_64": 64 bit x86 guest "armv7l": 32 bit arm guest "aarch64": 64 bit arm guest + ======== ============================================ What: /sys/hypervisor/properties/changeset Date: March 2009 diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso index 55406ec8a35a..951838d42781 100644 --- a/Documentation/ABI/stable/vdso +++ b/Documentation/ABI/stable/vdso @@ -1,3 +1,9 @@ +What: vDSO +Date: July 2011 +KernelVersion: 3.0 +Contact: Andy Lutomirski <luto@kernel.org> +Description: + On some architectures, when the kernel loads any userspace program it maps an ELF DSO into that program's address space. This DSO is called the vDSO and it often contains useful and highly-optimized alternatives @@ -23,6 +29,7 @@ Unless otherwise noted, the set of symbols with any given version and the ABI of those symbols is considered stable. It may vary across architectures, though. -(As of this writing, this ABI documentation as been confirmed for x86_64. +Note: + As of this writing, this ABI documentation as been confirmed for x86_64. The maintainers of the other vDSO-using architectures should confirm - that it is correct for their architecture.) + that it is correct for their architecture. diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi index 4ab4e99aa863..c09b640c3cb1 100644 --- a/Documentation/ABI/testing/configfs-acpi +++ b/Documentation/ABI/testing/configfs-acpi @@ -14,7 +14,8 @@ Description: This group contains the configuration for user defined ACPI tables. The attributes of a user define table are: - aml - a binary attribute that the user can use to + aml + - a binary attribute that the user can use to fill in the ACPI aml definitions. Once the aml data is written to this file and the file is closed the table will be loaded and ACPI devices @@ -26,11 +27,26 @@ Description: The rest of the attributes are read-only and are valid only after the table has been loaded by filling the aml entry: - signature - ASCII table signature - length - length of table in bytes, including the header - revision - ACPI Specification minor version number - oem_id - ASCII OEM identification - oem_table_id - ASCII OEM table identification - oem_revision - OEM revision number - asl_compiler_id - ASCII ASL compiler vendor ID - asl_compiler_revision - ASL compiler version + signature + - ASCII table signature + + length + - length of table in bytes, including the header + + revision + - ACPI Specification minor version number + + oem_id + - ASCII OEM identification + + oem_table_id + - ASCII OEM table identification + + oem_revision + - OEM revision number + + asl_compiler_id + - ASCII ASL compiler vendor ID + + asl_compiler_revision + - ASL compiler version diff --git a/Documentation/ABI/testing/configfs-most b/Documentation/ABI/testing/configfs-most index ed67a4d9f6d6..bc6b8bd18da4 100644 --- a/Documentation/ABI/testing/configfs-most +++ b/Documentation/ABI/testing/configfs-most @@ -15,22 +15,28 @@ KernelVersion: 5.2 Description: The attributes: - buffer_size configure the buffer size for this channel + buffer_size + configure the buffer size for this channel - subbuffer_size configure the sub-buffer size for this channel + subbuffer_size + configure the sub-buffer size for this channel (needed for synchronous and isochrnous data) - num_buffers configure number of buffers used for this + num_buffers + configure number of buffers used for this channel - datatype configure type of data that will travel over + datatype + configure type of data that will travel over this channel - direction configure whether this link will be an input + direction + configure whether this link will be an input or output - dbr_size configure DBR data buffer size (this is used + dbr_size + configure DBR data buffer size (this is used for MediaLB communication only) packets_per_xact @@ -39,18 +45,23 @@ Description: transmitted via USB (this is used for USB communication only) - device name of the device the link is to be attached to + device + name of the device the link is to be attached to - channel name of the channel the link is to be attached to + channel + name of the channel the link is to be attached to - comp_params pass parameters needed by some components + comp_params + pass parameters needed by some components - create_link write '1' to this attribute to trigger the + create_link + write '1' to this attribute to trigger the creation of the link. In case of speculative configuration, the creation is post-poned until a physical device is being attached to the bus. - destroy_link write '1' to this attribute to destroy an + destroy_link + write '1' to this attribute to destroy an active link What: /sys/kernel/config/most_video/<link> @@ -59,22 +70,28 @@ KernelVersion: 5.2 Description: The attributes: - buffer_size configure the buffer size for this channel + buffer_size + configure the buffer size for this channel - subbuffer_size configure the sub-buffer size for this channel + subbuffer_size + configure the sub-buffer size for this channel (needed for synchronous and isochrnous data) - num_buffers configure number of buffers used for this + num_buffers + configure number of buffers used for this channel - datatype configure type of data that will travel over + datatype + configure type of data that will travel over this channel - direction configure whether this link will be an input + direction + configure whether this link will be an input or output - dbr_size configure DBR data buffer size (this is used + dbr_size + configure DBR data buffer size (this is used for MediaLB communication only) packets_per_xact @@ -83,18 +100,23 @@ Description: transmitted via USB (this is used for USB communication only) - device name of the device the link is to be attached to + device + name of the device the link is to be attached to - channel name of the channel the link is to be attached to + channel + name of the channel the link is to be attached to - comp_params pass parameters needed by some components + comp_params + pass parameters needed by some components - create_link write '1' to this attribute to trigger the + create_link + write '1' to this attribute to trigger the creation of the link. In case of speculative configuration, the creation is post-poned until a physical device is being attached to the bus. - destroy_link write '1' to this attribute to destroy an + destroy_link + write '1' to this attribute to destroy an active link What: /sys/kernel/config/most_net/<link> @@ -103,22 +125,28 @@ KernelVersion: 5.2 Description: The attributes: - buffer_size configure the buffer size for this channel + buffer_size + configure the buffer size for this channel - subbuffer_size configure the sub-buffer size for this channel + subbuffer_size + configure the sub-buffer size for this channel (needed for synchronous and isochrnous data) - num_buffers configure number of buffers used for this + num_buffers + configure number of buffers used for this channel - datatype configure type of data that will travel over + datatype + configure type of data that will travel over this channel - direction configure whether this link will be an input + direction + configure whether this link will be an input or output - dbr_size configure DBR data buffer size (this is used + dbr_size + configure DBR data buffer size (this is used for MediaLB communication only) packets_per_xact @@ -127,18 +155,23 @@ Description: transmitted via USB (this is used for USB communication only) - device name of the device the link is to be attached to + device + name of the device the link is to be attached to - channel name of the channel the link is to be attached to + channel + name of the channel the link is to be attached to - comp_params pass parameters needed by some components + comp_params + pass parameters needed by some components - create_link write '1' to this attribute to trigger the + create_link + write '1' to this attribute to trigger the creation of the link. In case of speculative configuration, the creation is post-poned until a physical device is being attached to the bus. - destroy_link write '1' to this attribute to destroy an + destroy_link + write '1' to this attribute to destroy an active link What: /sys/kernel/config/most_sound/<card> @@ -147,7 +180,8 @@ KernelVersion: 5.2 Description: The attributes: - create_card write '1' to this attribute to trigger the + create_card + write '1' to this attribute to trigger the registration of the sound card with the ALSA subsystem. @@ -157,22 +191,28 @@ KernelVersion: 5.2 Description: The attributes: - buffer_size configure the buffer size for this channel + buffer_size + configure the buffer size for this channel - subbuffer_size configure the sub-buffer size for this channel + subbuffer_size + configure the sub-buffer size for this channel (needed for synchronous and isochrnous data) - num_buffers configure number of buffers used for this + num_buffers + configure number of buffers used for this channel - datatype configure type of data that will travel over + datatype + configure type of data that will travel over this channel - direction configure whether this link will be an input + direction + configure whether this link will be an input or output - dbr_size configure DBR data buffer size (this is used + dbr_size + configure DBR data buffer size (this is used for MediaLB communication only) packets_per_xact @@ -181,16 +221,21 @@ Description: transmitted via USB (this is used for USB communication only) - device name of the device the link is to be attached to + device + name of the device the link is to be attached to - channel name of the channel the link is to be attached to + channel + name of the channel the link is to be attached to - comp_params pass parameters needed by some components + comp_params + pass parameters needed by some components - create_link write '1' to this attribute to trigger the + create_link + write '1' to this attribute to trigger the creation of the link. In case of speculative configuration, the creation is post-poned until a physical device is being attached to the bus. - destroy_link write '1' to this attribute to destroy an + destroy_link + write '1' to this attribute to destroy an active link diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget index 840c324ef34d..cf877bd341df 100644 --- a/Documentation/ABI/testing/configfs-spear-pcie-gadget +++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget @@ -10,22 +10,24 @@ Description: This interfaces can be used to show spear's PCIe device capability. Nodes are only visible when configfs is mounted. To mount configfs - in /config directory use: - # mount -t configfs none /config/ + in /config directory use:: - For nth PCIe Device Controller - /config/pcie-gadget.n/ - link ... used to enable ltssm and read its status. - int_type ...used to configure and read type of supported - interrupt - no_of_msi ... used to configure number of MSI vector needed and + # mount -t configfs none /config/ + + For nth PCIe Device Controller /config/pcie-gadget.n/: + + =============== ====================================================== + link used to enable ltssm and read its status. + int_type used to configure and read type of supported interrupt + no_of_msi used to configure number of MSI vector needed and to read no of MSI granted. - inta ... write 1 to assert INTA and 0 to de-assert. - send_msi ... write MSI vector to be sent. - vendor_id ... used to write and read vendor id (hex) - device_id ... used to write and read device id (hex) - bar0_size ... used to write and read bar0_size - bar0_address ... used to write and read bar0 mapped area in hex. - bar0_rw_offset ... used to write and read offset of bar0 where - bar0_data will be written or read. - bar0_data ... used to write and read data at bar0_rw_offset. + inta write 1 to assert INTA and 0 to de-assert. + send_msi write MSI vector to be sent. + vendor_id used to write and read vendor id (hex) + device_id used to write and read device id (hex) + bar0_size used to write and read bar0_size + bar0_address used to write and read bar0 mapped area in hex. + bar0_rw_offset used to write and read offset of bar0 where bar0_data + will be written or read. + bar0_data used to write and read data at bar0_rw_offset. + =============== ====================================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget index 4594cc2435e8..dc351e9af80a 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -12,22 +12,24 @@ Description: The attributes of a gadget: - UDC - bind a gadget to UDC/unbind a gadget; - write UDC's name found in /sys/class/udc/* - to bind a gadget, empty string "" to unbind. - - max_speed - maximum speed the driver supports. Valid - names are super-speed-plus, super-speed, - high-speed, full-speed, and low-speed. - - bDeviceClass - USB device class code - bDeviceSubClass - USB device subclass code - bDeviceProtocol - USB device protocol code - bMaxPacketSize0 - maximum endpoint 0 packet size - bcdDevice - bcd device release number - bcdUSB - bcd USB specification version number - idProduct - product ID - idVendor - vendor ID + ================ ============================================ + UDC bind a gadget to UDC/unbind a gadget; + write UDC's name found in /sys/class/udc/* + to bind a gadget, empty string "" to unbind. + + max_speed maximum speed the driver supports. Valid + names are super-speed-plus, super-speed, + high-speed, full-speed, and low-speed. + + bDeviceClass USB device class code + bDeviceSubClass USB device subclass code + bDeviceProtocol USB device protocol code + bMaxPacketSize0 maximum endpoint 0 packet size + bcdDevice bcd device release number + bcdUSB bcd USB specification version number + idProduct product ID + idVendor vendor ID + ================ ============================================ What: /config/usb-gadget/gadget/configs Date: Jun 2013 @@ -41,8 +43,10 @@ KernelVersion: 3.11 Description: The attributes of a configuration: - bmAttributes - configuration characteristics - MaxPower - maximum power consumption from the bus + ================ ====================================== + bmAttributes configuration characteristics + MaxPower maximum power consumption from the bus + ================ ====================================== What: /config/usb-gadget/gadget/configs/config/strings Date: Jun 2013 @@ -57,7 +61,9 @@ KernelVersion: 3.11 Description: The attributes: - configuration - configuration description + ================ ========================= + configuration configuration description + ================ ========================= What: /config/usb-gadget/gadget/functions @@ -76,8 +82,10 @@ Description: The attributes: - compatible_id - 8-byte string for "Compatible ID" - sub_compatible_id - 8-byte string for "Sub Compatible ID" + ================= ===================================== + compatible_id 8-byte string for "Compatible ID" + sub_compatible_id 8-byte string for "Sub Compatible ID" + ================= ===================================== What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property> Date: May 2014 @@ -89,16 +97,19 @@ Description: The attributes: - type - value 1..7 for interpreting the data - 1: unicode string - 2: unicode string with environment variable - 3: binary - 4: little-endian 32-bit - 5: big-endian 32-bit - 6: unicode string with a symbolic link - 7: multiple unicode strings - data - blob of data to be interpreted depending on + ===== =============================================== + type value 1..7 for interpreting the data + + - 1: unicode string + - 2: unicode string with environment variable + - 3: binary + - 4: little-endian 32-bit + - 5: big-endian 32-bit + - 6: unicode string with a symbolic link + - 7: multiple unicode strings + data blob of data to be interpreted depending on type + ===== =============================================== What: /config/usb-gadget/gadget/strings Date: Jun 2013 @@ -113,9 +124,11 @@ KernelVersion: 3.11 Description: The attributes: - serialnumber - gadget's serial number (string) - product - gadget's product description - manufacturer - gadget's manufacturer description + ============ ================================= + serialnumber gadget's serial number (string) + product gadget's product description + manufacturer gadget's manufacturer description + ============ ================================= What: /config/usb-gadget/gadget/os_desc Date: May 2014 @@ -123,8 +136,10 @@ KernelVersion: 3.16 Description: This group contains "OS String" extension handling attributes. - use - flag turning "OS Desctiptors" support on/off - b_vendor_code - one-byte value used for custom per-device and + ============= =============================================== + use flag turning "OS Desctiptors" support on/off + b_vendor_code one-byte value used for custom per-device and per-interface requests - qw_sign - an identifier to be reported as "OS String" + qw_sign an identifier to be reported as "OS String" proper + ============= =============================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm index 0addf7704b4c..272bc1e4ce2e 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-ecm +++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm @@ -4,13 +4,17 @@ KernelVersion: 3.11 Description: The attributes: - ifname - network device interface name associated with + ifname + - network device interface name associated with this function instance - qmult - queue length multiplier for high and + qmult + - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + host_addr + - MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr + - MAC address of device's end of this Ethernet over USB link diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem index a4c57158fcde..178c3d5fb647 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-eem +++ b/Documentation/ABI/testing/configfs-usb-gadget-eem @@ -4,11 +4,13 @@ KernelVersion: 3.11 Description: The attributes: - ifname - network device interface name associated with + ========== ============================================= + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and + qmult queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + ========== ============================================= diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid index f12e00e6baa3..748705c4cb58 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-hid +++ b/Documentation/ABI/testing/configfs-usb-gadget-hid @@ -4,8 +4,10 @@ KernelVersion: 3.19 Description: The attributes: - protocol - HID protocol to use - report_desc - blob corresponding to HID report descriptors + ============= ============================================ + protocol HID protocol to use + report_desc blob corresponding to HID report descriptors except the data passed through /dev/hidg<N> - report_length - HID report length - subclass - HID device subclass to use + report_length HID report length + subclass HID device subclass to use + ============= ============================================ diff --git a/Documentation/ABI/testing/configfs-usb-gadget-loopback b/Documentation/ABI/testing/configfs-usb-gadget-loopback index 06beefbcf061..e6c6ba5ac7ff 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-loopback +++ b/Documentation/ABI/testing/configfs-usb-gadget-loopback @@ -4,5 +4,7 @@ KernelVersion: 3.13 Description: The attributes: - qlen - depth of loopback queue - buflen - buffer length + ======= ======================= + qlen depth of loopback queue + buflen buffer length + ======= ======================= diff --git a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage index 9931fb0d63ba..c86b63a7bb43 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage +++ b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage @@ -4,12 +4,14 @@ KernelVersion: 3.13 Description: The attributes: - stall - Set to permit function to halt bulk endpoints. + =========== ============================================== + stall Set to permit function to halt bulk endpoints. Disabled on some USB devices known not to work correctly. You should set it to true. - num_buffers - Number of pipeline buffers. Valid numbers + num_buffers Number of pipeline buffers. Valid numbers are 2..4. Available only if CONFIG_USB_GADGET_DEBUG_FILES is set. + =========== ============================================== What: /config/usb-gadget/gadget/functions/mass_storage.name/lun.name Date: Oct 2013 @@ -17,15 +19,17 @@ KernelVersion: 3.13 Description: The attributes: - file - The path to the backing file for the LUN. + =========== ============================================== + file The path to the backing file for the LUN. Required if LUN is not marked as removable. - ro - Flag specifying access to the LUN shall be + ro Flag specifying access to the LUN shall be read-only. This is implied if CD-ROM emulation is enabled as well as when it was impossible to open "filename" in R/W mode. - removable - Flag specifying that LUN shall be indicated as + removable Flag specifying that LUN shall be indicated as being removable. - cdrom - Flag specifying that LUN shall be reported as + cdrom Flag specifying that LUN shall be reported as being a CD-ROM. - nofua - Flag specifying that FUA flag + nofua Flag specifying that FUA flag in SCSI WRITE(10,12) + =========== ============================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi index 6b341df7249c..07389cddd51a 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-midi +++ b/Documentation/ABI/testing/configfs-usb-gadget-midi @@ -4,9 +4,11 @@ KernelVersion: 3.19 Description: The attributes: - index - index value for the USB MIDI adapter - id - ID string for the USB MIDI adapter - buflen - MIDI buffer length - qlen - USB read request queue length - in_ports - number of MIDI input ports - out_ports - number of MIDI output ports + ========== ==================================== + index index value for the USB MIDI adapter + id ID string for the USB MIDI adapter + buflen MIDI buffer length + qlen USB read request queue length + in_ports number of MIDI input ports + out_ports number of MIDI output ports + ========== ==================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-printer b/Documentation/ABI/testing/configfs-usb-gadget-printer index 6b0714e3c605..7aa731bac2da 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-printer +++ b/Documentation/ABI/testing/configfs-usb-gadget-printer @@ -4,6 +4,8 @@ KernelVersion: 4.1 Description: The attributes: - pnp_string - Data to be passed to the host in pnp string - q_len - Number of requests per endpoint + ========== =========================================== + pnp_string Data to be passed to the host in pnp string + q_len Number of requests per endpoint + ========== =========================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis index 137399095d74..9416eda7fe93 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-rndis +++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis @@ -4,14 +4,16 @@ KernelVersion: 3.11 Description: The attributes: - ifname - network device interface name associated with + ========= ============================================= + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and + qmult queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link - class - USB interface class, default is 02 (hex) - subclass - USB interface subclass, default is 06 (hex) - protocol - USB interface protocol, default is 00 (hex) + class USB interface class, default is 02 (hex) + subclass USB interface subclass, default is 06 (hex) + protocol USB interface protocol, default is 00 (hex) + ========= ============================================= diff --git a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink index f56335af2d88..1f3d31b607b7 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink +++ b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink @@ -4,11 +4,13 @@ KernelVersion: 3.13 Description: The attributes: - pattern - 0 (all zeros), 1 (mod63), 2 (none) - isoc_interval - 1..16 - isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss) - isoc_mult - 0..2 (hs/ss only) - isoc_maxburst - 0..15 (ss only) - buflen - buffer length - bulk_qlen - depth of queue for bulk - iso_qlen - depth of queue for iso + ============== ================================== + pattern 0 (all zeros), 1 (mod63), 2 (none) + isoc_interval 1..16 + isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) + isoc_mult 0..2 (hs/ss only) + isoc_maxburst 0..15 (ss only) + buflen buffer length + bulk_qlen depth of queue for bulk + iso_qlen depth of queue for iso + ============== ================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset index 9373e2c51ea4..0061b864351f 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-subset +++ b/Documentation/ABI/testing/configfs-usb-gadget-subset @@ -4,11 +4,13 @@ KernelVersion: 3.11 Description: The attributes: - ifname - network device interface name associated with + ========== ============================================= + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and + qmult queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + ========== ============================================= diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1 index abfe447c848f..dc23fd776943 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac1 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1 @@ -4,11 +4,13 @@ KernelVersion: 4.14 Description: The attributes: - c_chmask - capture channel mask - c_srate - capture sampling rate - c_ssize - capture sample size (bytes) - p_chmask - playback channel mask - p_srate - playback sampling rate - p_ssize - playback sample size (bytes) - req_number - the number of pre-allocated request - for both capture and playback + ========== =================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + req_number the number of pre-allocated request + for both capture and playback + ========== =================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 index 2bfdd4efa9bd..d4356c8b8cd6 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac2 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2 @@ -4,9 +4,11 @@ KernelVersion: 3.18 Description: The attributes: - c_chmask - capture channel mask - c_srate - capture sampling rate - c_ssize - capture sample size (bytes) - p_chmask - playback channel mask - p_srate - playback sampling rate - p_ssize - playback sample size (bytes) + ========= ============================ + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + ========= ============================ diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc index 809765bd9573..ac5e11af79a8 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uvc +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc @@ -3,9 +3,11 @@ Date: Dec 2014 KernelVersion: 4.0 Description: UVC function directory - streaming_maxburst - 0..15 (ss only) - streaming_maxpacket - 1..1023 (fs), 1..3072 (hs/ss) - streaming_interval - 1..16 + =================== ============================= + streaming_maxburst 0..15 (ss only) + streaming_maxpacket 1..1023 (fs), 1..3072 (hs/ss) + streaming_interval 1..16 + =================== ============================= What: /config/usb-gadget/gadget/functions/uvc.name/control Date: Dec 2014 @@ -13,8 +15,11 @@ KernelVersion: 4.0 Description: Control descriptors All attributes read only: - bInterfaceNumber - USB interface number for this - streaming interface + + ================ ============================= + bInterfaceNumber USB interface number for this + streaming interface + ================ ============================= What: /config/usb-gadget/gadget/functions/uvc.name/control/class Date: Dec 2014 @@ -47,13 +52,16 @@ KernelVersion: 4.0 Description: Default output terminal descriptors All attributes read only: - iTerminal - index of string descriptor - bSourceID - id of the terminal to which this terminal + + ============== ============================================= + iTerminal index of string descriptor + bSourceID id of the terminal to which this terminal is connected - bAssocTerminal - id of the input terminal to which this output + bAssocTerminal id of the input terminal to which this output terminal is associated - wTerminalType - terminal type - bTerminalID - a non-zero id of this terminal + wTerminalType terminal type + bTerminalID a non-zero id of this terminal + ============== ============================================= What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera Date: Dec 2014 @@ -66,16 +74,19 @@ KernelVersion: 4.0 Description: Default camera terminal descriptors All attributes read only: - bmControls - bitmap specifying which controls are - supported for the video stream - wOcularFocalLength - the value of Locular - wObjectiveFocalLengthMax- the value of Lmin - wObjectiveFocalLengthMin- the value of Lmax - iTerminal - index of string descriptor - bAssocTerminal - id of the output terminal to which - this terminal is connected - wTerminalType - terminal type - bTerminalID - a non-zero id of this terminal + + ======================== ==================================== + bmControls bitmap specifying which controls are + supported for the video stream + wOcularFocalLength the value of Locular + wObjectiveFocalLengthMax the value of Lmin + wObjectiveFocalLengthMin the value of Lmax + iTerminal index of string descriptor + bAssocTerminal id of the output terminal to which + this terminal is connected + wTerminalType terminal type + bTerminalID a non-zero id of this terminal + ======================== ==================================== What: /config/usb-gadget/gadget/functions/uvc.name/control/processing Date: Dec 2014 @@ -88,13 +99,16 @@ KernelVersion: 4.0 Description: Default processing unit descriptors All attributes read only: - iProcessing - index of string descriptor - bmControls - bitmap specifying which controls are + + =============== ======================================== + iProcessing index of string descriptor + bmControls bitmap specifying which controls are supported for the video stream - wMaxMultiplier - maximum digital magnification x100 - bSourceID - id of the terminal to which this unit is + wMaxMultiplier maximum digital magnification x100 + bSourceID id of the terminal to which this unit is connected - bUnitID - a non-zero id of this unit + bUnitID a non-zero id of this unit + =============== ======================================== What: /config/usb-gadget/gadget/functions/uvc.name/control/header Date: Dec 2014 @@ -114,8 +128,11 @@ KernelVersion: 4.0 Description: Streaming descriptors All attributes read only: - bInterfaceNumber - USB interface number for this - streaming interface + + ================ ============================= + bInterfaceNumber USB interface number for this + streaming interface + ================ ============================= What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class Date: Dec 2014 @@ -148,13 +165,16 @@ KernelVersion: 4.0 Description: Default color matching descriptors All attributes read only: - bMatrixCoefficients - matrix used to compute luma and - chroma values from the color primaries - bTransferCharacteristics- optoelectronic transfer - characteristic of the source picutre, - also called the gamma function - bColorPrimaries - color primaries and the reference - white + + ======================== ====================================== + bMatrixCoefficients matrix used to compute luma and + chroma values from the color primaries + bTransferCharacteristics optoelectronic transfer + characteristic of the source picutre, + also called the gamma function + bColorPrimaries color primaries and the reference + white + ======================== ====================================== What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg Date: Dec 2014 @@ -168,47 +188,52 @@ Description: Specific MJPEG format descriptors All attributes read only, except bmaControls and bDefaultFrameIndex: - bFormatIndex - unique id for this format descriptor; + + =================== ===================================== + bFormatIndex unique id for this format descriptor; only defined after parent header is linked into the streaming class; read-only - bmaControls - this format's data for bmaControls in + bmaControls this format's data for bmaControls in the streaming header - bmInterfaceFlags - specifies interlace information, + bmInterfaceFlags specifies interlace information, read-only - bAspectRatioY - the X dimension of the picture aspect + bAspectRatioY the X dimension of the picture aspect ratio, read-only - bAspectRatioX - the Y dimension of the picture aspect + bAspectRatioX the Y dimension of the picture aspect ratio, read-only - bmFlags - characteristics of this format, + bmFlags characteristics of this format, read-only - bDefaultFrameIndex - optimum frame index for this stream + bDefaultFrameIndex optimum frame index for this stream + =================== ===================================== What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name Date: Dec 2014 KernelVersion: 4.0 Description: Specific MJPEG frame descriptors - bFrameIndex - unique id for this framedescriptor; - only defined after parent format is - linked into the streaming header; - read-only - dwFrameInterval - indicates how frame interval can be - programmed; a number of values - separated by newline can be specified - dwDefaultFrameInterval - the frame interval the device would - like to use as default - dwMaxVideoFrameBufferSize- the maximum number of bytes the - compressor will produce for a video - frame or still image - dwMaxBitRate - the maximum bit rate at the shortest - frame interval in bps - dwMinBitRate - the minimum bit rate at the longest - frame interval in bps - wHeight - height of decoded bitmap frame in px - wWidth - width of decoded bitmam frame in px - bmCapabilities - still image support, fixed frame-rate - support + ========================= ===================================== + bFrameIndex unique id for this framedescriptor; + only defined after parent format is + linked into the streaming header; + read-only + dwFrameInterval indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate the minimum bit rate at the longest + frame interval in bps + wHeight height of decoded bitmap frame in px + wWidth width of decoded bitmam frame in px + bmCapabilities still image support, fixed frame-rate + support + ========================= ===================================== What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed Date: Dec 2014 @@ -220,50 +245,54 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Specific uncompressed format descriptors - bFormatIndex - unique id for this format descriptor; + ================== ======================================= + bFormatIndex unique id for this format descriptor; only defined after parent header is linked into the streaming class; read-only - bmaControls - this format's data for bmaControls in + bmaControls this format's data for bmaControls in the streaming header - bmInterfaceFlags - specifies interlace information, + bmInterfaceFlags specifies interlace information, read-only - bAspectRatioY - the X dimension of the picture aspect + bAspectRatioY the X dimension of the picture aspect ratio, read-only - bAspectRatioX - the Y dimension of the picture aspect + bAspectRatioX the Y dimension of the picture aspect ratio, read-only - bDefaultFrameIndex - optimum frame index for this stream - bBitsPerPixel - number of bits per pixel used to + bDefaultFrameIndex optimum frame index for this stream + bBitsPerPixel number of bits per pixel used to specify color in the decoded video frame - guidFormat - globally unique id used to identify + guidFormat globally unique id used to identify stream-encoding format + ================== ======================================= What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name Date: Dec 2014 KernelVersion: 4.0 Description: Specific uncompressed frame descriptors - bFrameIndex - unique id for this framedescriptor; - only defined after parent format is - linked into the streaming header; - read-only - dwFrameInterval - indicates how frame interval can be - programmed; a number of values - separated by newline can be specified - dwDefaultFrameInterval - the frame interval the device would - like to use as default - dwMaxVideoFrameBufferSize- the maximum number of bytes the - compressor will produce for a video - frame or still image - dwMaxBitRate - the maximum bit rate at the shortest - frame interval in bps - dwMinBitRate - the minimum bit rate at the longest - frame interval in bps - wHeight - height of decoded bitmap frame in px - wWidth - width of decoded bitmam frame in px - bmCapabilities - still image support, fixed frame-rate - support + ========================= ===================================== + bFrameIndex unique id for this framedescriptor; + only defined after parent format is + linked into the streaming header; + read-only + dwFrameInterval indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate the minimum bit rate at the longest + frame interval in bps + wHeight height of decoded bitmap frame in px + wWidth width of decoded bitmam frame in px + bmCapabilities still image support, fixed frame-rate + support + ========================= ===================================== What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header Date: Dec 2014 @@ -276,17 +305,20 @@ KernelVersion: 4.0 Description: Specific streaming header descriptors All attributes read only: - bTriggerUsage - how the host software will respond to + + ==================== ===================================== + bTriggerUsage how the host software will respond to a hardware trigger interrupt event - bTriggerSupport - flag specifying if hardware + bTriggerSupport flag specifying if hardware triggering is supported - bStillCaptureMethod - method of still image caputre + bStillCaptureMethod method of still image caputre supported - bTerminalLink - id of the output terminal to which + bTerminalLink id of the output terminal to which the video endpoint of this interface is connected - bmInfo - capabilities of this video streaming + bmInfo capabilities of this video streaming interface + ==================== ===================================== What: /sys/class/udc/udc.name/device/gadget/video4linux/video.name/function_name Date: May 2018 diff --git a/Documentation/ABI/testing/debugfs-cec-error-inj b/Documentation/ABI/testing/debugfs-cec-error-inj index 5afcd78fbdb7..8debcb08a3b5 100644 --- a/Documentation/ABI/testing/debugfs-cec-error-inj +++ b/Documentation/ABI/testing/debugfs-cec-error-inj @@ -23,7 +23,7 @@ error injections without having to know the details of the driver-specific commands. Note that the output of 'error-inj' shall be valid as input to 'error-inj'. -So this must work: +So this must work:: $ cat error-inj >einj.txt $ cat einj.txt >error-inj diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index 2e9ae311e02d..c5d678d39144 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -20,9 +20,13 @@ Description: Allow the root user to disable/enable in runtime the clock The user can supply a bitmask value, each bit represents a different engine to disable/enable its clock gating feature. The bitmask is composed of 20 bits: - 0 - 7 : DMA channels - 8 - 11 : MME engines - 12 - 19 : TPC engines + + ======= ============ + 0 - 7 DMA channels + 8 - 11 MME engines + 12 - 19 TPC engines + ======= ============ + The bit's location of a specific engine can be determined using (1 << GAUDI_ENGINE_ID_*). GAUDI_ENGINE_ID_* values are defined in uapi habanalabs.h file in enum gaudi_engine_id @@ -59,6 +63,7 @@ Description: Allows the root user to read or write directly through the the generic Linux user-space PCI mapping) because the DDR bar is very small compared to the DDR memory and only the driver can move the bar before and after the transaction. + If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory @@ -73,6 +78,7 @@ Description: Allows the root user to read or write 64 bit data directly the generic Linux user-space PCI mapping) because the DDR bar is very small compared to the DDR memory and only the driver can move the bar before and after the transaction. + If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec index 6546115a94da..ab6099daa8f5 100644 --- a/Documentation/ABI/testing/debugfs-ec +++ b/Documentation/ABI/testing/debugfs-ec @@ -6,7 +6,7 @@ Description: General information like which GPE is assigned to the EC and whether the global lock should get used. Knowing the EC GPE one can watch the amount of HW events related to -the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe): +the EC here (XY -> GPE number from `/sys/kernel/debug/ec/*/gpe`): /sys/firmware/acpi/interrupts/gpeXY The io file is binary and a userspace tool located here: @@ -14,7 +14,8 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec/ should get used to read out the 256 Embedded Controller registers or writing to them. -CAUTION: Do not write to the Embedded Controller if you don't know -what you are doing! Rebooting afterwards also is a good idea. -This can influence the way your machine is cooled and fans may -not get switched on again after you did a wrong write. +CAUTION: + Do not write to the Embedded Controller if you don't know + what you are doing! Rebooting afterwards also is a good idea. + This can influence the way your machine is cooled and fans may + not get switched on again after you did a wrong write. diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet index 67b1717794d8..6eee10c3d5a1 100644 --- a/Documentation/ABI/testing/debugfs-moxtet +++ b/Documentation/ABI/testing/debugfs-moxtet @@ -2,13 +2,19 @@ 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. +Description: (Read) 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 + + 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 @@ -17,7 +23,13 @@ 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 + + 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/debugfs-pfo-nx-crypto b/Documentation/ABI/testing/debugfs-pfo-nx-crypto index 685d5a448423..f75a655c1531 100644 --- a/Documentation/ABI/testing/debugfs-pfo-nx-crypto +++ b/Documentation/ABI/testing/debugfs-pfo-nx-crypto @@ -4,42 +4,42 @@ KernelVersion: 3.4 Contact: Kent Yoder <key@linux.vnet.ibm.com> Description: - These debugfs interfaces are built by the nx-crypto driver, built in +These debugfs interfaces are built by the nx-crypto driver, built in arch/powerpc/crypto/nx. Error Detection =============== errors: -- A u32 providing a total count of errors since the driver was loaded. The -only errors counted here are those returned from the hcall, H_COP_OP. + A u32 providing a total count of errors since the driver was loaded. The + only errors counted here are those returned from the hcall, H_COP_OP. last_error: -- The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not -recorded here (the hcall will retry until -EBUSY goes away). + The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not + recorded here (the hcall will retry until -EBUSY goes away). last_error_pid: -- The process ID of the process who received the most recent error from the -hcall. + The process ID of the process who received the most recent error from the + hcall. Device Use ========== aes_bytes: -- The total number of bytes encrypted using AES in any of the driver's -supported modes. + The total number of bytes encrypted using AES in any of the driver's + supported modes. aes_ops: -- The total number of AES operations submitted to the hardware. + The total number of AES operations submitted to the hardware. sha256_bytes: -- The total number of bytes hashed by the hardware using SHA-256. + The total number of bytes hashed by the hardware using SHA-256. sha256_ops: -- The total number of SHA-256 operations submitted to the hardware. + The total number of SHA-256 operations submitted to the hardware. sha512_bytes: -- The total number of bytes hashed by the hardware using SHA-512. + The total number of bytes hashed by the hardware using SHA-512. sha512_ops: -- The total number of SHA-512 operations submitted to the hardware. + The total number of SHA-512 operations submitted to the hardware. diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd index cf11736acb76..f6f65a4faea0 100644 --- a/Documentation/ABI/testing/debugfs-pktcdvd +++ b/Documentation/ABI/testing/debugfs-pktcdvd @@ -4,16 +4,15 @@ KernelVersion: 2.6.20 Contact: Thomas Maier <balagi@justmail.de> Description: -debugfs interface ------------------ - The pktcdvd module (packet writing driver) creates these files in debugfs: /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/ - info (0444) Lots of driver statistics and infos. -Example: -------- + ==== ====== ==================================== + info 0444 Lots of driver statistics and infos. + ==== ====== ==================================== + +Example:: -cat /sys/kernel/debug/pktcdvd/pktcdvd0/info + cat /sys/kernel/debug/pktcdvd/pktcdvd0/info diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm index 2b3255ee68fd..326df1b74707 100644 --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm @@ -2,8 +2,13 @@ What: /sys/kernel/debug/turris-mox-rwtm/do_sign Date: Jun 2020 KernelVersion: 5.8 Contact: Marek Behún <marek.behun@nic.cz> -Description: (W) Message to sign with the ECDSA private key stored in - device's OTP. The message must be exactly 64 bytes (since - this is intended for SHA-512 hashes). - (R) The resulting signature, 136 bytes. This contains the R and - S values of the ECDSA signature, both in big-endian format. +Description: + + ======= =========================================================== + (Write) Message to sign with the ECDSA private key stored in + device's OTP. The message must be exactly 64 bytes + (since this is intended for SHA-512 hashes). + (Read) The resulting signature, 136 bytes. This contains the + R and S values of the ECDSA signature, both in + big-endian format. + ======= =========================================================== diff --git a/Documentation/ABI/testing/debugfs-wilco-ec b/Documentation/ABI/testing/debugfs-wilco-ec index 9d8d9d2def5b..682e3c09ef4d 100644 --- a/Documentation/ABI/testing/debugfs-wilco-ec +++ b/Documentation/ABI/testing/debugfs-wilco-ec @@ -27,16 +27,17 @@ Description: for writing, two for the type and at least a single byte of data. - Example: - // Request EC info type 3 (EC firmware build date) - // Corresponds with sending type 0x00f0 with - // MBOX = [38, 00, 03, 00] - $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw - // View the result. The decoded ASCII result "12/21/18" is - // included after the raw hex. - // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...] - $ cat /sys/kernel/debug/wilco_ec/raw - 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8... + Example:: + + // Request EC info type 3 (EC firmware build date) + // Corresponds with sending type 0x00f0 with + // MBOX = [38, 00, 03, 00] + $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw + // View the result. The decoded ASCII result "12/21/18" is + // included after the raw hex. + // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...] + $ cat /sys/kernel/debug/wilco_ec/raw + 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8... Note that the first 16 bytes of the received MBOX[] will be printed, even if some of the data is junk, and skipping bytes diff --git a/Documentation/ABI/testing/dell-smbios-wmi b/Documentation/ABI/testing/dell-smbios-wmi index fc919ce16008..5f3a0dc67050 100644 --- a/Documentation/ABI/testing/dell-smbios-wmi +++ b/Documentation/ABI/testing/dell-smbios-wmi @@ -10,29 +10,29 @@ Description: <uapi/linux/wmi.h> 1) To perform an SMBIOS call from userspace, you'll need to - first determine the minimum size of the calling interface - buffer for your machine. - Platforms that contain larger buffers can return larger - objects from the system firmware. - Commonly this size is either 4k or 32k. + first determine the minimum size of the calling interface + buffer for your machine. + Platforms that contain larger buffers can return larger + objects from the system firmware. + Commonly this size is either 4k or 32k. - To determine the size of the buffer read() a u64 dword from - the WMI character device /dev/wmi/dell-smbios. + To determine the size of the buffer read() a u64 dword from + the WMI character device /dev/wmi/dell-smbios. 2) After you've determined the minimum size of the calling - interface buffer, you can allocate a structure that represents - the structure documented above. + interface buffer, you can allocate a structure that represents + the structure documented above. 3) In the 'length' object store the size of the buffer you - determined above and allocated. + determined above and allocated. 4) In this buffer object, prepare as necessary for the SMBIOS - call you're interested in. Typically SMBIOS buffers have - "class", "select", and "input" defined to values that coincide - with the data you are interested in. - Documenting class/select/input values is outside of the scope - of this documentation. Check with the libsmbios project for - further documentation on these values. + call you're interested in. Typically SMBIOS buffers have + "class", "select", and "input" defined to values that coincide + with the data you are interested in. + Documenting class/select/input values is outside of the scope + of this documentation. Check with the libsmbios project for + further documentation on these values. 6) Run the call by using ioctl() as described in the header. diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg index 3c0bb76e3417..a377b6c093c9 100644 --- a/Documentation/ABI/testing/dev-kmsg +++ b/Documentation/ABI/testing/dev-kmsg @@ -6,6 +6,7 @@ Description: The /dev/kmsg character device node provides userspace access to the kernel's printk buffer. Injecting messages: + Every write() to the opened device node places a log entry in the kernel's printk buffer. @@ -21,6 +22,7 @@ Description: The /dev/kmsg character device node provides userspace access the messages can always be reliably determined. Accessing the buffer: + Every read() from the opened device node receives one record of the kernel's printk buffer. @@ -48,6 +50,7 @@ Description: The /dev/kmsg character device node provides userspace access if needed, without limiting the interface to a single reader. The device supports seek with the following parameters: + SEEK_SET, 0 seek to the first entry in the buffer SEEK_END, 0 @@ -87,18 +90,22 @@ Description: The /dev/kmsg character device node provides userspace access readable context of the message, for reliable processing in userspace. - Example: - 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) - SUBSYSTEM=acpi - DEVICE=+acpi:PNP0A03:00 - 6,339,5140900,-;NET: Registered protocol family 10 - 30,340,5690716,-;udevd[80]: starting version 181 + Example:: + + 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) + SUBSYSTEM=acpi + DEVICE=+acpi:PNP0A03:00 + 6,339,5140900,-;NET: Registered protocol family 10 + 30,340,5690716,-;udevd[80]: starting version 181 The DEVICE= key uniquely identifies devices the following way: - b12:8 - block dev_t - c127:3 - char dev_t - n8 - netdev ifindex - +sound:card0 - subsystem:devname + + ============ ================= + b12:8 block dev_t + c127:3 char dev_t + n8 netdev ifindex + +sound:card0 subsystem:devname + ============ ================= The flags field carries '-' by default. A 'c' indicates a fragment of a line. Note, that these hints about continuation diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm index 201d10319fa1..3c477ba48a31 100644 --- a/Documentation/ABI/testing/evm +++ b/Documentation/ABI/testing/evm @@ -17,26 +17,33 @@ Description: echoing a value to <securityfs>/evm made up of the following bits: + === ================================================== Bit Effect + === ================================================== 0 Enable HMAC validation and creation 1 Enable digital signature validation 2 Permit modification of EVM-protected metadata at runtime. Not supported if HMAC validation and creation is enabled. 31 Disable further runtime modification of EVM policy + === ================================================== - For example: + For example:: - echo 1 ><securityfs>/evm + echo 1 ><securityfs>/evm will enable HMAC validation and creation - echo 0x80000003 ><securityfs>/evm + :: + + echo 0x80000003 ><securityfs>/evm will enable HMAC and digital signature validation and HMAC creation and disable all further modification of policy. - echo 0x80000006 ><securityfs>/evm + :: + + echo 0x80000006 ><securityfs>/evm will enable digital signature validation, permit modification of EVM-protected metadata and @@ -65,7 +72,7 @@ Description: Shows the set of extended attributes used to calculate or validate the EVM signature, and allows additional attributes to be added at runtime. Any signatures generated after - additional attributes are added (and on files posessing those + additional attributes are added (and on files possessing those additional attributes) will only be valid if the same additional attributes are configured on system boot. Writing a single period (.) will lock the xattr list from any further diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev index 7b265fbb47e3..66bdcd188b6c 100644 --- a/Documentation/ABI/testing/gpio-cdev +++ b/Documentation/ABI/testing/gpio-cdev @@ -12,15 +12,16 @@ Description: The following file operations are supported: open(2) - Currently the only useful flags are O_RDWR. + Currently the only useful flags are O_RDWR. ioctl(2) - Initiate various actions. - See the inline documentation in [include/uapi]<linux/gpio.h> - for descriptions of all ioctls. + Initiate various actions. + + See the inline documentation in [include/uapi]<linux/gpio.h> + for descriptions of all ioctls. close(2) - Stops and free up the I/O contexts that was associated - with the file descriptor. + Stops and free up the I/O contexts that was associated + with the file descriptor. Users: TBD diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index cd572912c593..e35263f97fc1 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -15,19 +15,22 @@ Description: IMA appraisal, if configured, uses these file measurements for local measurement appraisal. - rule format: action [condition ...] + :: - action: measure | dont_measure | appraise | dont_appraise | - audit | hash | dont_hash - condition:= base | lsm [option] + rule format: action [condition ...] + + action: measure | dont_measure | appraise | dont_appraise | + audit | hash | dont_hash + condition:= base | lsm [option] base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=] [euid=] [fowner=] [fsname=]] lsm: [[subj_user=] [subj_role=] [subj_type=] [obj_user=] [obj_role=] [obj_type=]] option: [[appraise_type=]] [template=] [permit_directio] [appraise_flag=] [keyrings=] - base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK] - [FIRMWARE_CHECK] + base: + func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK]MODULE_CHECK] + [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] [KEXEC_CMDLINE] [KEY_CHECK] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] @@ -37,8 +40,9 @@ Description: uid:= decimal value euid:= decimal value fowner:= decimal value - lsm: are LSM specific - option: appraise_type:= [imasig] [imasig|modsig] + lsm: are LSM specific + option: + appraise_type:= [imasig] [imasig|modsig] appraise_flag:= [check_blacklist] Currently, blacklist check is only for files signed with appended signature. @@ -49,7 +53,7 @@ Description: (eg, ima-ng). Only valid when action is "measure". pcr:= decimal value - default policy: + default policy: # PROC_SUPER_MAGIC dont_measure fsmagic=0x9fa0 dont_appraise fsmagic=0x9fa0 @@ -97,7 +101,8 @@ Description: Examples of LSM specific definitions: - SELinux: + SELinux:: + dont_measure obj_type=var_log_t dont_appraise obj_type=var_log_t dont_measure obj_type=auditd_log_t @@ -105,10 +110,11 @@ Description: measure subj_user=system_u func=FILE_CHECK mask=MAY_READ measure subj_role=system_r func=FILE_CHECK mask=MAY_READ - Smack: + Smack:: + measure subj_user=_ func=FILE_CHECK mask=MAY_READ - Example of measure rules using alternate PCRs: + Example of measure rules using alternate PCRs:: measure func=KEXEC_KERNEL_CHECK pcr=4 measure func=KEXEC_INITRAMFS_CHECK pcr=5 diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats index 70dcaf2481f4..e58d641443d3 100644 --- a/Documentation/ABI/testing/procfs-diskstats +++ b/Documentation/ABI/testing/procfs-diskstats @@ -6,32 +6,38 @@ Description: of block devices. Each line contains the following 14 fields: - 1 - major number - 2 - minor mumber - 3 - device name - 4 - reads completed successfully - 5 - reads merged - 6 - sectors read - 7 - time spent reading (ms) - 8 - writes completed - 9 - writes merged - 10 - sectors written - 11 - time spent writing (ms) - 12 - I/Os currently in progress - 13 - time spent doing I/Os (ms) - 14 - weighted time spent doing I/Os (ms) + == =================================== + 1 major number + 2 minor mumber + 3 device name + 4 reads completed successfully + 5 reads merged + 6 sectors read + 7 time spent reading (ms) + 8 writes completed + 9 writes merged + 10 sectors written + 11 time spent writing (ms) + 12 I/Os currently in progress + 13 time spent doing I/Os (ms) + 14 weighted time spent doing I/Os (ms) + == =================================== Kernel 4.18+ appends four more fields for discard tracking putting the total at 18: - 15 - discards completed successfully - 16 - discards merged - 17 - sectors discarded - 18 - time spent discarding + == =================================== + 15 discards completed successfully + 16 discards merged + 17 sectors discarded + 18 time spent discarding + == =================================== Kernel 5.5+ appends two more fields for flush requests: - 19 - flush requests completed successfully - 20 - time spent flushing + == ===================================== + 19 flush requests completed successfully + 20 time spent flushing + == ===================================== For more details refer to Documentation/admin-guide/iostats.rst diff --git a/Documentation/ABI/testing/procfs-smaps_rollup b/Documentation/ABI/testing/procfs-smaps_rollup index 046978193368..a4e31c465194 100644 --- a/Documentation/ABI/testing/procfs-smaps_rollup +++ b/Documentation/ABI/testing/procfs-smaps_rollup @@ -14,28 +14,28 @@ Description: For more details, see Documentation/filesystems/proc.rst and the procfs man page. - Typical output looks like this: + Typical output looks like this:: - 00100000-ff709000 ---p 00000000 00:00 0 [rollup] - Size: 1192 kB - KernelPageSize: 4 kB - MMUPageSize: 4 kB - Rss: 884 kB - Pss: 385 kB - Pss_Anon: 301 kB - Pss_File: 80 kB - Pss_Shmem: 4 kB - Shared_Clean: 696 kB - Shared_Dirty: 0 kB - Private_Clean: 120 kB - Private_Dirty: 68 kB - Referenced: 884 kB - Anonymous: 68 kB - LazyFree: 0 kB - AnonHugePages: 0 kB - ShmemPmdMapped: 0 kB - Shared_Hugetlb: 0 kB - Private_Hugetlb: 0 kB - Swap: 0 kB - SwapPss: 0 kB - Locked: 385 kB + 00100000-ff709000 ---p 00000000 00:00 0 [rollup] + Size: 1192 kB + KernelPageSize: 4 kB + MMUPageSize: 4 kB + Rss: 884 kB + Pss: 385 kB + Pss_Anon: 301 kB + Pss_File: 80 kB + Pss_Shmem: 4 kB + Shared_Clean: 696 kB + Shared_Dirty: 0 kB + Private_Clean: 120 kB + Private_Dirty: 68 kB + Referenced: 884 kB + Anonymous: 68 kB + LazyFree: 0 kB + AnonHugePages: 0 kB + ShmemPmdMapped: 0 kB + Shared_Hugetlb: 0 kB + Private_Hugetlb: 0 kB + Swap: 0 kB + SwapPss: 0 kB + Locked: 385 kB diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore index d45209abdb1b..5b02540781a2 100644 --- a/Documentation/ABI/testing/pstore +++ b/Documentation/ABI/testing/pstore @@ -9,25 +9,25 @@ Description: Generic interface to platform dependent persistent storage. provide a generic interface to show records captured in the dying moments. In the case of a panic the last part of the console log is captured, but other interesting - data can also be saved. + data can also be saved:: - # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore + # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore - $ ls -l /sys/fs/pstore/ - total 0 - -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1 + $ ls -l /sys/fs/pstore/ + total 0 + -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1 Different users of this interface will result in different filename prefixes. Currently two are defined: - "dmesg" - saved console log - "mce" - architecture dependent data from fatal h/w error + - "dmesg" - saved console log + - "mce" - architecture dependent data from fatal h/w error Once the information in a file has been read, removing the file will signal to the underlying persistent storage - device that it can reclaim the space for later re-use. + device that it can reclaim the space for later re-use:: - $ rm /sys/fs/pstore/dmesg-erst-1 + $ rm /sys/fs/pstore/dmesg-erst-1 The expectation is that all files in /sys/fs/pstore/ will be saved elsewhere and erased from persistent store @@ -44,4 +44,3 @@ Description: Generic interface to platform dependent persistent storage. backends are available, the preferred backend may be set by passing the pstore.backend= argument to the kernel at boot time. - diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index 2322eb748b38..e34cdeeeb9d4 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -4,23 +4,27 @@ Contact: Jerome Marchand <jmarchan@redhat.com> Description: The /sys/block/<disk>/stat files displays the I/O statistics of disk <disk>. They contain 11 fields: - 1 - reads completed successfully - 2 - reads merged - 3 - sectors read - 4 - time spent reading (ms) - 5 - writes completed - 6 - writes merged - 7 - sectors written - 8 - time spent writing (ms) - 9 - I/Os currently in progress - 10 - time spent doing I/Os (ms) - 11 - weighted time spent doing I/Os (ms) - 12 - discards completed - 13 - discards merged - 14 - sectors discarded - 15 - time spent discarding (ms) - 16 - flush requests completed - 17 - time spent flushing (ms) + + == ============================================== + 1 reads completed successfully + 2 reads merged + 3 sectors read + 4 time spent reading (ms) + 5 writes completed + 6 writes merged + 7 sectors written + 8 time spent writing (ms) + 9 I/Os currently in progress + 10 time spent doing I/Os (ms) + 11 weighted time spent doing I/Os (ms) + 12 discards completed + 13 discards merged + 14 sectors discarded + 15 time spent discarding (ms) + 16 flush requests completed + 17 time spent flushing (ms) + == ============================================== + For more details refer Documentation/admin-guide/iostats.rst diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device index 17f2bc7dd261..aa0fb500e3c9 100644 --- a/Documentation/ABI/testing/sysfs-block-device +++ b/Documentation/ABI/testing/sysfs-block-device @@ -8,11 +8,13 @@ Description: It has the following valid values: + == ======================================================== 0 OFF - the LED is not activated on activity 1 BLINK_ON - the LED blinks on every 10ms when activity is detected. 2 BLINK_OFF - the LED is on when idle, and blinks off every 10ms when activity is detected. + == ======================================================== Note that the user must turn sw_activity OFF it they wish to control the activity LED via the em_message file. diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd index 8f070b47f361..14a6fe9422b3 100644 --- a/Documentation/ABI/testing/sysfs-block-rnbd +++ b/Documentation/ABI/testing/sysfs-block-rnbd @@ -9,9 +9,9 @@ Description: To unmap a volume, "normal" or "force" has to be written to: is using the device. When "force" is used, the device is also unmapped when device is in use. All I/Os that are in progress will fail. - Example: + Example:: - # echo "normal" > /sys/block/rnbd0/rnbd/unmap_device + # echo "normal" > /sys/block/rnbd0/rnbd/unmap_device What: /sys/block/rnbd<N>/rnbd/state Date: Feb 2020 diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi index e7898cfe5fb1..58abacf59b2a 100644 --- a/Documentation/ABI/testing/sysfs-bus-acpi +++ b/Documentation/ABI/testing/sysfs-bus-acpi @@ -5,6 +5,7 @@ Description: This attribute indicates the full path of ACPI namespace object associated with the device object. For example, \_SB_.PCI0. + This file is not present for device objects representing fixed ACPI hardware features (like power and sleep buttons). @@ -67,14 +68,16 @@ Description: The return value is a decimal integer representing the device's status bitmap: - Bit [0] – Set if the device is present. - Bit [1] – Set if the device is enabled and decoding its - resources. - Bit [2] – Set if the device should be shown in the UI. - Bit [3] – Set if the device is functioning properly (cleared if - device failed its diagnostics). - Bit [4] – Set if the battery is present. - Bits [31:5] – Reserved (must be cleared) + =========== ================================================== + Bit [0] Set if the device is present. + Bit [1] Set if the device is enabled and decoding its + resources. + Bit [2] Set if the device should be shown in the UI. + Bit [3] Set if the device is functioning properly (cleared + if device failed its diagnostics). + Bit [4] Set if the battery is present. + Bits [31:5] Reserved (must be cleared) + =========== ================================================== If bit [0] is clear, then bit 1 must also be clear (a device that is not present cannot be enabled). diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti index 9d11502b4390..bf2869c413e7 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti @@ -8,50 +8,50 @@ What: /sys/bus/coresight/devices/<cti-name>/powered Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Indicate if the CTI hardware is powered. +Description: (Read) Indicate if the CTI hardware is powered. What: /sys/bus/coresight/devices/<cti-name>/ctmid Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Display the associated CTM ID +Description: (Read) Display the associated CTM ID What: /sys/bus/coresight/devices/<cti-name>/nr_trigger_cons Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Number of devices connected to triggers on this CTI +Description: (Read) Number of devices connected to triggers on this CTI What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/name Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Name of connected device <N> +Description: (Read) Name of connected device <N> What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_signals Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Input trigger signals from connected device <N> +Description: (Read) Input trigger signals from connected device <N> What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_types Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Functional types for the input trigger signals +Description: (Read) Functional types for the input trigger signals from connected device <N> What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_signals Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Output trigger signals to connected device <N> +Description: (Read) Output trigger signals to connected device <N> What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_types Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Functional types for the output trigger signals +Description: (Read) Functional types for the output trigger signals to connected device <N> What: /sys/bus/coresight/devices/<cti-name>/regs/inout_sel @@ -88,7 +88,7 @@ What: /sys/bus/coresight/devices/<cti-name>/regs/intack Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Write the INTACK register. +Description: (Write) Write the INTACK register. What: /sys/bus/coresight/devices/<cti-name>/regs/appset Date: March 2020 @@ -101,99 +101,99 @@ What: /sys/bus/coresight/devices/<cti-name>/regs/appclear Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Write APPCLEAR register to deactivate channel. +Description: (Write) Write APPCLEAR register to deactivate channel. What: /sys/bus/coresight/devices/<cti-name>/regs/apppulse Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Write APPPULSE to pulse a channel active for one clock +Description: (Write) Write APPPULSE to pulse a channel active for one clock cycle. What: /sys/bus/coresight/devices/<cti-name>/regs/chinstatus Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Read current status of channel inputs. +Description: (Read) Read current status of channel inputs. What: /sys/bus/coresight/devices/<cti-name>/regs/choutstatus Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) read current status of channel outputs. +Description: (Read) read current status of channel outputs. What: /sys/bus/coresight/devices/<cti-name>/regs/triginstatus Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) read current status of input trigger signals +Description: (Read) read current status of input trigger signals What: /sys/bus/coresight/devices/<cti-name>/regs/trigoutstatus Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) read current status of output trigger signals. +Description: (Read) read current status of output trigger signals. What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_attach Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Attach a CTI input trigger to a CTM channel. +Description: (Write) Attach a CTI input trigger to a CTM channel. What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_detach Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Detach a CTI input trigger from a CTM channel. +Description: (Write) Detach a CTI input trigger from a CTM channel. What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_attach Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Attach a CTI output trigger to a CTM channel. +Description: (Write) Attach a CTI output trigger to a CTM channel. What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_detach Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Detach a CTI output trigger from a CTM channel. +Description: (Write) Detach a CTI output trigger from a CTM channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_enable Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (RW) Enable CTIGATE for single channel (W) or list enabled +Description: (RW) Enable CTIGATE for single channel (Write) or list enabled channels through the gate (R). What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_disable Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Disable CTIGATE for single channel. +Description: (Write) Disable CTIGATE for single channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_set Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Activate a single channel. +Description: (Write) Activate a single channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_clear Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Deactivate a single channel. +Description: (Write) Deactivate a single channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_pulse Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Pulse a single channel - activate for a single clock cycle. +Description: (Write) Pulse a single channel - activate for a single clock cycle. What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_filtered Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) List of output triggers filtered across all connections. +Description: (Read) List of output triggers filtered across all connections. What: /sys/bus/coresight/devices/<cti-name>/channels/trig_filter_enable Date: March 2020 @@ -205,13 +205,13 @@ What: /sys/bus/coresight/devices/<cti-name>/channels/chan_inuse Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) show channels with at least one attached trigger signal. +Description: (Read) show channels with at least one attached trigger signal. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_free Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) show channels with no attached trigger signals. +Description: (Read) show channels with no attached trigger signals. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_sel Date: March 2020 @@ -224,18 +224,18 @@ What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_in Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Read to see input triggers connected to selected view +Description: (Read) Read to see input triggers connected to selected view channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_out Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (R) Read to see output triggers connected to selected view +Description: (Read) Read to see output triggers connected to selected view channel. What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_reset Date: March 2020 KernelVersion 5.7 Contact: Mike Leach or Mathieu Poirier -Description: (W) Clear all channel / trigger programming. +Description: (Write) Clear all channel / trigger programming. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 index b5f526081711..9a383f6a74eb 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 @@ -4,7 +4,10 @@ KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> Description: (RW) Add/remove a sink from a trace path. There can be multiple source for a single sink. - ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink + + ex:: + + echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink What: /sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr Date: November 2014 @@ -20,21 +23,21 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rdp Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Defines the depth, in words, of the trace RAM in powers of +Description: (Read) Defines the depth, in words, of the trace RAM in powers of 2. The value is read directly from HW register RDP, 0x004. What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/sts Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB status register. The value +Description: (Read) Shows the value held by the ETB status register. The value is read directly from HW register STS, 0x00C. What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rrp Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB RAM Read Pointer register +Description: (Read) Shows the value held by the ETB RAM Read Pointer register that is used to read entries from the Trace RAM over the APB interface. The value is read directly from HW register RRP, 0x014. @@ -43,7 +46,7 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rwp Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB RAM Write Pointer register +Description: (Read) Shows the value held by the ETB RAM Write Pointer register that is used to sets the write pointer to write entries from the CoreSight bus into the Trace RAM. The value is read directly from HW register RWP, 0x018. @@ -52,21 +55,21 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/trg Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Similar to "trigger_cntr" above except that this value is +Description: (Read) Similar to "trigger_cntr" above except that this value is read directly from HW register TRG, 0x01C. What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ctl Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB Control register. The value +Description: (Read) Shows the value held by the ETB Control register. The value is read directly from HW register CTL, 0x020. What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffsr Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB Formatter and Flush Status +Description: (Read) Shows the value held by the ETB Formatter and Flush Status register. The value is read directly from HW register FFSR, 0x300. @@ -74,6 +77,6 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffcr Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the ETB Formatter and Flush Control +Description: (Read) Shows the value held by the ETB Formatter and Flush Control register. The value is read directly from HW register FFCR, 0x304. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x index 924265a1295d..651602a61eac 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -146,28 +146,28 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Provides the number of address comparators pairs accessible +Description: (Read) Provides the number of address comparators pairs accessible on a trace unit, as specified by bit 3:0 of register ETMCCR. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Provides the number of counters accessible on a trace unit, +Description: (Read) Provides the number of counters accessible on a trace unit, as specified by bit 15:13 of register ETMCCR. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Provides the number of context ID comparator available on a +Description: (Read) Provides the number of context ID comparator available on a trace unit, as specified by bit 25:24 of register ETMCCR. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (W) Cancels all configuration on a trace unit and set it back +Description: (Write) Cancels all configuration on a trace unit and set it back to its boot configuration. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event @@ -216,7 +216,7 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Holds the current state of the sequencer. +Description: (Read) Holds the current state of the sequencer. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq Date: November 2014 diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x index 614874e2cf53..881f0cd99ce4 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x @@ -12,75 +12,75 @@ What: /sys/bus/coresight/devices/etm<N>/cpu Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) The CPU this tracing entity is associated with. +Description: (Read) The CPU this tracing entity is associated with. What: /sys/bus/coresight/devices/etm<N>/nr_pe_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of PE comparator inputs that are +Description: (Read) Indicates the number of PE comparator inputs that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/nr_addr_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of address comparator pairs that are +Description: (Read) Indicates the number of address comparator pairs that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/nr_cntr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of counters that are available for +Description: (Read) Indicates the number of counters that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/nr_ext_inp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates how many external inputs are implemented. +Description: (Read) Indicates how many external inputs are implemented. What: /sys/bus/coresight/devices/etm<N>/numcidc Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of Context ID comparators that are +Description: (Read) Indicates the number of Context ID comparators that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/numvmidc Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of VMID comparators that are available +Description: (Read) Indicates the number of VMID comparators that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/nrseqstate Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of sequencer states that are +Description: (Read) Indicates the number of sequencer states that are implemented. What: /sys/bus/coresight/devices/etm<N>/nr_resource Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of resource selection pairs that are +Description: (Read) Indicates the number of resource selection pairs that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/nr_ss_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the number of single-shot comparator controls that +Description: (Read) Indicates the number of single-shot comparator controls that are available for tracing. What: /sys/bus/coresight/devices/etm<N>/reset Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (W) Cancels all configuration on a trace unit and set it back +Description: (Write) Cancels all configuration on a trace unit and set it back to its boot configuration. What: /sys/bus/coresight/devices/etm<N>/mode @@ -300,7 +300,7 @@ What: /sys/bus/coresight/devices/etm<N>/addr_cmp_view Date: December 2019 KernelVersion: 5.5 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the current settings for the selected address +Description: (Read) Print the current settings for the selected address comparator. What: /sys/bus/coresight/devices/etm<N>/sshot_idx @@ -319,7 +319,7 @@ What: /sys/bus/coresight/devices/etm<N>/sshot_status Date: December 2019 KernelVersion: 5.5 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the current value of the selected single shot +Description: (Read) Print the current value of the selected single shot status register. What: /sys/bus/coresight/devices/etm<N>/sshot_pe_ctrl @@ -333,111 +333,111 @@ What: /sys/bus/coresight/devices/etm<N>/mgmt/trcoslsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the OS Lock Status Register (0x304). +Description: (Read) Print the content of the OS Lock Status Register (0x304). The value it taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdcr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Power Down Control Register +Description: (Read) Print the content of the Power Down Control Register (0x310). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Power Down Status Register +Description: (Read) Print the content of the Power Down Status Register (0x314). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trclsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the SW Lock Status Register +Description: (Read) Print the content of the SW Lock Status Register (0xFB4). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcauthstatus Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Authentication Status Register +Description: (Read) Print the content of the Authentication Status Register (0xFB8). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevid Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Device ID Register +Description: (Read) Print the content of the Device ID Register (0xFC8). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevtype Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Device Type Register +Description: (Read) Print the content of the Device Type Register (0xFCC). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr0 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Peripheral ID0 Register +Description: (Read) Print the content of the Peripheral ID0 Register (0xFE0). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr1 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Peripheral ID1 Register +Description: (Read) Print the content of the Peripheral ID1 Register (0xFE4). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr2 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Peripheral ID2 Register +Description: (Read) Print the content of the Peripheral ID2 Register (0xFE8). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr3 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the Peripheral ID3 Register +Description: (Read) Print the content of the Peripheral ID3 Register (0xFEC). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trcconfig Date: February 2016 KernelVersion: 4.07 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the trace configuration register +Description: (Read) Print the content of the trace configuration register (0x010) as currently set by SW. What: /sys/bus/coresight/devices/etm<N>/mgmt/trctraceid Date: February 2016 KernelVersion: 4.07 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Print the content of the trace ID register (0x040). +Description: (Read) Print the content of the trace ID register (0x040). What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr0 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the tracing capabilities of the trace unit (0x1E0). +Description: (Read) Returns the tracing capabilities of the trace unit (0x1E0). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr1 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the tracing capabilities of the trace unit (0x1E4). +Description: (Read) Returns the tracing capabilities of the trace unit (0x1E4). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr2 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the maximum size of the data value, data address, +Description: (Read) Returns the maximum size of the data value, data address, VMID, context ID and instuction address in the trace unit (0x1E8). The value is taken directly from the HW. @@ -445,7 +445,7 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr3 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the value associated with various resources +Description: (Read) Returns the value associated with various resources available to the trace unit. See the Trace Macrocell architecture specification for more details (0x1E8). The value is taken directly from the HW. @@ -454,42 +454,42 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr4 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns how many resources the trace unit supports (0x1F0). +Description: (Read) Returns how many resources the trace unit supports (0x1F0). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr5 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns how many resources the trace unit supports (0x1F4). +Description: (Read) Returns how many resources the trace unit supports (0x1F4). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr8 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the maximum speculation depth of the instruction +Description: (Read) Returns the maximum speculation depth of the instruction trace stream. (0x180). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr9 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the number of P0 right-hand keys that the trace unit +Description: (Read) Returns the number of P0 right-hand keys that the trace unit can use (0x184). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr10 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the number of P1 right-hand keys that the trace unit +Description: (Read) Returns the number of P1 right-hand keys that the trace unit can use (0x188). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr11 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the number of special P1 right-hand keys that the +Description: (Read) Returns the number of special P1 right-hand keys that the trace unit can use (0x18C). The value is taken directly from the HW. @@ -497,7 +497,7 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr12 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the number of conditional P1 right-hand keys that +Description: (Read) Returns the number of conditional P1 right-hand keys that the trace unit can use (0x190). The value is taken directly from the HW. @@ -505,6 +505,6 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr13 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Returns the number of special conditional P1 right-hand keys +Description: (Read) Returns the number of special conditional P1 right-hand keys that the trace unit can use (0x194). The value is taken directly from the HW. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm index 1dffabe7f48d..53e1f4815d64 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm @@ -42,7 +42,7 @@ What: /sys/bus/coresight/devices/<memory_map>.stm/status Date: April 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) List various control and status registers. The specific +Description: (Read) List various control and status registers. The specific layout and content is driver specific. What: /sys/bus/coresight/devices/<memory_map>.stm/traceid diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc index ab49b9ac3bcb..6aa527296c71 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc @@ -11,21 +11,21 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rsz Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Defines the size, in 32-bit words, of the local RAM buffer. +Description: (Read) Defines the size, in 32-bit words, of the local RAM buffer. The value is read directly from HW register RSZ, 0x004. What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/sts Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC status register. The value +Description: (Read) Shows the value held by the TMC status register. The value is read directly from HW register STS, 0x00C. What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rrp Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC RAM Read Pointer register +Description: (Read) Shows the value held by the TMC RAM Read Pointer register that is used to read entries from the Trace RAM over the APB interface. The value is read directly from HW register RRP, 0x014. @@ -34,7 +34,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rwp Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC RAM Write Pointer register +Description: (Read) Shows the value held by the TMC RAM Write Pointer register that is used to sets the write pointer to write entries from the CoreSight bus into the Trace RAM. The value is read directly from HW register RWP, 0x018. @@ -43,21 +43,21 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/trg Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Similar to "trigger_cntr" above except that this value is +Description: (Read) Similar to "trigger_cntr" above except that this value is read directly from HW register TRG, 0x01C. What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ctl Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC Control register. The value +Description: (Read) Shows the value held by the TMC Control register. The value is read directly from HW register CTL, 0x020. What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffsr Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC Formatter and Flush Status +Description: (Read) Shows the value held by the TMC Formatter and Flush Status register. The value is read directly from HW register FFSR, 0x300. @@ -65,7 +65,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffcr Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC Formatter and Flush Control +Description: (Read) Shows the value held by the TMC Formatter and Flush Control register. The value is read directly from HW register FFCR, 0x304. @@ -73,7 +73,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/mode Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Shows the value held by the TMC Mode register, which +Description: (Read) Shows the value held by the TMC Mode register, which indicate the mode the device has been configured to enact. The The value is read directly from the MODE register, 0x028. @@ -81,7 +81,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/devid Date: March 2016 KernelVersion: 4.7 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) Indicates the capabilities of the Coresight TMC. +Description: (Read) Indicates the capabilities of the Coresight TMC. The value is read directly from the DEVID register, 0xFC8, What: /sys/bus/coresight/devices/<memory_map>.tmc/buffer_size diff --git a/Documentation/ABI/testing/sysfs-bus-css b/Documentation/ABI/testing/sysfs-bus-css index 966f8504bd7b..12a733fe357f 100644 --- a/Documentation/ABI/testing/sysfs-bus-css +++ b/Documentation/ABI/testing/sysfs-bus-css @@ -20,6 +20,7 @@ Contact: Cornelia Huck <cornelia.huck@de.ibm.com> Description: Contains the ids of the channel paths used by this subchannel, as reported by the channel subsystem during subchannel recognition. + Note: This is an I/O-subchannel specific attribute. Users: s390-tools, HAL @@ -31,6 +32,7 @@ Description: Contains the PIM/PAM/POM values, as reported by the channel subsystem when last queried by the common I/O layer (this implies that this attribute is not necessarily in sync with the values current in the channel subsystem). + Note: This is an I/O-subchannel specific attribute. Users: s390-tools, HAL @@ -53,6 +55,7 @@ Description: This file allows the driver for a device to be specified. When opt-out of driver binding using a driver_override name such as "none". Only a single driver may be specified in the override, there is no support for parsing delimiters. + Note that unlike the mechanism of the same name for pci, this file does not allow to override basic matching rules. I.e., the driver must still match the subchannel type of the device. diff --git a/Documentation/ABI/testing/sysfs-bus-dfl b/Documentation/ABI/testing/sysfs-bus-dfl index 23543be904f2..b0265ab17200 100644 --- a/Documentation/ABI/testing/sysfs-bus-dfl +++ b/Documentation/ABI/testing/sysfs-bus-dfl @@ -4,6 +4,7 @@ KernelVersion: 5.10 Contact: Xu Yilun <yilun.xu@intel.com> Description: Read-only. It returns type of DFL FIU of the device. Now DFL supports 2 FIU types, 0 for FME, 1 for PORT. + Format: 0x%x What: /sys/bus/dfl/devices/dfl_dev.X/feature_id @@ -12,4 +13,5 @@ KernelVersion: 5.10 Contact: Xu Yilun <yilun.xu@intel.com> Description: Read-only. It returns feature identifier local to its DFL FIU type. + Format: 0x%x diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme index c9278a3b3df1..63a32ddcb95e 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme @@ -8,13 +8,13 @@ Description: Read-only. Attribute group to describe the magic bits Each attribute under this group defines a bit range of the perf_event_attr.config. All supported attributes are listed - below. + below:: event = "config:0-11" - event ID evtype = "config:12-15" - event type portid = "config:16-23" - event source - For example, + For example:: fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff" @@ -40,11 +40,11 @@ Description: Read-only. Attribute group to describe performance monitoring All supported performance monitoring events are listed below. - Basic events (evtype=0x00) + Basic events (evtype=0x00):: clock = "event=0x00,evtype=0x00,portid=0xff" - Cache events (evtype=0x01) + Cache events (evtype=0x01):: cache_read_hit = "event=0x00,evtype=0x01,portid=0xff" cache_read_miss = "event=0x01,evtype=0x01,portid=0xff" @@ -59,7 +59,7 @@ Description: Read-only. Attribute group to describe performance monitoring cache_rx_req_stall = "event=0x09,evtype=0x01,portid=0xff" cache_eviction = "event=0x0a,evtype=0x01,portid=0xff" - Fabric events (evtype=0x02) + Fabric events (evtype=0x02):: fab_pcie0_read = "event=0x00,evtype=0x02,portid=0xff" fab_pcie0_write = "event=0x01,evtype=0x02,portid=0xff" @@ -78,7 +78,7 @@ Description: Read-only. Attribute group to describe performance monitoring fab_port_mmio_read = "event=0x06,evtype=0x02,portid=?" fab_port_mmio_write = "event=0x07,evtype=0x02,portid=?" - VTD events (evtype=0x03) + VTD events (evtype=0x03):: vtd_port_read_transaction = "event=0x00,evtype=0x03,portid=?" vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?" @@ -88,7 +88,7 @@ Description: Read-only. Attribute group to describe performance monitoring vtd_port_devtlb_2m_fill = "event=0x05,evtype=0x03,portid=?" vtd_port_devtlb_1g_fill = "event=0x06,evtype=0x03,portid=?" - VTD SIP events (evtype=0x04) + VTD SIP events (evtype=0x04):: vtd_sip_iotlb_4k_hit = "event=0x00,evtype=0x04,portid=0xff" vtd_sip_iotlb_2m_hit = "event=0x01,evtype=0x04,portid=0xff" diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format index 5bb793ec926c..df7ccc1b2fba 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format @@ -10,7 +10,8 @@ Description: name/value pairs. Userspace must be prepared for the possibility that attributes - define overlapping bit ranges. For example: + define overlapping bit ranges. For example:: + attr1 = 'config:0-23' attr2 = 'config:0-7' attr3 = 'config:12-35' diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 index 2273627df190..de390a010af8 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -7,7 +7,7 @@ Description: Read-only. Attribute group to describe the magic bits Each attribute under this group defines a bit range of the perf_event_attr.config. All supported attributes are listed - below. + below:: chip = "config:16-31" core = "config:16-31" @@ -16,9 +16,9 @@ Description: Read-only. Attribute group to describe the magic bits offset = "config:32-63" vcpu = "config:16-31" - For example, + For example:: - PM_PB_CYC = "domain=1,offset=0x80,chip=?,lpar=0x0" + PM_PB_CYC = "domain=1,offset=0x80,chip=?,lpar=0x0" In this event, '?' after chip specifies that this value will be provided by user while running this event. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci index 6a023b42486c..12e2bf92783f 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci @@ -7,7 +7,7 @@ Description: Read-only. Attribute group to describe the magic bits Each attribute under this group defines a bit range of the perf_event_attr.config. All supported attributes are listed - below. + below:: counter_info_version = "config:16-23" length = "config:24-31" @@ -20,9 +20,9 @@ Description: Read-only. Attribute group to describe the magic bits secondary_index = "config:0-15" starting_index = "config:32-63" - For example, + For example:: - processor_core_utilization_instructions_completed = "request=0x94, + processor_core_utilization_instructions_completed = "request=0x94, phys_processor_idx=?,counter_info_version=0x8, length=8,offset=0x18" @@ -36,6 +36,7 @@ Description: '0' if the hypervisor is configured to forbid access to event counters being accumulated by other guests and to physical domain event counters. + '1' if that access is allowed. What: /sys/bus/event_source/devices/hv_gpci/interface/ga diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe index 657df13b100d..8fe787cc4ab7 100644 --- a/Documentation/ABI/testing/sysfs-bus-fcoe +++ b/Documentation/ABI/testing/sysfs-bus-fcoe @@ -3,16 +3,19 @@ Date: August 2012 KernelVersion: TBD Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org Description: The FCoE bus. Attributes in this directory are control interfaces. + Attributes: - ctlr_create: 'FCoE Controller' instance creation interface. Writing an + ctlr_create: + 'FCoE Controller' instance creation interface. Writing an <ifname> to this file will allocate and populate sysfs with a fcoe_ctlr_device (ctlr_X). The user can then configure any per-port settings and finally write to the fcoe_ctlr_device's 'start' attribute to begin the kernel's discovery and login process. - ctlr_destroy: 'FCoE Controller' instance removal interface. Writing a + ctlr_destroy: + 'FCoE Controller' instance removal interface. Writing a fcoe_ctlr_device's sysfs name to this file will log the fcoe_ctlr_device out of the fabric or otherwise connected FCoE devices. It will also free all kernel memory allocated @@ -32,11 +35,13 @@ Description: 'FCoE Controller' instances on the fcoe bus. Attributes: - fcf_dev_loss_tmo: Device loss timeout period (see below). Changing + fcf_dev_loss_tmo: + Device loss timeout period (see below). Changing this value will change the dev_loss_tmo for all FCFs discovered by this controller. - mode: Display or change the FCoE Controller's mode. Possible + mode: + Display or change the FCoE Controller's mode. Possible modes are 'Fabric' and 'VN2VN'. If a FCoE Controller is started in 'Fabric' mode then FIP FCF discovery is initiated and ultimately a fabric login is attempted. @@ -44,23 +49,30 @@ Attributes: FIP VN2VN discovery and login is performed. A FCoE Controller only supports one mode at a time. - enabled: Whether an FCoE controller is enabled or disabled. + enabled: + Whether an FCoE controller is enabled or disabled. 0 if disabled, 1 if enabled. Writing either 0 or 1 to this file will enable or disable the FCoE controller. - lesb/link_fail: Link Error Status Block (LESB) link failure count. + lesb/link_fail: + Link Error Status Block (LESB) link failure count. - lesb/vlink_fail: Link Error Status Block (LESB) virtual link + lesb/vlink_fail: + Link Error Status Block (LESB) virtual link failure count. - lesb/miss_fka: Link Error Status Block (LESB) missed FCoE + lesb/miss_fka: + Link Error Status Block (LESB) missed FCoE Initialization Protocol (FIP) Keep-Alives (FKA). - lesb/symb_err: Link Error Status Block (LESB) symbolic error count. + lesb/symb_err: + Link Error Status Block (LESB) symbolic error count. - lesb/err_block: Link Error Status Block (LESB) block error count. + lesb/err_block: + Link Error Status Block (LESB) block error count. - lesb/fcs_error: Link Error Status Block (LESB) Fibre Channel + lesb/fcs_error: + Link Error Status Block (LESB) Fibre Channel Services error count. Notes: ctlr_X (global increment starting at 0) @@ -75,31 +87,41 @@ Description: 'FCoE FCF' instances on the fcoe bus. A FCF is a Fibre Channel Fibre Channel frames into a FC fabric. It can also take outbound FC frames and pack them in Ethernet packets to be sent to their destination on the Ethernet segment. + Attributes: - fabric_name: Identifies the fabric that the FCF services. + fabric_name: + Identifies the fabric that the FCF services. - switch_name: Identifies the FCF. + switch_name: + Identifies the FCF. - priority: The switch's priority amongst other FCFs on the same + priority: + The switch's priority amongst other FCFs on the same fabric. - selected: 1 indicates that the switch has been selected for use; + selected: + 1 indicates that the switch has been selected for use; 0 indicates that the switch will not be used. - fc_map: The Fibre Channel MAP + fc_map: + The Fibre Channel MAP - vfid: The Virtual Fabric ID + vfid: + The Virtual Fabric ID - mac: The FCF's MAC address + mac: + The FCF's MAC address - fka_period: The FIP Keep-Alive period + fka_period: + The FIP Keep-Alive period fabric_state: The internal kernel state - "Unknown" - Initialization value - "Disconnected" - No link to the FCF/fabric - "Connected" - Host is connected to the FCF - "Deleted" - FCF is being removed from the system + + - "Unknown" - Initialization value + - "Disconnected" - No link to the FCF/fabric + - "Connected" - Host is connected to the FCF + - "Deleted" - FCF is being removed from the system dev_loss_tmo: The device loss timeout period for this FCF. diff --git a/Documentation/ABI/testing/sysfs-bus-fsl-mc b/Documentation/ABI/testing/sysfs-bus-fsl-mc index 80256b8b4f26..bf3c6af6ad89 100644 --- a/Documentation/ABI/testing/sysfs-bus-fsl-mc +++ b/Documentation/ABI/testing/sysfs-bus-fsl-mc @@ -6,8 +6,10 @@ Description: the driver to attempt to bind to the device found at this location. The format for the location is Object.Id and is the same as found in /sys/bus/fsl-mc/devices/. - For example: - # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind + + For example:: + + # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind What: /sys/bus/fsl-mc/drivers/.../unbind Date: December 2016 @@ -17,5 +19,7 @@ Description: driver to attempt to unbind from the device found at this location. The format for the location is Object.Id and is the same as found in /sys/bus/fsl-mc/devices/. - For example: - # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind + + For example:: + + # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 index 9de269bb0ae5..42dfc9399d2d 100644 --- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 @@ -3,19 +3,25 @@ Date: February 2011 Contact: Minkyu Kang <mk7.kang@samsung.com> Description: show what device is attached - NONE - no device - USB - USB device is attached - UART - UART is attached - CHARGER - Charger is attaced - JIG - JIG is attached + + ======= ====================== + NONE no device + USB USB device is attached + UART UART is attached + CHARGER Charger is attaced + JIG JIG is attached + ======= ====================== What: /sys/bus/i2c/devices/.../switch Date: February 2011 Contact: Minkyu Kang <mk7.kang@samsung.com> Description: show or set the state of manual switch - VAUDIO - switch to VAUDIO path - UART - switch to UART path - AUDIO - switch to AUDIO path - DHOST - switch to DHOST path - AUTO - switch automatically by device + + ======= ============================== + VAUDIO switch to VAUDIO path + UART switch to UART path + AUDIO switch to AUDIO path + DHOST switch to DHOST path + AUTO switch automatically by device + ======= ============================== diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x index 0b0de8cd0d13..b6c69eb80ca4 100644 --- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x @@ -6,15 +6,18 @@ Description: Value that exists only for mux devices that can be written to control the behaviour of the multiplexer on idle. Possible values: - -2 - disconnect on idle, i.e. deselect the last used - channel, which is useful when there is a device - with an address that conflicts with another - device on another mux on the same parent bus. - -1 - leave the mux as-is, which is the most optimal - setting in terms of I2C operations and is the - default mode. - 0..<nchans> - set the mux to a predetermined channel, - which is useful if there is one channel that is - used almost always, and you want to reduce the - latency for normal operations after rare - transactions on other channels + + =========== =============================================== + -2 disconnect on idle, i.e. deselect the last used + channel, which is useful when there is a device + with an address that conflicts with another + device on another mux on the same parent bus. + -1 leave the mux as-is, which is the most optimal + setting in terms of I2C operations and is the + default mode. + 0..<nchans> set the mux to a predetermined channel, + which is useful if there is one channel that is + used almost always, and you want to reduce the + latency for normal operations after rare + transactions on other channels + =========== =============================================== diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c index 2f332ec36f82..1f4a2662335b 100644 --- a/Documentation/ABI/testing/sysfs-bus-i3c +++ b/Documentation/ABI/testing/sysfs-bus-i3c @@ -84,6 +84,7 @@ Description: by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". See the I3C specification for more details about these HDR modes. + This entry describes the HDRCAP of the master controller driving the bus. @@ -135,6 +136,7 @@ Description: Expose the HDR (High Data Rate) capabilities of a device. Returns a list of supported HDR mode, each element is separated by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". + See the I3C specification for more details about these HDR modes. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index a9d51810a3ba..df42bed09f25 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -15,6 +15,7 @@ Description: based on hardware generated events (e.g. data ready) or provided by a separate driver for other hardware (e.g. periodic timer, GPIO or high resolution timer). + Contains trigger type specific elements. These do not generalize well and hence are not documented in this file. X is the IIO index of the trigger. @@ -65,6 +66,7 @@ Contact: linux-iio@vger.kernel.org Description: When the internal sampling clock can only take a specific set of frequencies, we can specify the available values with: + - a small discrete set of values like "0 2 4 6 8" - a range with minimum, step and maximum frequencies like "[min step max]" @@ -665,6 +667,7 @@ Description: <type>[Y][_name]_<raw|input>_thresh_falling_value may take different values, but the device can only enable both thresholds or neither. + Note the driver will assume the last p events requested are to be enabled where p is how many it supports (which may vary depending on the exact set requested. So if you want to be @@ -719,6 +722,7 @@ Description: <type>[Y][_name]_<raw|input>_roc_falling_value may take different values, but the device can only enable both rate of change thresholds or neither. + Note the driver will assume the last p events requested are to be enabled where p is however many it supports (which may vary depending on the exact set requested. So if you want to be @@ -774,9 +778,11 @@ Description: Specifies the value of threshold that the device is comparing against for the events enabled by <type>Y[_name]_thresh[_rising|falling]_en. + If separate attributes exist for the two directions, but direction is not specified for this attribute, then a single threshold value applies to both directions. + The raw or input element of the name indicates whether the value is in raw device units or in processed units (as _raw and _input do on sysfs direct channel read attributes). @@ -859,6 +865,7 @@ Description: If separate attributes exist for the two directions, but direction is not specified for this attribute, then a single hysteresis value applies to both directions. + For falling events the hysteresis is added to the _value attribute for this event to get the upper threshold for when the event goes back to normal, for rising events the hysteresis is subtracted from the _value @@ -905,6 +912,7 @@ Description: Specifies the value of rate of change threshold that the device is comparing against for the events enabled by <type>[Y][_name]_roc[_rising|falling]_en. + If separate attributes exist for the two directions, but direction is not specified for this attribute, then a single threshold value applies to both directions. @@ -1304,6 +1312,7 @@ Description: Proximity measurement indicating that some object is near the sensor, usually by observing reflectivity of infrared or ultrasound emitted. + Often these sensors are unit less and as such conversion to SI units is not possible. Higher proximity measurements indicate closer objects, and vice versa. Units after @@ -1449,9 +1458,12 @@ Contact: linux-iio@vger.kernel.org Description: A single positive integer specifying the maximum number of scan elements to wait for. + Poll will block until the watermark is reached. + Blocking read will wait until the minimum between the requested read amount or the low water mark is available. + Non-blocking read will retrieve the available samples from the buffer even if there are less samples then watermark level. This allows the application to block on poll with a timeout and read @@ -1480,11 +1492,13 @@ Description: device settings allows it (e.g. if a trigger is set that samples data differently that the hardware fifo does then hardware fifo will not enabled). + If the hardware fifo is enabled and the level of the hardware fifo reaches the hardware fifo watermark level the device will flush its hardware fifo to the device buffer. Doing a non blocking read on the device when no samples are present in the device buffer will also force a flush. + When the hardware fifo is enabled there is no need to use a trigger to use buffer mode since the watermark settings guarantees that the hardware fifo is flushed to the device @@ -1522,6 +1536,7 @@ Description: A single positive integer specifying the minimum watermark level for the hardware fifo of this device. If the device does not have a hardware fifo this entry is not present. + If the user sets buffer/watermark to a value less than this one, then the hardware watermark will remain unset. @@ -1532,6 +1547,7 @@ Description: A single positive integer specifying the maximum watermark level for the hardware fifo of this device. If the device does not have a hardware fifo this entry is not present. + If the user sets buffer/watermark to a value greater than this one, then the hardware watermark will be capped at this value. @@ -1543,6 +1559,7 @@ Description: levels for the hardware fifo. This entry is optional and if it is not present it means that all the values between hwfifo_watermark_min and hwfifo_watermark_max are supported. + If the user sets buffer/watermark to a value greater than hwfifo_watermak_min but not equal to any of the values in this list, the driver will chose an appropriate value for the @@ -1604,7 +1621,8 @@ KernelVersion: 4.1.0 Contact: linux-iio@vger.kernel.org Description: '1' (enable) or '0' (disable) specifying the enable - of heater function. Same reading values apply + of heater function. Same reading values apply. + This ABI is especially applicable for humidity sensors to heatup the device and get rid of any condensation in some humidity environment @@ -1627,17 +1645,21 @@ Description: Mounting matrix for IIO sensors. This is a rotation matrix which informs userspace about sensor chip's placement relative to the main hardware it is mounted on. + Main hardware placement is defined according to the local reference frame related to the physical quantity the sensor measures. + Given that the rotation matrix is defined in a board specific way (platform data and / or device-tree), the main hardware reference frame definition is left to the implementor's choice (see below for a magnetometer example). + Applications should apply this rotation matrix to samples so that when main hardware reference frame is aligned onto local reference frame, then sensor chip reference frame is also perfectly aligned with it. + Matrix is a 3x3 unitary matrix and typically looks like [0, 1, 0; 1, 0, 0; 0, 0, -1]. Identity matrix [1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and main hardware @@ -1646,8 +1668,10 @@ Description: For example, a mounting matrix for a magnetometer sensor informs userspace about sensor chip's ORIENTATION relative to the main hardware. + More specifically, main hardware orientation 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 ; @@ -1656,13 +1680,16 @@ Description: An implementor might consider that for a hand-held device, a 'natural' orientation would be 'front facing camera at the top'. The main hardware reference frame could then be described as : + * Y is in the plane of the screen and is positive towards the top of the screen ; * X is in the plane of the screen, perpendicular to Y axis, and positive towards the right hand side of the screen ; * Z is perpendicular to the screen plane and positive out of the screen. + Another example for a quadrotor UAV might be : + * Y is in the plane of the propellers and positive towards the front-view camera; * X is in the plane of the propellers, perpendicular to Y axis, @@ -1704,6 +1731,7 @@ Description: This interface is deprecated; please use the Counter subsystem. A list of possible counting directions which are: + - "up" : counter device is increasing. - "down": counter device is decreasing. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector index 2071f9bcfaa5..1c2a07f7a75e 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector @@ -5,7 +5,8 @@ Contact: Peter Rosin <peda@axentia.se> Description: The DAC is used to find the peak level of an alternating voltage input signal by a binary search using the output - of a comparator wired to an interrupt pin. Like so: + of a comparator wired to an interrupt pin. Like so:: + _ | \ input +------>-------|+ \ @@ -19,10 +20,12 @@ Description: | irq|------<-------' | | '-------' + The boolean invert attribute (0/1) should be set when the input signal is centered around the maximum value of the dac instead of zero. The envelope detector will search from below in this case and will also invert the result. + The edge/level of the interrupt is also switched to its opposite value. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 index f30b4c424fb6..4b01150af397 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 @@ -19,9 +19,11 @@ Description: is separately set for "GND-Open" and "Supply-Open" modes. Channels 0..31 have common low threshold values, but could have different sensing_modes. + The low voltage threshold range is between 2..21V. Hysteresis between low and high thresholds can not be lower then 2 and can not be odd. + If falling threshold results hysteresis to odd value then rising threshold is automatically subtracted by one. @@ -34,10 +36,13 @@ Description: this value then the threshold rising event is pushed. Depending on in_voltageY_sensing_mode the high voltage threshold is separately set for "GND-Open" and "Supply-Open" modes. + Channels 0..31 have common high threshold values, but could have different sensing_modes. + The high voltage threshold range is between 3..22V. Hysteresis between low and high thresholds can not be lower then 2 and can not be odd. + If rising threshold results hysteresis to odd value then falling threshold is automatically appended by one. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 index efe4c85e3c8b..1975c7a1af34 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 @@ -5,10 +5,13 @@ Description: The STM32 ADC can be configured to use external trigger sources (e.g. timers, pwm or exti gpio). Then, it can be tuned to start conversions on external trigger by either: + - "rising-edge" - "falling-edge" - "both-edges". + Reading returns current trigger polarity. + Writing value before enabling conversions sets trigger polarity. What: /sys/bus/iio/devices/triggerX/trigger_polarity_available diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec index 6158f831c761..adf24c40126f 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec +++ b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec @@ -4,7 +4,7 @@ KernelVersion: 4.7 Contact: linux-iio@vger.kernel.org Description: Writing '1' will perform a FOC (Fast Online Calibration). The - corresponding calibration offsets can be read from *_calibbias + corresponding calibration offsets can be read from `*_calibbias` entries. What: /sys/bus/iio/devices/iio:deviceX/location diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 index 0e66ae9b0071..91439d6d60b5 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 @@ -3,14 +3,20 @@ KernelVersion: 4.14 Contact: arnaud.pouliquen@st.com Description: For audio purpose only. + Used by audio driver to set/get the spi input frequency. + This is mandatory if DFSDM is slave on SPI bus, to provide information on the SPI clock frequency during runtime Notice that the SPI frequency should be a multiple of sample frequency to ensure the precision. - if DFSDM input is SPI master + + if DFSDM input is SPI master: + Reading SPI clkout frequency, error on writing + If DFSDM input is SPI Slave: + Reading returns value previously set. Writing value before starting conversions. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 index a133fd8d081a..40df5c9fef99 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 @@ -15,8 +15,11 @@ Description: first object echoed in meters. Default value is 6.020. This setting limits the time the driver is waiting for a echo. + Showing the range of available values is represented as the minimum value, the step and the maximum value, all enclosed in square brackets. - Example: - [0.043 0.043 11.008] + + Example:: + + [0.043 0.043 11.008] diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 index a91aeabe7b24..d065cda7dd96 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 @@ -8,7 +8,9 @@ KernelVersion: 3.4.0 Contact: linux-iio@vger.kernel.org Description: Reading returns either '1' or '0'. + '1' means that the clock in question is present. + '0' means that the clock is missing. What: /sys/bus/iio/devices/iio:deviceX/pllY_locked diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 index 302de64cb424..544548ee794c 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 @@ -27,12 +27,12 @@ What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name KernelVersion: Contact: linux-iio@vger.kernel.org Description: - Reading returns the datasheet name for channel Y: + Reading returns the datasheet name for channel Y:: - out_altvoltage0_name: RF8x - out_altvoltage1_name: RFAUX8x - out_altvoltage2_name: RF16x - out_altvoltage3_name: RF32x + out_altvoltage0_name: RF8x + out_altvoltage1_name: RFAUX8x + out_altvoltage2_name: RF16x + out_altvoltage3_name: RF32x What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown KernelVersion: diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x index 6adba9058b22..66b621f10223 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x +++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x @@ -6,10 +6,14 @@ Description: Get measured values from the ADC for these stages. Y is the specific stage number corresponding to datasheet stage names as follows: - 1 -> LED2 - 2 -> ALED2/LED3 - 3 -> LED1 - 4 -> ALED1/LED4 + + == ========== + 1 LED2 + 2 ALED2/LED3 + 3 LED1 + 4 ALED1/LED4 + == ========== + Note that channels 5 and 6 represent LED2-ALED2 and LED1-ALED1 respectively which simply helper channels containing the calculated difference in the value of stage 1 - 2 and 3 - 4. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 index f0ce0a0476ea..220206a20d98 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 +++ b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 @@ -15,5 +15,7 @@ Description: Scheme 0 has wider dynamic range, Scheme 1 proximity detection is less affected by the ambient IR noise variation. - 0 Sensing IR from LED and ambient - 1 Sensing IR from LED with ambient IR rejection + == ============================================= + 0 Sensing IR from LED and ambient + 1 Sensing IR from LED with ambient IR rejection + == ============================================= diff --git a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 index ad2cc63e4bf8..73498ff666bd 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 @@ -17,9 +17,11 @@ KernelVersion: 4.13 Contact: fabrice.gasnier@st.com Description: Configure the device counter quadrature modes: + - non-quadrature: Encoder IN1 input servers as the count input (up direction). + - quadrature: Encoder IN1 and IN2 inputs are mixed to get direction and count. @@ -35,23 +37,26 @@ KernelVersion: 4.13 Contact: fabrice.gasnier@st.com Description: Configure the device encoder/counter active edge: + - rising-edge - falling-edge - both-edges In non-quadrature mode, device counts up on active edge. + In quadrature mode, encoder counting scenarios are as follows: - ---------------------------------------------------------------- + + +---------+----------+--------------------+--------------------+ | Active | Level on | IN1 signal | IN2 signal | - | edge | opposite |------------------------------------------ + | edge | opposite +----------+---------+----------+---------+ | | signal | Rising | Falling | Rising | Falling | - ---------------------------------------------------------------- - | Rising | High -> | Down | - | Up | - | - | edge | Low -> | Up | - | Down | - | - ---------------------------------------------------------------- - | Falling | High -> | - | Up | - | Down | - | edge | Low -> | - | Down | - | Up | - ---------------------------------------------------------------- - | Both | High -> | Down | Up | Up | Down | - | edges | Low -> | Up | Down | Down | Up | - ---------------------------------------------------------------- + +---------+----------+----------+---------+----------+---------+ + | Rising | High -> | Down | - | Up | - | + | edge | Low -> | Up | - | Down | - | + +---------+----------+----------+---------+----------+---------+ + | Falling | High -> | - | Up | - | Down | + | edge | Low -> | - | Down | - | Up | + +---------+----------+----------+---------+----------+---------+ + | Both | High -> | Down | Up | Up | Down | + | edges | Low -> | Up | Down | Down | Up | + +---------+----------+----------+---------+----------+---------+ diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 index 6275e9f56e6c..13f099ef6a95 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 +++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 @@ -5,11 +5,16 @@ Contact: linux-iio@vger.kernel.org Description: Current configuration and available configurations for the bias current. - normal - Normal measurement configurations (default) - positivebias - Positive bias configuration - negativebias - Negative bias configuration - disabled - Only available on HMC5983. Disables magnetic + + ============ ============================================ + normal Normal measurement configurations (default) + positivebias Positive bias configuration + negativebias Negative bias configuration + disabled Only available on HMC5983. Disables magnetic sensor and enables temperature sensor. - Note: The effect of this configuration may vary - according to the device. For exact documentation - check the device's datasheet. + ============ ============================================ + + Note: + The effect of this configuration may vary + according to the device. For exact documentation + check the device's datasheet. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 index 3b3509a3ef2f..e5ef6d8e5da1 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 @@ -5,9 +5,12 @@ Description: Open-circuit fault. The detection of open-circuit faults, such as those caused by broken thermocouple wires. Reading returns either '1' or '0'. - '1' = An open circuit such as broken thermocouple wires - has been detected. - '0' = No open circuit or broken thermocouple wires are detected + + === ======================================================= + '1' An open circuit such as broken thermocouple wires + has been detected. + '0' No open circuit or broken thermocouple wires are detected + === ======================================================= What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv KernelVersion: 5.1 @@ -18,7 +21,11 @@ Description: cables by integrated MOSFETs at the T+ and T- inputs, and the BIAS output. These MOSFETs turn off when the input voltage is negative or greater than VDD. + Reading returns either '1' or '0'. - '1' = The input voltage is negative or greater than VDD. - '0' = The input voltage is positive and less than VDD (normal - state). + + === ======================================================= + '1' The input voltage is negative or greater than VDD. + '0' The input voltage is positive and less than VDD (normal + state). + === ======================================================= diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 index b7259234ad70..c4a4497c249a 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 @@ -3,67 +3,85 @@ KernelVersion: 4.11 Contact: benjamin.gaignard@st.com Description: Reading returns the list possible master modes which are: - - "reset" : The UG bit from the TIMx_EGR register is + + + - "reset" + The UG bit from the TIMx_EGR register is used as trigger output (TRGO). - - "enable" : The Counter Enable signal CNT_EN is used + - "enable" + The Counter Enable signal CNT_EN is used as trigger output. - - "update" : The update event is selected as trigger output. + - "update" + The update event is selected as trigger output. For instance a master timer can then be used as a prescaler for a slave timer. - - "compare_pulse" : The trigger output send a positive pulse - when the CC1IF flag is to be set. - - "OC1REF" : OC1REF signal is used as trigger output. - - "OC2REF" : OC2REF signal is used as trigger output. - - "OC3REF" : OC3REF signal is used as trigger output. - - "OC4REF" : OC4REF signal is used as trigger output. + - "compare_pulse" + The trigger output send a positive pulse + when the CC1IF flag is to be set. + - "OC1REF" + OC1REF signal is used as trigger output. + - "OC2REF" + OC2REF signal is used as trigger output. + - "OC3REF" + OC3REF signal is used as trigger output. + - "OC4REF" + OC4REF signal is used as trigger output. + Additional modes (on TRGO2 only): - - "OC5REF" : OC5REF signal is used as trigger output. - - "OC6REF" : OC6REF signal is used as trigger output. + + - "OC5REF" + OC5REF signal is used as trigger output. + - "OC6REF" + OC6REF signal is used as trigger output. - "compare_pulse_OC4REF": - OC4REF rising or falling edges generate pulses. + OC4REF rising or falling edges generate pulses. - "compare_pulse_OC6REF": - OC6REF rising or falling edges generate pulses. + OC6REF rising or falling edges generate pulses. - "compare_pulse_OC4REF_r_or_OC6REF_r": - OC4REF or OC6REF rising edges generate pulses. + OC4REF or OC6REF rising edges generate pulses. - "compare_pulse_OC4REF_r_or_OC6REF_f": - OC4REF rising or OC6REF falling edges generate pulses. + OC4REF rising or OC6REF falling edges generate + pulses. - "compare_pulse_OC5REF_r_or_OC6REF_r": - OC5REF or OC6REF rising edges generate pulses. + OC5REF or OC6REF rising edges generate pulses. - "compare_pulse_OC5REF_r_or_OC6REF_f": - OC5REF rising or OC6REF falling edges generate pulses. - - +-----------+ +-------------+ +---------+ - | Prescaler +-> | Counter | +-> | Master | TRGO(2) - +-----------+ +--+--------+-+ |-> | Control +--> - | | || +---------+ - +--v--------+-+ OCxREF || +---------+ - | Chx compare +----------> | Output | ChX - +-----------+-+ | | Control +--> - . | | +---------+ - . | | . - +-----------v-+ OC6REF | . - | Ch6 compare +---------+> - +-------------+ - - Example with: "compare_pulse_OC4REF_r_or_OC6REF_r": - - X - X X - X . . X - X . . X - X . . X - count X . . . . X - . . . . - . . . . - +---------------+ - OC4REF | . . | - +-+ . . +-+ - . +---+ . - OC6REF . | | . - +-------+ +-------+ - +-+ +-+ - TRGO2 | | | | - +-+ +---+ +---------+ + OC5REF rising or OC6REF falling edges generate + pulses. + + :: + + +-----------+ +-------------+ +---------+ + | Prescaler +-> | Counter | +-> | Master | TRGO(2) + +-----------+ +--+--------+-+ |-> | Control +--> + | | || +---------+ + +--v--------+-+ OCxREF || +---------+ + | Chx compare +----------> | Output | ChX + +-----------+-+ | | Control +--> + . | | +---------+ + . | | . + +-----------v-+ OC6REF | . + | Ch6 compare +---------+> + +-------------+ + + Example with: "compare_pulse_OC4REF_r_or_OC6REF_r":: + + X + X X + X . . X + X . . X + X . . X + count X . . . . X + . . . . + . . . . + +---------------+ + OC4REF | . . | + +-+ . . +-+ + . +---+ . + OC6REF . | | . + +-------+ +-------+ + +-+ +-+ + TRGO2 | | | | + +-+ +---+ +---------+ What: /sys/bus/iio/devices/triggerX/master_mode KernelVersion: 4.11 @@ -104,6 +122,7 @@ Description: Configure the device counter enable modes, in all case counting direction is set by in_count0_count_direction attribute and the counter is clocked by the internal clock. + always: Counter is always ON. diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth index 22d0843849a8..b7b2278fe042 100644 --- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth @@ -10,10 +10,13 @@ Date: June 2015 KernelVersion: 4.3 Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> Description: (RO) Output port type: - 0: not present, - 1: MSU (Memory Storage Unit) - 2: CTP (Common Trace Port) - 4: PTI (MIPI PTI). + + == ========================= + 0 not present, + 1 MSU (Memory Storage Unit) + 2 CTP (Common Trace Port) + 4 PTI (MIPI PTI). + == ========================= What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_drop Date: June 2015 diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc index 7fd2601c2831..a74252e580a5 100644 --- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc @@ -9,11 +9,13 @@ Date: June 2015 KernelVersion: 4.3 Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> 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; - 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. @@ -23,10 +25,12 @@ Date: June 2015 KernelVersion: 4.3 Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> Description: (RW) Configure MSC buffer size for "single" or "multi" modes. + In single mode, this is a single number of pages, has to be power of 2. In multiblock mode, this is a comma-separated list of numbers of pages for each window to be allocated. Number of windows is not limited. + Writing to this file deallocates existing buffer (provided there are no active users and tracing is not enabled) and then allocates a new one. diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most index ec0a603d804b..38cc03e408e7 100644 --- a/Documentation/ABI/testing/sysfs-bus-most +++ b/Documentation/ABI/testing/sysfs-bus-most @@ -235,7 +235,8 @@ KernelVersion: 4.15 Contact: Christian Gromm <christian.gromm@microchip.com> Description: This is to read back the configured direction of the channel. - The following strings will be accepted: + The following strings will be accepted:: + 'tx', 'rx' Users: @@ -246,7 +247,8 @@ KernelVersion: 4.15 Contact: Christian Gromm <christian.gromm@microchip.com> Description: This is to read back the configured data type of the channel. - The following strings will be accepted: + The following strings will be accepted:: + 'control', 'async', 'sync', diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices index 355958527fa3..4a6d61b44f3f 100644 --- a/Documentation/ABI/testing/sysfs-bus-moxtet-devices +++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices @@ -2,16 +2,16 @@ 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 +Description: (Read) 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 +Description: (Read) 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 +Description: (Read) Moxtet module name. Format: string diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit index e4f76e7eab93..63ef0b9ecce7 100644 --- a/Documentation/ABI/testing/sysfs-bus-nfit +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -1,4 +1,4 @@ -For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware +For all of the nmem device attributes under ``nfit/*``, see the 'NVDIMM Firmware Interface Table (NFIT)' section in the ACPI specification (http://www.uefi.org/specifications) for more details. diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm index d64380262be8..bff84a16812a 100644 --- a/Documentation/ABI/testing/sysfs-bus-nvdimm +++ b/Documentation/ABI/testing/sysfs-bus-nvdimm @@ -1,2 +1,8 @@ +What: nvdimm +Date: July 2020 +KernelVersion: 5.8 +Contact: Dan Williams <dan.j.williams@intel.com> +Description: + The libnvdimm sub-system implements a common sysfs interface for platform nvdimm resources. See Documentation/driver-api/nvdimm/. diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem index c1a67275c43f..8316c33862a0 100644 --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -11,19 +11,26 @@ Description: at 'Documentation/powerpc/papr_hcalls.rst' . Below are the flags reported in this sysfs file: - * "not_armed" : Indicates that NVDIMM contents will not + * "not_armed" + Indicates that NVDIMM contents will not survive a power cycle. - * "flush_fail" : Indicates that NVDIMM contents + * "flush_fail" + Indicates that NVDIMM contents couldn't be flushed during last shut-down event. - * "restore_fail": Indicates that NVDIMM contents + * "restore_fail" + Indicates that NVDIMM contents couldn't be restored during NVDIMM initialization. - * "encrypted" : NVDIMM contents are encrypted. - * "smart_notify": There is health event for the NVDIMM. - * "scrubbed" : Indicating that contents of the + * "encrypted" + NVDIMM contents are encrypted. + * "smart_notify" + There is health event for the NVDIMM. + * "scrubbed" + Indicating that contents of the NVDIMM have been scrubbed. - * "locked" : Indicating that NVDIMM contents cant + * "locked" + Indicating that NVDIMM contents cant be modified until next power cycle. What: /sys/bus/nd/devices/nmemX/papr/perf_stats @@ -51,4 +58,4 @@ Description: * "MedWDur " : Media Write Duration * "CchRHCnt" : Cache Read Hit Count * "CchWHCnt" : Cache Write Hit Count - * "FastWCnt" : Fast Write Count
\ No newline at end of file + * "FastWCnt" : Fast Write Count diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 450296cc7948..77ad9ec3c801 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -7,8 +7,10 @@ Description: this location. This is useful for overriding default bindings. The format for the location is: DDDD:BB:DD.F. That is Domain:Bus:Device.Function and is the same as - found in /sys/bus/pci/devices/. For example: - # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind + found in /sys/bus/pci/devices/. For example:: + + # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind + (Note: kernels before 2.6.28 may require echo -n). What: /sys/bus/pci/drivers/.../unbind @@ -20,8 +22,10 @@ Description: this location. This may be useful when overriding default bindings. The format for the location is: DDDD:BB:DD.F. That is Domain:Bus:Device.Function and is the same as - found in /sys/bus/pci/devices/. For example: - # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind + found in /sys/bus/pci/devices/. For example:: + + # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind + (Note: kernels before 2.6.28 may require echo -n). What: /sys/bus/pci/drivers/.../new_id @@ -38,8 +42,9 @@ Description: Class, Class Mask, and Private Driver Data. The Vendor ID and Device ID fields are required, the rest are optional. Upon successfully adding an ID, the driver will probe - for the device and attempt to bind to it. For example: - # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id + for the device and attempt to bind to it. For example:: + + # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id What: /sys/bus/pci/drivers/.../remove_id Date: February 2009 @@ -54,8 +59,9 @@ Description: required, the rest are optional. After successfully removing an ID, the driver will no longer support the device. This is useful to ensure auto probing won't - match the driver to the device. For example: - # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id + match the driver to the device. For example:: + + # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id What: /sys/bus/pci/rescan Date: January 2009 diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats index 3c9a8c4a25eb..860db53037a5 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats @@ -1,6 +1,6 @@ -========================== PCIe Device AER statistics -========================== +-------------------------- + These attributes show up under all the devices that are AER capable. These statistical counters indicate the errors "as seen/reported by the device". Note that this may mean that if an endpoint is causing problems, the AER @@ -17,19 +17,18 @@ Description: List of correctable errors seen and reported by this PCI device using ERR_COR. Note that since multiple errors may be reported using a single ERR_COR message, thus TOTAL_ERR_COR at the end of the file may not match the actual - total of all the errors in the file. Sample output: -------------------------------------------------------------------------- -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable -Receiver Error 2 -Bad TLP 0 -Bad DLLP 0 -RELAY_NUM Rollover 0 -Replay Timer Timeout 0 -Advisory Non-Fatal 0 -Corrected Internal Error 0 -Header Log Overflow 0 -TOTAL_ERR_COR 2 -------------------------------------------------------------------------- + total of all the errors in the file. Sample output:: + + localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable + Receiver Error 2 + Bad TLP 0 + Bad DLLP 0 + RELAY_NUM Rollover 0 + Replay Timer Timeout 0 + Advisory Non-Fatal 0 + Corrected Internal Error 0 + Header Log Overflow 0 + TOTAL_ERR_COR 2 What: /sys/bus/pci/devices/<dev>/aer_dev_fatal Date: July 2018 @@ -39,28 +38,27 @@ Description: List of uncorrectable fatal errors seen and reported by this PCI device using ERR_FATAL. Note that since multiple errors may be reported using a single ERR_FATAL message, thus TOTAL_ERR_FATAL at the end of the file may not match the actual - total of all the errors in the file. Sample output: -------------------------------------------------------------------------- -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal -Undefined 0 -Data Link Protocol 0 -Surprise Down Error 0 -Poisoned TLP 0 -Flow Control Protocol 0 -Completion Timeout 0 -Completer Abort 0 -Unexpected Completion 0 -Receiver Overflow 0 -Malformed TLP 0 -ECRC 0 -Unsupported Request 0 -ACS Violation 0 -Uncorrectable Internal Error 0 -MC Blocked TLP 0 -AtomicOp Egress Blocked 0 -TLP Prefix Blocked Error 0 -TOTAL_ERR_FATAL 0 -------------------------------------------------------------------------- + total of all the errors in the file. Sample output:: + + localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal + Undefined 0 + Data Link Protocol 0 + Surprise Down Error 0 + Poisoned TLP 0 + Flow Control Protocol 0 + Completion Timeout 0 + Completer Abort 0 + Unexpected Completion 0 + Receiver Overflow 0 + Malformed TLP 0 + ECRC 0 + Unsupported Request 0 + ACS Violation 0 + Uncorrectable Internal Error 0 + MC Blocked TLP 0 + AtomicOp Egress Blocked 0 + TLP Prefix Blocked Error 0 + TOTAL_ERR_FATAL 0 What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal Date: July 2018 @@ -70,32 +68,31 @@ Description: List of uncorrectable nonfatal errors seen and reported by this PCI device using ERR_NONFATAL. Note that since multiple errors may be reported using a single ERR_FATAL message, thus TOTAL_ERR_NONFATAL at the end of the file may not match the - actual total of all the errors in the file. Sample output: -------------------------------------------------------------------------- -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal -Undefined 0 -Data Link Protocol 0 -Surprise Down Error 0 -Poisoned TLP 0 -Flow Control Protocol 0 -Completion Timeout 0 -Completer Abort 0 -Unexpected Completion 0 -Receiver Overflow 0 -Malformed TLP 0 -ECRC 0 -Unsupported Request 0 -ACS Violation 0 -Uncorrectable Internal Error 0 -MC Blocked TLP 0 -AtomicOp Egress Blocked 0 -TLP Prefix Blocked Error 0 -TOTAL_ERR_NONFATAL 0 -------------------------------------------------------------------------- + actual total of all the errors in the file. Sample output:: + + localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal + Undefined 0 + Data Link Protocol 0 + Surprise Down Error 0 + Poisoned TLP 0 + Flow Control Protocol 0 + Completion Timeout 0 + Completer Abort 0 + Unexpected Completion 0 + Receiver Overflow 0 + Malformed TLP 0 + ECRC 0 + Unsupported Request 0 + ACS Violation 0 + Uncorrectable Internal Error 0 + MC Blocked TLP 0 + AtomicOp Egress Blocked 0 + TLP Prefix Blocked Error 0 + TOTAL_ERR_NONFATAL 0 -============================ PCIe Rootport AER statistics -============================ +---------------------------- + These attributes show up under only the rootports (or root complex event collectors) that are AER capable. These indicate the number of error messages as "reported to" the rootport. Please note that the rootports also transmit diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt index 8a200f4eefbd..f85db86d63e8 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt @@ -4,6 +4,7 @@ Contact: Cezary Rojewski <cezary.rojewski@intel.com> Description: Version of AudioDSP firmware ASoC catpt driver is communicating with. + Format: %d.%d.%d.%d, type:major:minor:build. What: /sys/devices/pci0000:00/<dev>/fw_info diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd index 60c60fa624b2..c90d97a80855 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd +++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd @@ -21,11 +21,11 @@ Description: number returns the port to normal operation. For example: To force the high-speed device attached to - port 4 on bus 2 to run at full speed: + port 4 on bus 2 to run at full speed:: echo 4 >/sys/bus/usb/devices/usb2/../companion - To return the port to high-speed operation: + To return the port to high-speed operation:: echo -4 >/sys/bus/usb/devices/usb2/../companion diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio index 13208b27dd87..634ea207a50a 100644 --- a/Documentation/ABI/testing/sysfs-bus-rapidio +++ b/Documentation/ABI/testing/sysfs-bus-rapidio @@ -4,24 +4,27 @@ Description: an individual subdirectory with the following name format of device_name "nn:d:iiii", where: - nn - two-digit hexadecimal ID of RapidIO network where the + ==== ======================================================== + nn two-digit hexadecimal ID of RapidIO network where the device resides - d - device type: 'e' - for endpoint or 's' - for switch - iiii - four-digit device destID for endpoints, or switchID for + d device type: 'e' - for endpoint or 's' - for switch + iiii four-digit device destID for endpoints, or switchID for switches + ==== ======================================================== For example, below is a list of device directories that represents a typical RapidIO network with one switch, one host, and two agent endpoints, as it is seen by the enumerating host - (with destID = 1): + (with destID = 1):: - /sys/bus/rapidio/devices/00:e:0000 - /sys/bus/rapidio/devices/00:e:0002 - /sys/bus/rapidio/devices/00:s:0001 + /sys/bus/rapidio/devices/00:e:0000 + /sys/bus/rapidio/devices/00:e:0002 + /sys/bus/rapidio/devices/00:s:0001 - NOTE: An enumerating or discovering endpoint does not create a - sysfs entry for itself, this is why an endpoint with destID=1 is - not shown in the list. + NOTE: + An enumerating or discovering endpoint does not create a + sysfs entry for itself, this is why an endpoint with destID=1 + is not shown in the list. Attributes Common for All RapidIO Devices ----------------------------------------- diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd index cc30bee8b5f4..417a2fe21be1 100644 --- a/Documentation/ABI/testing/sysfs-bus-rbd +++ b/Documentation/ABI/testing/sysfs-bus-rbd @@ -7,6 +7,8 @@ Description: Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>] + Example:: + $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add The snapshot name can be "-" or omitted to map the image @@ -23,6 +25,8 @@ Description: Usage: <dev-id> [force] + Example:: + $ echo 2 > /sys/bus/rbd/remove Optional "force" argument which when passed will wait for @@ -80,26 +84,29 @@ Date: Oct, 2010 KernelVersion: v2.6.37 Contact: Sage Weil <sage@newdream.net> Description: - size: (RO) The size (in bytes) of the mapped block + + ============== ================================================ + size (RO) The size (in bytes) of the mapped block device. - major: (RO) The block device major number. + major (RO) The block device major number. - client_id: (RO) The ceph unique client id that was assigned + client_id (RO) The ceph unique client id that was assigned for this specific session. - pool: (RO) The name of the storage pool where this rbd + pool (RO) The name of the storage pool where this rbd image resides. An rbd image name is unique within its pool. - name: (RO) The name of the rbd image. + name (RO) The name of the rbd image. - refresh: (WO) Writing to this file will reread the image + refresh (WO) Writing to this file will reread the image header data and set all relevant data structures accordingly. - current_snap: (RO) The current snapshot for which the device + current_snap (RO) The current snapshot for which the device is mapped. + ============== ================================================ What: /sys/bus/rbd/devices/<dev-id>/pool_id @@ -117,11 +124,13 @@ Date: Oct, 2012 KernelVersion: v3.7 Contact: Sage Weil <sage@newdream.net> Description: - image_id: (RO) The unique id for the rbd image. (For rbd + ========= =============================================== + image_id (RO) The unique id for the rbd image. (For rbd image format 1 this is empty.) - features: (RO) A hexadecimal encoding of the feature bits + features (RO) A hexadecimal encoding of the feature bits for this image. + ========= =============================================== What: /sys/bus/rbd/devices/<dev-id>/parent @@ -149,14 +158,16 @@ Date: Aug, 2016 KernelVersion: v4.9 Contact: Sage Weil <sage@newdream.net> Description: - snap_id: (RO) The current snapshot's id. + ============ ================================================ + snap_id (RO) The current snapshot's id. - config_info: (RO) The string written into + config_info (RO) The string written into /sys/bus/rbd/add{,_single_major}. - cluster_fsid: (RO) The ceph cluster UUID. + cluster_fsid (RO) The ceph cluster UUID. - client_addr: (RO) The ceph unique client + client_addr (RO) The ceph unique client entity_addr_t (address + nonce). The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or '[1:2:3:4:5:6:7:8]:1234/5678'. + ============ ================================================ diff --git a/Documentation/ABI/testing/sysfs-bus-siox b/Documentation/ABI/testing/sysfs-bus-siox index c2a403f20b90..50e80238f30d 100644 --- a/Documentation/ABI/testing/sysfs-bus-siox +++ b/Documentation/ABI/testing/sysfs-bus-siox @@ -8,6 +8,7 @@ Description: When the file contains a "1" the bus is operated and periodically does a push-pull cycle to write and read data from the connected devices. + When writing a "0" or "1" the bus moves to the described state. What: /sys/bus/siox/devices/siox-X/device_add @@ -21,8 +22,10 @@ Description: to add a new device dynamically. <type> is the name that is used to match to a driver (similar to the platform bus). <inbytes> and <outbytes> define the length of the input and output shift register in bytes respectively. + <statustype> defines the 4 bit device type that is check to identify connection problems. + The new device is added to the end of the existing chain. What: /sys/bus/siox/devices/siox-X/device_remove diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index dd565c378b40..0b4ab9e4b8f4 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -37,16 +37,18 @@ Contact: thunderbolt-software@lists.01.org Description: This attribute holds current Thunderbolt security level set by the system BIOS. Possible values are: - none: All devices are automatically authorized - user: Devices are only authorized based on writing - appropriate value to the authorized attribute - secure: Require devices that support secure connect at - minimum. User needs to authorize each device. - dponly: Automatically tunnel Display port (and USB). No - PCIe tunnels are created. - usbonly: Automatically tunnel USB controller of the + ======= ================================================== + none All devices are automatically authorized + user Devices are only authorized based on writing + appropriate value to the authorized attribute + secure Require devices that support secure connect at + minimum. User needs to authorize each device. + dponly Automatically tunnel Display port (and USB). No + PCIe tunnels are created. + usbonly Automatically tunnel USB controller of the connected Thunderbolt dock (and Display Port). All PCIe links downstream of the dock are removed. + ======= ================================================== What: /sys/bus/thunderbolt/devices/.../authorized Date: Sep 2017 @@ -61,17 +63,23 @@ Description: This attribute is used to authorize Thunderbolt devices yet authorized. Possible values are supported: - 1: The device will be authorized and connected + + == =========================================== + 1 The device will be authorized and connected + == =========================================== When key attribute contains 32 byte hex string the possible values are: - 1: The 32 byte hex string is added to the device NVM and - the device is authorized. - 2: Send a challenge based on the 32 byte hex string. If the - challenge response from device is valid, the device is - authorized. In case of failure errno will be ENOKEY if - the device did not contain a key at all, and - EKEYREJECTED if the challenge response did not match. + + == ======================================================== + 1 The 32 byte hex string is added to the device NVM and + the device is authorized. + 2 Send a challenge based on the 32 byte hex string. If the + challenge response from device is valid, the device is + authorized. In case of failure errno will be ENOKEY if + the device did not contain a key at all, and + EKEYREJECTED if the challenge response did not match. + == ======================================================== What: /sys/bus/thunderbolt/devices/.../boot Date: Jun 2018 @@ -185,10 +193,11 @@ Description: When new NVM image is written to the non-active NVM verification fails an error code is returned instead. This file will accept writing values "1" or "2" + - Writing "1" will flush the image to the storage - area and authenticate the image in one action. + area and authenticate the image in one action. - Writing "2" will run some basic validation on the image - and flush it to the storage area. + and flush it to the storage area. When read holds status of the last authentication operation if an error occurred during the process. This @@ -205,9 +214,11 @@ Description: This contains name of the property directory the XDomain question. Following directories are already reserved by the Apple XDomain specification: - network: IP/ethernet over Thunderbolt - targetdm: Target disk mode protocol over Thunderbolt - extdisp: External display mode protocol over Thunderbolt + ======== =============================================== + network IP/ethernet over Thunderbolt + targetdm Target disk mode protocol over Thunderbolt + extdisp External display mode protocol over Thunderbolt + ======== =============================================== What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/modalias Date: Jan 2018 @@ -285,7 +296,8 @@ Description: For supported devices, automatically authenticate the new Thunderbo image when the device is disconnected from the host system. This file will accept writing values "1" or "2" + - Writing "1" will flush the image to the storage - area and prepare the device for authentication on disconnect. + area and prepare the device for authentication on disconnect. - Writing "2" will run some basic validation on the image - and flush it to the storage area. + and flush it to the storage area. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 614d216dff1d..bf2c1968525f 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -9,6 +9,7 @@ Description: by writing INTERFACE to /sys/bus/usb/drivers_probe This allows to avoid side-effects with drivers that need multiple interfaces. + A deauthorized interface cannot be probed or claimed. What: /sys/bus/usb/devices/usbX/interface_authorized_default @@ -72,24 +73,27 @@ Description: table at compile time. The format for the device ID is: idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct The vendor ID and device ID fields are required, the - rest is optional. The Ref* tuple can be used to tell the + rest is optional. The `Ref*` tuple can be used to tell the driver to use the same driver_data for the new device as it is used for the reference device. Upon successfully adding an ID, the driver will probe - for the device and attempt to bind to it. For example: - # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id + for the device and attempt to bind to it. For example:: + + # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id Here add a new device (0458:7045) using driver_data from - an already supported device (0458:704c): - # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id + an already supported device (0458:704c):: + + # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id Reading from this file will list all dynamically added device IDs in the same format, with one entry per - line. For example: - # cat /sys/bus/usb/drivers/foo/new_id - 8086 10f5 - dead beef 06 - f00d cafe + line. For example:: + + # cat /sys/bus/usb/drivers/foo/new_id + 8086 10f5 + dead beef 06 + f00d cafe The list will be truncated at PAGE_SIZE bytes due to sysfs restrictions. @@ -209,9 +213,11 @@ Description: advance, and behaves well according to the specification. This attribute is a bit-field that controls the behavior of a specific port: + - Bit 0 of this field selects the "old" enumeration scheme, as it is considerably faster (it only causes one USB reset instead of 2). + The old enumeration scheme can also be selected globally using /sys/module/usbcore/parameters/old_scheme_first, but it is often not desirable as the new scheme was introduced to @@ -233,10 +239,10 @@ Description: poll() for monitoring changes to this value in user space. Any time this value changes the corresponding hub device will send a - udev event with the following attributes: + udev event with the following attributes:: - OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX - OVER_CURRENT_COUNT=[current value of this sysfs attribute] + OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX + OVER_CURRENT_COUNT=[current value of this sysfs attribute] What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit Date: November 2015 diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg index 9ade80f81f96..2f86e4223bfc 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg @@ -12,8 +12,11 @@ KernelVersion: 2.6.26 Contact: Harrison Metzger <harrisonmetz@gmail.com> Description: Controls the devices display mode. For a 6 character display the values are + MSB 0x06; LSB 0x3F, and + for an 8 character display the values are + MSB 0x08; LSB 0xFF. What: /sys/bus/usb/.../textmode @@ -37,7 +40,7 @@ KernelVersion: 2.6.26 Contact: Harrison Metzger <harrisonmetz@gmail.com> Description: Controls the decimal places on the device. To set the nth decimal place, give this field - the value of 10 ** n. Assume this field has + the value of ``10 ** n``. Assume this field has the value k and has 1 or more decimal places set, to set the mth place (where m is not already set), - change this fields value to k + 10 ** m. + change this fields value to ``k + 10 ** m``. diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev index 452dbe39270e..59fc804265db 100644 --- a/Documentation/ABI/testing/sysfs-bus-vfio-mdev +++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev @@ -28,8 +28,9 @@ Description: Writing UUID to this file will create mediated device of type <type-id> for parent device <device>. This is a write-only file. - For example: - # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \ + For example:: + + # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \ /sys/devices/foo/mdev_supported_types/foo-1/create What: /sys/.../mdev_supported_types/<type-id>/devices/ @@ -107,5 +108,6 @@ Description: Writing '1' to this file destroys the mediated device. The vendor driver can fail the remove() callback if that device is active and the vendor driver doesn't support hot unplug. - Example: - # echo 1 > /sys/bus/mdev/devices/<UUID>/remove + Example:: + + # echo 1 > /sys/bus/mdev/devices/<UUID>/remove diff --git a/Documentation/ABI/testing/sysfs-c2port b/Documentation/ABI/testing/sysfs-c2port index 716cffc457e9..f7b8cf6e4398 100644 --- a/Documentation/ABI/testing/sysfs-c2port +++ b/Documentation/ABI/testing/sysfs-c2port @@ -66,13 +66,6 @@ Description: the "erase" command on the on-board flash of the connected micro. -What: /sys/class/c2port/c2portX/flash_erase -Date: October 2008 -Contact: Rodolfo Giometti <giometti@linux.it> -Description: - The /sys/class/c2port/c2portX/flash_erase file show the - on-board flash size of the connected micro. - What: /sys/class/c2port/c2portX/reset Date: October 2008 Contact: Rodolfo Giometti <giometti@linux.it> diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight index 3ab175a3f5cb..1fc86401bf95 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight +++ b/Documentation/ABI/testing/sysfs-class-backlight @@ -24,3 +24,63 @@ Description: non-linear The brightness changes non-linearly with each step. Brightness controls should use a linear mapping for a linear perception. + +What: /sys/class/backlight/<backlight>/ambient_light_level +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich <michael.hennerich@analog.com> +Description: + (RO) Get conversion value of the light sensor. + + The value is automatically updated every 80 ms when the + light sensor is enabled. + + The value range is device-driver specific: + + For ADP8870: + + It returns integer between 0 (dark) and 8000 (max ambient + brightness). + + For ADP8860: + + It returns a 13-bits integer. + +What: /sys/class/backlight/<backlight>/ambient_light_zone +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich <michael.hennerich@analog.com>, + device-drivers-devel@blackfin.uclinux.org + +Description: + (RW) Read or write the specific brightness level at which the + backlight operates. + + The value meaning is device-driver specific: + + For ADP8860: + + == ========================== + 0 Off: Backlight set to 0 mA + 1 Level 1: daylight + 2 Level 2: bright + 3 Level 3: dark + == ========================== + + For ADP8870: + + == ========================== + 0 Off: Backlight set to 0 mA + 1 Level 1: daylight + 2 Level 2: bright + 3 Level 3: office + 4 Level 4: indoor + 5 Level 5: dark + == ========================== + + Writing 0 returns to normal/automatic ambient light level + operation. + + It can be enabled by writing the value stored in + /sys/class/backlight/<backlight>/max_brightness to + /sys/class/backlight/<backlight>/brightness. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 index 54d61c788b1b..6610ac73f9ba 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 +++ b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 @@ -6,25 +6,8 @@ adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and dark (level 3). By default the brightness operates at the daylight brightness level. -What: /sys/class/backlight/<backlight>/ambient_light_level -Date: Apr, 2010 -KernelVersion: v2.6.35 -Contact: Michael Hennerich <michael.hennerich@analog.com> -Description: - (RO) 13-bit conversion value for the first light sensor—high - byte (Bit 12 to Bit 8). The value is updated every 80 ms (when - the light sensor is enabled). - - -What: /sys/class/backlight/<backlight>/ambient_light_zone -Date: Apr, 2010 -KernelVersion: v2.6.35 -Contact: Michael Hennerich <michael.hennerich@analog.com> -Description: - (RW) Read or write the specific level at which the backlight - operates. Value "0" enables automatic ambient light sensing, and - values "1", "2" or "3" set the control to daylight, office or - dark respectively. +See also /sys/class/backlight/<backlight>/ambient_light_level and +/sys/class/backlight/<backlight>/ambient_light_zone. What: /sys/class/backlight/<backlight>/l1_daylight_max diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 index 33e648808117..b08ca912cad4 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 @@ -1,3 +1,6 @@ +See also /sys/class/backlight/<backlight>/ambient_light_level and +/sys/class/backlight/<backlight>/ambient_light_zone. + What: /sys/class/backlight/<backlight>/<ambient light zone>_max What: /sys/class/backlight/<backlight>/l1_daylight_max What: /sys/class/backlight/<backlight>/l2_bright_max @@ -27,30 +30,3 @@ Description: set to 0. Full off when the backlight is disabled. This file will also show the dim brightness level stored for this <ambient light zone>. - -What: /sys/class/backlight/<backlight>/ambient_light_level -Date: May 2011 -KernelVersion: 3.0 -Contact: device-drivers-devel@blackfin.uclinux.org -Description: - Get conversion value of the light sensor. - This value is updated every 80 ms (when the light sensor - is enabled). Returns integer between 0 (dark) and - 8000 (max ambient brightness) - -What: /sys/class/backlight/<backlight>/ambient_light_zone -Date: May 2011 -KernelVersion: 3.0 -Contact: device-drivers-devel@blackfin.uclinux.org -Description: - Get/Set current ambient light zone. Reading returns - integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark). - Writing a value between 1..5 forces the backlight controller - to enter the corresponding ambient light zone. - Writing 0 returns to normal/automatic ambient light level - operation. The ambient light sensing feature on these devices - is an extension to the API documented in - Documentation/ABI/stable/sysfs-class-backlight. - It can be enabled by writing the value stored in - /sys/class/backlight/<backlight>/max_brightness to - /sys/class/backlight/<backlight>/brightness. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 index c0e0a9ae7b3d..8251e78abc49 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 @@ -6,8 +6,10 @@ Description: Get the ALS output channel used as input in ALS-current-control mode (0, 1), where: - 0 - out_current0 (backlight 0) - 1 - out_current1 (backlight 1) + == ========================== + 0 out_current0 (backlight 0) + 1 out_current1 (backlight 1) + == ========================== What: /sys/class/backlight/<backlight>/als_en Date: May 2012 @@ -30,8 +32,10 @@ Contact: Johan Hovold <jhovold@gmail.com> Description: Set the brightness-mapping mode (0, 1), where: - 0 - exponential mode - 1 - linear mode + == ================ + 0 exponential mode + 1 linear mode + == ================ What: /sys/class/backlight/<backlight>/pwm Date: April 2012 @@ -40,9 +44,11 @@ Contact: Johan Hovold <jhovold@gmail.com> Description: Set the PWM-input control mask (5 bits), where: - bit 5 - PWM-input enabled in Zone 4 - bit 4 - PWM-input enabled in Zone 3 - bit 3 - PWM-input enabled in Zone 2 - bit 2 - PWM-input enabled in Zone 1 - bit 1 - PWM-input enabled in Zone 0 - bit 0 - PWM-input enabled + ===== =========================== + bit 5 PWM-input enabled in Zone 4 + bit 4 PWM-input enabled in Zone 3 + bit 3 PWM-input enabled in Zone 2 + bit 2 PWM-input enabled in Zone 1 + bit 1 PWM-input enabled in Zone 0 + bit 0 PWM-input enabled + ===== =========================== diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi index d773d5697cf5..5402bd74ba43 100644 --- a/Documentation/ABI/testing/sysfs-class-bdi +++ b/Documentation/ABI/testing/sysfs-class-bdi @@ -24,7 +24,6 @@ default filesystems which do not provide their own BDI. Files under /sys/class/bdi/<bdi>/ ---------------------------------- read_ahead_kb (read-write) diff --git a/Documentation/ABI/testing/sysfs-class-chromeos b/Documentation/ABI/testing/sysfs-class-chromeos index 5819699d66ec..74ece942722e 100644 --- a/Documentation/ABI/testing/sysfs-class-chromeos +++ b/Documentation/ABI/testing/sysfs-class-chromeos @@ -17,13 +17,14 @@ Date: August 2015 KernelVersion: 4.2 Description: Tell the EC to reboot in various ways. Options are: - "cancel": Cancel a pending reboot. - "ro": Jump to RO without rebooting. - "rw": Jump to RW without rebooting. - "cold": Cold reboot. - "disable-jump": Disable jump until next reboot. - "hibernate": Hibernate the EC. - "at-shutdown": Reboot after an AP shutdown. + + - "cancel": Cancel a pending reboot. + - "ro": Jump to RO without rebooting. + - "rw": Jump to RW without rebooting. + - "cold": Cold reboot. + - "disable-jump": Disable jump until next reboot. + - "hibernate": Hibernate the EC. + - "at-shutdown": Reboot after an AP shutdown. What: /sys/class/chromeos/<ec-device-name>/version Date: August 2015 diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl index 7970e3713e70..818f55970efb 100644 --- a/Documentation/ABI/testing/sysfs-class-cxl +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -72,11 +72,16 @@ Description: read/write when performing the START_WORK ioctl. Only applicable when running under hashed page table mmu. Possible values: - none: No prefaulting (default) - work_element_descriptor: Treat the work element - descriptor as an effective address and - prefault what it points to. - all: all segments process calling START_WORK maps. + + ======================= ====================================== + none No prefaulting (default) + work_element_descriptor Treat the work element + descriptor as an effective address and + prefault what it points to. + all all segments process calling + START_WORK maps. + ======================= ====================================== + Users: https://github.com/ibm-capi/libcxl What: /sys/class/cxl/<afu>/reset @@ -212,6 +217,7 @@ Description: read/write card. A power cycle is required to load the image. "none" could be useful for debugging because the trace arrays are preserved. + "user" and "factory" means PERST will cause either the user or user or factory image to be loaded. Default is to reload on PERST whichever image the card has @@ -235,8 +241,11 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read/write Trust that when an image is reloaded via PERST, it will not have changed. - 0 = don't trust, the image may be different (default) - 1 = trust that the image will not change. + + == ================================================= + 0 don't trust, the image may be different (default) + 1 trust that the image will not change. + == ================================================= Users: https://github.com/ibm-capi/libcxl What: /sys/class/cxl/<card>/psl_timebase_synced diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index deefffb3bbe4..b8ebff4b1c4c 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -62,7 +62,8 @@ Description: driver should provide the list of available frequencies with its profile. If need to reset the statistics of devfreq behavior on a specific device, enter 0(zero) to 'trans_stat' - as following: + as following:: + echo 0 > /sys/class/devfreq/.../trans_stat What: /sys/class/devfreq/.../userspace/set_freq @@ -117,6 +118,7 @@ Description: This work timer is used by devfreq workqueue in order to monitor the device status such as utilization. The user can change the work timer on runtime according to their demand - as following: + as following:: + echo deferrable > /sys/class/devfreq/.../timer echo delayed > /sys/class/devfreq/.../timer diff --git a/Documentation/ABI/testing/sysfs-class-devlink b/Documentation/ABI/testing/sysfs-class-devlink index 64791b65c9a3..b662f747c83e 100644 --- a/Documentation/ABI/testing/sysfs-class-devlink +++ b/Documentation/ABI/testing/sysfs-class-devlink @@ -18,9 +18,9 @@ Description: This will be one of the following strings: - 'consumer unbind' - 'supplier unbind' - 'never' + - 'consumer unbind' + - 'supplier unbind' + - 'never' 'consumer unbind' means the device link will be removed when the consumer's driver is unbound from the consumer device. @@ -49,8 +49,10 @@ Description: This will be one of the following strings: - '0' - Does not affect runtime power management - '1' - Affects runtime power management + === ======================================== + '0' Does not affect runtime power management + '1' Affects runtime power management + === ======================================== What: /sys/class/devlink/.../status Date: May 2020 @@ -68,13 +70,13 @@ Description: This will be one of the following strings: - 'not tracked' - 'dormant' - 'available' - 'consumer probing' - 'active' - 'supplier unbinding' - 'unknown' + - 'not tracked' + - 'dormant' + - 'available' + - 'consumer probing' + - 'active' + - 'supplier unbinding' + - 'unknown' 'not tracked' means this device link does not track the status and has no impact on the binding, unbinding and syncing the @@ -114,8 +116,10 @@ Description: This will be one of the following strings: + === ================================ '0' - '1' - Affects runtime power management + '1' Affects runtime power management + === ================================ '0' means the device link can affect other device behaviors like binding/unbinding, suspend/resume, runtime power diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon index 57a726232912..fde0fecd5de9 100644 --- a/Documentation/ABI/testing/sysfs-class-extcon +++ b/Documentation/ABI/testing/sysfs-class-extcon @@ -39,19 +39,22 @@ Description: callback. If the default callback for showing function is used, the - format is like this: - # cat state - USB_OTG=1 - HDMI=0 - TA=1 - EAR_JACK=0 - # + format is like this:: + + # cat state + USB_OTG=1 + HDMI=0 + TA=1 + EAR_JACK=0 + # + In this example, the extcon device has USB_OTG and TA cables attached and HDMI and EAR_JACK cables detached. In order to update the state of an extcon device, enter a hex - state number starting with 0x: - # echo 0xHEX > state + state number starting with 0x:: + + # echo 0xHEX > state This updates the whole state of the extcon device. Inputs of all the methods are required to meet the @@ -84,12 +87,13 @@ Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: Shows the relations of mutually exclusiveness. For example, if the mutually_exclusive array of extcon device is - {0x3, 0x5, 0xC, 0x0}, then the output is: - # ls mutually_exclusive/ - 0x3 - 0x5 - 0xc - # + {0x3, 0x5, 0xC, 0x0}, then the output is:: + + # ls mutually_exclusive/ + 0x3 + 0x5 + 0xc + # Note that mutually_exclusive is a sub-directory of the extcon device and the file names under the mutually_exclusive diff --git a/Documentation/ABI/testing/sysfs-class-fpga-manager b/Documentation/ABI/testing/sysfs-class-fpga-manager index 5284fa33d4c5..d78689c357a5 100644 --- a/Documentation/ABI/testing/sysfs-class-fpga-manager +++ b/Documentation/ABI/testing/sysfs-class-fpga-manager @@ -28,8 +28,7 @@ Description: Read fpga manager state as a string. * firmware request = firmware class request in progress * firmware request error = firmware request failed * write init = preparing FPGA for programming - * write init error = Error while preparing FPGA for - programming + * write init error = Error while preparing FPGA for programming * write = FPGA ready to receive image data * write error = Error while programming * write complete = Doing post programming steps @@ -47,7 +46,7 @@ Description: Read fpga manager status as a string. programming errors to userspace. This is a list of strings for the supported status. - * reconfig operation error - invalid operations detected by + * reconfig operation error - invalid operations detected by reconfiguration hardware. e.g. start reconfiguration with errors not cleared diff --git a/Documentation/ABI/testing/sysfs-class-gnss b/Documentation/ABI/testing/sysfs-class-gnss index 2467b6900eae..c8553d972edd 100644 --- a/Documentation/ABI/testing/sysfs-class-gnss +++ b/Documentation/ABI/testing/sysfs-class-gnss @@ -6,9 +6,11 @@ Description: The GNSS receiver type. The currently identified types reflect the protocol(s) supported by the receiver: + ====== =========== "NMEA" NMEA 0183 "SiRF" SiRF Binary "UBX" UBX + ====== =========== Note that also non-"NMEA" type receivers typically support a subset of NMEA 0183 with vendor extensions (e.g. to allow diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led index 5f67f7ab277b..2e24ac3bd7ef 100644 --- a/Documentation/ABI/testing/sysfs-class-led +++ b/Documentation/ABI/testing/sysfs-class-led @@ -3,9 +3,26 @@ Date: March 2006 KernelVersion: 2.6.17 Contact: Richard Purdie <rpurdie@rpsys.net> Description: - Set the brightness of the LED. Most LEDs don't - have hardware brightness support, so will just be turned on for - non-zero brightness settings. The value is between 0 and + Set the brightness of the LED. + + Most LEDs don't have hardware brightness support, so will + just be turned on for non-zero brightness settings. + + .. Note:: + + For multicolor LEDs, writing to this file will update all + LEDs within the group to a calculated percentage of what + each color LED intensity is set to. + + The percentage is calculated for each grouped LED via + the equation below:: + + led_brightness = brightness * multi_intensity/max_brightness + + For additional details please refer to + Documentation/leds/leds-class-multicolor.rst. + + The value is between 0 and /sys/class/leds/<led>/max_brightness. Writing 0 to this file clears active trigger. @@ -13,6 +30,8 @@ Description: Writing non-zero to this file while trigger is active changes the top brightness trigger is going to use. + + What: /sys/class/leds/<led>/max_brightness Date: March 2006 KernelVersion: 2.6.17 @@ -47,10 +66,11 @@ Contact: Richard Purdie <rpurdie@rpsys.net> Description: Set the trigger for this LED. A trigger is a kernel based source of LED events. + You can change triggers in a similar manner to the way an IO scheduler is chosen. Trigger specific parameters can appear in /sys/class/leds/<led> once a given trigger is selected. For - their documentation see sysfs-class-led-trigger-*. + their documentation see `sysfs-class-led-trigger-*`. What: /sys/class/leds/<led>/inverted Date: January 2011 diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 index f520ece9b64c..04f3ffdc5936 100644 --- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 +++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 @@ -1,133 +1,3 @@ -What: /sys/class/leds/<led>/hw_pattern -Date: September 2019 -KernelVersion: 5.5 -Description: - Specify a hardware pattern for the EL15203000 LED. - The LEDs board supports only predefined patterns by firmware - for specific LEDs. - - Breathing mode for Screen frame light tube: - "0 4000 1 4000" - - ^ - | - Max-| --- - | / \ - | / \ - | / \ / - | / \ / - Min-|- --- - | - 0------4------8--> time (sec) - - Cascade mode for Pipe LED: - "1 800 2 800 4 800 8 800 16 800" - - ^ - | - 0 On -|----+ +----+ +--- - | | | | | - Off-| +-------------------+ +-------------------+ - | - 1 On -| +----+ +----+ - | | | | | - Off |----+ +-------------------+ +------------------ - | - 2 On -| +----+ +----+ - | | | | | - Off-|---------+ +-------------------+ +------------- - | - 3 On -| +----+ +----+ - | | | | | - Off-|--------------+ +-------------------+ +-------- - | - 4 On -| +----+ +----+ - | | | | | - Off-|-------------------+ +-------------------+ +--- - | - 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) - - Inverted cascade mode for Pipe LED: - "30 800 29 800 27 800 23 800 15 800" - - ^ - | - 0 On -| +-------------------+ +-------------------+ - | | | | | - Off-|----+ +----+ +--- - | - 1 On -|----+ +-------------------+ +------------------ - | | | | | - Off | +----+ +----+ - | - 2 On -|---------+ +-------------------+ +------------- - | | | | | - Off-| +----+ +----+ - | - 3 On -|--------------+ +-------------------+ +-------- - | | | | | - Off-| +----+ +----+ - | - 4 On -|-------------------+ +-------------------+ +--- - | | | | | - Off-| +----+ +----+ - | - 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) - - Bounce mode for Pipe LED: - "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800" - - ^ - | - 0 On -|----+ +-------- - | | | - Off-| +---------------------------------------+ - | - 1 On -| +----+ +----+ - | | | | | - Off |----+ +-----------------------------+ +-------- - | - 2 On -| +----+ +----+ - | | | | | - Off-|---------+ +-------------------+ +------------- - | - 3 On -| +----+ +----+ - | | | | | - Off-|--------------+ +---------+ +------------------ - | - 4 On -| +---------+ - | | | - Off-|-------------------+ +----------------------- - | - 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) - - Inverted bounce mode for Pipe LED: - "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800" - - ^ - | - 0 On -| +---------------------------------------+ - | | | - Off-|----+ +-------- - | - 1 On -|----+ +-----------------------------+ +-------- - | | | | | - Off | +----+ +----+ - | - 2 On -|---------+ +-------------------+ +------------- - | | | | | - Off-| +----+ +----+ - | - 3 On -|--------------+ +---------+ +------------------ - | | | | | - Off-| +----+ +----+ - | - 4 On -|-------------------+ +----------------------- - | | | - Off-| +---------+ - | - 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) - What: /sys/class/leds/<led>/repeat Date: September 2019 KernelVersion: 5.5 diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 index e4c89b261546..e38a835d0a85 100644 --- a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 +++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 @@ -6,8 +6,10 @@ Description: Set the ALS output channel to use as input in ALS-current-control mode (1, 2), where: - 1 - out_current1 - 2 - out_current2 + == ============ + 1 out_current1 + 2 out_current2 + == ============ What: /sys/class/leds/<led>/als_en Date: May 2012 @@ -24,14 +26,16 @@ Contact: Johan Hovold <jhovold@gmail.com> Description: Set the pattern generator fall and rise times (0..7), where: - 0 - 2048 us - 1 - 262 ms - 2 - 524 ms - 3 - 1.049 s - 4 - 2.097 s - 5 - 4.194 s - 6 - 8.389 s - 7 - 16.78 s + == ======= + 0 2048 us + 1 262 ms + 2 524 ms + 3 1.049 s + 4 2.097 s + 5 4.194 s + 6 8.389 s + 7 16.78 s + == ======= What: /sys/class/leds/<led>/id Date: April 2012 @@ -47,8 +51,10 @@ Contact: Johan Hovold <jhovold@gmail.com> Description: Set the brightness-mapping mode (0, 1), where: - 0 - exponential mode - 1 - linear mode + == ================ + 0 exponential mode + 1 linear mode + == ================ What: /sys/class/leds/<led>/pwm Date: April 2012 @@ -57,9 +63,11 @@ Contact: Johan Hovold <jhovold@gmail.com> Description: Set the PWM-input control mask (5 bits), where: - bit 5 - PWM-input enabled in Zone 4 - bit 4 - PWM-input enabled in Zone 3 - bit 3 - PWM-input enabled in Zone 2 - bit 2 - PWM-input enabled in Zone 1 - bit 1 - PWM-input enabled in Zone 0 - bit 0 - PWM-input enabled + ===== =========================== + bit 5 PWM-input enabled in Zone 4 + bit 4 PWM-input enabled in Zone 3 + bit 3 PWM-input enabled in Zone 2 + bit 2 PWM-input enabled in Zone 1 + bit 1 PWM-input enabled in Zone 0 + bit 0 PWM-input enabled + ===== =========================== diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx deleted file mode 100644 index 45b1e605d355..000000000000 --- a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx +++ /dev/null @@ -1,22 +0,0 @@ -What: /sys/class/leds/<led>/hw_pattern -Date: September 2018 -KernelVersion: 4.20 -Description: - Specify a hardware pattern for the SC27XX LED. For the SC27XX - LED controller, it only supports 4 stages to make a single - hardware pattern, which is used to configure the rise time, - high time, fall time and low time for the breathing mode. - - For the breathing mode, the SC27XX LED only expects one brightness - for the high stage. To be compatible with the hardware pattern - format, we should set brightness as 0 for rise stage, fall - stage and low stage. - - Min stage duration: 125 ms - Max stage duration: 31875 ms - - Since the stage duration step is 125 ms, the duration should be - a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms. - - Thus the format of the hardware pattern values should be: - "0 rise_duration brightness high_duration 0 fall_duration 0 low_duration". diff --git a/Documentation/ABI/testing/sysfs-class-led-flash b/Documentation/ABI/testing/sysfs-class-led-flash index 220a0270b47b..11e5677c3672 100644 --- a/Documentation/ABI/testing/sysfs-class-led-flash +++ b/Documentation/ABI/testing/sysfs-class-led-flash @@ -55,26 +55,35 @@ Description: read only Flash faults are re-read after strobing the flash. Possible flash faults: - * led-over-voltage - flash controller voltage to the flash LED + * led-over-voltage + flash controller voltage to the flash LED has exceeded the limit specific to the flash controller - * flash-timeout-exceeded - the flash strobe was still on when + * flash-timeout-exceeded + the flash strobe was still on when the timeout set by the user has expired; not all flash controllers may set this in all such conditions - * controller-over-temperature - the flash controller has + * controller-over-temperature + the flash controller has overheated - * controller-short-circuit - the short circuit protection + * controller-short-circuit + the short circuit protection of the flash controller has been triggered - * led-power-supply-over-current - current in the LED power + * led-power-supply-over-current + current in the LED power supply has exceeded the limit specific to the flash controller - * indicator-led-fault - the flash controller has detected + * indicator-led-fault + the flash controller has detected a short or open circuit condition on the indicator LED - * led-under-voltage - flash controller voltage to the flash + * led-under-voltage + flash controller voltage to the flash LED has been below the minimum limit specific to the flash - * controller-under-voltage - the input voltage of the flash + * controller-under-voltage + the input voltage of the flash controller is below the limit under which strobing the flash at full current will not be possible; the condition persists until this flag is no longer set - * led-over-temperature - the temperature of the LED has exceeded + * led-over-temperature + the temperature of the LED has exceeded its allowed upper limit diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor index eeeddcbdbbe3..16fc827b10cb 100644 --- a/Documentation/ABI/testing/sysfs-class-led-multicolor +++ b/Documentation/ABI/testing/sysfs-class-led-multicolor @@ -1,20 +1,3 @@ -What: /sys/class/leds/<led>/brightness -Date: March 2020 -KernelVersion: 5.9 -Contact: Dan Murphy <dmurphy@ti.com> -Description: read/write - Writing to this file will update all LEDs within the group to a - calculated percentage of what each color LED intensity is set - to. The percentage is calculated for each grouped LED via the - equation below: - - led_brightness = brightness * multi_intensity/max_brightness - - For additional details please refer to - Documentation/leds/leds-class-multicolor.rst. - - The value of the LED is from 0 to - /sys/class/leds/<led>/max_brightness. What: /sys/class/leds/<led>/multi_index Date: March 2020 @@ -25,6 +8,9 @@ Description: read as an array of strings as they are indexed in the multi_intensity file. + For additional details please refer to + Documentation/leds/leds-class-multicolor.rst. + What: /sys/class/leds/<led>/multi_intensity Date: March 2020 KernelVersion: 5.9 @@ -33,3 +19,6 @@ Description: read/write This file contains array of integers. Order of components is described by the multi_index array. The maximum intensity should not exceed /sys/class/leds/<led>/max_brightness. + + For additional details please refer to + Documentation/leds/leds-class-multicolor.rst. diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev index 451af6d6768c..646540950e38 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev @@ -19,18 +19,23 @@ KernelVersion: 4.16 Contact: linux-leds@vger.kernel.org Description: Signal the link state of the named network device. + If set to 0 (default), the LED's normal state is off. + If set to 1, the LED's normal state reflects the link state of the named network device. Setting this value also immediately changes the LED state. + What: /sys/class/leds/<led>/tx Date: Dec 2017 KernelVersion: 4.16 Contact: linux-leds@vger.kernel.org Description: Signal transmission of data on the named network device. + If set to 0 (default), the LED will not blink on transmission. + If set to 1, the LED will blink for the milliseconds specified in interval to signal transmission. @@ -40,6 +45,8 @@ KernelVersion: 4.16 Contact: linux-leds@vger.kernel.org Description: Signal reception of data on the named network device. + If set to 0 (default), the LED will not blink on reception. + If set to 1, the LED will blink for the milliseconds specified in interval to signal reception. diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern index bd92ef9d6faa..d91a07767adf 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern @@ -23,8 +23,8 @@ Description: Since different LED hardware can have different semantics of hardware patterns, each driver is expected to provide its own - description for the hardware patterns in their ABI documentation - file. + description for the hardware patterns in their documentation + file at Documentation/leds/. What: /sys/class/leds/<led>/repeat Date: September 2018 diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport index f440e690daef..eb81152b8348 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport @@ -8,5 +8,6 @@ Description: selected for the USB port trigger. Selecting ports makes trigger observing them for any connected devices and lighting on LED if there are any. + Echoing "1" value selects USB port. Echoing "0" unselects it. Current state can be also read. diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r b/Documentation/ABI/testing/sysfs-class-leds-gt683r index 6adab27f646e..b57ffb26e722 100644 --- a/Documentation/ABI/testing/sysfs-class-leds-gt683r +++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r @@ -7,9 +7,11 @@ Description: of one LED will update the mode of its two sibling devices as well. Possible values are: - 0 - normal - 1 - audio - 2 - breathing + == ========= + 0 normal + 1 audio + 2 breathing + == ========= Normal: LEDs are fully on when enabled Audio: LEDs brightness depends on sound level diff --git a/Documentation/ABI/testing/sysfs-class-mic b/Documentation/ABI/testing/sysfs-class-mic index 6ef682603179..bd0e780c3760 100644 --- a/Documentation/ABI/testing/sysfs-class-mic +++ b/Documentation/ABI/testing/sysfs-class-mic @@ -41,24 +41,33 @@ Description: When read, this entry provides the current state of an Intel MIC device in the context of the card OS. Possible values that will be read are: - "ready" - The MIC device is ready to boot the card OS. On - reading this entry after an OSPM resume, a "boot" has to be - written to this entry if the card was previously shutdown - during OSPM suspend. - "booting" - The MIC device has initiated booting a card OS. - "online" - The MIC device has completed boot and is online - "shutting_down" - The card OS is shutting down. - "resetting" - A reset has been initiated for the MIC device - "reset_failed" - The MIC device has failed to reset. + + + =============== =============================================== + "ready" The MIC device is ready to boot the card OS. + On reading this entry after an OSPM resume, + a "boot" has to be written to this entry if + the card was previously shutdown during OSPM + suspend. + "booting" The MIC device has initiated booting a card OS. + "online" The MIC device has completed boot and is online + "shutting_down" The card OS is shutting down. + "resetting" A reset has been initiated for the MIC device + "reset_failed" The MIC device has failed to reset. + =============== =============================================== When written, this sysfs entry triggers different state change operations depending upon the current state of the card OS. Acceptable values are: - "boot" - Boot the card OS image specified by the combination - of firmware, ramdisk, cmdline and bootmode - sysfs entries. - "reset" - Initiates device reset. - "shutdown" - Initiates card OS shutdown. + + + ========== =================================================== + "boot" Boot the card OS image specified by the combination + of firmware, ramdisk, cmdline and bootmode + sysfs entries. + "reset" Initiates device reset. + "shutdown" Initiates card OS shutdown. + ========== =================================================== What: /sys/class/mic/mic(x)/shutdown_status Date: October 2013 @@ -69,12 +78,15 @@ Description: OS can shutdown because of various reasons. When read, this entry provides the status on why the card OS was shutdown. Possible values are: - "nop" - shutdown status is not applicable, when the card OS is - "online" - "crashed" - Shutdown because of a HW or SW crash. - "halted" - Shutdown because of a halt command. - "poweroff" - Shutdown because of a poweroff command. - "restart" - Shutdown because of a restart command. + + ========== =================================================== + "nop" shutdown status is not applicable, when the card OS + is "online" + "crashed" Shutdown because of a HW or SW crash. + "halted" Shutdown because of a halt command. + "poweroff" Shutdown because of a poweroff command. + "restart" Shutdown because of a restart command. + ========== =================================================== What: /sys/class/mic/mic(x)/cmdline Date: October 2013 diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 3b404577f380..1f2002df5ba2 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -4,10 +4,13 @@ KernelVersion: 3.17 Contact: netdev@vger.kernel.org Description: Indicates the name assignment type. Possible values are: - 1: enumerated by the kernel, possibly in an unpredictable way - 2: predictably named by the kernel - 3: named by userspace - 4: renamed + + == ========================================================== + 1 enumerated by the kernel, possibly in an unpredictable way + 2 predictably named by the kernel + 3 named by userspace + 4 renamed + == ========================================================== What: /sys/class/net/<iface>/addr_assign_type Date: July 2010 @@ -15,10 +18,13 @@ KernelVersion: 3.2 Contact: netdev@vger.kernel.org Description: Indicates the address assignment type. Possible values are: - 0: permanent address - 1: randomly generated - 2: stolen from another device - 3: set using dev_set_mac_address + + == ============================= + 0 permanent address + 1 randomly generated + 2 stolen from another device + 3 set using dev_set_mac_address + == ============================= What: /sys/class/net/<iface>/addr_len Date: April 2005 @@ -51,9 +57,12 @@ Description: Default value 0 does not forward any link local frames. Restricted bits: - 0: 01-80-C2-00-00-00 Bridge Group Address used for STP - 1: 01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE - 2: 01-80-C2-00-00-02 (Link Aggregation) 802.3ad + + == ======================================================== + 0 01-80-C2-00-00-00 Bridge Group Address used for STP + 1 01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE + 2 01-80-C2-00-00-02 (Link Aggregation) 802.3ad + == ======================================================== Any values not setting these bits can be used. Take special care when forwarding control frames e.g. 802.1X-PAE or LLDP. @@ -74,8 +83,11 @@ Contact: netdev@vger.kernel.org Description: Indicates the current physical link state of the interface. Posssible values are: - 0: physical link is down - 1: physical link is up + + == ===================== + 0 physical link is down + 1 physical link is up + == ===================== Note: some special devices, e.g: bonding and team drivers will allow this attribute to be written to force a link state for @@ -131,21 +143,27 @@ Contact: netdev@vger.kernel.org Description: Indicates whether the interface is under test. Possible values are: - 0: interface is not being tested - 1: interface is being tested + + == ============================= + 0 interface is not being tested + 1 interface is being tested + == ============================= When an interface is under test, it cannot be expected to pass packets as normal. -What: /sys/clas/net/<iface>/duplex +What: /sys/class/net/<iface>/duplex Date: October 2009 KernelVersion: 2.6.33 Contact: netdev@vger.kernel.org Description: Indicates the interface latest or current duplex value. Possible values are: - half: half duplex - full: full duplex + + ==== =========== + half half duplex + full full duplex + ==== =========== Note: This attribute is only valid for interfaces that implement the ethtool get_link_ksettings method (mostly Ethernet). @@ -196,8 +214,11 @@ Description: Indicates the interface link mode, as a decimal number. This attribute should be used in conjunction with 'dormant' attribute to determine the interface usability. Possible values: - 0: default link mode - 1: dormant link mode + + == ================= + 0 default link mode + 1 dormant link mode + == ================= What: /sys/class/net/<iface>/mtu Date: April 2005 @@ -226,7 +247,9 @@ KernelVersion: 2.6.17 Contact: netdev@vger.kernel.org Description: Indicates the interface RFC2863 operational state as a string. + Possible values are: + "unknown", "notpresent", "down", "lowerlayerdown", "testing", "dormant", "up". diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm index f7be0e88b139..06416d0e163d 100644 --- a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm +++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm @@ -91,9 +91,9 @@ Date: May 2014 KernelVersion: 3.16 Contact: Bjørn Mork <bjorn@mork.no> Description: - Bit 0: 16-bit NTB supported (set to 1) - Bit 1: 32-bit NTB supported - Bits 2 – 15: reserved (reset to zero; must be ignored by host) + - Bit 0: 16-bit NTB supported (set to 1) + - Bit 1: 32-bit NTB supported + - Bits 2 – 15: reserved (reset to zero; must be ignored by host) What: /sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize Date: May 2014 diff --git a/Documentation/ABI/testing/sysfs-class-net-phydev b/Documentation/ABI/testing/sysfs-class-net-phydev index 206cbf538b59..40ced0ea4316 100644 --- a/Documentation/ABI/testing/sysfs-class-net-phydev +++ b/Documentation/ABI/testing/sysfs-class-net-phydev @@ -35,7 +35,9 @@ Description: Ethernet driver during bus enumeration, encoded in string. This interface mode is used to configure the Ethernet MAC with the appropriate mode for its data lines to the PHY hardware. + Possible values are: + <empty> (not available), mii, gmii, sgmii, tbi, rev-mii, rmii, rgmii, rgmii-id, rgmii-rxid, rgmii-txid, rtbi, smii xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui, diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl index ae1276efa45a..847a7edc3113 100644 --- a/Documentation/ABI/testing/sysfs-class-ocxl +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -11,8 +11,11 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read only Number of contexts for the AFU, in the format <n>/<max> where: - n: number of currently active contexts, for debug - max: maximum number of contexts supported by the AFU + + ==== =============================================== + n number of currently active contexts, for debug + max maximum number of contexts supported by the AFU + ==== =============================================== What: /sys/class/ocxl/<afu name>/pp_mmio_size Date: January 2018 @@ -40,7 +43,9 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read/write Control whether the FPGA is reloaded on a link reset. Enabled through a vendor-specific logic block on the FPGA. - 0 Do not reload FPGA image from flash - 1 Reload FPGA image from flash - unavailable - The device does not support this capability + + =========== =========================================== + 0 Do not reload FPGA image from flash + 1 Reload FPGA image from flash + unavailable The device does not support this capability + =========== =========================================== diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd index dde4f26d0780..ba1ce626591d 100644 --- a/Documentation/ABI/testing/sysfs-class-pktcdvd +++ b/Documentation/ABI/testing/sysfs-class-pktcdvd @@ -11,15 +11,17 @@ KernelVersion: 2.6.20 Contact: Thomas Maier <balagi@justmail.de> Description: - add: (WO) Write a block device id (major:minor) to + ========== ============================================== + add (WO) Write a block device id (major:minor) to create a new pktcdvd device and map it to the block device. - remove: (WO) Write the pktcdvd device id (major:minor) + remove (WO) Write the pktcdvd device id (major:minor) to remove the pktcdvd device. - device_map: (RO) Shows the device mapping in format: + device_map (RO) Shows the device mapping in format: pktcdvd[0-7] <pktdevid> <blkdevid> + ========== ============================================== What: /sys/class/pktcdvd/pktcdvd[0-7]/dev @@ -65,29 +67,31 @@ Date: Oct. 2006 KernelVersion: 2.6.20 Contact: Thomas Maier <balagi@justmail.de> Description: - size: (RO) Contains the size of the bio write queue. + ============== ================================================ + size (RO) Contains the size of the bio write queue. - congestion_off: (RW) If bio write queue size is below this mark, + congestion_off (RW) If bio write queue size is below this mark, accept new bio requests from the block layer. - congestion_on: (RW) If bio write queue size is higher as this + congestion_on (RW) If bio write queue size is higher as this mark, do no longer accept bio write requests from the block layer and wait till the pktcdvd device has processed enough bio's so that bio write queue size is below congestion off mark. A value of <= 0 disables congestion control. + ============== ================================================ Example: -------- -To use the pktcdvd sysfs interface directly, you can do: - -# create a new pktcdvd device mapped to /dev/hdc -echo "22:0" >/sys/class/pktcdvd/add -cat /sys/class/pktcdvd/device_map -# assuming device pktcdvd0 was created, look at stat's -cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written -# print the device id of the mapped block device -fgrep pktcdvd0 /sys/class/pktcdvd/device_map -# remove device, using pktcdvd0 device id 253:0 -echo "253:0" >/sys/class/pktcdvd/remove +To use the pktcdvd sysfs interface directly, you can do:: + + # create a new pktcdvd device mapped to /dev/hdc + echo "22:0" >/sys/class/pktcdvd/add + cat /sys/class/pktcdvd/device_map + # assuming device pktcdvd0 was created, look at stat's + cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written + # print the device id of the mapped block device + fgrep pktcdvd0 /sys/class/pktcdvd/device_map + # remove device, using pktcdvd0 device id 253:0 + echo "253:0" >/sys/class/pktcdvd/remove diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index dbccb2fcd7ce..ca830c6cd809 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -1,4 +1,4 @@ -===== General Properties ===== +**General Properties** What: /sys/class/power_supply/<supply_name>/manufacturer Date: May 2007 @@ -36,14 +36,238 @@ Description: Access: Read Valid values: "Battery", "UPS", "Mains", "USB", "Wireless" -===== Battery Properties ===== +**Battery and USB properties** + +What: /sys/class/power_supply/<supply_name>/current_avg +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports an average IBAT current reading for the battery, over + a fixed period. Normally devices will provide a fixed interval + in which they average readings to smooth out the reported + value. + + USB: + + Reports an average IBUS current reading over a fixed period. + Normally devices will provide a fixed interval in which they + average readings to smooth out the reported value. + + Access: Read + + Valid values: Represented in microamps. Negative values are + used for discharging batteries, positive values for charging + batteries and for USB IBUS current. + +What: /sys/class/power_supply/<supply_name>/current_max +Date: October 2010 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the maximum IBAT current allowed into the battery. + + USB: + + Reports the maximum IBUS current the supply can support. + + Access: Read + Valid values: Represented in microamps + +What: /sys/class/power_supply/<supply_name>/current_now +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + + Battery: + + Reports an instant, single IBAT current reading for the + battery. This value is not averaged/smoothed. + + Access: Read + + USB: + + Reports the IBUS current supplied now. This value is generally + read-only reporting, unless the 'online' state of the supply + is set to be programmable, in which case this value can be set + within the reported min/max range. + + Access: Read, Write + + Valid values: Represented in microamps. Negative values are + used for discharging batteries, positive values for charging + batteries and for USB IBUS current. + +What: /sys/class/power_supply/<supply_name>/temp +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the current TBAT battery temperature reading. + + USB: + + Reports the current supply temperature reading. This would + normally be the internal temperature of the device itself + (e.g TJUNC temperature of an IC) + + Access: Read + + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/temp_alert_max +Date: July 2012 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Maximum TBAT temperature trip-wire value where the supply will + notify user-space of the event. + + USB: + + Maximum supply temperature trip-wire value where the supply + will notify user-space of the event. + + This is normally used for the charging scenario where + user-space needs to know if the temperature has crossed an + upper threshold so it can take appropriate action (e.g. warning + user that the temperature is critically high, and charging has + stopped). + + Access: Read + + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/temp_alert_min +Date: July 2012 +Contact: linux-pm@vger.kernel.org +Description: + + Battery: + + Minimum TBAT temperature trip-wire value where the supply will + notify user-space of the event. + + USB: + + Minimum supply temperature trip-wire value where the supply + will notify user-space of the event. + + This is normally used for the charging scenario where user-space + needs to know if the temperature has crossed a lower threshold + so it can take appropriate action (e.g. warning user that + temperature level is high, and charging current has been + reduced accordingly to remedy the situation). + + Access: Read + + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/temp_max +Date: July 2014 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the maximum allowed TBAT battery temperature for + charging. + + USB: + + Reports the maximum allowed supply temperature for operation. + + Access: Read + + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/temp_min +Date: July 2014 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the minimum allowed TBAT battery temperature for + charging. + + USB: + + Reports the minimum allowed supply temperature for operation. + + Access: Read + + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/voltage_max, +Date: January 2008 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the maximum safe VBAT voltage permitted for the + battery, during charging. + + USB: + + Reports the maximum VBUS voltage the supply can support. + + Access: Read + + Valid values: Represented in microvolts + +What: /sys/class/power_supply/<supply_name>/voltage_min, +Date: January 2008 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports the minimum safe VBAT voltage permitted for the + battery, during discharging. + + USB: + + Reports the minimum VBUS voltage the supply can support. + + Access: Read + + Valid values: Represented in microvolts + +What: /sys/class/power_supply/<supply_name>/voltage_now, +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Battery: + + Reports an instant, single VBAT voltage reading for the + battery. This value is not averaged/smoothed. + + Access: Read + + USB: + + Reports the VBUS voltage supplied now. This value is generally + read-only reporting, unless the 'online' state of the supply + is set to be programmable, in which case this value can be set + within the reported min/max range. + + Access: Read, Write + + Valid values: Represented in microvolts + +**Battery Properties** What: /sys/class/power_supply/<supply_name>/capacity Date: May 2007 Contact: linux-pm@vger.kernel.org Description: Fine grain representation of battery capacity. + Access: Read + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/capacity_alert_max @@ -58,6 +282,7 @@ Description: low). Access: Read, Write + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/capacity_alert_min @@ -72,6 +297,7 @@ Description: critically low). Access: Read, Write + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/capacity_error_margin @@ -87,6 +313,7 @@ Description: completely useless. Access: Read + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/capacity_level @@ -96,40 +323,10 @@ Description: Coarse representation of battery capacity. Access: Read - Valid values: "Unknown", "Critical", "Low", "Normal", "High", - "Full" - -What: /sys/class/power_supply/<supply_name>/current_avg -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports an average IBAT current reading for the battery, over a - fixed period. Normally devices will provide a fixed interval in - which they average readings to smooth out the reported value. - - Access: Read - Valid values: Represented in microamps. Negative values are used - for discharging batteries, positive values for charging batteries. -What: /sys/class/power_supply/<supply_name>/current_max -Date: October 2010 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum IBAT current allowed into the battery. - - Access: Read - Valid values: Represented in microamps - -What: /sys/class/power_supply/<supply_name>/current_now -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports an instant, single IBAT current reading for the battery. - This value is not averaged/smoothed. - - Access: Read - Valid values: Represented in microamps. Negative values are used - for discharging batteries, positive values for charging batteries. + Valid values: + "Unknown", "Critical", "Low", "Normal", "High", + "Full" What: /sys/class/power_supply/<supply_name>/charge_control_limit Date: Oct 2012 @@ -139,6 +336,7 @@ Description: throttling for thermal cooling or improving battery health. Access: Read, Write + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/charge_control_limit_max @@ -148,6 +346,7 @@ Description: Maximum legal value for the charge_control_limit property. Access: Read + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/charge_control_start_threshold @@ -168,6 +367,7 @@ Description: stop. Access: Read, Write + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/charge_type @@ -183,7 +383,9 @@ Description: different algorithm. Access: Read, Write - Valid values: "Unknown", "N/A", "Trickle", "Fast", "Standard", + + Valid values: + "Unknown", "N/A", "Trickle", "Fast", "Standard", "Adaptive", "Custom" What: /sys/class/power_supply/<supply_name>/charge_term_current @@ -194,6 +396,7 @@ Description: when the battery is considered full and charging should end. Access: Read + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/health @@ -204,7 +407,9 @@ Description: functionality. Access: Read - Valid values: "Unknown", "Good", "Overheat", "Dead", + + Valid values: + "Unknown", "Good", "Overheat", "Dead", "Over voltage", "Unspecified failure", "Cold", "Watchdog timer expire", "Safety timer expire", "Over current", "Calibration required", "Warm", @@ -218,6 +423,7 @@ Description: for a battery charge cycle. Access: Read + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/present @@ -227,9 +433,13 @@ Description: Reports whether a battery is present or not in the system. Access: Read + Valid values: + + == ======= 0: Absent 1: Present + == ======= What: /sys/class/power_supply/<supply_name>/status Date: May 2007 @@ -240,7 +450,9 @@ Description: used to enable/disable charging to the battery. Access: Read, Write - Valid values: "Unknown", "Charging", "Discharging", + + Valid values: + "Unknown", "Charging", "Discharging", "Not charging", "Full" What: /sys/class/power_supply/<supply_name>/technology @@ -250,66 +462,11 @@ Description: Describes the battery technology supported by the supply. Access: Read - Valid values: "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe", - "NiCd", "LiMn" - -What: /sys/class/power_supply/<supply_name>/temp -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports the current TBAT battery temperature reading. - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_alert_max -Date: July 2012 -Contact: linux-pm@vger.kernel.org -Description: - Maximum TBAT temperature trip-wire value where the supply will - notify user-space of the event. This is normally used for the - battery charging scenario where user-space needs to know the - battery temperature has crossed an upper threshold so it can - take appropriate action (e.g. warning user that battery level is - critically high, and charging has stopped). - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_alert_min -Date: July 2012 -Contact: linux-pm@vger.kernel.org -Description: - Minimum TBAT temperature trip-wire value where the supply will - notify user-space of the event. This is normally used for the - battery charging scenario where user-space needs to know the - battery temperature has crossed a lower threshold so it can take - appropriate action (e.g. warning user that battery level is - high, and charging current has been reduced accordingly to - remedy the situation). - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_max -Date: July 2014 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum allowed TBAT battery temperature for - charging. - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius -What: /sys/class/power_supply/<supply_name>/temp_min -Date: July 2014 -Contact: linux-pm@vger.kernel.org -Description: - Reports the minimum allowed TBAT battery temperature for - charging. + Valid values: + "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe", + "NiCd", "LiMn" - Access: Read - Valid values: Represented in 1/10 Degrees Celsius What: /sys/class/power_supply/<supply_name>/voltage_avg, Date: May 2007 @@ -320,72 +477,10 @@ Description: which they average readings to smooth out the reported value. Access: Read - Valid values: Represented in microvolts - -What: /sys/class/power_supply/<supply_name>/voltage_max, -Date: January 2008 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum safe VBAT voltage permitted for the battery, - during charging. - - Access: Read - Valid values: Represented in microvolts - -What: /sys/class/power_supply/<supply_name>/voltage_min, -Date: January 2008 -Contact: linux-pm@vger.kernel.org -Description: - Reports the minimum safe VBAT voltage permitted for the battery, - during discharging. - Access: Read Valid values: Represented in microvolts -What: /sys/class/power_supply/<supply_name>/voltage_now, -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports an instant, single VBAT voltage reading for the battery. - This value is not averaged/smoothed. - - Access: Read - Valid values: Represented in microvolts - -===== USB Properties ===== - -What: /sys/class/power_supply/<supply_name>/current_avg -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports an average IBUS current reading over a fixed period. - Normally devices will provide a fixed interval in which they - average readings to smooth out the reported value. - - Access: Read - Valid values: Represented in microamps - - -What: /sys/class/power_supply/<supply_name>/current_max -Date: October 2010 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum IBUS current the supply can support. - - Access: Read - Valid values: Represented in microamps - -What: /sys/class/power_supply/<supply_name>/current_now -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports the IBUS current supplied now. This value is generally - read-only reporting, unless the 'online' state of the supply - is set to be programmable, in which case this value can be set - within the reported min/max range. - - Access: Read, Write - Valid values: Represented in microamps +**USB Properties** What: /sys/class/power_supply/<supply_name>/input_current_limit Date: July 2014 @@ -399,6 +494,7 @@ Description: solved using power limit use input_current_limit. Access: Read, Write + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/input_voltage_limit @@ -416,6 +512,7 @@ Description: solved using power limit use input_voltage_limit. Access: Read, Write + Valid values: Represented in microvolts What: /sys/class/power_supply/<supply_name>/input_power_limit @@ -429,6 +526,7 @@ Description: limit only for problems that can be solved using power limit. Access: Read, Write + Valid values: Represented in microwatts What: /sys/class/power_supply/<supply_name>/online, @@ -441,69 +539,14 @@ Description: USB supply so voltage and current can be controlled). Access: Read, Write + Valid values: + + == ================================================== 0: Offline 1: Online Fixed - Fixed Voltage Supply 2: Online Programmable - Programmable Voltage Supply - -What: /sys/class/power_supply/<supply_name>/temp -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports the current supply temperature reading. This would - normally be the internal temperature of the device itself (e.g - TJUNC temperature of an IC) - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_alert_max -Date: July 2012 -Contact: linux-pm@vger.kernel.org -Description: - Maximum supply temperature trip-wire value where the supply will - notify user-space of the event. This is normally used for the - charging scenario where user-space needs to know the supply - temperature has crossed an upper threshold so it can take - appropriate action (e.g. warning user that the supply - temperature is critically high, and charging has stopped to - remedy the situation). - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_alert_min -Date: July 2012 -Contact: linux-pm@vger.kernel.org -Description: - Minimum supply temperature trip-wire value where the supply will - notify user-space of the event. This is normally used for the - charging scenario where user-space needs to know the supply - temperature has crossed a lower threshold so it can take - appropriate action (e.g. warning user that the supply - temperature is high, and charging current has been reduced - accordingly to remedy the situation). - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_max -Date: July 2014 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum allowed supply temperature for operation. - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius - -What: /sys/class/power_supply/<supply_name>/temp_min -Date: July 2014 -Contact: linux-pm@vger.kernel.org -Description: - Reports the mainimum allowed supply temperature for operation. - - Access: Read - Valid values: Represented in 1/10 Degrees Celsius + == ================================================== What: /sys/class/power_supply/<supply_name>/usb_type Date: March 2018 @@ -514,40 +557,12 @@ Description: is attached. Access: Read-Only - Valid values: "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD", - "PD_DRP", "PD_PPS", "BrickID" - -What: /sys/class/power_supply/<supply_name>/voltage_max -Date: January 2008 -Contact: linux-pm@vger.kernel.org -Description: - Reports the maximum VBUS voltage the supply can support. - - Access: Read - Valid values: Represented in microvolts - -What: /sys/class/power_supply/<supply_name>/voltage_min -Date: January 2008 -Contact: linux-pm@vger.kernel.org -Description: - Reports the minimum VBUS voltage the supply can support. - Access: Read - Valid values: Represented in microvolts - -What: /sys/class/power_supply/<supply_name>/voltage_now -Date: May 2007 -Contact: linux-pm@vger.kernel.org -Description: - Reports the VBUS voltage supplied now. This value is generally - read-only reporting, unless the 'online' state of the supply - is set to be programmable, in which case this value can be set - within the reported min/max range. - - Access: Read, Write - Valid values: Represented in microvolts + Valid values: + "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD", + "PD_DRP", "PD_PPS", "BrickID" -===== Device Specific Properties ===== +**Device Specific Properties** What: /sys/class/power/ds2760-battery.*/charge_now Date: May 2010 @@ -581,6 +596,7 @@ Description: will drop to 0 A) and will trigger interrupt. Valid values: + - 5, 6 or 7 (hours), - 0: disabled. @@ -595,6 +611,7 @@ Description: will drop to 0 A) and will trigger interrupt. Valid values: + - 4 - 16 (hours), step by 2 (rounded down) - 0: disabled. @@ -609,6 +626,7 @@ Description: interrupt and start top-off charging mode. Valid values: + - 100000 - 200000 (microamps), step by 25000 (rounded down) - 200000 - 350000 (microamps), step by 50000 (rounded down) - 0: disabled. @@ -624,6 +642,7 @@ Description: will drop to 0 A) and will trigger interrupt. Valid values: + - 0 - 70 (minutes), step by 10 (rounded down) What: /sys/class/power_supply/bq24257-charger/ovp_voltage @@ -637,6 +656,7 @@ Description: device datasheet for details. Valid values: + - 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000, 10500000 (all uV) @@ -652,6 +672,7 @@ Description: lower than the set value. See device datasheet for details. Valid values: + - 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000, 4760000 (all uV) @@ -666,6 +687,7 @@ Description: the charger operates normally. See device datasheet for details. Valid values: + - 1: enabled - 0: disabled @@ -681,6 +703,7 @@ Description: from the system. See device datasheet for details. Valid values: + - 1: enabled - 0: disabled @@ -692,6 +715,7 @@ Description: manufactured. Access: Read + Valid values: Reported as integer What: /sys/class/power_supply/<supply_name>/manufacture_month @@ -701,6 +725,7 @@ Description: Reports the month when the device has been manufactured. Access: Read + Valid values: 1-12 What: /sys/class/power_supply/<supply_name>/manufacture_day diff --git a/Documentation/ABI/testing/sysfs-class-power-mp2629 b/Documentation/ABI/testing/sysfs-class-power-mp2629 index 327a07e22805..914d67caac0d 100644 --- a/Documentation/ABI/testing/sysfs-class-power-mp2629 +++ b/Documentation/ABI/testing/sysfs-class-power-mp2629 @@ -5,4 +5,5 @@ Description: Represents a battery impedance compensation to accelerate charging. Access: Read, Write + Valid values: Represented in milli-ohms. Valid range is [0, 140]. diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030 index b4fd32d210c5..b52f7023f8ba 100644 --- a/Documentation/ABI/testing/sysfs-class-power-twl4030 +++ b/Documentation/ABI/testing/sysfs-class-power-twl4030 @@ -4,18 +4,20 @@ Description: Writing to this can disable charging. Possible values are: - "auto" - draw power as appropriate for detected - power source and battery status. - "off" - do not draw any power. - "continuous" - - activate mode described as "linear" in - TWL data sheets. This uses whatever - current is available and doesn't switch off - when voltage drops. - This is useful for unstable power sources - such as bicycle dynamo, but care should - be taken that battery is not over-charged. + ============= =========================================== + "auto" draw power as appropriate for detected + power source and battery status. + "off" do not draw any power. + "continuous" activate mode described as "linear" in + TWL data sheets. This uses whatever + current is available and doesn't switch off + when voltage drops. + + This is useful for unstable power sources + such as bicycle dynamo, but care should + be taken that battery is not over-charged. + ============= =========================================== What: /sys/class/power_supply/twl4030_ac/mode Description: @@ -23,6 +25,9 @@ Description: Writing to this can disable charging. Possible values are: - "auto" - draw power as appropriate for detected - power source and battery status. - "off" - do not draw any power. + + ====== =========================================== + "auto" draw power as appropriate for detected + power source and battery status. + "off" do not draw any power. + ====== =========================================== diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco index 84fde1d0ada0..82af180fcaab 100644 --- a/Documentation/ABI/testing/sysfs-class-power-wilco +++ b/Documentation/ABI/testing/sysfs-class-power-wilco @@ -4,17 +4,23 @@ KernelVersion: 5.2 Description: What charging algorithm to use: - Standard: Fully charges battery at a standard rate. - Adaptive: Battery settings adaptively optimized based on + Standard: + Fully charges battery at a standard rate. + Adaptive: + Battery settings adaptively optimized based on typical battery usage pattern. - Fast: Battery charges over a shorter period. - Trickle: Extends battery lifespan, intended for users who + Fast: + Battery charges over a shorter period. + Trickle: + Extends battery lifespan, intended for users who primarily use their Chromebook while connected to AC. - Custom: A low and high threshold percentage is specified. + Custom: + A low and high threshold percentage is specified. Charging begins when level drops below charge_control_start_threshold, and ceases when level is above charge_control_end_threshold. - Long Life: Customized charge rate for last longer battery life. + Long Life: + Customized charge rate for last longer battery life. On Wilco device this mode is pre-configured in the factory through EC's private PID. Swiching to a different mode will be denied by Wilco EC when Long Life mode is enabled. diff --git a/Documentation/ABI/testing/sysfs-class-rapidio b/Documentation/ABI/testing/sysfs-class-rapidio index 8716beeb16c1..19aefb21b639 100644 --- a/Documentation/ABI/testing/sysfs-class-rapidio +++ b/Documentation/ABI/testing/sysfs-class-rapidio @@ -6,6 +6,7 @@ Description: The /sys/class/rapidio_port subdirectory contains individual subdirectories named as "rapidioN" where N = mport ID registered with RapidIO subsystem. + NOTE: An mport ID is not a RapidIO destination ID assigned to a given local mport device. @@ -16,7 +17,9 @@ Contact: Matt Porter <mporter@kernel.crashing.org>, Alexandre Bounine <alexandre.bounine@idt.com> Description: (RO) reports RapidIO common transport system size: + 0 = small (8-bit destination ID, max. 256 devices), + 1 = large (16-bit destination ID, max. 65536 devices). What: /sys/class/rapidio_port/rapidioN/port_destid @@ -25,31 +28,32 @@ KernelVersion: v3.15 Contact: Matt Porter <mporter@kernel.crashing.org>, Alexandre Bounine <alexandre.bounine@idt.com> Description: - (RO) reports RapidIO destination ID assigned to the given - RapidIO mport device. If value 0xFFFFFFFF is returned this means - that no valid destination ID have been assigned to the mport - (yet). Normally, before enumeration/discovery have been executed - only fabric enumerating mports have a valid destination ID - assigned to them using "hdid=..." rapidio module parameter. + +(RO) reports RapidIO destination ID assigned to the given +RapidIO mport device. If value 0xFFFFFFFF is returned this means +that no valid destination ID have been assigned to the mport +(yet). Normally, before enumeration/discovery have been executed +only fabric enumerating mports have a valid destination ID +assigned to them using "hdid=..." rapidio module parameter. After enumeration or discovery was performed for a given mport device, the corresponding subdirectory will also contain subdirectories for each child RapidIO device connected to the mport. The example below shows mport device subdirectory with several child RapidIO -devices attached to it. - -[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l -total 0 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003 -drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005 -lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0 --r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid -drwxr-xr-x 2 root root 0 Feb 11 15:11 power -lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port --r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size --rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent +devices attached to it:: + + [rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l + total 0 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003 + drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005 + lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0 + -r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid + drwxr-xr-x 2 root root 0 Feb 11 15:11 power + lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port + -r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size + -rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc index 6c0d6c8cb911..9c8ff7910858 100644 --- a/Documentation/ABI/testing/sysfs-class-rc +++ b/Documentation/ABI/testing/sysfs-class-rc @@ -21,15 +21,22 @@ KernelVersion: 2.6.36 Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Reading this file returns a list of available protocols, - something like: + something like:: + "rc5 [rc6] nec jvc [sony]" + Enabled protocols are shown in [] brackets. + Writing "+proto" will add a protocol to the list of enabled protocols. + Writing "-proto" will remove a protocol from the list of enabled protocols. + Writing "proto" will enable only "proto". + Writing "none" will disable all protocols. + Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used. @@ -39,11 +46,13 @@ KernelVersion: 3.15 Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Sets the scancode filter expected value. + Use in combination with /sys/class/rc/rcN/filter_mask to set the expected value of the bits set in the filter mask. If the hardware supports it then scancodes which do not match the filter will be ignored. Otherwise the write will fail with an error. + This value may be reset to 0 if the current protocol is altered. What: /sys/class/rc/rcN/filter_mask @@ -56,9 +65,11 @@ Description: of the scancode which should be compared against the expected value. A value of 0 disables the filter to allow all valid scancodes to be processed. + If the hardware supports it then scancodes which do not match the filter will be ignored. Otherwise the write will fail with an error. + This value may be reset to 0 if the current protocol is altered. What: /sys/class/rc/rcN/wakeup_protocols @@ -67,15 +78,22 @@ KernelVersion: 4.11 Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Reading this file returns a list of available protocols to use - for the wakeup filter, something like: + for the wakeup filter, something like:: + "rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce" + Note that protocol variants are listed, so "nec", "sony", "rc-5", "rc-6" have their different bit length encodings listed if available. + The enabled wakeup protocol is shown in [] brackets. + Only one protocol can be selected at a time. + Writing "proto" will use "proto" for wakeup events. + Writing "none" will disable wakeup. + Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used, or if wakeup is not supported by the hardware. @@ -86,13 +104,17 @@ KernelVersion: 3.15 Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Sets the scancode wakeup filter expected value. + Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to set the expected value of the bits set in the wakeup filter mask to trigger a system wake event. + If the hardware supports it and wakeup_filter_mask is not 0 then scancodes which match the filter will wake the system from e.g. suspend to RAM or power off. + Otherwise the write will fail with an error. + This value may be reset to 0 if the wakeup protocol is altered. What: /sys/class/rc/rcN/wakeup_filter_mask @@ -101,11 +123,15 @@ KernelVersion: 3.15 Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Sets the scancode wakeup filter mask of bits to compare. + Use in combination with /sys/class/rc/rcN/wakeup_filter to set the bits of the scancode which should be compared against the expected value to trigger a system wake event. + If the hardware supports it and wakeup_filter_mask is not 0 then scancodes which match the filter will wake the system from e.g. suspend to RAM or power off. + Otherwise the write will fail with an error. + This value may be reset to 0 if the wakeup protocol is altered. diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator index bc578bc60628..8516f08806dd 100644 --- a/Documentation/ABI/testing/sysfs-class-regulator +++ b/Documentation/ABI/testing/sysfs-class-regulator @@ -35,13 +35,13 @@ Description: This will be one of the following strings: - off - on - error - fast - normal - idle - standby + - off + - on + - error + - fast + - normal + - idle + - standby "off" means the regulator is not supplying power to the system. @@ -74,9 +74,9 @@ Description: This will be one of the following strings: - 'voltage' - 'current' - 'unknown' + - 'voltage' + - 'current' + - 'unknown' 'voltage' means the regulator output voltage can be controlled by software. @@ -129,11 +129,11 @@ Description: The opmode value can be one of the following strings: - 'fast' - 'normal' - 'idle' - 'standby' - 'unknown' + - 'fast' + - 'normal' + - 'idle' + - 'standby' + - 'unknown' The modes are described in include/linux/regulator/consumer.h @@ -360,9 +360,9 @@ Description: This will be one of the following strings: - 'enabled' - 'disabled' - 'unknown' + - 'enabled' + - 'disabled' + - 'unknown' 'enabled' means the regulator is in bypass mode. diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc index 066b9b6f4924..0c9ee55098b8 100644 --- a/Documentation/ABI/testing/sysfs-class-remoteproc +++ b/Documentation/ABI/testing/sysfs-class-remoteproc @@ -16,11 +16,11 @@ Description: Remote processor state Reports the state of the remote processor, which will be one of: - "offline" - "suspended" - "running" - "crashed" - "invalid" + - "offline" + - "suspended" + - "running" + - "crashed" + - "invalid" "offline" means the remote processor is powered off. @@ -38,8 +38,8 @@ Description: Remote processor state Writing this file controls the state of the remote processor. The following states can be written: - "start" - "stop" + - "start" + - "stop" Writing "start" will attempt to start the processor running the firmware indicated by, or written to, diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client index c084f203b41e..00c0286733d4 100644 --- a/Documentation/ABI/testing/sysfs-class-rnbd-client +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client @@ -5,62 +5,70 @@ Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud Description: Provide information about RNBD-client. All sysfs files that are not read-only provide the usage information on read: - Example: - # cat /sys/class/rnbd-client/ctl/map_device + Example:: - > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr> - > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side> - > [access_mode=<ro|rw|migration>] > map_device - > - > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ] + # cat /sys/class/rnbd-client/ctl/map_device + + > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr> + > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side> + > [access_mode=<ro|rw|migration>] > map_device + > + > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ] What: /sys/class/rnbd-client/ctl/map_device Date: Feb 2020 KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> -Description: Expected format is the following: +Description: Expected format is the following:: - sessname=<name of the rtrs session> - path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...] - device_path=<full path on remote side> - [access_mode=<ro|rw|migration>] + sessname=<name of the rtrs session> + path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...] + device_path=<full path on remote side> + [access_mode=<ro|rw|migration>] Where: - sessname: accepts a string not bigger than 256 chars, which identifies - a given session on the client and on the server. - I.e. "clt_hostname-srv_hostname" could be a natural choice. + sessname: + accepts a string not bigger than 256 chars, which identifies + a given session on the client and on the server. + I.e. "clt_hostname-srv_hostname" could be a natural choice. + + path: + describes a connection between the client and the server by + specifying destination and, when required, the source address. + The addresses are to be provided in the following format:: - path: describes a connection between the client and the server by - specifying destination and, when required, the source address. - The addresses are to be provided in the following format: + ip:<IPv6> + ip:<IPv4> + gid:<GID> - ip:<IPv6> - ip:<IPv4> - gid:<GID> + for example:: - for example: + path=ip:10.0.0.66 - path=ip:10.0.0.66 The single addr is treated as the destination. The connection will be established to this server from any client IP address. - path=ip:10.0.0.66,ip:10.0.1.66 + :: + + path=ip:10.0.0.66,ip:10.0.1.66 + First addr is the source address and the second is the destination. If multiple "path=" options are specified multiple connection will be established and data will be sent according to the selected multipath policy (see RTRS mp_policy sysfs entry description). - device_path: Path to the block device on the server side. Path is specified - relative to the directory on server side configured in the - 'dev_search_path' module parameter of the rnbd_server. - The rnbd_server prepends the <device_path> received from client - with <dev_search_path> and tries to open the - <dev_search_path>/<device_path> block device. On success, - a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/ - directory and an entry in /sys/class/rnbd-client/ctl/devices - will be created. + device_path: + Path to the block device on the server side. Path is specified + relative to the directory on server side configured in the + 'dev_search_path' module parameter of the rnbd_server. + The rnbd_server prepends the <device_path> received from client + with <dev_search_path> and tries to open the + <dev_search_path>/<device_path> block device. On success, + a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/ + directory and an entry in /sys/class/rnbd-client/ctl/devices + will be created. If 'dev_search_path' contains '%SESSNAME%', then each session can have different devices namespace, e.g. server was configured with @@ -68,11 +76,12 @@ Description: Expected format is the following: client has this string "sessname=blya device_path=sda", then server will try to open: /run/rnbd-devs/blya/sda. - access_mode: the access_mode parameter specifies if the device is to be - mapped as "ro" read-only or "rw" read-write. The server allows - a device to be exported in rw mode only once. The "migration" - access mode has to be specified if a second mapping in read-write - mode is desired. + access_mode: + the access_mode parameter specifies if the device is to be + mapped as "ro" read-only or "rw" read-write. The server allows + a device to be exported in rw mode only once. The "migration" + access mode has to be specified if a second mapping in read-write + mode is desired. By default "rw" is used. @@ -91,7 +100,7 @@ Description: Expected format is the following: is the same as the device name. By extracting the last part of the path the path to the device /dev/<dev-name> can be build. - o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev) + * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev) How to find the <device_id> of the device is described on the next section. @@ -106,6 +115,6 @@ Description: For each device mapped on the client a new symbolic link is created The <device_id> of each device is created as follows: - If the 'device_path' provided during mapping contains slashes ("/"), - they are replaced by exclamation mark ("!") and used as as the - <device_id>. Otherwise, the <device_id> will be the same as the - "device_path" provided. + they are replaced by exclamation mark ("!") and used as as the + <device_id>. Otherwise, the <device_id> will be the same as the + "device_path" provided. diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration index ec950c93e5c6..ee8ed6494a01 100644 --- a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration +++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration @@ -7,6 +7,7 @@ Description: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock calibrate the AB8500.s 32KHz Real Time Clock. Every 60 seconds the AB8500 will correct the RTC's value by adding to it the value of this attribute. + The range of the attribute is -127 to +127 in units of 30.5 micro-seconds (half-parts-per-million of the 32KHz clock) Users: The /vendor/st-ericsson/base_utilities/core/rtc_calibration diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client index e7e718db8941..0f7165aab251 100644 --- a/Documentation/ABI/testing/sysfs-class-rtrs-client +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client @@ -10,10 +10,10 @@ Date: Feb 2020 KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> Description: RW, adds a new path (connection) to an existing session. Expected format is the - following: + following:: - <[source addr,]destination addr> - *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ] + <[source addr,]destination addr> + *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ] What: /sys/class/rtrs-client/<session-name>/max_reconnect_attempts Date: Feb 2020 @@ -29,10 +29,10 @@ Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud Description: Multipath policy specifies which path should be selected on each IO: round-robin (0): - select path in per CPU round-robin manner. + select path in per CPU round-robin manner. min-inflight (1): - select path with minimum inflights. + select path with minimum inflights. What: /sys/class/rtrs-client/<session-name>/paths/ Date: Feb 2020 @@ -109,8 +109,11 @@ Description: RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's not the case, the processing of an I/O response could be processed on a different CPU than where it was originally submitted. This file shows how many interrupts where generated on a non expected CPU. - "from:" is the CPU on which the IRQ was expected, but not generated. - "to:" is the CPU on which the IRQ was generated, but not expected. + + "from:" + is the CPU on which the IRQ was expected, but not generated. + "to:" + is the CPU on which the IRQ was generated, but not expected. What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects Date: Feb 2020 @@ -125,7 +128,7 @@ Date: Feb 2020 KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> Description: Contains statistics regarding rdma operations and inflight operations. - The output consists of 6 values: + The output consists of 6 values:: - <read-count> <read-total-size> <write-count> <write-total-size> \ - <inflights> <failovered> + <read-count> <read-total-size> <write-count> \ + <write-total-size> <inflights> <failovered> diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host index bafc59fd7b69..7c98d8f43c45 100644 --- a/Documentation/ABI/testing/sysfs-class-scsi_host +++ b/Documentation/ABI/testing/sysfs-class-scsi_host @@ -56,8 +56,9 @@ Description: management) on top, which makes it match the Windows IRST (Intel Rapid Storage Technology) driver settings. This setting is also close to min_power, except that: + a) It does not use host-initiated slumber mode, but it does - allow device-initiated slumber + allow device-initiated slumber b) It does not enable low power device sleep mode (DevSlp). What: /sys/class/scsi_host/hostX/em_message @@ -70,8 +71,8 @@ Description: protocol, writes and reads correspond to the LED message format as defined in the AHCI spec. - The user must turn sw_activity (under /sys/block/*/device/) OFF - it they wish to control the activity LED via the em_message + The user must turn sw_activity (under `/sys/block/*/device/`) + OFF it they wish to control the activity LED via the em_message file. em_message_type: (RO) Displays the current enclosure management diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec index b834671522d6..b7794e02ad20 100644 --- a/Documentation/ABI/testing/sysfs-class-typec +++ b/Documentation/ABI/testing/sysfs-class-typec @@ -40,10 +40,13 @@ Description: attribute will not return until the operation has finished. Valid values: - - source (The port will behave as source only DFP port) - - sink (The port will behave as sink only UFP port) - - dual (The port will behave as dual-role-data and + + ====== ============================================== + source (The port will behave as source only DFP port) + sink (The port will behave as sink only UFP port) + dual (The port will behave as dual-role-data and dual-role-power port) + ====== ============================================== What: /sys/class/typec/<port>/vconn_source Date: April 2017 @@ -59,6 +62,7 @@ Description: generates uevent KOBJ_CHANGE. Valid values: + - "no" when the port is not the VCONN Source - "yes" when the port is the VCONN Source @@ -72,6 +76,7 @@ Description: power operation mode should show "usb_power_delivery". Valid values: + - default - 1.5A - 3.0A @@ -191,6 +196,7 @@ Date: April 2017 Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> Description: Shows type of the plug on the cable: + - type-a - Standard A - type-b - Standard B - type-c diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc index a0578751c1e3..6c5dcad21e19 100644 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc @@ -66,11 +66,14 @@ Description: <channel> <type> [<bpst offset>] to start (or stop) scanning on a channel. <type> is one of: - 0 - scan - 1 - scan outside BP - 2 - scan while inactive - 3 - scanning disabled - 4 - scan (with start time of <bpst offset>) + + == ======================================= + 0 scan + 1 scan outside BP + 2 scan while inactive + 3 scanning disabled + 4 scan (with start time of <bpst offset>) + == ======================================= What: /sys/class/uwb_rc/uwbN/mac_address Date: July 2008 diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog index 9860a8b2ba75..585caecda3a5 100644 --- a/Documentation/ABI/testing/sysfs-class-watchdog +++ b/Documentation/ABI/testing/sysfs-class-watchdog @@ -91,10 +91,13 @@ Description: h/w strapping (for WDT2 only). At alternate flash the 'access_cs0' sysfs node provides: - ast2400: a way to get access to the primary SPI flash + + ast2400: + a way to get access to the primary SPI flash chip at CS0 after booting from the alternate chip at CS1. - ast2500: a way to restore the normal address mapping + ast2500: + a way to restore the normal address mapping from (CS0->CS1, CS1->CS0) to (CS0->CS0, CS1->CS1). diff --git a/Documentation/ABI/testing/sysfs-dev b/Documentation/ABI/testing/sysfs-dev index a9f2b8b0530f..d1739063e762 100644 --- a/Documentation/ABI/testing/sysfs-dev +++ b/Documentation/ABI/testing/sysfs-dev @@ -9,9 +9,10 @@ Description: The /sys/dev tree provides a method to look up the sysfs the form "<major>:<minor>". These links point to the corresponding sysfs path for the given device. - Example: - $ readlink /sys/dev/block/8:32 - ../../block/sdc + Example:: + + $ readlink /sys/dev/block/8:32 + ../../block/sdc Entries in /sys/dev/char and /sys/dev/block will be dynamically created and destroyed as devices enter and diff --git a/Documentation/ABI/testing/sysfs-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping index 490ccfd67f12..8d202bac9394 100644 --- a/Documentation/ABI/testing/sysfs-devices-mapping +++ b/Documentation/ABI/testing/sysfs-devices-mapping @@ -8,26 +8,27 @@ Description: block. For example, on 4-die Xeon platform with up to 6 IIO stacks per die and, therefore, 6 IIO PMON blocks per die, the mapping of - IIO PMON block 0 exposes as the following: + IIO PMON block 0 exposes as the following:: - $ ls /sys/devices/uncore_iio_0/die* - -r--r--r-- /sys/devices/uncore_iio_0/die0 - -r--r--r-- /sys/devices/uncore_iio_0/die1 - -r--r--r-- /sys/devices/uncore_iio_0/die2 - -r--r--r-- /sys/devices/uncore_iio_0/die3 + $ ls /sys/devices/uncore_iio_0/die* + -r--r--r-- /sys/devices/uncore_iio_0/die0 + -r--r--r-- /sys/devices/uncore_iio_0/die1 + -r--r--r-- /sys/devices/uncore_iio_0/die2 + -r--r--r-- /sys/devices/uncore_iio_0/die3 - $ tail /sys/devices/uncore_iio_0/die* - ==> /sys/devices/uncore_iio_0/die0 <== - 0000:00 - ==> /sys/devices/uncore_iio_0/die1 <== - 0000:40 - ==> /sys/devices/uncore_iio_0/die2 <== - 0000:80 - ==> /sys/devices/uncore_iio_0/die3 <== - 0000:c0 + $ tail /sys/devices/uncore_iio_0/die* + ==> /sys/devices/uncore_iio_0/die0 <== + 0000:00 + ==> /sys/devices/uncore_iio_0/die1 <== + 0000:40 + ==> /sys/devices/uncore_iio_0/die2 <== + 0000:80 + ==> /sys/devices/uncore_iio_0/die3 <== + 0000:c0 - Which means: - IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000 - IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000 - IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000 - IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000 + Which means:: + + IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000 + IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000 + IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000 + IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000 diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory index deef3b5723cf..2da2b1fba2c1 100644 --- a/Documentation/ABI/testing/sysfs-devices-memory +++ b/Documentation/ABI/testing/sysfs-devices-memory @@ -47,16 +47,19 @@ Description: online/offline state of the memory section. When written, root can toggle the the online/offline state of a removable memory section (see removable file description above) - using the following commands. - # echo online > /sys/devices/system/memory/memoryX/state - # echo offline > /sys/devices/system/memory/memoryX/state + using the following commands:: + + # echo online > /sys/devices/system/memory/memoryX/state + # echo offline > /sys/devices/system/memory/memoryX/state For example, if /sys/devices/system/memory/memory22/removable contains a value of 1 and /sys/devices/system/memory/memory22/state contains the string "online" the following command can be executed by - by root to offline that section. - # echo offline > /sys/devices/system/memory/memory22/state + by root to offline that section:: + + # echo offline > /sys/devices/system/memory/memory22/state + Users: hotplug memory remove tools http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils @@ -78,6 +81,7 @@ Description: For example, the following symbolic link is created for memory section 9 on node0: + /sys/devices/system/memory/memory9/node0 -> ../../node/node0 @@ -90,4 +94,5 @@ Description: points to the corresponding /sys/devices/system/memory/memoryY memory section directory. For example, the following symbolic link is created for memory section 9 on node0. + /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD index 7e43cdce9a52..f7b360a61b21 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD +++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD @@ -7,6 +7,7 @@ Description: (RO) Hexadecimal bitmask of the TAD attributes are reported by the platform firmware (see ACPI 6.2, section 9.18.2): + ======= ====================================================== BIT(0): AC wakeup implemented if set BIT(1): DC wakeup implemented if set BIT(2): Get/set real time features implemented if set @@ -16,6 +17,7 @@ Description: BIT(6): The AC timer wakes up from S5 if set BIT(7): The DC timer wakes up from S4 if set BIT(8): The DC timer wakes up from S5 if set + ======= ====================================================== The other bits are reserved. @@ -62,9 +64,11 @@ Description: timer status with the following meaning of bits (see ACPI 6.2, Section 9.18.5): + ======= ====================================================== Bit(0): The timer has expired if set. Bit(1): The timer has woken up the system from a sleep state (S3 or S4/S5 if supported) if set. + ======= ====================================================== The other bits are reserved. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget index d548eaac230a..40f29a01fd14 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget +++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget @@ -3,8 +3,9 @@ Date: April 2010 Contact: Fabien Chouteau <fabien.chouteau@barco.com> Description: Show the suspend state of an USB composite gadget. - 1 -> suspended - 0 -> resumed + + - 1 -> suspended + - 0 -> resumed (_UDC_ is the name of the USB Device Controller driver) @@ -17,5 +18,6 @@ Description: Storage mode. Possible values are: - 1 -> ignore the FUA flag - 0 -> obey the FUA flag + + - 1 -> ignore the FUA flag + - 0 -> obey the FUA flag diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3 index 8aa36716882f..378c42694bfb 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-docg3 +++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3 @@ -9,8 +9,10 @@ Description: The protection has information embedded whether it blocks reads, writes or both. The result is: - 0 -> the DPS is not keylocked - 1 -> the DPS is keylocked + + - 0 -> the DPS is not keylocked + - 1 -> the DPS is keylocked + Users: None identified so far. What: /sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key @@ -27,8 +29,12 @@ Description: Entering the correct value toggle the lock, and can be observed through f[0-3]_dps[01]_is_keylocked. Possible values are: + - 8 bytes + Typical values are: + - "00000000" - "12345678" + Users: None identified so far. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ipmi b/Documentation/ABI/testing/sysfs-devices-platform-ipmi index afb5db856e1c..07df0ddc0b69 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-ipmi +++ b/Documentation/ABI/testing/sysfs-devices-platform-ipmi @@ -123,38 +123,40 @@ KernelVersion: v4.15 Contact: openipmi-developer@lists.sourceforge.net Description: - idles: (RO) Number of times the interface was + ====================== ======================================== + idles (RO) Number of times the interface was idle while being polled. - watchdog_pretimeouts: (RO) Number of watchdog pretimeouts. + watchdog_pretimeouts (RO) Number of watchdog pretimeouts. - complete_transactions: (RO) Number of completed messages. + complete_transactions (RO) Number of completed messages. - events: (RO) Number of IPMI events received from + events (RO) Number of IPMI events received from the hardware. - interrupts: (RO) Number of interrupts the driver + interrupts (RO) Number of interrupts the driver handled. - hosed_count: (RO) Number of times the hardware didn't + hosed_count (RO) Number of times the hardware didn't follow the state machine. - long_timeouts: (RO) Number of times the driver + long_timeouts (RO) Number of times the driver requested a timer while nothing was in progress. - flag_fetches: (RO) Number of times the driver + flag_fetches (RO) Number of times the driver requested flags from the hardware. - attentions: (RO) Number of time the driver got an + attentions (RO) Number of time the driver got an ATTN from the hardware. - incoming_messages: (RO) Number of asynchronous messages + incoming_messages (RO) Number of asynchronous messages received. - short_timeouts: (RO) Number of times the driver + short_timeouts (RO) Number of times the driver requested a timer while an operation was in progress. + ====================== ======================================== What: /sys/devices/platform/ipmi_si.*/interrupts_enabled @@ -201,38 +203,40 @@ Date: Sep, 2017 KernelVersion: v4.15 Contact: openipmi-developer@lists.sourceforge.net Description: - hosed: (RO) Number of times the hardware didn't + ====================== ======================================== + hosed (RO) Number of times the hardware didn't follow the state machine. - alerts: (RO) Number of alerts received. + alerts (RO) Number of alerts received. - sent_messages: (RO) Number of total messages sent. + sent_messages (RO) Number of total messages sent. - sent_message_parts: (RO) Number of message parts sent. + sent_message_parts (RO) Number of message parts sent. Messages may be broken into parts if they are long. - received_messages: (RO) Number of message responses + received_messages (RO) Number of message responses received. - received_message_parts: (RO) Number of message fragments + received_message_parts (RO) Number of message fragments received. - events: (RO) Number of received events. + events (RO) Number of received events. - watchdog_pretimeouts: (RO) Number of watchdog pretimeouts. + watchdog_pretimeouts (RO) Number of watchdog pretimeouts. - flag_fetches: (RO) Number of times a flag fetch was + flag_fetches (RO) Number of times a flag fetch was requested. - send_retries: (RO) Number of time a message was + send_retries (RO) Number of time a message was retried. - receive_retries: (RO) Number of times the receive of a + receive_retries (RO) Number of times the receive of a message was retried. - send_errors: (RO) Number of times the send of a + send_errors (RO) Number of times the send of a message failed. - receive_errors: (RO) Number of errors in receiving + receive_errors (RO) Number of errors in receiving messages. + ====================== ======================================== diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb index 2107082426da..e45ac2e865d5 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb +++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb @@ -17,10 +17,10 @@ Description: to overlay planes. Selects the composition mode for the overlay. Possible values - are + are: - 0 - Alpha Blending - 1 - ROP3 + - 0 - Alpha Blending + - 1 - ROP3 What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position Date: May 2012 @@ -30,7 +30,7 @@ Description: to overlay planes. Stores the x,y overlay position on the display in pixels. The - position format is `[0-9]+,[0-9]+'. + position format is `[0-9]+,[0-9]+`. What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3 Date: May 2012 diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu index a8daceb4a956..ee253b033280 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu @@ -102,6 +102,8 @@ Description: 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. @@ -111,21 +113,29 @@ Description: 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]. + == =========================================== What: /sys/devices/platform/stratix10-rsu.0/dcmf0 Date: June 2020 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index b555df825447..1a04ca8162ad 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -151,23 +151,28 @@ Description: The processor idle states which are available for use have the following attributes: - name: (RO) Name of the idle state (string). + ======== ==== ================================================= + name: (RO) Name of the idle state (string). latency: (RO) The latency to exit out of this idle state (in - microseconds). + microseconds). - power: (RO) The power consumed while in this idle state (in - milliwatts). + power: (RO) The power consumed while in this idle state (in + milliwatts). - time: (RO) The total time spent in this idle state (in microseconds). + time: (RO) The total time spent in this idle state + (in microseconds). - usage: (RO) Number of times this state was entered (a count). + usage: (RO) Number of times this state was entered (a count). - above: (RO) Number of times this state was entered, but the - observed CPU idle duration was too short for it (a count). + above: (RO) Number of times this state was entered, but the + observed CPU idle duration was too short for it + (a count). - below: (RO) Number of times this state was entered, but the - observed CPU idle duration was too long for it (a count). + below: (RO) Number of times this state was entered, but the + observed CPU idle duration was too long for it + (a count). + ======== ==== ================================================= What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/desc Date: February 2008 @@ -290,6 +295,7 @@ Description: Processor frequency boosting control This switch controls the boost setting for the whole system. Boosting allows the CPU and the firmware to run at a frequency beyound it's nominal limit. + More details can be found in Documentation/admin-guide/pm/cpufreq.rst @@ -337,43 +343,57 @@ Contact: Sudeep Holla <sudeep.holla@arm.com> Description: Parameters for the CPU cache attributes allocation_policy: - - WriteAllocate: allocate a memory location to a cache line - on a cache miss because of a write - - ReadAllocate: allocate a memory location to a cache line + - WriteAllocate: + allocate a memory location to a cache line + on a cache miss because of a write + - ReadAllocate: + allocate a memory location to a cache line on a cache miss because of a read - - ReadWriteAllocate: both writeallocate and readallocate + - ReadWriteAllocate: + both writeallocate and readallocate - attributes: LEGACY used only on IA64 and is same as write_policy + attributes: + LEGACY used only on IA64 and is same as write_policy - coherency_line_size: the minimum amount of data in bytes that gets + coherency_line_size: + the minimum amount of data in bytes that gets transferred from memory to cache - level: the cache hierarchy in the multi-level cache configuration + level: + the cache hierarchy in the multi-level cache configuration - number_of_sets: total number of sets in the cache, a set is a + number_of_sets: + total number of sets in the cache, a set is a collection of cache lines with the same cache index - physical_line_partition: number of physical cache line per cache tag + physical_line_partition: + number of physical cache line per cache tag - shared_cpu_list: the list of logical cpus sharing the cache + shared_cpu_list: + the list of logical cpus sharing the cache - shared_cpu_map: logical cpu mask containing the list of cpus sharing + shared_cpu_map: + logical cpu mask containing the list of cpus sharing the cache - size: the total cache size in kB + size: + the total cache size in kB type: - Instruction: cache that only holds instructions - Data: cache that only caches data - Unified: cache that holds both data and instructions - ways_of_associativity: degree of freedom in placing a particular block - of memory in the cache + ways_of_associativity: + degree of freedom in placing a particular block + of memory in the cache write_policy: - - WriteThrough: data is written to both the cache line + - WriteThrough: + data is written to both the cache line and to the block in the lower-level memory - - WriteBack: data is written only to the cache line and + - WriteBack: + data is written only to the cache line and the modified cache line is written to main memory only when it is replaced @@ -414,30 +434,30 @@ Description: POWERNV CPUFreq driver's frequency throttle stats directory and throttle attributes exported in the 'throttle_stats' directory: - turbo_stat : This file gives the total number of times the max - frequency is throttled to lower frequency in turbo (at and above - nominal frequency) range of frequencies. + frequency is throttled to lower frequency in turbo (at and above + nominal frequency) range of frequencies. - sub_turbo_stat : This file gives the total number of times the - max frequency is throttled to lower frequency in sub-turbo(below - nominal frequency) range of frequencies. + max frequency is throttled to lower frequency in sub-turbo(below + nominal frequency) range of frequencies. - unthrottle : This file gives the total number of times the max - frequency is unthrottled after being throttled. + frequency is unthrottled after being throttled. - powercap : This file gives the total number of times the max - frequency is throttled due to 'Power Capping'. + frequency is throttled due to 'Power Capping'. - overtemp : This file gives the total number of times the max - frequency is throttled due to 'CPU Over Temperature'. + frequency is throttled due to 'CPU Over Temperature'. - supply_fault : This file gives the total number of times the - max frequency is throttled due to 'Power Supply Failure'. + max frequency is throttled due to 'Power Supply Failure'. - overcurrent : This file gives the total number of times the - max frequency is throttled due to 'Overcurrent'. + max frequency is throttled due to 'Overcurrent'. - occ_reset : This file gives the total number of times the max - frequency is throttled due to 'OCC Reset'. + frequency is throttled due to 'OCC Reset'. The sysfs attributes representing different throttle reasons like powercap, overtemp, supply_fault, overcurrent and occ_reset map to @@ -469,8 +489,9 @@ What: /sys/devices/system/cpu/cpuX/regs/ Date: June 2016 Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> Description: AArch64 CPU registers + 'identification' directory exposes the CPU ID registers for - identifying model and revision of the CPU. + identifying model and revision of the CPU. What: /sys/devices/system/cpu/cpu#/cpu_capacity Date: December 2016 @@ -497,9 +518,11 @@ Description: Information about CPU vulnerabilities vulnerabilities. The output of those files reflects the state of the CPUs in the system. Possible output values: + ================ ============================================== "Not affected" CPU is not affected by the vulnerability "Vulnerable" CPU is affected and no mitigation in effect "Mitigation: $M" CPU is affected and mitigation $M is in effect + ================ ============================================== See also: Documentation/admin-guide/hw-vuln/index.rst @@ -515,12 +538,14 @@ Description: Control Symetric Multi Threading (SMT) control: Read/write interface to control SMT. Possible values: + ================ ========================================= "on" SMT is enabled "off" SMT is disabled "forceoff" SMT is force disabled. Cannot be changed. "notsupported" SMT is not supported by the CPU "notimplemented" SMT runtime toggling is not implemented for the architecture + ================ ========================================= If control status is "forceoff" or "notsupported" writes are rejected. @@ -576,7 +601,7 @@ Description: Secure Virtual Machine Facility in POWER9 and newer processors. i.e., it is a Secure Virtual Machine. -What: /sys/devices/system/cpu/cpuX/purr +What: /sys/devices/system/cpu/cpuX/purr Date: Apr 2005 Contact: Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org> Description: PURR ticks for this CPU since the system boot. diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl index 470def06ab0a..1a8ee26e92ae 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl +++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl @@ -5,8 +5,10 @@ Contact: Vernon Mauery <vernux@us.ibm.com> Description: The state file allows a means by which to change in and out of Premium Real-Time Mode (PRTM), as well as the ability to query the current state. - 0 => PRTM off - 1 => PRTM enabled + + - 0 => PRTM off + - 1 => PRTM enabled + Users: The ibm-prtm userspace daemon uses this interface. diff --git a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator index 4d63a7904b94..42214b4ff14a 100644 --- a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator +++ b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator @@ -6,11 +6,13 @@ Description: Read/write the current state of DDR Backup Mode, which controls if DDR power rails will be kept powered during system suspend. ("on"/"1" = enabled, "off"/"0" = disabled). Two types of power switches (or control signals) can be used: + A. With a momentary power switch (or pulse signal), DDR Backup Mode is enabled by default when available, as the PMIC will be configured only during system suspend. B. With a toggle power switch (or level signal), the following steps must be followed exactly: + 1. Configure PMIC for backup mode, to change the role of the accessory power switch from a power switch to a wake-up switch, @@ -20,8 +22,10 @@ Description: Read/write the current state of DDR Backup Mode, which controls 3. Suspend system, 4. Switch accessory power switch on, to resume the system. + DDR Backup Mode must be explicitly enabled by the user, to invoke step 1. + See also Documentation/devicetree/bindings/mfd/bd9571mwv.txt. Users: User space applications for embedded boards equipped with a BD9571MWV PMIC. diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe index 64ac6d567c4b..69d855dc4c47 100644 --- a/Documentation/ABI/testing/sysfs-driver-genwqe +++ b/Documentation/ABI/testing/sysfs-driver-genwqe @@ -29,8 +29,12 @@ What: /sys/class/genwqe/genwqe<n>_card/reload_bitstream Date: May 2014 Contact: klebers@linux.vnet.ibm.com Description: Interface to trigger a PCIe card reset to reload the bitstream. + + :: + sudo sh -c 'echo 1 > \ /sys/class/genwqe/genwqe0_card/reload_bitstream' + If successfully, the card will come back with the bitstream set on 'next_bitstream'. @@ -64,8 +68,11 @@ Description: Base clock frequency of the card. What: /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs Date: Oct 2013 Contact: haver@linux.vnet.ibm.com -Description: Enable VFs (1..15): +Description: Enable VFs (1..15):: + sudo sh -c 'echo 15 > \ /sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs' - Disable VFs: + + Disable VFs:: + Write a 0 into the same sysfs entry. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-lenovo b/Documentation/ABI/testing/sysfs-driver-hid-lenovo index 53a0725962e1..aee85ca1f6be 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-lenovo +++ b/Documentation/ABI/testing/sysfs-driver-hid-lenovo @@ -3,14 +3,18 @@ Date: July 2011 Contact: linux-input@vger.kernel.org Description: This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be is being controlled by press_speed. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging Date: July 2011 Contact: linux-input@vger.kernel.org Description: If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select @@ -25,7 +29,9 @@ Date: July 2011 Contact: linux-input@vger.kernel.org Description: This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate a left or right mouse button click. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity @@ -39,12 +45,16 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid- Date: July 2011 Contact: linux-input@vger.kernel.org Description: This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled. + Values are decimal integers from 1 (slowest) to 255 (fastest). + Applies to Thinkpad USB Keyboard with TrackPoint. What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fn_lock Date: July 2014 Contact: linux-input@vger.kernel.org Description: This setting controls whether Fn Lock is enabled on the keyboard (i.e. if F1 is Mute or F1) + Values are 0 or 1 + Applies to ThinkPad Compact (USB|Bluetooth) Keyboard with TrackPoint. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff index 305dffd229a8..de07be314efc 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff @@ -12,7 +12,9 @@ KernelVersion: 4.1 Contact: Michal Malý <madcatxster@devoid-pointer.net> Description: Displays a set of alternate modes supported by a wheel. Each mode is listed as follows: + Tag: Mode Name + Currently active mode is marked with an asterisk. List also contains an abstract item "native" which always denotes the native mode of the wheel. Echoing the mode tag switches the @@ -24,24 +26,30 @@ Description: Displays a set of alternate modes supported by a wheel. Each This entry is not created for devices that have only one mode. Currently supported mode switches: - Driving Force Pro: + + Driving Force Pro:: + DF-EX --> DFP - G25: + G25:: + DF-EX --> DFP --> G25 - G27: + G27:: + DF-EX <*> DFP <-> G25 <-> G27 DF-EX <*--------> G25 <-> G27 DF-EX <*----------------> G27 - G29: + G29:: + DF-EX <*> DFP <-> G25 <-> G27 <-> G29 DF-EX <*--------> G25 <-> G27 <-> G29 DF-EX <*----------------> G27 <-> G29 DF-EX <*------------------------> G29 - DFGT: + DFGT:: + DF-EX <*> DFP <-> DFGT DF-EX <*--------> DFGT diff --git a/Documentation/ABI/testing/sysfs-driver-hid-ntrig b/Documentation/ABI/testing/sysfs-driver-hid-ntrig index e574a5625efe..0e323a5cec6c 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-ntrig +++ b/Documentation/ABI/testing/sysfs-driver-hid-ntrig @@ -29,12 +29,13 @@ Contact: linux-input@vger.kernel.org Description: Threholds to override activation slack. - activation_width: (RW) Width threshold to immediately + ================= ===================================== + activation_width (RW) Width threshold to immediately start processing touch events. - activation_height: (RW) Height threshold to immediately + activation_height (RW) Height threshold to immediately start processing touch events. - + ================= ===================================== What: /sys/bus/hid/drivers/ntrig/<dev>/min_width What: /sys/bus/hid/drivers/ntrig/<dev>/min_height @@ -44,11 +45,13 @@ Contact: linux-input@vger.kernel.org Description: Minimum size contact accepted. - min_width: (RW) Minimum touch contact width to decide + ========== =========================================== + min_width (RW) Minimum touch contact width to decide activation and activity. - min_height: (RW) Minimum touch contact height to decide + min_height (RW) Minimum touch contact height to decide activation and activity. + ========== =========================================== What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_width diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone index 8f7982c70d72..11cd9bf0ad18 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone @@ -3,17 +3,21 @@ Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: It is possible to switch the dpi setting of the mouse with the press of a button. + When read, this file returns the raw number of the actual dpi setting reported by the mouse. This number has to be further processed to receive the real dpi value: + ===== ===== VALUE DPI + ===== ===== 1 800 2 1200 3 1600 4 2000 5 2400 6 3200 + ===== ===== This file is readonly. Users: http://roccat.sourceforge.net @@ -22,6 +26,7 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid- Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When read, this file returns the number of the actual profile. + This file is readonly. Users: http://roccat.sourceforge.net @@ -33,6 +38,7 @@ Description: When read, this file returns the raw integer version number of the further usage in other programs. To receive the real version number the decimal point has to be shifted 2 positions to the left. E.g. a returned value of 138 means 1.38 + This file is readonly. Users: http://roccat.sourceforge.net @@ -43,10 +49,13 @@ Description: The mouse can store 5 profiles which can be switched by the press of a button. A profile holds information like button mappings, sensitivity, the colors of the 5 leds and light effects. + When read, these files return the respective profile. The returned data is 975 bytes in size. + When written, this file lets one write the respective profile data back to the mouse. The data has to be 975 bytes long. + The mouse will reject invalid data, whereas the profile number stored in the profile doesn't need to fit the number of the store. @@ -58,6 +67,7 @@ Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When read, this file returns the settings stored in the mouse. The size of the data is 36 bytes and holds information like the startup_profile, tcu state and calibration_data. + When written, this file lets write settings back to the mouse. The data has to be 36 bytes long. The mouse will reject invalid data. @@ -67,8 +77,10 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid- Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: The integer value of this attribute ranges from 1 to 5. + When read, this attribute returns the number of the profile that's active when the mouse is powered on. + When written, this file sets the number of the startup profile and the mouse activates this profile immediately. Users: http://roccat.sourceforge.net @@ -80,9 +92,12 @@ Description: The mouse has a "Tracking Control Unit" which lets the user calibrate the laser power to fit the mousepad surface. When read, this file returns the current state of the TCU, where 0 means off and 1 means on. + Writing 0 in this file will switch the TCU off. + Writing 1 in this file will start the calibration which takes around 6 seconds to complete and activates the TCU. + Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/weight @@ -93,14 +108,18 @@ Description: The mouse can be equipped with one of four supplied weights and its value can be read out. When read, this file returns the raw value returned by the mouse which eases further processing in other software. + The values map to the weights as follows: + ===== ====== VALUE WEIGHT + ===== ====== 0 none 1 5g 2 10g 3 15g 4 20g + ===== ====== This file is readonly. Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote index 39dfa5cb1cc5..3bf43d9dcdfe 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote +++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote @@ -20,6 +20,7 @@ Description: This file contains the currently connected and initialized the official Nintendo Nunchuck extension and classic is the Nintendo Classic Controller extension. The motionp extension can be combined with the other two. + Starting with kernel-version 3.11 Motion Plus hotplugging is supported and if detected, it's no longer reported as static extension. You will get uevent notifications for the motion-plus @@ -39,9 +40,13 @@ Description: While a device is initialized by the wiimote driver, we perform Other strings for each device-type are available and may be added if new device-specific detections are added. Currently supported are: - gen10: First Wii Remote generation - gen20: Second Wii Remote Plus generation (builtin MP) + + ============= ======================================= + gen10: First Wii Remote generation + gen20: Second Wii Remote Plus generation + (builtin MP) balanceboard: Wii Balance Board + ============= ======================================= What: /sys/bus/hid/drivers/wiimote/<dev>/bboard_calib Date: May 2013 @@ -54,6 +59,7 @@ Description: This attribute is only provided if the device was detected as a First, 0kg values for all 4 sensors are written, followed by the 17kg values for all 4 sensors and last the 34kg values for all 4 sensors. + Calibration data is already applied by the kernel to all input values but may be used by user-space to perform other transformations. @@ -68,9 +74,11 @@ Description: This attribute is only provided if the device was detected as a is prefixed with a +/-. Each value is a signed 16bit number. Data is encoded as decimal numbers and specifies the offsets of the analog sticks of the pro-controller. + Calibration data is already applied by the kernel to all input values but may be used by user-space to perform other transformations. + Calibration data is detected by the kernel during device setup. You can write "scan\n" into this file to re-trigger calibration. You can also write data directly in the form "x1:y1 x2:y2" to diff --git a/Documentation/ABI/testing/sysfs-driver-input-exc3000 b/Documentation/ABI/testing/sysfs-driver-input-exc3000 index 3d316d54f81c..cd7c578aef2c 100644 --- a/Documentation/ABI/testing/sysfs-driver-input-exc3000 +++ b/Documentation/ABI/testing/sysfs-driver-input-exc3000 @@ -4,6 +4,7 @@ Contact: linux-input@vger.kernel.org Description: Reports the firmware version provided by the touchscreen, for example "00_T6" on a EXC80H60 Access: Read + Valid values: Represented as string What: /sys/bus/i2c/devices/xxx/model @@ -12,4 +13,5 @@ Contact: linux-input@vger.kernel.org Description: Reports the model identification provided by the touchscreen, for example "Orion_1320" on a EXC80H60 Access: Read + Valid values: Represented as string diff --git a/Documentation/ABI/testing/sysfs-driver-jz4780-efuse b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse index bb6f5d6ceea0..4cf595d681e6 100644 --- a/Documentation/ABI/testing/sysfs-driver-jz4780-efuse +++ b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse @@ -4,7 +4,9 @@ Contact: PrasannaKumar Muralidharan <prasannatsmkumar@gmail.com> Description: read-only access to the efuse on the Ingenic JZ4780 SoC The SoC has a one time programmable 8K efuse that is split into segments. The driver supports read only. - The segments are + The segments are: + + ===== ======== ================= 0x000 64 bit Random Number 0x008 128 bit Ingenic Chip ID 0x018 128 bit Customer ID @@ -12,5 +14,7 @@ Description: read-only access to the efuse on the Ingenic JZ4780 SoC 0x1E0 8 bit Protect Segment 0x1E1 2296 bit HDMI Key 0x300 2048 bit Security boot key + ===== ======== ================= + Users: any user space application which wants to read the Chip and Customer ID diff --git a/Documentation/ABI/testing/sysfs-driver-pciback b/Documentation/ABI/testing/sysfs-driver-pciback index 73308c2b81b0..49f5fd0c8bbd 100644 --- a/Documentation/ABI/testing/sysfs-driver-pciback +++ b/Documentation/ABI/testing/sysfs-driver-pciback @@ -7,8 +7,10 @@ Description: the format of DDDD:BB:DD.F-REG:SIZE:MASK will allow the guest to write and read from the PCI device. That is Domain:Bus: Device.Function-Register:Size:Mask (Domain is optional). - For example: - #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks + For example:: + + #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks + will allow the guest to read and write to the configuration register 0x0E. diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop index 34d3a3359cf4..28c9c040de5d 100644 --- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop @@ -9,10 +9,12 @@ Description: Some Samsung laptops have different "performance levels" their fans quiet at all costs. Reading from this file will show the current performance level. Writing to the file can change this value. + Valid options: - "silent" - "normal" - "overclock" + - "silent" + - "normal" + - "overclock" + Note that not all laptops support all of these options. Specifically, not all support the "overclock" option, and it's still unknown if this value even changes @@ -25,8 +27,9 @@ Contact: Corentin Chary <corentin.chary@gmail.com> Description: Max battery charge level can be modified, battery cycle life can be extended by reducing the max battery charge level. - 0 means normal battery mode (100% charge) - 1 means battery life extender mode (80% charge) + + - 0 means normal battery mode (100% charge) + - 1 means battery life extender mode (80% charge) What: /sys/devices/platform/samsung/usb_charge Date: December 1, 2011 diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi index f34221b52b14..e5a438d84e1f 100644 --- a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi @@ -4,10 +4,12 @@ KernelVersion: 3.15 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the keyboard backlight operation mode, valid values are: + * 0x1 -> FN-Z * 0x2 -> AUTO (also called TIMER) * 0x8 -> ON * 0x10 -> OFF + Note that from kernel 3.16 onwards this file accepts all listed parameters, kernel 3.15 only accepts the first two (FN-Z and AUTO). @@ -41,8 +43,10 @@ KernelVersion: 3.15 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This files controls the status of the touchpad and pointing stick (if available), valid values are: + * 0 -> OFF * 1 -> ON + Users: KToshiba What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes @@ -51,10 +55,12 @@ KernelVersion: 3.16 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file shows the supported keyboard backlight modes the system supports, which can be: + * 0x1 -> FN-Z * 0x2 -> AUTO (also called TIMER) * 0x8 -> ON * 0x10 -> OFF + Note that not all keyboard types support the listed modes. See the entry named "available_kbd_modes" Users: KToshiba @@ -65,6 +71,7 @@ KernelVersion: 3.16 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file shows the current keyboard backlight type, which can be: + * 1 -> Type 1, supporting modes FN-Z and AUTO * 2 -> Type 2, supporting modes TIMER, ON and OFF Users: KToshiba @@ -75,10 +82,12 @@ KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the USB Sleep & Charge charging mode, which can be: + * 0 -> Disabled (0x00) * 1 -> Alternate (0x09) * 2 -> Auto (0x21) * 3 -> Typical (0x11) + Note that from kernel 4.1 onwards this file accepts all listed values, kernel 4.0 only supports the first three. Note that this feature only works when connected to power, if @@ -93,8 +102,10 @@ Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the USB Sleep Functions under battery, and set the level at which point they will be disabled, accepted values can be: + * 0 -> Disabled * 1-100 -> Battery level to disable sleep functions + Currently it prints two values, the first one indicates if the feature is enabled or disabled, while the second one shows the current battery level set. @@ -107,8 +118,10 @@ Date: January 23, 2015 KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the USB Rapid Charge state, which can be: + * 0 -> Disabled * 1 -> Enabled + Note that toggling this value requires a reboot for changes to take effect. Users: KToshiba @@ -118,8 +131,10 @@ Date: January 23, 2015 KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the Sleep & Music state, which values can be: + * 0 -> Disabled * 1 -> Enabled + Note that this feature only works when connected to power, if you want to use it under battery, see the entry named "sleep_functions_on_battery" @@ -138,6 +153,7 @@ KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the state of the internal fan, valid values are: + * 0 -> OFF * 1 -> ON @@ -147,8 +163,10 @@ KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the Special Functions (hotkeys) operation mode, valid values are: + * 0 -> Normal Operation * 1 -> Special Functions + In the "Normal Operation" mode, the F{1-12} keys are as usual and the hotkeys are accessed via FN-F{1-12}. In the "Special Functions" mode, the F{1-12} keys trigger the @@ -163,8 +181,10 @@ KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls whether the laptop should turn ON whenever the LID is opened, valid values are: + * 0 -> Disabled * 1 -> Enabled + Note that toggling this value requires a reboot for changes to take effect. Users: KToshiba @@ -174,8 +194,10 @@ Date: February 12, 2015 KernelVersion: 4.0 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the USB 3 functionality, valid values are: + * 0 -> Disabled (Acts as a regular USB 2) * 1 -> Enabled (Full USB 3 functionality) + Note that toggling this value requires a reboot for changes to take effect. Users: KToshiba @@ -188,10 +210,14 @@ Description: This file controls the Cooling Method feature. Reading this file prints two values, the first is the actual cooling method and the second is the maximum cooling method supported. When the maximum cooling method is ONE, valid values are: + * 0 -> Maximum Performance * 1 -> Battery Optimized + When the maximum cooling method is TWO, valid values are: + * 0 -> Maximum Performance * 1 -> Performance * 2 -> Battery Optimized + Users: KToshiba diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps index a662370b4dbf..c938690ce10d 100644 --- a/Documentation/ABI/testing/sysfs-driver-toshiba_haps +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps @@ -4,10 +4,12 @@ KernelVersion: 3.17 Contact: Azael Avalos <coproscefalo@gmail.com> Description: This file controls the built-in accelerometer protection level, valid values are: + * 0 -> Disabled * 1 -> Low * 2 -> Medium * 3 -> High + The default potection value is set to 2 (Medium). Users: KToshiba diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs index d1a352194d2e..adc0d0e91607 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -18,6 +18,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the device type. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_class @@ -26,6 +27,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the device class. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_sub_class @@ -34,6 +36,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the UFS storage subclass. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/protocol @@ -43,6 +46,7 @@ Description: This file shows the protocol supported by an UFS device. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_luns @@ -51,6 +55,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows number of logical units. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_wluns @@ -60,6 +65,7 @@ Description: This file shows number of well known logical units. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/boot_enable @@ -69,6 +75,7 @@ Description: This file shows value that indicates whether the device is enabled for boot. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/descriptor_access_enable @@ -79,6 +86,7 @@ Description: This file shows value that indicates whether the device of the boot sequence. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_power_mode @@ -88,6 +96,7 @@ Description: This file shows value that defines the power mode after device initialization or hardware reset. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/high_priority_lun @@ -96,6 +105,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the high priority lun. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/secure_removal_type @@ -104,6 +114,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the secure removal type. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/support_security_lun @@ -113,6 +124,7 @@ Description: This file shows whether the security lun is supported. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/bkops_termination_latency @@ -122,6 +134,7 @@ Description: This file shows the background operations termination latency. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_active_icc_level @@ -130,6 +143,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the initial active ICC level. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/specification_version @@ -138,6 +152,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the specification version. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturing_date @@ -147,6 +162,7 @@ Description: This file shows the manufacturing date in BCD format. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturer_id @@ -155,6 +171,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the manufacturee ID. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtt_capability @@ -164,6 +181,7 @@ Description: This file shows the maximum number of outstanding RTTs supported by the device. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtc_update @@ -173,6 +191,7 @@ Description: This file shows the frequency and method of the realtime clock update. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/ufs_features @@ -182,6 +201,7 @@ Description: This file shows which features are supported by the device. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/ffu_timeout @@ -190,6 +210,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the FFU timeout. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/queue_depth @@ -198,6 +219,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the device queue depth. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_version @@ -206,6 +228,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the device version. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_secure_wpa @@ -215,6 +238,7 @@ Description: This file shows number of secure write protect areas supported by the device. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_max_data_size @@ -225,6 +249,7 @@ Description: This file shows the maximum amount of data that may be This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_state_timeout @@ -234,6 +259,7 @@ Description: This file shows the command maximum timeout for a change in PSA state. This is one of the UFS device descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -244,6 +270,7 @@ Description: This file shows the MIPI UniPro version number in BCD format. This is one of the UFS interconnect descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/interconnect_descriptor/mphy_version @@ -253,6 +280,7 @@ Description: This file shows the MIPI M-PHY version number in BCD format. This is one of the UFS interconnect descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -264,6 +292,7 @@ Description: This file shows the total memory quantity available to of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_luns @@ -273,6 +302,7 @@ Description: This file shows the maximum number of logical units supported by the UFS device. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/segment_size @@ -281,6 +311,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the segment size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/allocation_unit_size @@ -289,6 +320,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the allocation unit size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/min_addressable_block_size @@ -298,6 +330,7 @@ Description: This file shows the minimum addressable block size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_read_block_size @@ -307,6 +340,7 @@ Description: This file shows the optimal read block size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_write_block_size @@ -316,6 +350,7 @@ Description: This file shows the optimal write block size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_in_buffer_size @@ -325,6 +360,7 @@ Description: This file shows the maximum data-in buffer size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_out_buffer_size @@ -334,6 +370,7 @@ Description: This file shows the maximum data-out buffer size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/rpmb_rw_size @@ -343,6 +380,7 @@ Description: This file shows the maximum number of RPMB frames allowed in Security Protocol In/Out. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/dyn_capacity_resource_policy @@ -352,6 +390,7 @@ Description: This file shows the dynamic capacity resource policy. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/data_ordering @@ -361,6 +400,7 @@ Description: This file shows support for out-of-order data transfer. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_contexts @@ -370,6 +410,7 @@ Description: This file shows maximum available number of contexts which are supported by the device. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_unit_size @@ -378,6 +419,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows system data tag unit size. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_resource_size @@ -388,6 +430,7 @@ Description: This file shows maximum storage area size allocated by This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/secure_removal_types @@ -397,6 +440,7 @@ Description: This file shows supported secure removal types. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/memory_types @@ -406,6 +450,7 @@ Description: This file shows supported memory types. This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_max_alloc_units @@ -416,6 +461,7 @@ Description: This file shows the maximum number of allocation units for enhanced type 1-4). This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_capacity_adjustment_factor @@ -426,6 +472,7 @@ Description: This file shows the memory capacity adjustment factor for enhanced type 1-4). This is one of the UFS geometry descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -436,6 +483,7 @@ Description: This file shows preend of life information. This is one of the UFS health descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_a @@ -445,6 +493,7 @@ Description: This file shows indication of the device life time (method a). This is one of the UFS health descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_b @@ -454,6 +503,7 @@ Description: This file shows indication of the device life time (method b). This is one of the UFS health descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -464,6 +514,7 @@ Description: This file shows maximum VCC, VCCQ and VCCQ2 value for active ICC levels from 0 to 15. This is one of the UFS power descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -473,6 +524,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file contains a device manufactureer name string. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_name @@ -480,6 +532,7 @@ Date: February 2018 Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file contains a product name string. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/oem_id @@ -487,6 +540,7 @@ Date: February 2018 Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file contains a OEM ID string. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/serial_number @@ -495,6 +549,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file contains a device serial number string. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_revision @@ -503,6 +558,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file contains a product revision string. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -512,6 +568,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows boot LUN information. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/lun_write_protect @@ -520,6 +577,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows LUN write protection status. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/lun_queue_depth @@ -528,6 +586,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows LUN queue depth. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/psa_sensitive @@ -536,6 +595,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows PSA sensitivity. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/lun_memory_type @@ -544,6 +604,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows LUN memory type. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/data_reliability @@ -553,6 +614,7 @@ Description: This file defines the device behavior when a power failure occurs during a write operation. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/logical_block_size @@ -562,6 +624,7 @@ Description: This file shows the size of addressable logical blocks (calculated as an exponent with base 2). This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/logical_block_count @@ -571,6 +634,7 @@ Description: This file shows total number of addressable logical blocks. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/erase_block_size @@ -579,6 +643,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the erase block size. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/provisioning_type @@ -587,6 +652,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the thin provisioning type. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/physical_memory_resourse_count @@ -595,6 +661,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the total physical memory resources. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/context_capabilities @@ -603,6 +670,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the context capabilities. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/large_unit_granularity @@ -611,6 +679,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the granularity of the LUN. This is one of the UFS unit descriptor parameters. The full information about the descriptor could be found at UFS specifications 2.1. + The file is read only. @@ -619,6 +688,7 @@ Date: February 2018 Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the device init status. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/permanent_wpe @@ -627,6 +697,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether permanent write protection is enabled. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/power_on_wpe @@ -636,6 +707,7 @@ Description: This file shows whether write protection is enabled on all logical units configured as power on write protected. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/bkops_enable @@ -644,6 +716,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether the device background operations are enabled. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/life_span_mode_enable @@ -652,6 +725,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether the device life span mode is enabled. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/phy_resource_removal @@ -660,6 +734,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether physical resource removal is enable. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/busy_rtc @@ -668,6 +743,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether the device is executing internal operation related to real time clock. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/disable_fw_update @@ -676,6 +752,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows whether the device FW update is permanently disabled. The full information about the flag could be found at UFS specifications 2.1. + The file is read only. @@ -685,6 +762,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the boot lun enabled UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/current_power_mode @@ -693,6 +771,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the current power mode UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/active_icc_level @@ -701,6 +780,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the active icc level UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/ooo_data_enabled @@ -709,6 +789,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the out of order data transfer enabled UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/bkops_status @@ -717,6 +798,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the background operations status UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/purge_status @@ -725,6 +807,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the purge operation status UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_in_size @@ -733,6 +816,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the maximum data size in a DATA IN UPIU. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_out_size @@ -741,6 +825,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file shows the maximum number of bytes that can be requested with a READY TO TRANSFER UPIU. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/reference_clock_frequency @@ -749,6 +834,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the reference clock frequency UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/configuration_descriptor_lock @@ -765,6 +851,7 @@ Description: This file provides the maximum current number of outstanding RTTs in device that is allowed. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_control @@ -773,6 +860,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the exception event control UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_status @@ -781,6 +869,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the exception event status UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/ffu_status @@ -789,6 +878,7 @@ Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file provides the ffu status UFS device attribute. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/psa_state @@ -796,6 +886,7 @@ Date: February 2018 Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> Description: This file show the PSA feature status. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/psa_data_size @@ -805,6 +896,7 @@ Description: This file shows the amount of data that the host plans to load to all logical units in pre-soldering state. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. @@ -815,6 +907,7 @@ Description: This file shows the The amount of physical memory needed to be removed from the physical memory resources pool of the particular logical unit. The full information about the attribute could be found at UFS specifications 2.1. + The file is read only. @@ -824,24 +917,28 @@ Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry could be used to set or show the UFS device runtime power management level. The current driver implementation supports 6 levels with next target states: - 0 - an UFS device will stay active, an UIC link will - stay active - 1 - an UFS device will stay active, an UIC link will - hibernate - 2 - an UFS device will moved to sleep, an UIC link will - stay active - 3 - an UFS device will moved to sleep, an UIC link will - hibernate - 4 - an UFS device will be powered off, an UIC link will - hibernate - 5 - an UFS device will be powered off, an UIC link will - be powered off + + == ==================================================== + 0 an UFS device will stay active, an UIC link will + stay active + 1 an UFS device will stay active, an UIC link will + hibernate + 2 an UFS device will moved to sleep, an UIC link will + stay active + 3 an UFS device will moved to sleep, an UIC link will + hibernate + 4 an UFS device will be powered off, an UIC link will + hibernate + 5 an UFS device will be powered off, an UIC link will + be powered off + == ==================================================== What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_dev_state Date: February 2018 Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry shows the target power mode of an UFS device for the chosen runtime power management level. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_link_state @@ -849,6 +946,7 @@ Date: February 2018 Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry shows the target state of an UFS UIC link for the chosen runtime power management level. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/spm_lvl @@ -857,24 +955,28 @@ Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry could be used to set or show the UFS device system power management level. The current driver implementation supports 6 levels with next target states: - 0 - an UFS device will stay active, an UIC link will - stay active - 1 - an UFS device will stay active, an UIC link will - hibernate - 2 - an UFS device will moved to sleep, an UIC link will - stay active - 3 - an UFS device will moved to sleep, an UIC link will - hibernate - 4 - an UFS device will be powered off, an UIC link will - hibernate - 5 - an UFS device will be powered off, an UIC link will - be powered off + + == ==================================================== + 0 an UFS device will stay active, an UIC link will + stay active + 1 an UFS device will stay active, an UIC link will + hibernate + 2 an UFS device will moved to sleep, an UIC link will + stay active + 3 an UFS device will moved to sleep, an UIC link will + hibernate + 4 an UFS device will be powered off, an UIC link will + hibernate + 5 an UFS device will be powered off, an UIC link will + be powered off + == ==================================================== What: /sys/bus/platform/drivers/ufshcd/*/spm_target_dev_state Date: February 2018 Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry shows the target power mode of an UFS device for the chosen system power management level. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/spm_target_link_state @@ -882,18 +984,21 @@ Date: February 2018 Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry shows the target state of an UFS UIC link for the chosen system power management level. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows if preserve user-space was configured + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the shared allocated units of WB buffer + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type @@ -901,6 +1006,7 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the configured WB type. 0x1 for shared buffer mode. 0x0 for dedicated buffer mode. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj @@ -910,6 +1016,7 @@ Description: This entry shows the total user-space decrease in shared buffer mode. The value of this parameter is 3 for TLC NAND when SLC mode is used as WriteBooster Buffer. 2 for MLC NAND. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units @@ -917,6 +1024,7 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the Maximum total WriteBooster Buffer size which is supported by the entire device. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns @@ -924,6 +1032,7 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the maximum number of luns that can support WriteBooster. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type @@ -937,46 +1046,59 @@ Description: The supportability of user space reduction mode preserve user space type. 02h: Device can be configured in either user space reduction type or preserve user space type. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: The supportability of WriteBooster Buffer type. - 00h: LU based WriteBooster Buffer configuration - 01h: Single shared WriteBooster Buffer - configuration - 02h: Supporting both LU based WriteBooster - Buffer and Single shared WriteBooster Buffer - configuration + + === ========================================================== + 00h LU based WriteBooster Buffer configuration + 01h Single shared WriteBooster Buffer configuration + 02h Supporting both LU based WriteBooster. + Buffer and Single shared WriteBooster Buffer configuration + === ========================================================== + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_enable Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the status of WriteBooster. - 0: WriteBooster is not enabled. - 1: WriteBooster is enabled + + == ============================ + 0 WriteBooster is not enabled. + 1 WriteBooster is enabled + == ============================ + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows if flush is enabled. - 0: Flush operation is not performed. - 1: Flush operation is performed. + + == ================================= + 0 Flush operation is not performed. + 1 Flush operation is performed. + == ================================= + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8 Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: Flush WriteBooster Buffer during hibernate state. - 0: Device is not allowed to flush the - WriteBooster Buffer during link hibernate - state. - 1: Device is allowed to flush the - WriteBooster Buffer during link hibernate - state + + == ================================================= + 0 Device is not allowed to flush the + WriteBooster Buffer during link hibernate state. + 1 Device is allowed to flush the + WriteBooster Buffer during link hibernate state. + == ================================================= + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf @@ -984,23 +1106,30 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the amount of unused WriteBooster buffer available. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the amount of unused current buffer. + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the flush operation status. - 00h: idle - 01h: Flush operation in progress - 02h: Flush operation stopped prematurely. - 03h: Flush operation completed successfully - 04h: Flush operation general failure + + + === ====================================== + 00h idle + 01h Flush operation in progress + 02h Flush operation stopped prematurely. + 03h Flush operation completed successfully + 04h Flush operation general failure + === ====================================== + The file is read only. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est @@ -1008,9 +1137,13 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows an indication of the WriteBooster Buffer lifetime based on the amount of performed program/erase cycles - 01h: 0% - 10% WriteBooster Buffer life time used + + === ============================================= + 01h 0% - 10% WriteBooster Buffer life time used ... - 0Ah: 90% - 100% WriteBooster Buffer life time used + 0Ah 90% - 100% WriteBooster Buffer life time used + === ============================================= + The file is read only. What: /sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units @@ -1018,4 +1151,5 @@ Date: June 2020 Contact: Asutosh Das <asutoshd@codeaurora.org> Description: This entry shows the configured size of WriteBooster buffer. 0400h corresponds to 4GB. + The file is read only. diff --git a/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 index d301e7017afe..e92aba4eb594 100644 --- a/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 +++ b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 @@ -5,7 +5,9 @@ Contact: Jan Kandziora <jjj@gmx.de> Description: When written, this file sets the I2C speed on the connected DS28E17 chip. When read, it reads the current setting from the DS28E17 chip. + Valid values: 100, 400, 900 [kBaud]. + Default 100, can be set by w1_ds28e17.speed= module parameter. Users: w1_ds28e17 driver @@ -17,5 +19,6 @@ Description: When written, this file sets the multiplier used to calculate the busy timeout for I2C operations on the connected DS28E17 chip. When read, returns the current setting. Valid values: 1 to 9. + Default 1, can be set by w1_ds28e17.stretch= module parameter. Users: w1_ds28e17 driver diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm index 8873bbb075cb..6a37dc33ffdb 100644 --- a/Documentation/ABI/testing/sysfs-driver-w1_therm +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm @@ -22,8 +22,10 @@ Description: device data to its embedded EEPROM, either restore data embedded in device EEPROM. Be aware that devices support limited EEPROM writing cycles (typical 50k) + * 'save': save device RAM to EEPROM * 'restore': restore EEPROM data in device RAM + Users: any user space application which wants to communicate with w1_term device @@ -33,9 +35,11 @@ Date: May 2020 Contact: Akira Shimahara <akira215corp@gmail.com> Description: (RO) return the power status by asking the device + * '0': device parasite powered * '1': device externally powered * '-xx': xx is kernel error when reading power status + Users: any user space application which wants to communicate with w1_term device @@ -49,10 +53,12 @@ Description: will be changed only in device RAM, so it will be cleared when power is lost. Trigger a 'save' to EEPROM command to keep values after power-on. Read or write are : + * '9..14': device resolution in bit - or resolution to set in bit + or resolution to set in bit * '-xx': xx is kernel error when reading the resolution * Anything else: do nothing + Some DS18B20 clones are fixed in 12-bit resolution, so the actual resolution is read back from the chip and verified. Error is reported if the results differ. @@ -65,16 +71,18 @@ Date: May 2020 Contact: Akira Shimahara <akira215corp@gmail.com> Description: (RO) return the temperature in 1/1000 degC. + * If a bulk read has been triggered, it will directly - return the temperature computed when the bulk read - occurred, if available. If not yet available, nothing - is returned (a debug kernel message is sent), you - should retry later on. + return the temperature computed when the bulk read + occurred, if available. If not yet available, nothing + is returned (a debug kernel message is sent), you + should retry later on. * If no bulk read has been triggered, it will trigger - a conversion and send the result. Note that the - conversion duration depend on the resolution (if - device support this feature). It takes 94ms in 9bits - resolution, 750ms for 12bits. + a conversion and send the result. Note that the + conversion duration depend on the resolution (if + device support this feature). It takes 94ms in 9bits + resolution, 750ms for 12bits. + Users: any user space application which wants to communicate with w1_term device @@ -86,12 +94,14 @@ Description: (RW) return the temperature in 1/1000 degC. *read*: return 2 lines with the hexa output data sent on the bus, return the CRC check and temperature in 1/1000 degC - *write* : + *write*: + * '0' : save the 2 or 3 bytes to the device EEPROM - (i.e. TH, TL and config register) + (i.e. TH, TL and config register) * '9..14' : set the device resolution in RAM - (if supported) + (if supported) * Anything else: do nothing + refer to Documentation/w1/slaves/w1_therm.rst for detailed information. Users: any user space application which wants to communicate with @@ -103,14 +113,21 @@ Date: May 2020 Contact: Akira Shimahara <akira215corp@gmail.com> Description: (RW) trigger a bulk read conversion. read the status + *read*: - * '-1': conversion in progress on at least 1 sensor - * '1' : conversion complete but at least one sensor + * '-1': + conversion in progress on at least 1 sensor + * '1' : + conversion complete but at least one sensor value has not been read yet - * '0' : no bulk operation. Reading temperature will + * '0' : + no bulk operation. Reading temperature will trigger a conversion on each device - *write*: 'trigger': trigger a bulk read on all supporting + + *write*: + 'trigger': trigger a bulk read on all supporting devices on the bus + Note that if a bulk read is sent but one sensor is not read immediately, the next access to temperature on this device will return the temperature measured at the time of issue @@ -128,14 +145,19 @@ Description: reset to default (datasheet) conversion time for a new resolution. - *read*: Actual conversion time in milliseconds. *write*: - '0': Set the default conversion time from the datasheet. - '1': Measure and set the conversion time. Make a single + *read*: + Actual conversion time in milliseconds. + + *write*: + * '0': + Set the default conversion time from the datasheet. + * '1': + Measure and set the conversion time. Make a single temperature conversion, measure an actual value. Increase it by 20% for temperature range. A new conversion time can be obtained by reading this same attribute. - other positive value: + * other positive value: Set the conversion time in milliseconds. Users: An application using the w1_term device @@ -148,16 +170,21 @@ Description: (RW) Control optional driver settings. Bit masks to read/write (bitwise OR): - 1: Enable check for conversion success. If byte 6 of + == ============================================================ + 1 Enable check for conversion success. If byte 6 of scratchpad memory is 0xC after conversion, and temperature reads 85.00 (powerup value) or 127.94 (insufficient power) - return a conversion error. - 2: Enable poll for conversion completion. Generate read cycles + 2 Enable poll for conversion completion. Generate read cycles after the conversion start and wait for 1's. In parasite power mode this feature is not available. + == ============================================================ + + *read*: + Currently selected features. - *read*: Currently selected features. - *write*: Select features. + *write*: + Select features. Users: An application using the w1_term device diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom index afc48fc163b5..16acaa5712ec 100644 --- a/Documentation/ABI/testing/sysfs-driver-wacom +++ b/Documentation/ABI/testing/sysfs-driver-wacom @@ -79,7 +79,9 @@ Description: When the Wacom Intuos 4 is connected over Bluetooth, the image has to contain 256 bytes (64x32 px 1 bit colour). The format is also scrambled, like in the USB mode, and it can - be summarized by converting 76543210 into GECA6420. + be summarized by converting:: + + 76543210 into GECA6420. HGFEDCBA HFDB7531 What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index 613f42a9d5cd..b16d30a71709 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -12,11 +12,14 @@ Description: image: The image bitmap. Currently a 32-bit BMP. status: 1 if the image is valid, 0 if firmware invalidated it. type: 0 indicates image is in BMP format. + + ======== =================================================== version: The version of the BGRT. Currently 1. xoffset: The number of pixels between the left of the screen and the left edge of the image. yoffset: The number of pixels between the top of the screen and the top edge of the image. + ======== =================================================== What: /sys/firmware/acpi/hotplug/ Date: February 2013 @@ -33,12 +36,14 @@ Description: The following setting is available to user space for each hotplug profile: + ======== ======================================================= enabled: If set, the ACPI core will handle notifications of - hotplug events associated with the given class of - devices and will allow those devices to be ejected with - the help of the _EJ0 control method. Unsetting it - effectively disables hotplug for the correspoinding - class of devices. + hotplug events associated with the given class of + devices and will allow those devices to be ejected with + the help of the _EJ0 control method. Unsetting it + effectively disables hotplug for the correspoinding + class of devices. + ======== ======================================================= The value of the above attribute is an integer number: 1 (set) or 0 (unset). Attempts to write any other values to it will @@ -71,86 +76,90 @@ Description: To figure out where all the SCI's are coming from, /sys/firmware/acpi/interrupts contains a file listing every possible source, and the count of how many - times it has triggered. - - $ cd /sys/firmware/acpi/interrupts - $ grep . * - error: 0 - ff_gbl_lock: 0 enable - ff_pmtimer: 0 invalid - ff_pwr_btn: 0 enable - ff_rt_clk: 2 disable - ff_slp_btn: 0 invalid - gpe00: 0 invalid - gpe01: 0 enable - gpe02: 108 enable - gpe03: 0 invalid - gpe04: 0 invalid - gpe05: 0 invalid - gpe06: 0 enable - gpe07: 0 enable - gpe08: 0 invalid - gpe09: 0 invalid - gpe0A: 0 invalid - gpe0B: 0 invalid - gpe0C: 0 invalid - gpe0D: 0 invalid - gpe0E: 0 invalid - gpe0F: 0 invalid - gpe10: 0 invalid - gpe11: 0 invalid - gpe12: 0 invalid - gpe13: 0 invalid - gpe14: 0 invalid - gpe15: 0 invalid - gpe16: 0 invalid - gpe17: 1084 enable - gpe18: 0 enable - gpe19: 0 invalid - gpe1A: 0 invalid - gpe1B: 0 invalid - gpe1C: 0 invalid - gpe1D: 0 invalid - gpe1E: 0 invalid - gpe1F: 0 invalid - gpe_all: 1192 - sci: 1194 - sci_not: 0 - - sci - The number of times the ACPI SCI - has been called and claimed an interrupt. - - sci_not - The number of times the ACPI SCI - has been called and NOT claimed an interrupt. - - gpe_all - count of SCI caused by GPEs. - - gpeXX - count for individual GPE source - - ff_gbl_lock - Global Lock - - ff_pmtimer - PM Timer - - ff_pwr_btn - Power Button - - ff_rt_clk - Real Time Clock - - ff_slp_btn - Sleep Button - - error - an interrupt that can't be accounted for above. - - invalid: it's either a GPE or a Fixed Event that - doesn't have an event handler. - - disable: the GPE/Fixed Event is valid but disabled. - - enable: the GPE/Fixed Event is valid and enabled. - - Root has permission to clear any of these counters. Eg. - # echo 0 > gpe11 - - All counters can be cleared by clearing the total "sci": - # echo 0 > sci + times it has triggered:: + + $ cd /sys/firmware/acpi/interrupts + $ grep . * + error: 0 + ff_gbl_lock: 0 enable + ff_pmtimer: 0 invalid + ff_pwr_btn: 0 enable + ff_rt_clk: 2 disable + ff_slp_btn: 0 invalid + gpe00: 0 invalid + gpe01: 0 enable + gpe02: 108 enable + gpe03: 0 invalid + gpe04: 0 invalid + gpe05: 0 invalid + gpe06: 0 enable + gpe07: 0 enable + gpe08: 0 invalid + gpe09: 0 invalid + gpe0A: 0 invalid + gpe0B: 0 invalid + gpe0C: 0 invalid + gpe0D: 0 invalid + gpe0E: 0 invalid + gpe0F: 0 invalid + gpe10: 0 invalid + gpe11: 0 invalid + gpe12: 0 invalid + gpe13: 0 invalid + gpe14: 0 invalid + gpe15: 0 invalid + gpe16: 0 invalid + gpe17: 1084 enable + gpe18: 0 enable + gpe19: 0 invalid + gpe1A: 0 invalid + gpe1B: 0 invalid + gpe1C: 0 invalid + gpe1D: 0 invalid + gpe1E: 0 invalid + gpe1F: 0 invalid + gpe_all: 1192 + sci: 1194 + sci_not: 0 + + =========== ================================================== + sci The number of times the ACPI SCI + has been called and claimed an interrupt. + + sci_not The number of times the ACPI SCI + has been called and NOT claimed an interrupt. + + gpe_all count of SCI caused by GPEs. + + gpeXX count for individual GPE source + + ff_gbl_lock Global Lock + + ff_pmtimer PM Timer + + ff_pwr_btn Power Button + + ff_rt_clk Real Time Clock + + ff_slp_btn Sleep Button + + error an interrupt that can't be accounted for above. + + invalid it's either a GPE or a Fixed Event that + doesn't have an event handler. + + disable the GPE/Fixed Event is valid but disabled. + + enable the GPE/Fixed Event is valid and enabled. + =========== ================================================== + + Root has permission to clear any of these counters. Eg.:: + + # echo 0 > gpe11 + + All counters can be cleared by clearing the total "sci":: + + # echo 0 > sci None of these counters has an effect on the function of the system, they are simply statistics. @@ -165,32 +174,34 @@ Description: Let's take power button fixed event for example, please kill acpid and other user space applications so that the machine won't shutdown - when pressing the power button. - # cat ff_pwr_btn - 0 enabled - # press the power button for 3 times; - # cat ff_pwr_btn - 3 enabled - # echo disable > ff_pwr_btn - # cat ff_pwr_btn - 3 disabled - # press the power button for 3 times; - # cat ff_pwr_btn - 3 disabled - # echo enable > ff_pwr_btn - # cat ff_pwr_btn - 4 enabled - /* - * this is because the status bit is set even if the enable bit is cleared, - * and it triggers an ACPI fixed event when the enable bit is set again - */ - # press the power button for 3 times; - # cat ff_pwr_btn - 7 enabled - # echo disable > ff_pwr_btn - # press the power button for 3 times; - # echo clear > ff_pwr_btn /* clear the status bit */ - # echo disable > ff_pwr_btn - # cat ff_pwr_btn - 7 enabled + when pressing the power button:: + + # cat ff_pwr_btn + 0 enabled + # press the power button for 3 times; + # cat ff_pwr_btn + 3 enabled + # echo disable > ff_pwr_btn + # cat ff_pwr_btn + 3 disabled + # press the power button for 3 times; + # cat ff_pwr_btn + 3 disabled + # echo enable > ff_pwr_btn + # cat ff_pwr_btn + 4 enabled + /* + * this is because the status bit is set even if the enable + * bit is cleared, and it triggers an ACPI fixed event when + * the enable bit is set again + */ + # press the power button for 3 times; + # cat ff_pwr_btn + 7 enabled + # echo disable > ff_pwr_btn + # press the power button for 3 times; + # echo clear > ff_pwr_btn /* clear the status bit */ + # echo disable > ff_pwr_btn + # cat ff_pwr_btn + 7 enabled diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries index 210ad44b95a5..fe0289c87768 100644 --- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries @@ -33,7 +33,7 @@ Description: doesn't matter), they will be represented in sysfs as entries "T-0" through "T-(N-1)": - Example entry directories: + Example entry directories:: /sys/firmware/dmi/entries/17-0 /sys/firmware/dmi/entries/17-1 @@ -50,61 +50,65 @@ Description: Each DMI entry in sysfs has the common header values exported as attributes: - handle : The 16bit 'handle' that is assigned to this + ======== ================================================= + handle The 16bit 'handle' that is assigned to this entry by the firmware. This handle may be referred to by other entries. - length : The length of the entry, as presented in the + length The length of the entry, as presented in the entry itself. Note that this is _not the total count of bytes associated with the - entry_. This value represents the length of + entry. This value represents the length of the "formatted" portion of the entry. This "formatted" region is sometimes followed by the "unformatted" region composed of nul terminated strings, with termination signalled by a two nul characters in series. - raw : The raw bytes of the entry. This includes the + raw The raw bytes of the entry. This includes the "formatted" portion of the entry, the "unformatted" strings portion of the entry, and the two terminating nul characters. - type : The type of the entry. This value is the same + type The type of the entry. This value is the same as found in the directory name. It indicates how the rest of the entry should be interpreted. - instance: The instance ordinal of the entry for the + instance The instance ordinal of the entry for the given type. This value is the same as found in the parent directory name. - position: The ordinal position (zero-based) of the entry + position The ordinal position (zero-based) of the entry within the entirety of the DMI entry table. + ======== ================================================= - === Entry Specialization === + **Entry Specialization** Some entry types may have other information available in sysfs. Not all types are specialized. - --- Type 15 - System Event Log --- + **Type 15 - System Event Log** This entry allows the firmware to export a log of events the system has taken. This information is typically backed by nvram, but the implementation details are abstracted by this table. This entry's data - is exported in the directory: + is exported in the directory:: - /sys/firmware/dmi/entries/15-0/system_event_log + /sys/firmware/dmi/entries/15-0/system_event_log and has the following attributes (documented in the SMBIOS / DMI specification under "System Event Log (Type 15)": - area_length - header_start_offset - data_start_offset - access_method - status - change_token - access_method_address - header_format - per_log_type_descriptor_length - type_descriptors_supported_count + - area_length + - header_start_offset + - data_start_offset + - access_method + - status + - change_token + - access_method_address + - header_format + - per_log_type_descriptor_length + - type_descriptors_supported_count As well, the kernel exports the binary attribute: - raw_event_log : The raw binary bits of the event log + ============= ==================================== + raw_event_log The raw binary bits of the event log as described by the DMI entry. + ============= ==================================== diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-esrt b/Documentation/ABI/testing/sysfs-firmware-efi-esrt index 6e431d1a4e79..31b57676d4ad 100644 --- a/Documentation/ABI/testing/sysfs-firmware-efi-esrt +++ b/Documentation/ABI/testing/sysfs-firmware-efi-esrt @@ -35,10 +35,13 @@ What: /sys/firmware/efi/esrt/entries/entry$N/fw_type Date: February 2015 Contact: Peter Jones <pjones@redhat.com> Description: What kind of firmware entry this is: - 0 - Unknown - 1 - System Firmware - 2 - Device Firmware - 3 - UEFI Driver + + == =============== + 0 Unknown + 1 System Firmware + 2 Device Firmware + 3 UEFI Driver + == =============== What: /sys/firmware/efi/esrt/entries/entry$N/fw_class Date: February 2015 @@ -71,11 +74,14 @@ Date: February 2015 Contact: Peter Jones <pjones@redhat.com> Description: The result of the last firmware update attempt for the firmware resource entry. - 0 - Success - 1 - Insufficient resources - 2 - Incorrect version - 3 - Invalid format - 4 - Authentication error - 5 - AC power event - 6 - Battery power event + + == ====================== + 0 Success + 1 Insufficient resources + 2 Incorrect version + 3 Invalid format + 4 Authentication error + 5 AC power event + 6 Battery power event + == ====================== diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map index c61b9b348e99..9c4d581be396 100644 --- a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map +++ b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map @@ -14,7 +14,7 @@ Description: Switching efi runtime services to virtual mode requires /sys/firmware/efi/runtime-map/ is the directory the kernel exports that information in. - subdirectories are named with the number of the memory range: + subdirectories are named with the number of the memory range:: /sys/firmware/efi/runtime-map/0 /sys/firmware/efi/runtime-map/1 @@ -24,11 +24,13 @@ Description: Switching efi runtime services to virtual mode requires Each subdirectory contains five files: - attribute : The attributes of the memory range. - num_pages : The size of the memory range in pages. - phys_addr : The physical address of the memory range. - type : The type of the memory range. - virt_addr : The virtual address of the memory range. + ========= ========================================= + attribute The attributes of the memory range. + num_pages The size of the memory range in pages. + phys_addr The physical address of the memory range. + type The type of the memory range. + virt_addr The virtual address of the memory range. + ========= ========================================= Above values are all hexadecimal numbers with the '0x' prefix. Users: Kexec diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi index 0faa0aaf4b6a..7a558354c1ee 100644 --- a/Documentation/ABI/testing/sysfs-firmware-gsmi +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi @@ -20,7 +20,7 @@ Description: This directory has the same layout (and underlying implementation as /sys/firmware/efi/vars. - See Documentation/ABI/*/sysfs-firmware-efi-vars + See `Documentation/ABI/*/sysfs-firmware-efi-vars` for more information on how to interact with this structure. diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap index eca0d65087dc..1f6f4d3a32c0 100644 --- a/Documentation/ABI/testing/sysfs-firmware-memmap +++ b/Documentation/ABI/testing/sysfs-firmware-memmap @@ -20,7 +20,7 @@ Description: the raw memory map to userspace. The structure is as follows: Under /sys/firmware/memmap there - are subdirectories with the number of the entry as their name: + are subdirectories with the number of the entry as their name:: /sys/firmware/memmap/0 /sys/firmware/memmap/1 @@ -34,14 +34,16 @@ Description: Each directory contains three files: - start : The start address (as hexadecimal number with the + ======== ===================================================== + start The start address (as hexadecimal number with the '0x' prefix). - end : The end address, inclusive (regardless whether the + end The end address, inclusive (regardless whether the firmware provides inclusive or exclusive ranges). - type : Type of the entry as string. See below for a list of + type Type of the entry as string. See below for a list of valid types. + ======== ===================================================== - So, for example: + So, for example:: /sys/firmware/memmap/0/start /sys/firmware/memmap/0/end @@ -57,9 +59,8 @@ Description: - reserved Following shell snippet can be used to display that memory - map in a human-readable format: + map in a human-readable format:: - -------------------- 8< ---------------------------------------- #!/bin/bash cd /sys/firmware/memmap for dir in * ; do @@ -68,4 +69,3 @@ Description: type=$(cat $dir/type) printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type" done - -------------------- >8 ---------------------------------------- diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg index 011dda4f8e8a..ee0d6dbc810e 100644 --- a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg +++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg @@ -15,7 +15,7 @@ Description: to the fw_cfg device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree. - === SysFS fw_cfg Interface === + **SysFS fw_cfg Interface** The fw_cfg sysfs interface described in this document is only intended to display discoverable blobs (i.e., those registered @@ -31,7 +31,7 @@ Description: /sys/firmware/qemu_fw_cfg/rev - --- Discoverable fw_cfg blobs by selector key --- + **Discoverable fw_cfg blobs by selector key** All discoverable blobs listed in the fw_cfg file directory are displayed as entries named after their unique selector key @@ -45,24 +45,26 @@ Description: Each such fw_cfg sysfs entry has the following values exported as attributes: - name : The 56-byte nul-terminated ASCII string used as the + ==== ==================================================== + name The 56-byte nul-terminated ASCII string used as the blob's 'file name' in the fw_cfg directory. - size : The length of the blob, as given in the fw_cfg + size The length of the blob, as given in the fw_cfg directory. - key : The value of the blob's selector key as given in the + key The value of the blob's selector key as given in the fw_cfg directory. This value is the same as used in the parent directory name. - raw : The raw bytes of the blob, obtained by selecting the + raw The raw bytes of the blob, obtained by selecting the entry via the control register, and reading a number of bytes equal to the blob size from the data register. + ==== ==================================================== - --- Listing fw_cfg blobs by file name --- + **Listing fw_cfg blobs by file name** While the fw_cfg device does not impose any specific naming convention on the blobs registered in the file directory, QEMU developers have traditionally used path name semantics - to give each blob a descriptive name. For example: + to give each blob a descriptive name. For example:: "bootorder" "genroms/kvmvapic.bin" @@ -81,7 +83,7 @@ Description: of directories matching the path name components of fw_cfg blob names, ending in symlinks to the by_key entry for each "basename", as illustrated below (assume current directory is - /sys/firmware): + /sys/firmware):: qemu_fw_cfg/by_name/bootorder -> ../by_key/38 qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35 diff --git a/Documentation/ABI/testing/sysfs-firmware-sfi b/Documentation/ABI/testing/sysfs-firmware-sfi index 4be7d44aeacf..5210e0f06ddb 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sfi +++ b/Documentation/ABI/testing/sysfs-firmware-sfi @@ -9,7 +9,7 @@ Description: http://simplefirmware.org/documentation While the tables are used by the kernel, user-space - can observe them this way: + can observe them this way:: - # cd /sys/firmware/sfi/tables - # cat $TABLENAME > $TABLENAME.bin + # cd /sys/firmware/sfi/tables + # cat $TABLENAME > $TABLENAME.bin diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv index 4573fd4b7876..637c668cbe45 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv @@ -1,27 +1,159 @@ What: /sys/firmware/sgi_uv/ -Date: August 2008 -Contact: Russ Anderson <rja@sgi.com> +Date: September 2020 +Contact: Justin Ernst <justin.ernst@hpe.com> Description: The /sys/firmware/sgi_uv directory contains information - about the SGI UV platform. + about the UV platform. - Under that directory are a number of files: + Under that directory are a number of read-only attributes:: + archtype + hub_type + hubless partition_id coherence_id + uv_type + + The archtype entry contains the UV architecture type that + is used to select arch-dependent addresses and features. + It can be set via the OEM_ID in the ACPI MADT table or by + UVsystab entry both passed from UV BIOS. + + The hub_type entry is used to select the type of hub which is + similar to uv_type but encoded in a binary format. Include + the file uv_hub.h to get the definitions. + + The hubless entry basically is present and set only if there + is no hub. In this case the hub_type entry is not present. The partition_id entry contains the partition id. - SGI UV systems can be partitioned into multiple physical + UV systems can be partitioned into multiple physical machines, which each partition running a unique copy - of the operating system. Each partition will have a unique - partition id. To display the partition id, use the command: - - cat /sys/firmware/sgi_uv/partition_id + of the operating system. Each partition will have a unique + partition id. The coherence_id entry contains the coherence id. - A partitioned SGI UV system can have one or more coherence - domain. The coherence id indicates which coherence domain - this partition is in. To display the coherence id, use the - command: + A partitioned UV system can have one or more coherence + domains. The coherence id indicates which coherence domain + this partition is in. + + The uv_type entry contains the hub revision number. + This value can be used to identify the UV system version:: + "0.*" = Hubless UV ('*' is subtype) + + "3.0" = UV2 + "5.0" = UV3 + "7.0" = UV4 + "7.1" = UV4a + "9.0" = UV5 + + The /sys/firmware/sgi_uv directory also contains two directories:: + + hubs/ + pcibuses/ + + The hubs directory contains a number of hub objects, each representing + a UV Hub visible to the BIOS. Each hub object's name is appended by a + unique ordinal value (ex. /sys/firmware/sgi_uv/hubs/hub_5) + + Each hub object directory contains a number of read-only attributes:: + + cnode + location + name + nasid + shared + this_partition + + The cnode entry contains the cnode number of the corresponding hub. + If a cnode value is not applicable, the value returned will be -1. + + The location entry contains the location string of the corresponding hub. + This value is used to physically identify a hub within a system. + + The name entry contains the name of the corresponding hub. This name can + be two variants:: + + "UVHub x.x" = A 'node' ASIC, connecting a CPU to the interconnect + fabric. The 'x.x' value represents the ASIC revision. + (ex. 'UVHub 5.0') + + "NLxRouter" = A 'router ASIC, only connecting other ASICs to + the interconnect fabric. The 'x' value representing + the fabric technology version. (ex. 'NL8Router') + + The nasid entry contains the nasid number of the corresponding hub. + If a nasid value is not applicable, the value returned will be -1. + + The shared entry contains a boolean value describing whether the + corresponding hub is shared between system partitions. + + The this_partition entry contains a boolean value describing whether + the corresponding hub is local to the current partition. + + Each hub object directory also contains a number of port objects, + each representing a fabric port on the corresponding hub. + A port object's name is appended by a unique ordinal value + (ex. /sys/firmware/sgi_uv/hubs/hub_5/port_3) + + Each port object directory contains a number of read-only attributes:: + + conn_hub + conn_port + + The conn_hub entry contains a value representing the unique + oridinal value of the hub on the other end of the fabric + cable plugged into the port. If the port is disconnected, + the value returned will be -1. + + The conn_port entry contains a value representing the unique + oridinal value of the port on the other end of the fabric cable + plugged into the port. If the port is disconnected, the value + returned will be -1. + + Ex: + A value of '3' is read from: + /sys/firmware/sgi_uv/hubs/hub_5/port_3/conn_hub + + and a value of '6' is read from: + /sys/firmware/sgi_uv/hubs/hub_5/port_3/conn_port + + representing that this port is connected to: + /sys/firmware/sgi_uv/hubs/hub_3/port_6 + + The pcibuses directory contains a number of PCI bus objects. + Each PCI bus object's name is appended by its PCI bus address. + (ex. pcibus_0003:80) + + Each pcibus object has a number of possible read-only attributes:: + + type + location + slot + ppb_addr + iio_stack + + The type entry contains a value describing the type of IO at + the corresponding PCI bus address. Known possible values + across all UV versions are:: + + BASE IO + PCIe IO + PCIe SLOT + NODE IO + Riser + PPB + + The location entry contains the location string of the UV Hub + of the CPU physically connected to the corresponding PCI bus. + + The slot entry contains the physical slot number of the + corresponding PCI bus. This value is used to physically locate + PCI cards within a system. + + The ppb_addr entry contains the PCI address string of the + bridged PCI bus. This entry is only present when the PCI bus + object type is 'PPB'. - cat /sys/firmware/sgi_uv/coherence_id + The iio_stack entry contains a value describing the IIO stack + number that the corresponding PCI bus object is connected to. diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm index 15595fab88d1..b8631f5a29c4 100644 --- a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm +++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm @@ -2,21 +2,21 @@ 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. +Description: (Read) 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. +Description: (Read) 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 +Description: (Read) 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 @@ -25,7 +25,7 @@ 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 +Description: (Read) 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 @@ -33,5 +33,5 @@ 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. +Description: (Read) Serial number burned into eFuses of this Turris Mox device. Format: %016X diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4 index 78604db56279..99e3d92f8299 100644 --- a/Documentation/ABI/testing/sysfs-fs-ext4 +++ b/Documentation/ABI/testing/sysfs-fs-ext4 @@ -45,8 +45,8 @@ Description: parameter will have their blocks allocated out of a block group specific preallocation pool, so that small files are packed closely together. Each large file - will have its blocks allocated out of its own unique - preallocation pool. + will have its blocks allocated out of its own unique + preallocation pool. What: /sys/fs/ext4/<disk>/inode_readahead_blks Date: March 2008 diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 834d0becae6d..67b3ed8e8c2f 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -20,10 +20,13 @@ What: /sys/fs/f2fs/<disk>/gc_idle Date: July 2013 Contact: "Namjae Jeon" <namjae.jeon@samsung.com> Description: Controls the victim selection policy for garbage collection. - Setting gc_idle = 0(default) will disable this option. Setting - gc_idle = 1 will select the Cost Benefit approach & setting - gc_idle = 2 will select the greedy approach & setting - gc_idle = 3 will select the age-threshold based approach. + Setting gc_idle = 0(default) will disable this option. Setting: + + =========== =============================================== + gc_idle = 1 will select the Cost Benefit approach & setting + gc_idle = 2 will select the greedy approach & setting + gc_idle = 3 will select the age-threshold based approach. + =========== =============================================== What: /sys/fs/f2fs/<disk>/reclaim_segments Date: October 2013 @@ -46,10 +49,17 @@ Date: November 2013 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> Description: Controls the in-place-update policy. updates in f2fs. User can set: - 0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR, - 0x04: F2FS_IPU_UTIL, 0x08: F2FS_IPU_SSR_UTIL, - 0x10: F2FS_IPU_FSYNC, 0x20: F2FS_IPU_ASYNC, - 0x40: F2FS_IPU_NOCACHE. + + ==== ================= + 0x01 F2FS_IPU_FORCE + 0x02 F2FS_IPU_SSR + 0x04 F2FS_IPU_UTIL + 0x08 F2FS_IPU_SSR_UTIL + 0x10 F2FS_IPU_FSYNC + 0x20 F2FS_IPU_ASYNC, + 0x40 F2FS_IPU_NOCACHE + ==== ================= + Refer segment.h for details. What: /sys/fs/f2fs/<disk>/min_ipu_util @@ -332,18 +342,28 @@ Date: April 2020 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Give a way to attach REQ_META|FUA to data writes given temperature-based bits. Now the bits indicate: - * REQ_META | REQ_FUA | - * 5 | 4 | 3 | 2 | 1 | 0 | - * Cold | Warm | Hot | Cold | Warm | Hot | + + +-------------------+-------------------+ + | REQ_META | REQ_FUA | + +------+------+-----+------+------+-----+ + | 5 | 4 | 3 | 2 | 1 | 0 | + +------+------+-----+------+------+-----+ + | Cold | Warm | Hot | Cold | Warm | Hot | + +------+------+-----+------+------+-----+ What: /sys/fs/f2fs/<disk>/node_io_flag Date: June 2020 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Give a way to attach REQ_META|FUA to node writes given temperature-based bits. Now the bits indicate: - * REQ_META | REQ_FUA | - * 5 | 4 | 3 | 2 | 1 | 0 | - * Cold | Warm | Hot | Cold | Warm | Hot | + + +-------------------+-------------------+ + | REQ_META | REQ_FUA | + +------+------+-----+------+------+-----+ + | 5 | 4 | 3 | 2 | 1 | 0 | + +------+------+-----+------+------+-----+ + | Cold | Warm | Hot | Cold | Warm | Hot | + +------+------+-----+------+------+-----+ What: /sys/fs/f2fs/<disk>/iostat_period_ms Date: April 2020 diff --git a/Documentation/ABI/testing/sysfs-hypervisor-xen b/Documentation/ABI/testing/sysfs-hypervisor-xen index 53b7b2ea7515..4dbe0c49b393 100644 --- a/Documentation/ABI/testing/sysfs-hypervisor-xen +++ b/Documentation/ABI/testing/sysfs-hypervisor-xen @@ -15,14 +15,17 @@ KernelVersion: 4.3 Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com> Description: If running under Xen: Describes mode that Xen's performance-monitoring unit (PMU) - uses. Accepted values are - "off" -- PMU is disabled - "self" -- The guest can profile itself - "hv" -- The guest can profile itself and, if it is + uses. Accepted values are: + + ====== ============================================ + "off" PMU is disabled + "self" The guest can profile itself + "hv" The guest can profile itself and, if it is privileged (e.g. dom0), the hypervisor - "all" -- The guest can profile itself, the hypervisor + "all" The guest can profile itself, the hypervisor and all other guests. Only available to privileged guests. + ====== ============================================ What: /sys/hypervisor/pmu/pmu_features Date: August 2015 diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params index eca38ce2852d..7f9bda453c4d 100644 --- a/Documentation/ABI/testing/sysfs-kernel-boot_params +++ b/Documentation/ABI/testing/sysfs-kernel-boot_params @@ -23,16 +23,17 @@ Description: The /sys/kernel/boot_params directory contains two representation of setup_data type. "data" file is the binary representation of setup_data payload. - The whole boot_params directory structure is like below: - /sys/kernel/boot_params - |__ data - |__ setup_data - | |__ 0 - | | |__ data - | | |__ type - | |__ 1 - | |__ data - | |__ type - |__ version + The whole boot_params directory structure is like below:: + + /sys/kernel/boot_params + |__ data + |__ setup_data + | |__ 0 + | | |__ data + | | |__ type + | |__ 1 + | |__ data + | |__ type + |__ version Users: Kexec diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages index fdaa2162fae1..294387e2c7fb 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages +++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages @@ -7,9 +7,11 @@ Description: of the hugepages supported by the kernel/CPU combination. Under these directories are a number of files: - nr_hugepages - nr_overcommit_hugepages - free_hugepages - surplus_hugepages - resv_hugepages + + - nr_hugepages + - nr_overcommit_hugepages + - free_hugepages + - surplus_hugepages + - resv_hugepages + See Documentation/admin-guide/mm/hugetlbpage.rst for details. diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm index dfc13244cda3..1c9bed5595f5 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-ksm +++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm @@ -34,8 +34,9 @@ Description: Kernel Samepage Merging daemon sysfs interface in a tree. run: write 0 to disable ksm, read 0 while ksm is disabled. - write 1 to run ksm, read 1 while ksm is running. - write 2 to disable ksm and unmerge all its pages. + + - write 1 to run ksm, read 1 while ksm is running. + - write 2 to disable ksm and unmerge all its pages. sleep_millisecs: how many milliseconds ksm should sleep between scans. diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab index ed35833ad7f0..c9f12baf8baa 100644 --- a/Documentation/ABI/testing/sysfs-kernel-slab +++ b/Documentation/ABI/testing/sysfs-kernel-slab @@ -346,6 +346,7 @@ Description: number of objects per slab. If a slab cannot be allocated because of fragmentation, SLUB will retry with the minimum order possible depending on its characteristics. + When debug_guardpage_minorder=N (N > 0) parameter is specified (see Documentation/admin-guide/kernel-parameters.rst), the minimum possible order is used and this sysfs entry can not be used to change @@ -361,6 +362,7 @@ Description: new slab has not been possible at the cache's order and instead fallen back to its minimum possible order. It can be written to clear the current count. + Available when CONFIG_SLUB_STATS is enabled. What: /sys/kernel/slab/cache/partial @@ -410,6 +412,7 @@ Description: slab from a remote node as opposed to allocating a new slab on the local node. This reduces the amount of wasted memory over the entire system but can be expensive. + Available when CONFIG_NUMA is enabled. What: /sys/kernel/slab/cache/sanity_checks diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module index 0aac02e7fb0e..353c0db5bc1f 100644 --- a/Documentation/ABI/testing/sysfs-module +++ b/Documentation/ABI/testing/sysfs-module @@ -17,14 +17,15 @@ KernelVersion: 3.1 Contact: Kirill Smelkov <kirr@mns.spb.ru> Description: Maximum time allowed for periodic transfers per microframe (μs) - [ USB 2.0 sets maximum allowed time for periodic transfers per + Note: + USB 2.0 sets maximum allowed time for periodic transfers per microframe to be 80%, that is 100 microseconds out of 125 microseconds (full microframe). However there are cases, when 80% max isochronous bandwidth is too limiting. For example two video streams could require 110 microseconds of isochronous bandwidth per microframe to work - together. ] + together. Through this setting it is possible to raise the limit so that the host controller would allow allocating more than 100 @@ -45,8 +46,10 @@ Date: Jan 2012 KernelVersion:»·3.3 Contact: Kay Sievers <kay.sievers@vrfy.org> Description: Module taint flags: - P - proprietary module - O - out-of-tree module - F - force-loaded module - C - staging driver module - E - unsigned module + == ===================== + P proprietary module + O out-of-tree module + F force-loaded module + C staging driver module + E unsigned module + == ===================== diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop index 8b0e8205a6a2..c78d358dbdbe 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop @@ -4,13 +4,16 @@ KernelVersion: 2.6.20 Contact: "Corentin Chary" <corentincj@iksaif.net> Description: This file allows display switching. The value - is composed by 4 bits and defined as follow: - 4321 - |||`- LCD - ||`-- CRT - |`--- TV - `---- DVI - Ex: - 0 (0000b) means no display + is composed by 4 bits and defined as follow:: + + 4321 + |||`- LCD + ||`-- CRT + |`--- TV + `---- DVI + + Ex: + - 0 (0000b) means no display - 3 (0011b) CRT+LCD. What: /sys/devices/platform/asus_laptop/gps @@ -28,8 +31,10 @@ Contact: "Corentin Chary" <corentincj@iksaif.net> Description: Some models like the W1N have a LED display that can be used to display several items of information. - To control the LED display, use the following : + To control the LED display, use the following:: + echo 0x0T000DDD > /sys/devices/platform/asus_laptop/ + where T control the 3 letters display, and DDD the 3 digits display. The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index 1efac0ddb417..04885738cf15 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -5,6 +5,7 @@ Contact: "Corentin Chary" <corentincj@iksaif.net> Description: Change CPU clock configuration (write-only). There are three available clock configuration: + * 0 -> Super Performance Mode * 1 -> High Performance Mode * 2 -> Power Saving Mode diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91 index 4cc6a865ae66..b146be74b8e0 100644 --- a/Documentation/ABI/testing/sysfs-platform-at91 +++ b/Documentation/ABI/testing/sysfs-platform-at91 @@ -18,8 +18,10 @@ Description: In order to use an extended can_id add the CAN_EFF_FLAG (0x80000000U) to the can_id. Example: - - standard id 0x7ff: - echo 0x7ff > /sys/class/net/can0/mb0_id + - standard id 0x7ff:: - - extended id 0x1fffffff: - echo 0x9fffffff > /sys/class/net/can0/mb0_id + echo 0x7ff > /sys/class/net/can0/mb0_id + + - extended id 0x1fffffff:: + + echo 0x9fffffff > /sys/class/net/can0/mb0_id diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop index 9b917c7453de..82bcfe9df66e 100644 --- a/Documentation/ABI/testing/sysfs-platform-dell-laptop +++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop @@ -34,9 +34,12 @@ Description: this file. To disable a trigger, write its name preceded by '-' instead. - For example, to enable the keyboard as trigger run: + For example, to enable the keyboard as trigger run:: + echo +keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers - To disable it: + + To disable it:: + echo -keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers Note that not all the available triggers can be configured. @@ -57,7 +60,8 @@ Description: with any the above units. If no unit is specified, the value is assumed to be expressed in seconds. - For example, to set the timeout to 10 minutes run: + For example, to set the timeout to 10 minutes run:: + echo 10m > /sys/class/leds/dell::kbd_backlight/stop_timeout Note that when this file is read, the returned value might be diff --git a/Documentation/ABI/testing/sysfs-platform-dell-smbios b/Documentation/ABI/testing/sysfs-platform-dell-smbios index 205d3b6361e0..e6e0f7f834a7 100644 --- a/Documentation/ABI/testing/sysfs-platform-dell-smbios +++ b/Documentation/ABI/testing/sysfs-platform-dell-smbios @@ -13,8 +13,8 @@ Description: For example the token ID "5" would be available as the following attributes: - 0005_location - 0005_value + - 0005_location + - 0005_value Tokens will vary from machine to machine, and only tokens available on that machine will be diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme index 3683cb1cdc3d..d6ab34e81b9b 100644 --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme @@ -113,8 +113,11 @@ KernelVersion: 5.5 Contact: Wu Hao <hao.wu@intel.com> Description: Read-Only. Read this file to get the name of hwmon device, it supports values: - 'dfl_fme_thermal' - thermal hwmon device name - 'dfl_fme_power' - power hwmon device name + + ================= ========================= + 'dfl_fme_thermal' thermal hwmon device name + 'dfl_fme_power' power hwmon device name + ================= ========================= What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input Date: October 2019 @@ -169,8 +172,11 @@ KernelVersion: 5.5 Contact: Wu Hao <hao.wu@intel.com> Description: Read-Only. Read this file to get the policy of hardware threshold1 (see 'temp1_max'). It only supports two values (policies): - 0 - AP2 state (90% throttling) - 1 - AP1 state (50% throttling) + + == ========================== + 0 AP2 state (90% throttling) + 1 AP1 state (50% throttling) + == ========================== What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input Date: October 2019 diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf index 2cbc660d163b..141834342a4d 100644 --- a/Documentation/ABI/testing/sysfs-platform-dptf +++ b/Documentation/ABI/testing/sysfs-platform-dptf @@ -27,12 +27,15 @@ KernelVersion: v4.10 Contact: linux-acpi@vger.kernel.org Description: (RO) Display the platform power source + + ========= ============================ bits[3:0] Current power source - 0x00 = DC - 0x01 = AC - 0x02 = USB - 0x03 = Wireless Charger + - 0x00 = DC + - 0x01 = AC + - 0x02 = USB + - 0x03 = Wireless Charger bits[7:4] Power source sequence number + ========= ============================ What: /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power Date: Jul, 2016 diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop index 5b026c69587a..70dbe0733cf6 100644 --- a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop +++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop @@ -4,9 +4,11 @@ KernelVersion: 2.6.26 Contact: "Corentin Chary" <corentincj@iksaif.net> Description: This file allows display switching. + - 1 = LCD - 2 = CRT - 3 = LCD+CRT + If you run X11, you should use xrandr instead. What: /sys/devices/platform/eeepc/camera @@ -30,16 +32,20 @@ Contact: "Corentin Chary" <corentincj@iksaif.net> Description: Change CPU clock configuration. On the Eee PC 1000H there are three available clock configuration: + * 0 -> Super Performance Mode * 1 -> High Performance Mode * 2 -> Power Saving Mode + On Eee PC 701 there is only 2 available clock configurations. Available configuration are listed in available_cpufv file. Reading this file will show the raw hexadecimal value which - is defined as follow: - | 8 bit | 8 bit | - | `---- Current mode - `------------ Availables modes + is defined as follow:: + + | 8 bit | 8 bit | + | `---- Current mode + `------------ Availables modes + For example, 0x301 means: mode 1 selected, 3 available modes. What: /sys/devices/platform/eeepc/available_cpufv diff --git a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl index c394b808be19..b6a138b50d99 100644 --- a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl +++ b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl @@ -5,9 +5,9 @@ Contact: Wolfram Sang <wsa+renesas@sang-engineering.com> Description: Reading the file will give you a list of masters which can be selected for a demultiplexed bus. The format is - "<index>:<name>". Example from a Renesas Lager board: + "<index>:<name>". Example from a Renesas Lager board:: - 0:/i2c@e6500000 1:/i2c@e6508000 + 0:/i2c@e6500000 1:/i2c@e6508000 What: /sys/devices/platform/<i2c-demux-name>/current_master Date: January 2016 diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop index 1b31be3f996a..fd2ac02bc5bd 100644 --- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop @@ -12,6 +12,7 @@ Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" Description: Change fan mode There are four available modes: + * 0 -> Super Silent Mode * 1 -> Standard Mode * 2 -> Dust Cleaning @@ -32,9 +33,11 @@ KernelVersion: 4.18 Contact: "Oleg Keri <ezhi99@gmail.com>" Description: Control fn-lock mode. + * 1 -> Switched On * 0 -> Switched Off - For example: - # echo "0" > \ - /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock + For example:: + + # echo "0" > \ + /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update index 5aa618987cad..02ae1e9bbfc8 100644 --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update @@ -8,5 +8,6 @@ Description: of 0 and userspace can signal SBL to update firmware, on next reboot, by writing a value of 1. There are two available states: + * 0 -> Skip firmware update while rebooting * 1 -> Attempt firmware update on next reboot diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt index 8af65059d519..e19144fd5d86 100644 --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt @@ -7,5 +7,6 @@ Description: Thunderbolt controllers to turn on or off when no devices are connected (write-only) There are two available states: + * 0 -> Force power disabled * 1 -> Force power enabled diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim index c1653271872a..a7f81de68046 100644 --- a/Documentation/ABI/testing/sysfs-platform-kim +++ b/Documentation/ABI/testing/sysfs-platform-kim @@ -5,6 +5,7 @@ Contact: "Pavan Savoy" <pavan_savoy@ti.com> Description: Name of the UART device at which the WL128x chip is connected. example: "/dev/ttyS0". + The device name flows down to architecture specific board initialization file from the SFI/ATAGS bootloader firmware. The name exposed is read from the user-space diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl index 401d202f478b..e79ca22e2f45 100644 --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl @@ -5,10 +5,13 @@ Contact: "Liming Sun <lsun@mellanox.com>" Description: The Life-cycle state of the SoC, which could be one of the following values. - Production - Production state and can be updated to secure - GA Secured - Secure chip and not able to change state - GA Non-Secured - Non-Secure chip and not able to change state - RMA - Return Merchandise Authorization + + ============== ============================================= + Production Production state and can be updated to secure + GA Secured Secure chip and not able to change state + GA Non-Secured Non-Secure chip and not able to change state + RMA Return Merchandise Authorization + ============== ============================================= What: /sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog Date: Oct 2019 @@ -25,10 +28,13 @@ KernelVersion: 5.5 Contact: "Liming Sun <lsun@mellanox.com>" Description: The source of the boot stream for the next reset. It could be - one of the following values. - external - boot from external source (USB or PCIe) - emmc - boot from the onchip eMMC - emmc_legacy - boot from the onchip eMMC in legacy (slow) mode + one of the following values: + + =========== =============================================== + external boot from external source (USB or PCIe) + emmc boot from the onchip eMMC + emmc_legacy boot from the onchip eMMC in legacy (slow) mode + =========== =============================================== What: /sys/bus/platform/devices/MLNXBF04:00/second_reset_action Date: Oct 2019 @@ -38,11 +44,14 @@ Description: Update the source of the boot stream after next reset. It could be one of the following values and will be applied after next reset. - external - boot from external source (USB or PCIe) - emmc - boot from the onchip eMMC - emmc_legacy - boot from the onchip eMMC in legacy (slow) mode - swap_emmc - swap the primary / secondary boot partition - none - cancel the action + + =========== =============================================== + external boot from external source (USB or PCIe) + emmc boot from the onchip eMMC + emmc_legacy boot from the onchip eMMC in legacy (slow) mode + swap_emmc swap the primary / secondary boot partition + none cancel the action + =========== =============================================== What: /sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state Date: Oct 2019 @@ -50,9 +59,12 @@ KernelVersion: 5.5 Contact: "Liming Sun <lsun@mellanox.com>" Description: The state of eFuse versions with the following values. - InUse - burnt, valid and currently in use - Used - burnt and valid - Free - not burnt and free to use - Skipped - not burnt but not free (skipped) - Wasted - burnt and invalid - Invalid - not burnt but marked as valid (error state). + + ======= =============================================== + InUse burnt, valid and currently in use + Used burnt and valid + Free not burnt and free to use + Skipped not burnt but not free (skipped) + Wasted burnt and invalid + Invalid not burnt but marked as valid (error state). + ======= =============================================== diff --git a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 index 6212697bbf6f..bc510ccc37a7 100644 --- a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 +++ b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 @@ -7,9 +7,11 @@ Description: The file can show/change the phy mode for role swap of usb. Write the following strings to change the mode: - "host" - switching mode from peripheral to host. - "peripheral" - switching mode from host to peripheral. + + - "host" - switching mode from peripheral to host. + - "peripheral" - switching mode from host to peripheral. Read the file, then it shows the following strings: - "host" - The mode is host now. - "peripheral" - The mode is peripheral now. + + - "host" - The mode is host now. + - "peripheral" - The mode is peripheral now. diff --git a/Documentation/ABI/testing/sysfs-platform-renesas_usb3 b/Documentation/ABI/testing/sysfs-platform-renesas_usb3 index 5621c15d5dc0..8af5b9c3fabb 100644 --- a/Documentation/ABI/testing/sysfs-platform-renesas_usb3 +++ b/Documentation/ABI/testing/sysfs-platform-renesas_usb3 @@ -7,9 +7,11 @@ Description: The file can show/change the drd mode of usb. Write the following string to change the mode: - "host" - switching mode from peripheral to host. - "peripheral" - switching mode from host to peripheral. + + - "host" - switching mode from peripheral to host. + - "peripheral" - switching mode from host to peripheral. Read the file, then it shows the following strings: - "host" - The mode is host now. - "peripheral" - The mode is peripheral now. + + - "host" - The mode is host now. + - "peripheral" - The mode is peripheral now. diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom index 0d07c0395660..d5f6e21f0e42 100644 --- a/Documentation/ABI/testing/sysfs-platform-sst-atom +++ b/Documentation/ABI/testing/sysfs-platform-sst-atom @@ -5,13 +5,22 @@ Contact: "Sebastien Guiriec" <sebastien.guiriec@intel.com> Description: LPE Firmware version for SST driver on all atom plaforms (BYT/CHT/Merrifield/BSW). - If the FW has never been loaded it will display: + If the FW has never been loaded it will display:: + "FW not yet loaded" - If FW has been loaded it will display: + + If FW has been loaded it will display:: + "v01.aa.bb.cc" + aa: Major version is reflecting SoC version: + + === ============= 0d: BYT FW 0b: BSW FW 07: Merrifield FW + === ============= + bb: Minor version + cc: Build version diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc index 81fcfb454913..53622d3ba27c 100644 --- a/Documentation/ABI/testing/sysfs-platform-usbip-vudc +++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc @@ -16,10 +16,13 @@ Contact: Krzysztof Opasiak <k.opasiak@samsung.com> Description: Current status of the device. Allowed values: - 1 - Device is available and can be exported - 2 - Device is currently exported - 3 - Fatal error occurred during communication - with peer + + == ========================================== + 1 Device is available and can be exported + 2 Device is currently exported + 3 Fatal error occurred during communication + with peer + == ========================================== What: /sys/devices/platform/usbip-vudc.%d/usbip_sockfd Date: April 2016 diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec index 5f60b184a5a5..4439d0644091 100644 --- a/Documentation/ABI/testing/sysfs-platform-wilco-ec +++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec @@ -39,6 +39,7 @@ Description: which affects charging via the special USB PowerShare port (marked with a small lightning bolt or battery icon) when in low power states: + - In S0, the port will always provide power. - In S0ix, if usb_charge is enabled, then power will be supplied to the port when on AC or if battery is > 50%. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 5e6ead29124c..51c0f578bfce 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -47,14 +47,18 @@ Description: suspend-to-disk mechanism. Reading from this file returns the name of the method by which the system will be put to sleep on the next suspend. There are four methods supported: + 'firmware' - means that the memory image will be saved to disk by some firmware, in which case we also assume that the firmware will handle the system suspend. + 'platform' - the memory image will be saved by the kernel and the system will be put to sleep by the platform driver (e.g. ACPI or other PM registers). + 'shutdown' - the memory image will be saved by the kernel and the system will be powered off. + 'reboot' - the memory image will be saved by the kernel and the system will be rebooted. @@ -74,12 +78,12 @@ Description: The suspend-to-disk method may be chosen by writing to this file one of the accepted strings: - 'firmware' - 'platform' - 'shutdown' - 'reboot' - 'testproc' - 'test' + - 'firmware' + - 'platform' + - 'shutdown' + - 'reboot' + - 'testproc' + - 'test' It will only change to 'firmware' or 'platform' if the system supports that. @@ -114,9 +118,9 @@ Description: string representing a nonzero integer into it. To use this debugging feature you should attempt to suspend - the machine, then reboot it and run + the machine, then reboot it and run:: - dmesg -s 1000000 | grep 'hash matches' + dmesg -s 1000000 | grep 'hash matches' If you do not get any matches (or they appear to be false positives), it is possible that the last PM event point @@ -244,6 +248,7 @@ Description: wakeup sources created with the help of /sys/power/wake_lock. When a string is written to /sys/power/wake_unlock, it will be assumed to represent the name of a wakeup source to deactivate. + If a wakeup source object of that name exists and is active at the moment, it will be deactivated. diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling index 8a8e466eb2c0..e39dd3a0ceef 100644 --- a/Documentation/ABI/testing/sysfs-profiling +++ b/Documentation/ABI/testing/sysfs-profiling @@ -5,7 +5,7 @@ Description: /sys/kernel/profiling is the runtime equivalent of the boot-time profile= option. - You can get the same effect running: + You can get the same effect running:: echo 2 > /sys/kernel/profiling diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp index a17f817a9309..2363ad810ddb 100644 --- a/Documentation/ABI/testing/sysfs-ptp +++ b/Documentation/ABI/testing/sysfs-ptp @@ -69,7 +69,7 @@ Description: pin offered by the PTP hardware clock. The file name is the hardware dependent pin name. Reading from this file produces two numbers, the assigned function (see - the PTP_PF_ enumeration values in linux/ptp_clock.h) + the `PTP_PF_` enumeration values in linux/ptp_clock.h) and the channel number. The function and channel assignment may be changed by two writing numbers into the file. diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent index aa39f8d7bcdf..0b6227706b35 100644 --- a/Documentation/ABI/testing/sysfs-uevent +++ b/Documentation/ABI/testing/sysfs-uevent @@ -6,42 +6,46 @@ Description: Enable passing additional variables for synthetic uevents that are generated by writing /sys/.../uevent file. - Recognized extended format is ACTION [UUID [KEY=VALUE ...]. + Recognized extended format is:: - The ACTION is compulsory - it is the name of the uevent action - ("add", "change", "remove"). There is no change compared to - previous functionality here. The rest of the extended format - is optional. + ACTION [UUID [KEY=VALUE ...] + + The ACTION is compulsory - it is the name of the uevent + action (``add``, ``change``, ``remove``). There is no change + compared to previous functionality here. The rest of the + extended format is optional. You need to pass UUID first before any KEY=VALUE pairs. - The UUID must be in "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + The UUID must be in ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` format where 'x' is a hex digit. The UUID is considered to be a transaction identifier so it's possible to use the same UUID value for one or more synthetic uevents in which case we logically group these uevents together for any userspace listeners. The UUID value appears in uevent as - "SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" environment + ``SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` environment variable. If UUID is not passed in, the generated synthetic uevent gains - "SYNTH_UUID=0" environment variable automatically. + ``SYNTH_UUID=0`` environment variable automatically. The KEY=VALUE pairs can contain alphanumeric characters only. + It's possible to define zero or more pairs - each pair is then delimited by a space character ' '. Each pair appears in - synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY - name gains "SYNTH_ARG_" prefix to avoid possible collisions + synthetic uevent as ``SYNTH_ARG_KEY=VALUE``. That means the KEY + name gains ``SYNTH_ARG_`` prefix to avoid possible collisions with existing variables. - Example of valid sequence written to the uevent file: + Example of valid sequence written to the uevent file:: add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc - This generates synthetic uevent including these variables: + This generates synthetic uevent including these variables:: ACTION=add SYNTH_ARG_A=1 SYNTH_ARG_B=abc SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed + Users: udev, userspace tools generating synthetic uevents diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf index a99c5f86a37a..2969d3694ec0 100644 --- a/Documentation/ABI/testing/sysfs-wusb_cbaf +++ b/Documentation/ABI/testing/sysfs-wusb_cbaf @@ -45,7 +45,8 @@ Description: 7. Device is unplugged. References: - [WUSB-AM] Association Models Supplement to the + [WUSB-AM] + Association Models Supplement to the Certified Wireless Universal Serial Bus Specification, version 1.0. diff --git a/Documentation/ABI/testing/usb-charger-uevent b/Documentation/ABI/testing/usb-charger-uevent index 419a92dd0d86..1db89b0cf80f 100644 --- a/Documentation/ABI/testing/usb-charger-uevent +++ b/Documentation/ABI/testing/usb-charger-uevent @@ -3,44 +3,52 @@ Date: 2020-01-14 KernelVersion: 5.6 Contact: linux-usb@vger.kernel.org Description: There are two USB charger states: - USB_CHARGER_ABSENT - USB_CHARGER_PRESENT + + - USB_CHARGER_ABSENT + - USB_CHARGER_PRESENT + There are five USB charger types: - USB_CHARGER_UNKNOWN_TYPE: Charger type is unknown - USB_CHARGER_SDP_TYPE: Standard Downstream Port - USB_CHARGER_CDP_TYPE: Charging Downstream Port - USB_CHARGER_DCP_TYPE: Dedicated Charging Port - USB_CHARGER_ACA_TYPE: Accessory Charging Adapter + + ======================== ========================== + USB_CHARGER_UNKNOWN_TYPE Charger type is unknown + USB_CHARGER_SDP_TYPE Standard Downstream Port + USB_CHARGER_CDP_TYPE Charging Downstream Port + USB_CHARGER_DCP_TYPE Dedicated Charging Port + USB_CHARGER_ACA_TYPE Accessory Charging Adapter + ======================== ========================== + https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement - Here are two examples taken using udevadm monitor -p when - USB charger is online: - UDEV change /devices/soc0/usbphynop1 (platform) - ACTION=change - DEVPATH=/devices/soc0/usbphynop1 - DRIVER=usb_phy_generic - MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv - OF_COMPATIBLE_0=usb-nop-xceiv - OF_COMPATIBLE_N=1 - OF_FULLNAME=/usbphynop1 - OF_NAME=usbphynop1 - SEQNUM=2493 - SUBSYSTEM=platform - USB_CHARGER_STATE=USB_CHARGER_PRESENT - USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE - USEC_INITIALIZED=227422826 - - USB charger is offline: - KERNEL change /devices/soc0/usbphynop1 (platform) - ACTION=change - DEVPATH=/devices/soc0/usbphynop1 - DRIVER=usb_phy_generic - MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv - OF_COMPATIBLE_0=usb-nop-xceiv - OF_COMPATIBLE_N=1 - OF_FULLNAME=/usbphynop1 - OF_NAME=usbphynop1 - SEQNUM=2494 - SUBSYSTEM=platform - USB_CHARGER_STATE=USB_CHARGER_ABSENT - USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE + Here are two examples taken using ``udevadm monitor -p`` when + USB charger is online:: + + UDEV change /devices/soc0/usbphynop1 (platform) + ACTION=change + DEVPATH=/devices/soc0/usbphynop1 + DRIVER=usb_phy_generic + MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv + OF_COMPATIBLE_0=usb-nop-xceiv + OF_COMPATIBLE_N=1 + OF_FULLNAME=/usbphynop1 + OF_NAME=usbphynop1 + SEQNUM=2493 + SUBSYSTEM=platform + USB_CHARGER_STATE=USB_CHARGER_PRESENT + USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE + USEC_INITIALIZED=227422826 + + USB charger is offline:: + + KERNEL change /devices/soc0/usbphynop1 (platform) + ACTION=change + DEVPATH=/devices/soc0/usbphynop1 + DRIVER=usb_phy_generic + MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv + OF_COMPATIBLE_0=usb-nop-xceiv + OF_COMPATIBLE_N=1 + OF_FULLNAME=/usbphynop1 + OF_NAME=usbphynop1 + SEQNUM=2494 + SUBSYSTEM=platform + USB_CHARGER_STATE=USB_CHARGER_ABSENT + USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE diff --git a/Documentation/ABI/testing/usb-uevent b/Documentation/ABI/testing/usb-uevent index d35c3cad892c..2b8eca4bf2b1 100644 --- a/Documentation/ABI/testing/usb-uevent +++ b/Documentation/ABI/testing/usb-uevent @@ -6,22 +6,22 @@ Description: When the USB Host Controller has entered a state where it is no longer functional a uevent will be raised. The uevent will contain ACTION=offline and ERROR=DEAD. - Here is an example taken using udevadm monitor -p: + Here is an example taken using udevadm monitor -p:: - KERNEL[130.428945] offline /devices/pci0000:00/0000:00:10.0/usb2 (usb) - ACTION=offline - BUSNUM=002 - DEVNAME=/dev/bus/usb/002/001 - DEVNUM=001 - DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2 - DEVTYPE=usb_device - DRIVER=usb - ERROR=DEAD - MAJOR=189 - MINOR=128 - PRODUCT=1d6b/2/414 - SEQNUM=2168 - SUBSYSTEM=usb - TYPE=9/0/1 + KERNEL[130.428945] offline /devices/pci0000:00/0000:00:10.0/usb2 (usb) + ACTION=offline + BUSNUM=002 + DEVNAME=/dev/bus/usb/002/001 + DEVNUM=001 + DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2 + DEVTYPE=usb_device + DRIVER=usb + ERROR=DEAD + MAJOR=189 + MINOR=128 + PRODUCT=1d6b/2/414 + SEQNUM=2168 + SUBSYSTEM=usb + TYPE=9/0/1 Users: chromium-os-dev@chromium.org diff --git a/Documentation/Kconfig b/Documentation/Kconfig index 66046fa1c341..e549a61f4d96 100644 --- a/Documentation/Kconfig +++ b/Documentation/Kconfig @@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS If unsure, select 'N'. +config WARN_ABI_ERRORS + bool "Warn if there are errors at ABI files" + depends on COMPILE_TEST + help + The files under Documentation/ABI should follow what's + described at Documentation/ABI/README. Yet, as they're manually + written, it would be possible that some of those files would + have errors that would break them for being parsed by + scripts/get_abi.pl. Add a check to verify them. + If unsure, select 'N'. diff --git a/Documentation/Makefile b/Documentation/Makefile index 6b12dd82f712..61a7310b49e0 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -10,6 +10,11 @@ ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) $(shell $(srctree)/scripts/documentation-file-ref-check --warn) endif +# Check for broken ABI files +ifeq ($(CONFIG_WARN_ABI_ERRORS),y) +$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI) +endif + # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS = @@ -21,6 +26,10 @@ BUILDDIR = $(obj)/output PDFLATEX = xelatex LATEXOPTS = -interaction=batchmode +ifeq ($(KBUILD_VERBOSE),0) +SPHINXOPTS += "-q" +endif + # User-friendly check for sphinx-build HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 17996c9070e2..0ec34863c674 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -107,7 +107,7 @@ for a UID/GID will prevent that UID/GID from obtaining auxiliary setid privileges, such as allowing a user to set up user namespace UID/GID mappings. Note on GID policies and setgroups() -================== +==================================== In v5.9 we are adding support for limiting CAP_SETGID privileges as was done previously for CAP_SETUID. However, for compatibility with common sandboxing related code conventions in userspace, we currently allow arbitrary diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst new file mode 100644 index 000000000000..d095867899c5 --- /dev/null +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -0,0 +1,11 @@ +ABI obsolete symbols +==================== + +Documents interfaces that are still remaining in the kernel, but are +marked to be removed at some later point in time. + +The description of the interface will document the reason why it is +obsolete and when it can be expected to be removed. + +.. kernel-abi:: $srctree/Documentation/ABI/obsolete + :rst: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst new file mode 100644 index 000000000000..f7e9e43023c1 --- /dev/null +++ b/Documentation/admin-guide/abi-removed.rst @@ -0,0 +1,5 @@ +ABI removed symbols +=================== + +.. kernel-abi:: $srctree/Documentation/ABI/removed + :rst: diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst new file mode 100644 index 000000000000..70490736e0d3 --- /dev/null +++ b/Documentation/admin-guide/abi-stable.rst @@ -0,0 +1,14 @@ +ABI stable symbols +================== + +Documents the interfaces that the developer has defined to be stable. + +Userspace programs are free to use these interfaces with no +restrictions, and backward compatibility for them will be guaranteed +for at least 2 years. + +Most interfaces (like syscalls) are expected to never change and always +be available. + +.. kernel-abi:: $srctree/Documentation/ABI/stable + :rst: diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst new file mode 100644 index 000000000000..b205b16a72d0 --- /dev/null +++ b/Documentation/admin-guide/abi-testing.rst @@ -0,0 +1,20 @@ +ABI testing symbols +=================== + +Documents interfaces that are felt to be stable, +as the main development of this interface has been completed. + +The interface can be changed to add new features, but the +current interface will not break by doing this, unless grave +errors or security problems are found in them. + +Userspace programs can start to rely on these interfaces, but they must +be aware of changes that can occur before these interfaces move to +be marked stable. + +Programs that use these interfaces are strongly encouraged to add their +name to the description of these interfaces, so that the kernel +developers can easily notify them if any changes occur. + +.. kernel-abi:: $srctree/Documentation/ABI/testing + :rst: diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst new file mode 100644 index 000000000000..bcab3ef2597c --- /dev/null +++ b/Documentation/admin-guide/abi.rst @@ -0,0 +1,11 @@ +===================== +Linux ABI description +===================== + +.. toctree:: + :maxdepth: 2 + + abi-stable + abi-testing + abi-obsolete + abi-removed diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index a22024f9175e..9b90efcc3a35 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -137,15 +137,24 @@ Boot Kernel With a Boot Config ============================== Since the boot configuration file is loaded with initrd, it will be added -to the end of the initrd (initramfs) image file with size, checksum and -12-byte magic word as below. +to the end of the initrd (initramfs) image file with padding, size, +checksum and 12-byte magic word as below. -[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n] +[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +The size and checksum fields are unsigned 32bit little endian value. + +When the boot configuration is added to the initrd image, the total +file size is aligned to 4 bytes. To fill the gap, null characters +(``\0``) will be added. Thus the ``size`` is the length of the bootconfig +file + padding bytes. The Linux kernel decodes the last part of the initrd image in memory to get the boot configuration data. Because of this "piggyback" method, there is no need to change or -update the boot loader and the kernel image itself. +update the boot loader and the kernel image itself as long as the boot +loader passes the correct initrd file size. If by any chance, the boot +loader passes a longer size, the kernel feils to find the bootconfig data. To do this operation, Linux kernel provides "bootconfig" command under tools/bootconfig, which allows admin to apply or delete the config file @@ -176,7 +185,8 @@ up to 512 key-value pairs. If keys contains 3 words in average, it can contain 256 key-value pairs. In most cases, the number of config items will be under 100 entries and smaller than 8KB, so it would be enough. If the node number exceeds 1024, parser returns an error even if the file -size is smaller than 32KB. +size is smaller than 32KB. (Note that this maximum size is not including +the padding null characters.) Anyway, since bootconfig command verifies it when appending a boot config to initrd image, user can notice it before boot. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index ed1cf94ea50c..4e0c4ae44acd 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -18,6 +18,8 @@ etc. devices sysctl/index + abi + This section describes CPU vulnerabilities and their mitigations. .. toctree:: diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 526d65d8573a..a7d60d847584 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2858,6 +2858,8 @@ mds=off [X86] tsx_async_abort=off [X86] kvm.nx_huge_pages=off [X86] + no_entry_flush [PPC] + no_uaccess_flush [PPC] Exceptions: This does not have any effect on @@ -3186,6 +3188,8 @@ noefi Disable EFI runtime services support. + no_entry_flush [PPC] Don't flush the L1-D cache when entering the kernel. + noexec [IA-64] noexec [X86] @@ -3235,6 +3239,9 @@ nospec_store_bypass_disable [HW] Disable all mitigations for the Speculative Store Bypass vulnerability + no_uaccess_flush + [PPC] Don't flush the L1-D cache after accessing user data. + noxsave [BUGS=X86] Disables x86 extended register state save and restore using xsave. The kernel will fallback to enabling legacy floating-point and sse state. @@ -3368,6 +3375,8 @@ nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. + nosgx [X86-64,SGX] Disables Intel SGX kernel support. + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, and disable the IO APIC. legacy for "maxcpus=0". diff --git a/Documentation/admin-guide/media/rkisp1.rst b/Documentation/admin-guide/media/rkisp1.rst index 42e37ed255f6..2267e4fb475e 100644 --- a/Documentation/admin-guide/media/rkisp1.rst +++ b/Documentation/admin-guide/media/rkisp1.rst @@ -86,7 +86,7 @@ the driver through the rkisp_params node to improve image quality during a video stream. The buffer format is defined by struct :c:type:`rkisp1_stat_buffer`, and userspace should set -:ref:`V4L2_META_FMT_RK_ISP1_STAT_3A <v4l2-meta-fmt-stat-rkisp1>` as the +:ref:`V4L2_META_FMT_RK_ISP1_STAT_3A <v4l2-meta-fmt-rk-isp1-stat-3a>` as the dataformat. .. _rkisp1_params: @@ -100,7 +100,7 @@ and others. The buffer format is defined by struct :c:type:`rkisp1_params_cfg`, and userspace should set -:ref:`V4L2_META_FMT_RK_ISP1_PARAMS <v4l2-meta-fmt-params-rkisp1>` as the +:ref:`V4L2_META_FMT_RK_ISP1_PARAMS <v4l2-meta-fmt-rk-isp1-params>` as the dataformat. diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index 37940a0584ec..10fde58d0869 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -478,7 +478,7 @@ order to ask the hardware to enter that state. Also, for each statistics of the given idle state. That information is exposed by the kernel via ``sysfs``. -For each CPU in the system, there is a :file:`/sys/devices/system/cpu<N>/cpuidle/` +For each CPU in the system, there is a :file:`/sys/devices/system/cpu/cpu<N>/cpuidle/` directory in ``sysfs``, where the number ``<N>`` is assigned to the given CPU at the initialization time. That directory contains a set of subdirectories called :file:`state0`, :file:`state1` and so on, up to the number of idle state @@ -494,7 +494,7 @@ object corresponding to it, as follows: residency. ``below`` - Total number of times this idle state had been asked for, but cerainly + Total number of times this idle state had been asked for, but certainly a deeper idle state would have been a better match for the observed idle duration. diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 57fd6ce68fe0..f2ab8a5b6a4b 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -300,6 +300,7 @@ Note: 0: 0 1 2 3 4 5 6 7 RSS hash key: 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 + netdev_tstamp_prequeue ---------------------- diff --git a/Documentation/arm/sunxi.rst b/Documentation/arm/sunxi.rst index 62b533d0ba94..0c536ae1d7c2 100644 --- a/Documentation/arm/sunxi.rst +++ b/Documentation/arm/sunxi.rst @@ -148,3 +148,13 @@ SunXi family * User Manual http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf + + - Allwinner H6 + + * Datasheet + + https://linux-sunxi.org/images/5/5c/Allwinner_H6_V200_Datasheet_V1.1.pdf + + * User Manual + + https://linux-sunxi.org/images/4/46/Allwinner_H6_V200_User_Manual_V1.1.pdf diff --git a/Documentation/arm64/memory-tagging-extension.rst b/Documentation/arm64/memory-tagging-extension.rst index 034d37c605e8..b540178a93f8 100644 --- a/Documentation/arm64/memory-tagging-extension.rst +++ b/Documentation/arm64/memory-tagging-extension.rst @@ -102,7 +102,9 @@ applications. system call) are not checked if the user thread tag checking mode is ``PR_MTE_TCF_NONE`` or ``PR_MTE_TCF_ASYNC``. If the tag checking mode is ``PR_MTE_TCF_SYNC``, the kernel makes a best effort to check its user -address accesses, however it cannot always guarantee it. +address accesses, however it cannot always guarantee it. Kernel accesses +to user addresses are always performed with an effective ``PSTATE.TCO`` +value of zero, regardless of the user configuration. Excluding Tags in the ``IRG``, ``ADDG`` and ``SUBG`` instructions ----------------------------------------------------------------- diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index d3587805de64..719510247292 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -90,6 +90,8 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A76 | #1463225 | ARM64_ERRATUM_1463225 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A77 | #1508412 | ARM64_ERRATUM_1508412 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1349291 | N/A | diff --git a/Documentation/conf.py b/Documentation/conf.py index 376dd0ddf39c..ed2b43ec7754 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -38,7 +38,8 @@ needs_sphinx = '1.3' # ones. extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', - 'maintainers_include', 'sphinx.ext.autosectionlabel' ] + 'maintainers_include', 'sphinx.ext.autosectionlabel', + 'kernel_abi'] # # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* @@ -50,7 +51,7 @@ if major >= 3: support for Sphinx v3.0 and above is brand new. Be prepared for possible issues in the generated output. ''') - if minor > 0 or patch >= 2: + if (major > 3) or (minor > 0 or patch >= 2): # Sphinx c function parser is more pedantic with regards to type # checking. Due to that, having macros at c:function cause problems. # Those needed to be scaped by using c_id_attributes[] array diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index c09c9ca2ff1c..2b68addaadcd 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -295,11 +295,13 @@ print the number of the test and the status of the test: pass:: ok 28 - kmalloc_double_kzfree + or, if kmalloc failed:: # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 Expected ptr is not null, but is not ok 4 - kmalloc_large_oob_right + or, if a KASAN report was expected, but not found:: # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629 diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 1628862e7024..8d5029ad210a 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -90,7 +90,7 @@ things to try. re-run kunit_tool. 5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This may help clean up any residual config items which could be causing problems. -6. Finally, try running KUnit outside UML. KUnit and KUnit tests can run be +6. Finally, try running KUnit outside UML. KUnit and KUnit tests can be built into any kernel, or can be built as a module and loaded at runtime. Doing so should allow you to determine if UML is causing the issue you're seeing. When tests are built-in, they will execute when the kernel boots, and diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index d23385e3e159..454f307813ea 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -197,7 +197,7 @@ Now add the following to ``drivers/misc/Kconfig``: config MISC_EXAMPLE_TEST bool "Test for my example" - depends on MISC_EXAMPLE && KUNIT + depends on MISC_EXAMPLE && KUNIT=y and the following to ``drivers/misc/Makefile``: diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index da1d6f0ed6bc..8dbcdc552606 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -175,17 +175,17 @@ An example Kconfig entry: .. code-block:: none - config FOO_KUNIT_TEST - tristate "KUnit test for foo" if !KUNIT_ALL_TESTS - depends on KUNIT - default KUNIT_ALL_TESTS - help - This builds unit tests for foo. + config FOO_KUNIT_TEST + tristate "KUnit test for foo" if !KUNIT_ALL_TESTS + depends on KUNIT + default KUNIT_ALL_TESTS + help + This builds unit tests for foo. - For more information on KUnit and unit tests in general, please refer - to the KUnit documentation in Documentation/dev-tools/kunit + For more information on KUnit and unit tests in general, please refer + to the KUnit documentation in Documentation/dev-tools/kunit/. - If unsure, say N + If unsure, say N. Test File and Module Names diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 961d3ea3ca19..9c28c518e6a3 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -92,7 +92,7 @@ behavior of a function called ``add``; the first parameter is always of type the second parameter, in this case, is what the value is expected to be; the last value is what the value actually is. If ``add`` passes all of these expectations, the test case, ``add_test_basic`` will pass; if any one of these -expectations fail, the test case will fail. +expectations fails, the test case will fail. It is important to understand that a test case *fails* when any expectation is violated; however, the test will continue running, potentially trying other @@ -202,7 +202,7 @@ Example: kunit_test_suite(example_test_suite); In the above example the test suite, ``example_test_suite``, would run the test -cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``, +cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``; each would have ``example_test_init`` called immediately before it and would have ``example_test_exit`` called immediately after it. ``kunit_test_suite(example_test_suite)`` registers the test suite with the @@ -229,7 +229,7 @@ through some sort of indirection where a function is exposed as part of an API such that the definition of that function can be changed without affecting the rest of the code base. In the kernel this primarily comes from two constructs, classes, structs that contain function pointers that are provided by the -implementer, and architecture specific functions which have definitions selected +implementer, and architecture-specific functions which have definitions selected at compile time. Classes @@ -459,7 +459,7 @@ KUnit on non-UML architectures By default KUnit uses UML as a way to provide dependencies for code under test. Under most circumstances KUnit's usage of UML should be treated as an implementation detail of how KUnit works under the hood. Nevertheless, there -are instances where being able to run architecture specific code or test +are instances where being able to run architecture-specific code or test against real hardware is desirable. For these reasons KUnit supports running on other architectures. @@ -561,6 +561,11 @@ Once the kernel is built and installed, a simple ...will run the tests. +.. note:: + Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig + if the test does not support module build. Otherwise, it will trigger + compile errors if ``CONFIG_KUNIT`` is ``m``. + Writing new tests for other architectures ----------------------------------------- @@ -594,7 +599,7 @@ writing normal KUnit tests. One special caveat is that you have to reset hardware state in between test cases; if this is not possible, you may only be able to run one test case per invocation. -.. TODO(brendanhiggins@google.com): Add an actual example of an architecture +.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- dependent KUnit test. KUnit debugfs representation diff --git a/Documentation/devicetree/bindings/arm/actions.yaml b/Documentation/devicetree/bindings/arm/actions.yaml index fe22c66e9c15..02dc72c97645 100644 --- a/Documentation/devicetree/bindings/arm/actions.yaml +++ b/Documentation/devicetree/bindings/arm/actions.yaml @@ -49,3 +49,5 @@ properties: - enum: - ucrobotics,bubblegum-96 # uCRobotics Bubblegum-96 - const: actions,s900 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/altera.yaml b/Documentation/devicetree/bindings/arm/altera.yaml index 0bc5020b7539..c15c92fdf2ed 100644 --- a/Documentation/devicetree/bindings/arm/altera.yaml +++ b/Documentation/devicetree/bindings/arm/altera.yaml @@ -19,4 +19,7 @@ properties: - altr,socfpga-arria5 - altr,socfpga-arria10 - const: altr,socfpga + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/amazon,al.yaml b/Documentation/devicetree/bindings/arm/amazon,al.yaml index a3a4d710bd02..0f03135d91b6 100644 --- a/Documentation/devicetree/bindings/arm/amazon,al.yaml +++ b/Documentation/devicetree/bindings/arm/amazon,al.yaml @@ -30,4 +30,6 @@ properties: - amazon,al-alpine-v3-evp - const: amazon,al-alpine-v3 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 0ee7c5b7b3f6..3341788d1096 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -173,4 +173,7 @@ properties: - enum: - amlogic,ad401 - const: amlogic,a1 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/arm,integrator.yaml b/Documentation/devicetree/bindings/arm/arm,integrator.yaml index f0daf990e077..528eee64290a 100644 --- a/Documentation/devicetree/bindings/arm/arm,integrator.yaml +++ b/Documentation/devicetree/bindings/arm/arm,integrator.yaml @@ -83,4 +83,6 @@ required: - compatible - core-module@10000000 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/arm,realview.yaml b/Documentation/devicetree/bindings/arm/arm,realview.yaml index 1d0b4e2bc7d2..4f9b21f49e84 100644 --- a/Documentation/devicetree/bindings/arm/arm,realview.yaml +++ b/Documentation/devicetree/bindings/arm/arm,realview.yaml @@ -120,4 +120,6 @@ required: - compatible - soc +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/arm,versatile.yaml b/Documentation/devicetree/bindings/arm/arm,versatile.yaml index 06efd2a075c9..34b437c72751 100644 --- a/Documentation/devicetree/bindings/arm/arm,versatile.yaml +++ b/Documentation/devicetree/bindings/arm/arm,versatile.yaml @@ -68,4 +68,6 @@ required: - compatible - core-module@10000000 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml index 26829a803fda..55ef656d1192 100644 --- a/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml +++ b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml @@ -216,4 +216,6 @@ allOf: required: - arm,hbi +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index 614c91956798..6fc5a22ad962 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -184,4 +184,6 @@ properties: - const: atmel,samv71 - const: atmel,samv7 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/axxia.yaml b/Documentation/devicetree/bindings/arm/axxia.yaml index 3ea5f2fdcd96..e0d2bb71cf50 100644 --- a/Documentation/devicetree/bindings/arm/axxia.yaml +++ b/Documentation/devicetree/bindings/arm/axxia.yaml @@ -18,4 +18,6 @@ properties: - const: lsi,axm5516-amarillo - const: lsi,axm5516 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml b/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml index dd52e29b0642..812ae8cc5959 100644 --- a/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml @@ -51,4 +51,6 @@ properties: - raspberrypi,3-compute-module-lite - const: brcm,bcm2837 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml index 497600a2ffb9..c60324357435 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml @@ -18,4 +18,6 @@ properties: - brcm,bcm28155-ap - const: brcm,bcm11351 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml index e0ee931723dc..b3020757380f 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml @@ -18,4 +18,6 @@ properties: - brcm,bcm21664-garnet - const: brcm,bcm21664 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml index 40d12ea56e54..37f3a6fcde76 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml @@ -18,4 +18,6 @@ properties: - brcm,bcm23550-sparrow - const: brcm,bcm23550 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml index 988e0bbb2a62..434d3c6db61e 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -87,4 +87,7 @@ properties: - const: brcm,brcm53012 - const: brcm,brcm53016 - const: brcm,bcm4708 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml index 9ba7b16e1fc4..432ccf990f9e 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml @@ -26,4 +26,6 @@ properties: - brcm,bcm58305 - const: brcm,cygnus +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml index ae614b6722c2..294948399f82 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml @@ -25,4 +25,6 @@ properties: - const: brcm,bcm53342 - const: brcm,hr2 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml index 0749adf94c28..c4847abbecd8 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml @@ -20,4 +20,6 @@ properties: - brcm,ns2-xmc - const: brcm,ns2 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml index 8c2cacb2bb4f..476bc23a7f75 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml @@ -33,4 +33,6 @@ properties: - brcm,bcm88312 - const: brcm,nsp +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml index c13cb96545a2..c638e04ebae0 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml @@ -21,4 +21,6 @@ properties: - brcm,bcm958802a802x - const: brcm,stingray +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml index ccdf9f99cb2b..4eba182abd53 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml @@ -19,4 +19,6 @@ properties: - cavium,thunderx2-cn9900 - const: brcm,vulcan-soc +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/bitmain.yaml b/Documentation/devicetree/bindings/arm/bitmain.yaml index 5880083ab8d0..90ba02be48ce 100644 --- a/Documentation/devicetree/bindings/arm/bitmain.yaml +++ b/Documentation/devicetree/bindings/arm/bitmain.yaml @@ -17,4 +17,7 @@ properties: - enum: - bitmain,sophon-edge - const: bitmain,bm1880 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/calxeda.yaml b/Documentation/devicetree/bindings/arm/calxeda.yaml index aa5571d23c39..46f78addebb0 100644 --- a/Documentation/devicetree/bindings/arm/calxeda.yaml +++ b/Documentation/devicetree/bindings/arm/calxeda.yaml @@ -20,3 +20,5 @@ properties: - enum: - calxeda,highbank - calxeda,ecx-2000 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/digicolor.yaml b/Documentation/devicetree/bindings/arm/digicolor.yaml index 849e20518339..a35de3c9e284 100644 --- a/Documentation/devicetree/bindings/arm/digicolor.yaml +++ b/Documentation/devicetree/bindings/arm/digicolor.yaml @@ -15,4 +15,6 @@ properties: compatible: const: cnxt,cx92755 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 1ca9dfa8ce9a..934289446abb 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -621,4 +621,6 @@ properties: - fsl,s32v234-evb # S32V234-EVB2 Customer Evaluation Board - const: fsl,s32v234 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml index 43b8ce2227aa..b38458022946 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml @@ -64,4 +64,7 @@ properties: items: - const: H836ASDJ - const: hisilicon,sd5203 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/intel,keembay.yaml b/Documentation/devicetree/bindings/arm/intel,keembay.yaml index 06a7b05f435f..69cd30872928 100644 --- a/Documentation/devicetree/bindings/arm/intel,keembay.yaml +++ b/Documentation/devicetree/bindings/arm/intel,keembay.yaml @@ -16,4 +16,7 @@ properties: - enum: - intel,keembay-evm - const: intel,keembay + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml index f18302efb90e..d72e92bdf7c1 100644 --- a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml +++ b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml @@ -22,3 +22,5 @@ properties: - enum: - gateworks,gw2358 - const: intel,ixp43x + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml index 7597bc93a55f..5cbcacaeb441 100644 --- a/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml +++ b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml @@ -42,3 +42,5 @@ properties: - description: TI-SCI processor id for the remote processor device - description: TI-SCI host id to which processor control ownership should be transferred to + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml b/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml index a9828c50c0fb..e9bf3054529f 100644 --- a/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml +++ b/Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml @@ -59,3 +59,5 @@ properties: - const: marvell,cn9130 - const: marvell,armada-ap807-quad - const: marvell,armada-ap807 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 30908963ae26..f736e8c859fa 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -119,4 +119,7 @@ properties: - const: google,krane-sku176 - const: google,krane - const: mediatek,mt8183 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml index ecf6fa12e6ad..6193388c6318 100644 --- a/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml +++ b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml @@ -62,4 +62,6 @@ required: - compatible - axi@600000000 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/moxart.yaml b/Documentation/devicetree/bindings/arm/moxart.yaml index c068df59fad2..670d24ce8ec5 100644 --- a/Documentation/devicetree/bindings/arm/moxart.yaml +++ b/Documentation/devicetree/bindings/arm/moxart.yaml @@ -16,4 +16,5 @@ properties: - const: moxa,moxart-uc-7112-lx - const: moxa,moxart +additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/mrvl/mrvl.yaml b/Documentation/devicetree/bindings/arm/mrvl/mrvl.yaml index 3235ec9e9bad..d58116136154 100644 --- a/Documentation/devicetree/bindings/arm/mrvl/mrvl.yaml +++ b/Documentation/devicetree/bindings/arm/mrvl/mrvl.yaml @@ -35,4 +35,7 @@ properties: - enum: - dell,wyse-ariel - const: marvell,mmp3 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml index c2f980b00b06..7c787405bb2f 100644 --- a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml +++ b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml @@ -31,3 +31,5 @@ properties: - enum: - 70mai,midrived08 # 70mai midrive d08 - const: mstar,mercury5 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml b/Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml index f7f024910e71..214c97bc3063 100644 --- a/Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml +++ b/Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml @@ -21,4 +21,6 @@ properties: - ea,ea3250 - phytec,phy3250 - const: nxp,lpc3250 + +additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index ad25deba4d86..c97d4a580f47 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -178,4 +178,6 @@ properties: - qcom,sm8250-mtp - const: qcom,sm8250 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/rda.yaml b/Documentation/devicetree/bindings/arm/rda.yaml index 9672aa0c760d..a5c0444aa2b4 100644 --- a/Documentation/devicetree/bindings/arm/rda.yaml +++ b/Documentation/devicetree/bindings/arm/rda.yaml @@ -19,4 +19,6 @@ properties: - xunlong,orangepi-i96 # Orange Pi i96 - const: rda,8810pl +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/realtek.yaml b/Documentation/devicetree/bindings/arm/realtek.yaml index 845f9c76d6f7..9fb0297fe1ce 100644 --- a/Documentation/devicetree/bindings/arm/realtek.yaml +++ b/Documentation/devicetree/bindings/arm/realtek.yaml @@ -54,4 +54,7 @@ properties: - enum: - realtek,mjolnir # Realtek Mjolnir EVB - const: realtek,rtd1619 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index 01a6d0c571ad..ff94c45eefb0 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -299,4 +299,6 @@ properties: - renesas,rzn1d400-db # RZN1D-DB (RZ/N1D Demo Board for the RZ/N1D 400 pins package) - const: renesas,r9a06g032 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 65b4cc2c63f7..b621752aaa65 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -569,4 +569,7 @@ properties: items: - const: zkmagic,a95x-z2 - const: rockchip,rk3318 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml index eb92f9eefaba..272508010b02 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml @@ -180,3 +180,5 @@ properties: required: - compatible + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/sirf.yaml b/Documentation/devicetree/bindings/arm/sirf.yaml index 0b597032c923..b25eb35d1b66 100644 --- a/Documentation/devicetree/bindings/arm/sirf.yaml +++ b/Documentation/devicetree/bindings/arm/sirf.yaml @@ -24,4 +24,7 @@ properties: - items: - const: sirf,prima2-cb - const: sirf,prima2 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml b/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml index 2bd519d2e855..aa1d4afbc510 100644 --- a/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml +++ b/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml @@ -19,4 +19,7 @@ properties: - enum: - socionext,milbeaut-m10v-evb - const: socionext,sc2000a + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml b/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml index 6caf1f9be390..8c0e91658474 100644 --- a/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml +++ b/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml @@ -60,3 +60,5 @@ properties: - enum: - socionext,uniphier-pxs3-ref - const: socionext,uniphier-pxs3 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/spear.yaml b/Documentation/devicetree/bindings/arm/spear.yaml index f6ec731c9531..605ad3f882ef 100644 --- a/Documentation/devicetree/bindings/arm/spear.yaml +++ b/Documentation/devicetree/bindings/arm/spear.yaml @@ -22,4 +22,7 @@ properties: - st,spear320 - st,spear1310 - st,spear1340 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/sprd/sprd.yaml b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml index 0258a96bfbde..7b6ae3070396 100644 --- a/Documentation/devicetree/bindings/arm/sprd/sprd.yaml +++ b/Documentation/devicetree/bindings/arm/sprd/sprd.yaml @@ -30,4 +30,6 @@ properties: - sprd,sp9863a-1h10 - const: sprd,sc9863a +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/sti.yaml b/Documentation/devicetree/bindings/arm/sti.yaml index 47f9b8eebaa0..b1f28d16d3fb 100644 --- a/Documentation/devicetree/bindings/arm/sti.yaml +++ b/Documentation/devicetree/bindings/arm/sti.yaml @@ -20,4 +20,7 @@ properties: - st,stih407 - st,stih410 - st,stih418 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index deacb4e686e8..009b424e456e 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -54,8 +54,11 @@ properties: - const: st,stm32mp157 - description: Odyssey STM32MP1 SoM based Boards items: - - enum: - - seeed,stm32mp157c-odyssey - - const: seeed,stm32mp157c-odyssey-som - - const: st,stm32mp157 + - enum: + - seeed,stm32mp157c-odyssey + - const: seeed,stm32mp157c-odyssey-som + - const: st,stm32mp157 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index afa00268c7db..cab8e1b6417b 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -893,3 +893,5 @@ properties: items: - const: xunlong,orangepi-zero-plus2-h3 - const: allwinner,sun8i-h3 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml index 8ae44948e873..767e86354c8e 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -125,3 +125,5 @@ properties: - enum: - nvidia,tegra234-vdk - const: nvidia,tegra234 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index 829751209543..c6e1c1e63e43 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -32,4 +32,7 @@ properties: - description: K3 J7200 SoC items: - const: ti,j7200 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/ti/nspire.yaml b/Documentation/devicetree/bindings/arm/ti/nspire.yaml index e372b43da62f..cc2023bb7fa6 100644 --- a/Documentation/devicetree/bindings/arm/ti/nspire.yaml +++ b/Documentation/devicetree/bindings/arm/ti/nspire.yaml @@ -21,4 +21,7 @@ properties: - ti,nspire-tp # Clickpad models - ti,nspire-clp + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml b/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml index a8765ba29476..c022d325fc08 100644 --- a/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml +++ b/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml @@ -23,4 +23,7 @@ properties: - enbw,cmc # EnBW AM1808 based CMC board - lego,ev3 # LEGO MINDSTORMS EV3 (AM1808 based) - const: ti,da850 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/toshiba.yaml b/Documentation/devicetree/bindings/arm/toshiba.yaml index 0e066290238e..001bbbcd1432 100644 --- a/Documentation/devicetree/bindings/arm/toshiba.yaml +++ b/Documentation/devicetree/bindings/arm/toshiba.yaml @@ -19,4 +19,7 @@ properties: - enum: - toshiba,tmpv7708-rm-mbrc # TMPV7708 RM main board - const: toshiba,tmpv7708 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/ux500.yaml b/Documentation/devicetree/bindings/arm/ux500.yaml index accaee906050..5db7cfba81a4 100644 --- a/Documentation/devicetree/bindings/arm/ux500.yaml +++ b/Documentation/devicetree/bindings/arm/ux500.yaml @@ -34,3 +34,5 @@ properties: items: - const: samsung,golden - const: st-ericsson,u8500 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/vt8500.yaml b/Documentation/devicetree/bindings/arm/vt8500.yaml index 7b25b6fa34e9..29ff399551ca 100644 --- a/Documentation/devicetree/bindings/arm/vt8500.yaml +++ b/Documentation/devicetree/bindings/arm/vt8500.yaml @@ -21,3 +21,6 @@ properties: - wm,wm8650 - wm,wm8750 - wm,wm8850 + +additionalProperties: true + diff --git a/Documentation/devicetree/bindings/arm/xilinx.yaml b/Documentation/devicetree/bindings/arm/xilinx.yaml index c73b1f5c7f49..e0c6787f6e94 100644 --- a/Documentation/devicetree/bindings/arm/xilinx.yaml +++ b/Documentation/devicetree/bindings/arm/xilinx.yaml @@ -111,4 +111,6 @@ properties: - const: xlnx,zynqmp-zcu111 - const: xlnx,zynqmp +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/zte.yaml b/Documentation/devicetree/bindings/arm/zte.yaml index 2d3fefdccdff..672f8129cd31 100644 --- a/Documentation/devicetree/bindings/arm/zte.yaml +++ b/Documentation/devicetree/bindings/arm/zte.yaml @@ -23,4 +23,6 @@ properties: - zte,zx296718-evb - const: zte,zx296718 +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml b/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml new file mode 100644 index 000000000000..a1d55a2634a5 --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/auxdisplay/modtronix,lcd2s.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Modtronix engineering LCD2S Character LCD Display + +maintainers: + - Lars Poeschel <poeschel@lemonage.de> + +description: + The LCD2S is a Character LCD Display manufactured by Modtronix Engineering. + The display supports a serial I2C and SPI interface. The driver currently + only supports the I2C interface. + +properties: + compatible: + const: modtronix,lcd2s + + reg: + maxItems: 1 + description: + I2C bus address of the display. + + display-height-chars: + description: Height of the display, in character cells. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 4 + + display-width-chars: + description: Width of the display, in character cells. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 16 + maximum: 20 + +required: + - compatible + - reg + - display-height-chars + - display-width-chars + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + lcd2s: auxdisplay@28 { + compatible = "modtronix,lcd2s"; + reg = <0x28>; + display-height-chars = <4>; + display-width-chars = <20>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/hi6220-clock.txt b/Documentation/devicetree/bindings/clock/hi6220-clock.txt index ef3deb7b86ea..17ac4a3dd26a 100644 --- a/Documentation/devicetree/bindings/clock/hi6220-clock.txt +++ b/Documentation/devicetree/bindings/clock/hi6220-clock.txt @@ -4,7 +4,7 @@ Clock control registers reside in different Hi6220 system controllers, please refer the following document to know more about the binding rules for these system controllers: -Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml Required Properties: diff --git a/Documentation/devicetree/bindings/clock/imx5-clock.yaml b/Documentation/devicetree/bindings/clock/imx5-clock.yaml index 4d9e7c73dce9..90775c2669b8 100644 --- a/Documentation/devicetree/bindings/clock/imx5-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx5-clock.yaml @@ -57,7 +57,7 @@ examples: }; can@53fc8000 { - compatible = "fsl,imx53-flexcan", "fsl,p1010-flexcan"; + compatible = "fsl,imx53-flexcan", "fsl,imx25-flexcan"; reg = <0x53fc8000 0x4000>; interrupts = <82>; clocks = <&clks IMX5_CLK_CAN1_IPG_GATE>, <&clks IMX5_CLK_CAN1_SERIAL_GATE>; diff --git a/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml new file mode 100644 index 000000000000..ee2c099981b2 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/intel,keembay-ocs-aes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay OCS AES Device Tree Bindings + +maintainers: + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + The Intel Keem Bay Offload and Crypto Subsystem (OCS) AES engine provides + hardware-accelerated AES/SM4 encryption/decryption. + +properties: + compatible: + const: intel,keembay-ocs-aes + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + crypto@30008000 { + compatible = "intel,keembay-ocs-aes"; + reg = <0x30008000 0x1000>; + interrupts = <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scmi_clk 95>; + }; diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml index 03a76729d26c..7ce06f9f9f8e 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml @@ -76,6 +76,12 @@ properties: resets: maxItems: 1 + wifi-2.4ghz-coexistence: + type: boolean + description: > + Should the pixel frequencies in the WiFi frequencies range be + avoided? + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml new file mode 100644 index 000000000000..60585a4fc22b --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 Analogix Semiconductor, Inc. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/display/bridge/analogix,anx7625.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Analogix ANX7625 SlimPort (4K Mobile HD Transmitter) + +maintainers: + - Xin Ji <xji@analogixsemi.com> + +description: | + The ANX7625 is an ultra-low power 4K Mobile HD Transmitter + designed for portable devices. + +properties: + compatible: + items: + - const: analogix,anx7625 + + reg: + maxItems: 1 + + interrupts: + description: used for interrupt pin B8. + maxItems: 1 + + enable-gpios: + description: used for power on chip control, POWER_EN pin D2. + maxItems: 1 + + reset-gpios: + description: used for reset chip control, RESET_N pin B7. + maxItems: 1 + + ports: + type: object + + properties: + port@0: + type: object + description: + Video port for MIPI DSI input. + + port@1: + type: object + description: + Video port for panel or connector. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + encoder@58 { + compatible = "analogix,anx7625"; + reg = <0x58>; + enable-gpios = <&pio 45 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pio 73 GPIO_ACTIVE_HIGH>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + mipi2dp_bridge_in: port@0 { + reg = <0>; + anx7625_in: endpoint { + remote-endpoint = <&mipi_dsi>; + }; + }; + + mipi2dp_bridge_out: port@1 { + reg = <1>; + anx7625_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml new file mode 100644 index 000000000000..ab5be2625224 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/intel,keembay-dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay mipi dsi controller + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +properties: + compatible: + const: intel,keembay-dsi + + reg: + items: + - description: MIPI registers range + + reg-names: + items: + - const: mipi + + clocks: + items: + - description: MIPI DSI clock + - description: MIPI DSI econfig clock + - description: MIPI DSI config clock + + clock-names: + items: + - const: clk_mipi + - const: clk_mipi_ecfg + - const: clk_mipi_cfg + + ports: + type: object + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@0: + type: object + description: MIPI DSI input port. + + port@1: + type: object + description: DSI output port. + + required: + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + mipi-dsi@20900000 { + compatible = "intel,keembay-dsi"; + reg = <0x20900000 0x4000>; + reg-names = "mipi"; + clocks = <&scmi_clk 0x86>, + <&scmi_clk 0x88>, + <&scmi_clk 0x89>; + clock-names = "clk_mipi", "clk_mipi_ecfg", + "clk_mipi_cfg"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi_in: endpoint { + remote-endpoint = <&disp_out>; + }; + }; + + port@1 { + reg = <1>; + dsi_out: endpoint { + remote-endpoint = <&adv7535_input>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml index d60208359234..7a1c89b995e2 100644 --- a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml +++ b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml @@ -4,18 +4,19 @@ $id: http://devicetree.org/schemas/display/bridge/lontium,lt9611.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Lontium LT9611 2 Port MIPI to HDMI Bridge +title: Lontium LT9611(UXC) 2 Port MIPI to HDMI Bridge maintainers: - Vinod Koul <vkoul@kernel.org> description: | - The LT9611 is a bridge device which converts DSI to HDMI + The LT9611 and LT9611UXC are bridge devices which convert DSI to HDMI properties: compatible: enum: - lontium,lt9611 + - lontium,lt9611uxc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt index 0d1db3f9da84..02c21b584741 100644 --- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt +++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt @@ -8,6 +8,8 @@ Optional properties: - interrupts: describe the interrupt line used to inform the host about hotplug events. - reset-gpios: OF device-tree gpio specification for RST_N pin. + - iovcc-supply: I/O Supply Voltage (1.8V or 3.3V) + - cvcc12-supply: Digital Core Supply Voltage (1.2V) HDMI audio properties: - #sound-dai-cells: <0> or <1>. <0> if only i2s or spdif pin @@ -54,6 +56,8 @@ Example: compatible = "sil,sii9022"; reg = <0x39>; reset-gpios = <&pioA 1 0>; + iovcc-supply = <&v3v3_hdmi>; + cvcc12-supply = <&v1v2_hdmi>; #sound-dai-cells = <0>; sil,i2s-data-lanes = < 0 1 2 >; diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml index 31f085d8ab13..fd3113aa9ccd 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml @@ -7,17 +7,17 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Toshiba TC358775 DSI to LVDS bridge bindings maintainers: - - Vinay Simha BN <simhavcs@gmail.com> + - Vinay Simha BN <simhavcs@gmail.com> description: | - This binding supports DSI to LVDS bridge TC358775 + This binding supports DSI to LVDS bridge TC358775 - MIPI DSI-RX Data 4-lane, CLK 1-lane with data rates up to 800 Mbps/lane. - Video frame size: - Up to 1600x1200 24-bit/pixel resolution for single-link LVDS display panel - limited by 135 MHz LVDS speed - Up to WUXGA (1920x1200 24-bit pixels) resolution for dual-link LVDS display - panel, limited by 270 MHz LVDS speed. + MIPI DSI-RX Data 4-lane, CLK 1-lane with data rates up to 800 Mbps/lane. + Video frame size: + Up to 1600x1200 24-bit/pixel resolution for single-link LVDS display panel + limited by 135 MHz LVDS speed + Up to WUXGA (1920x1200 24-bit pixels) resolution for dual-link LVDS display + panel, limited by 270 MHz LVDS speed. properties: compatible: @@ -29,7 +29,7 @@ properties: vdd-supply: maxItems: 1 - description: 1.2V LVDS Power Supply + description: 1.2V LVDS Power Supply vddio-supply: maxItems: 1 @@ -77,16 +77,18 @@ properties: - port@1 required: - - compatible - - reg - - vdd-supply - - vddio-supply - - stby-gpios - - reset-gpios - - ports + - compatible + - reg + - vdd-supply + - vddio-supply + - stby-gpios + - reset-gpios + - ports + +additionalProperties: false examples: - - | + - | #include <dt-bindings/gpio/gpio.h> /* For single-link LVDS display panel */ @@ -147,7 +149,7 @@ examples: }; }; - - | + - | /* For dual-link LVDS display panel */ i2c@78b8000 { diff --git a/Documentation/devicetree/bindings/display/intel,keembay-display.yaml b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml new file mode 100644 index 000000000000..0a697d45c2ad --- /dev/null +++ b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/intel,keembay-display.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay display controller + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +properties: + compatible: + const: intel,keembay-display + + reg: + items: + - description: LCD registers range + + reg-names: + items: + - const: lcd + + clocks: + items: + - description: LCD controller clock + - description: pll0 clock + + clock-names: + items: + - const: clk_lcd + - const: clk_pll0 + + interrupts: + maxItems: 1 + + port: + type: object + description: Display output node to DSI. + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - interrupts + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display@20930000 { + compatible = "intel,keembay-display"; + reg = <0x20930000 0x3000>; + reg-names = "lcd"; + interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scmi_clk 0x83>, + <&scmi_clk 0x0>; + clock-names = "clk_lcd", "clk_pll0"; + + port { + disp_out: endpoint { + remote-endpoint = <&dsi_in>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml b/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml new file mode 100644 index 000000000000..40caa6118809 --- /dev/null +++ b/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/intel,keembay-msscam.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay MSSCAM + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +description: | + MSSCAM controls local clocks in the display subsystem namely LCD clocks and + MIPI DSI clocks. It also configures the interconnect between LCD and + MIPI DSI. + +properties: + compatible: + items: + - const: intel,keembay-msscam + - const: syscon + + reg: + maxItems: 1 + + reg-io-width: + const: 4 + +required: + - compatible + - reg + - reg-io-width + +additionalProperties: false + +examples: + - | + msscam:msscam@20910000 { + compatible = "intel,keembay-msscam", "syscon"; + reg = <0x20910000 0x30>; + reg-io-width = <4>; + }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index 121220745d46..33977e15bebd 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -43,7 +43,7 @@ Required properties (all function blocks): "mediatek,<chip>-dpi" - DPI controller, see mediatek,dpi.txt "mediatek,<chip>-disp-mutex" - display mutex "mediatek,<chip>-disp-od" - overdrive - the supported chips are mt2701, mt7623, mt2712 and mt8173. + the supported chips are mt2701, mt7623, mt2712, mt8167 and mt8173. - reg: Physical base address and length of the function block register space - interrupts: The interrupt signal from the function block (required, except for merge and split function blocks). @@ -59,7 +59,7 @@ Required properties (DMA function blocks): "mediatek,<chip>-disp-ovl" "mediatek,<chip>-disp-rdma" "mediatek,<chip>-disp-wdma" - the supported chips are mt2701 and mt8173. + the supported chips are mt2701, mt8167 and mt8173. - larb: Should contain a phandle pointing to the local arbiter device as defined in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt - iommus: Should point to the respective IOMMU block with master port as diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt deleted file mode 100644 index dc1ebd13cc88..000000000000 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt +++ /dev/null @@ -1,42 +0,0 @@ -Mediatek DPI Device -=================== - -The Mediatek DPI function block is a sink of the display subsystem and -provides 8-bit RGB/YUV444 or 8/10/10-bit YUV422 pixel data on a parallel -output bus. - -Required properties: -- compatible: "mediatek,<chip>-dpi" - the supported chips are mt2701, mt7623, mt8173 and mt8183. -- reg: Physical base address and length of the controller's registers -- interrupts: The interrupt signal from the function block. -- clocks: device clocks - See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. -- clock-names: must contain "pixel", "engine", and "pll" -- port: Output port node with endpoint definitions as described in - Documentation/devicetree/bindings/graph.txt. This port should be connected - to the input port of an attached HDMI or LVDS encoder chip. - -Optional properties: -- pinctrl-names: Contain "default" and "sleep". - -Example: - -dpi0: dpi@1401d000 { - compatible = "mediatek,mt8173-dpi"; - reg = <0 0x1401d000 0 0x1000>; - interrupts = <GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; - clocks = <&mmsys CLK_MM_DPI_PIXEL>, - <&mmsys CLK_MM_DPI_ENGINE>, - <&apmixedsys CLK_APMIXED_TVDPLL>; - clock-names = "pixel", "engine", "pll"; - pinctrl-names = "default", "sleep"; - pinctrl-0 = <&dpi_pin_func>; - pinctrl-1 = <&dpi_pin_idle>; - - port { - dpi0_out: endpoint { - remote-endpoint = <&hdmi0_in>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml new file mode 100644 index 000000000000..6cdb734c91a9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/mediatek/mediatek,dpi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: mediatek DPI Controller Device Tree Bindings + +maintainers: + - CK Hu <ck.hu@mediatek.com> + - Jitao shi <jitao.shi@mediatek.com> + +description: | + The Mediatek DPI function block is a sink of the display subsystem and + provides 8-bit RGB/YUV444 or 8/10/10-bit YUV422 pixel data on a parallel + output bus. + +properties: + compatible: + enum: + - mediatek,mt2701-dpi + - mediatek,mt7623-dpi + - mediatek,mt8173-dpi + - mediatek,mt8183-dpi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Pixel Clock + - description: Engine Clock + - description: DPI PLL + + clock-names: + items: + - const: pixel + - const: engine + - const: pll + + pinctrl-0: true + pinctrl-1: true + + pinctrl-names: + items: + - const: default + - const: sleep + + port: + type: object + description: + Output port node with endpoint definitions as described in + Documentation/devicetree/bindings/graph.txt. This port should be connected + to the input port of an attached HDMI or LVDS encoder chip. + + properties: + endpoint: + type: object + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + dpi0: dpi@1401d000 { + compatible = "mediatek,mt8173-dpi"; + reg = <0x1401d000 0x1000>; + interrupts = <GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; + clocks = <&mmsys CLK_MM_DPI_PIXEL>, + <&mmsys CLK_MM_DPI_ENGINE>, + <&apmixedsys CLK_APMIXED_TVDPLL>; + clock-names = "pixel", "engine", "pll"; + pinctrl-names = "default", "sleep"; + pinctrl-0 = <&dpi_pin_func>; + pinctrl-1 = <&dpi_pin_idle>; + + port { + dpi0_out: endpoint { + remote-endpoint = <&hdmi0_in>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 1af0ff102b50..090dcb3fc34d 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -39,6 +39,10 @@ Required properties: a4xx Snapdragon SoCs. See Documentation/devicetree/bindings/sram/qcom,ocmem.yaml. +Optional properties: +- #cooling-cells: The value must be 2. For details, please refer + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml. + Example 3xx/4xx: / { @@ -61,6 +65,7 @@ Example 3xx/4xx: power-domains = <&mmcc OXILICX_GDSC>; operating-points-v2 = <&gpu_opp_table>; iommus = <&gpu_iommu 0>; + #cooling-cells = <2>; }; gpu_sram: ocmem@fdd00000 { @@ -98,6 +103,8 @@ Example a6xx (with GMU): reg = <0x5000000 0x40000>, <0x509e000 0x10>; reg-names = "kgsl_3d0_reg_memory", "cx_mem"; + #cooling-cells = <2>; + /* * Look ma, no clocks! The GPU clocks and power are * controlled entirely by the GMU diff --git a/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml new file mode 100644 index 000000000000..91cb4c3e0198 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/abt,y030xx067a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Asia Better Technology 3.0" (320x480 pixels) 24-bit IPS LCD panel + +description: | + The panel must obey the rules for a SPI slave device as specified in + spi/spi-controller.yaml + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: abt,y030xx067a + + backlight: true + port: true + power-supply: true + reg: true + reset-gpios: true + +required: + - compatible + - reg + - power-supply + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "abt,y030xx067a"; + reg = <0>; + + spi-max-frequency = <3125000>; + + reset-gpios = <&gpe 2 GPIO_ACTIVE_LOW>; + + backlight = <&backlight>; + power-supply = <&vcc>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml index c60b3bd74337..b2fcec4f22fd 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml @@ -13,9 +13,8 @@ properties: compatible: items: - enum: - - bananapi,lhr050h41 - - feixin,k101-im2byl02 - + - bananapi,lhr050h41 + - feixin,k101-im2byl02 - const: ilitek,ili9881c backlight: true diff --git a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml index 937323cc9aaa..51f423297ec8 100644 --- a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml +++ b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml @@ -37,6 +37,9 @@ properties: reset-gpios: true + 'mantix,tp-rstn-gpios': + description: second reset line that triggers DSI config load + backlight: true required: @@ -63,6 +66,7 @@ examples: avee-supply = <®_avee>; vddi-supply = <®_1v8_p>; reset-gpios = <&gpio1 29 GPIO_ACTIVE_LOW>; + mantix,tp-rstn-gpios = <&gpio1 24 GPIO_ACTIVE_LOW>; backlight = <&backlight>; }; }; diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml new file mode 100644 index 000000000000..d2170de6b723 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/novatek,nt36672a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Novatek NT36672A based DSI display Panels + +maintainers: + - Sumit Semwal <sumit.semwal@linaro.org> + +description: | + The nt36672a IC from Novatek is a generic DSI Panel IC used to drive dsi + panels. + Right now, support is added only for a Tianma FHD+ LCD display panel with a + resolution of 1080x2246. It is a video mode DSI panel. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - tianma,fhd-video + - const: novatek,nt36672a + description: This indicates the panel manufacturer of the panel that is + in turn using the NT36672A panel driver. This compatible string + determines how the NT36672A panel driver is configured for the indicated + panel. The novatek,nt36672a compatible shall always be provided as a fallback. + + reset-gpios: + description: phandle of gpio for reset line - This should be 8mA, gpio + can be configured using mux, pinctrl, pinctrl-names (active high) + + vddio-supply: + description: phandle of the regulator that provides the supply voltage + Power IC supply + + vddpos-supply: + description: phandle of the positive boost supply regulator + + vddneg-supply: + description: phandle of the negative boost supply regulator + + reg: true + port: true + +required: + - compatible + - reg + - vddi0-supply + - vddpos-supply + - vddneg-supply + - reset-gpios + - port + +unevaluatedProperties: false + +examples: + - |+ + #include <dt-bindings/gpio/gpio.h> + + dsi0 { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "tianma,fhd-video", "novatek,nt36672a"; + reg = <0>; + vddi0-supply = <&vreg_l14a_1p88>; + vddpos-supply = <&lab>; + vddneg-supply = <&ibb>; + + reset-gpios = <&tlmm 6 GPIO_ACTIVE_HIGH>; + + #address-cells = <1>; + #size-cells = <0>; + port { + tianma_nt36672a_in_0: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index c0dd9fa29f1d..72e4b6d4d5e1 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -47,6 +47,12 @@ properties: - panasonic,vvx10f004b00 # Panasonic 10" WUXGA TFT LCD panel - panasonic,vvx10f034n00 + # Samsung s6e3fc2x01 1080x2340 AMOLED panel + - samsung,s6e3fc2x01 + # Samsung sofef00 1080x2280 AMOLED panel + - samsung,sofef00 + # Shangai Top Display Optoelectronics 7" TL070WSH30 1024x600 TFT LCD panel + - tdo,tl070wsh30 reg: maxItems: 1 @@ -54,6 +60,7 @@ properties: backlight: true enable-gpios: true + reset-gpios: true port: true power-supply: true diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index edb53ab0d9eb..f9750b0b6708 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -282,6 +282,8 @@ properties: - vxt,vl050-8048nt-c01 # Winstar Display Corporation 3.5" QVGA (320x240) TFT LCD panel - winstar,wf35ltiacd + # Yes Optoelectronics YTC700TLAG-05-201C 7" TFT LCD panel + - yes-optoelectronics,ytc700tlag-05-201c backlight: true enable-gpios: true diff --git a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml index 4f9185462ed3..4dc30738ee57 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml @@ -55,6 +55,14 @@ properties: - const: vp1 - const: vp2 + assigned-clocks: + minItems: 1 + maxItems: 3 + + assigned-clock-parents: + minItems: 1 + maxItems: 3 + interrupts: maxItems: 1 @@ -62,6 +70,9 @@ properties: maxItems: 1 description: phandle to the associated power domain + dma-coherent: + type: boolean + ports: type: object description: diff --git a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml index 173730d56334..c9a947d55fa4 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml @@ -77,6 +77,14 @@ properties: - const: vp3 - const: vp4 + assigned-clocks: + minItems: 1 + maxItems: 5 + + assigned-clock-parents: + minItems: 1 + maxItems: 5 + interrupts: items: - description: common_m DSS Master common @@ -95,6 +103,9 @@ properties: maxItems: 1 description: phandle to the associated power domain + dma-coherent: + type: boolean + ports: type: object description: diff --git a/Documentation/devicetree/bindings/edac/amazon,al-mc-edac.yaml b/Documentation/devicetree/bindings/edac/amazon,al-mc-edac.yaml index a25387df0865..57e5270a0741 100644 --- a/Documentation/devicetree/bindings/edac/amazon,al-mc-edac.yaml +++ b/Documentation/devicetree/bindings/edac/amazon,al-mc-edac.yaml @@ -48,6 +48,7 @@ required: - "#address-cells" - "#size-cells" +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt index 6a0f3d90d682..8ca9e0a049d8 100644 --- a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt +++ b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt @@ -1,6 +1,6 @@ -Aspeed AST2500 SoC EDAC node +Aspeed BMC SoC EDAC node -The Aspeed AST2500 SoC supports DDR3 and DDR4 memory with and without ECC (error +The Aspeed BMC SoC supports DDR3 and DDR4 memory with and without ECC (error correction check). The memory controller supports SECDED (single bit error correction, double bit @@ -11,7 +11,10 @@ Note, the bootloader must configure ECC mode in the memory controller. Required properties: -- compatible: should be "aspeed,ast2500-sdram-edac" +- compatible: should be one of + - "aspeed,ast2400-sdram-edac" + - "aspeed,ast2500-sdram-edac" + - "aspeed,ast2600-sdram-edac" - reg: sdram controller register set should be <0x1e6e0000 0x174> - interrupts: should be AVIC interrupt #0 diff --git a/Documentation/devicetree/bindings/eeprom/at25.yaml b/Documentation/devicetree/bindings/eeprom/at25.yaml index 9810619a2b5c..744973637678 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.yaml +++ b/Documentation/devicetree/bindings/eeprom/at25.yaml @@ -81,14 +81,14 @@ properties: at25,byte-len: $ref: /schemas/types.yaml#/definitions/uint32 description: - Total eeprom size in bytes. Deprecated, use "size" property instead. + Total eeprom size in bytes. Deprecated, use "size" property instead. deprecated: true at25,addr-mode: $ref: /schemas/types.yaml#/definitions/uint32 description: - Addr-mode flags, as defined in include/linux/spi/eeprom.h. - Deprecated, use "address-width" property instead. + Addr-mode flags, as defined in include/linux/spi/eeprom.h. + Deprecated, use "address-width" property instead. deprecated: true at25,page-size: diff --git a/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml b/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml index e2d2c10e536a..b032471831e7 100644 --- a/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml @@ -43,8 +43,8 @@ properties: gpio-controller: true gpio-line-names: - minItems: 1 - maxItems: 8 + minItems: 1 + maxItems: 8 required: - compatible diff --git a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml new file mode 100644 index 000000000000..b386e4128a79 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/i2c/google,cros-ec-i2c-tunnel.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: I2C bus that tunnels through the ChromeOS EC (cros-ec) + +maintainers: + - Doug Anderson <dianders@chromium.org> + - Benson Leung <bleung@chromium.org> + - Enric Balletbo i Serra <enric.balletbo@collabora.com> + +description: | + On some ChromeOS board designs we've got a connection to the EC + (embedded controller) but no direct connection to some devices on the + other side of the EC (like a battery and PMIC). To get access to + those devices we need to tunnel our i2c commands through the EC. + + The node for this device should be under a cros-ec node like + google,cros-ec-spi or google,cros-ec-i2c. + +allOf: + - $ref: i2c-controller.yaml# + +properties: + compatible: + const: google,cros-ec-i2c-tunnel + + google,remote-bus: + description: The EC bus we'd like to talk to. + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - google,remote-bus + +unevaluatedProperties: false + +examples: + - | + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + cros-ec@0 { + compatible = "google,cros-ec-spi"; + reg = <0>; + spi-max-frequency = <5000000>; + + i2c-tunnel { + compatible = "google,cros-ec-i2c-tunnel"; + #address-cells = <1>; + #size-cells = <0>; + + google,remote-bus = <0>; + + battery: sbs-battery@b { + compatible = "sbs,sbs-battery"; + reg = <0xb>; + sbs,poll-retry-count = <1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-cros-ec-tunnel.txt b/Documentation/devicetree/bindings/i2c/i2c-cros-ec-tunnel.txt deleted file mode 100644 index 898f030eba62..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-cros-ec-tunnel.txt +++ /dev/null @@ -1,39 +0,0 @@ -I2C bus that tunnels through the ChromeOS EC (cros-ec) -====================================================== -On some ChromeOS board designs we've got a connection to the EC (embedded -controller) but no direct connection to some devices on the other side of -the EC (like a battery and PMIC). To get access to those devices we need -to tunnel our i2c commands through the EC. - -The node for this device should be under a cros-ec node like google,cros-ec-spi -or google,cros-ec-i2c. - - -Required properties: -- compatible: google,cros-ec-i2c-tunnel -- google,remote-bus: The EC bus we'd like to talk to. - -Optional child nodes: -- One node per I2C device connected to the tunnelled I2C bus. - - -Example: - cros-ec@0 { - compatible = "google,cros-ec-spi"; - - ... - - i2c-tunnel { - compatible = "google,cros-ec-i2c-tunnel"; - #address-cells = <1>; - #size-cells = <0>; - - google,remote-bus = <0>; - - battery: sbs-battery@b { - compatible = "sbs,sbs-battery"; - reg = <0xb>; - sbs,poll-retry-count = <1>; - }; - }; - } diff --git a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml index 0e7b4b8a7e48..e1e65eb4f795 100644 --- a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml @@ -19,11 +19,11 @@ properties: compatible: oneOf: - enum: - - ingenic,jz4770-i2c - - ingenic,x1000-i2c + - ingenic,jz4770-i2c + - ingenic,x1000-i2c - items: - - const: ingenic,jz4780-i2c - - const: ingenic,jz4770-i2c + - const: ingenic,jz4780-i2c + - const: ingenic,jz4770-i2c reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml index 6feafb7e531e..930f9e3904d7 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml @@ -43,4 +43,5 @@ examples: vref-supply = <&adc_vref>; }; }; -...
\ No newline at end of file +... + diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml index d3733ad8785a..8f32800fe5b7 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml @@ -46,7 +46,8 @@ properties: spi-max-frequency: true spi-cpol: true - spi-cpha : true + + spi-cpha: true "#io-channel-cells": const: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml b/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml index 5d92b477e23f..4e695b97d015 100644 --- a/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml @@ -22,8 +22,8 @@ properties: adc-reserved-channels: $ref: /schemas/types.yaml#/definitions/uint32 description: - Bitmask of reserved channels, i.e. channels that cannot be - used by the OS. + Bitmask of reserved channels, i.e. channels that cannot be + used by the OS. clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml b/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml index 9514c3381c42..52490cbb0af0 100644 --- a/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml +++ b/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml @@ -21,7 +21,7 @@ properties: gpios: description: - GPIO used for controlling the reset pin + GPIO used for controlling the reset pin maxItems: 1 spi-max-frequency: true diff --git a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml index 6a176f551d75..c1772b568cd1 100644 --- a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml +++ b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml @@ -28,6 +28,8 @@ required: - reg - vref-supply +additionalProperties: false + examples: - | i2c { diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml index dc870eb2875f..7037f82ec753 100644 --- a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml +++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml @@ -32,6 +32,8 @@ required: - compatible - reg +additionalProperties: false + examples: - | i2c0 { diff --git a/Documentation/devicetree/bindings/input/cros-ec-keyb.txt b/Documentation/devicetree/bindings/input/cros-ec-keyb.txt deleted file mode 100644 index 0f6355ce39b5..000000000000 --- a/Documentation/devicetree/bindings/input/cros-ec-keyb.txt +++ /dev/null @@ -1,72 +0,0 @@ -ChromeOS EC Keyboard - -Google's ChromeOS EC Keyboard is a simple matrix keyboard implemented on -a separate EC (Embedded Controller) device. It provides a message for reading -key scans from the EC. These are then converted into keycodes for processing -by the kernel. - -This binding is based on matrix-keymap.txt and extends/modifies it as follows: - -Required properties: -- compatible: "google,cros-ec-keyb" - -Optional properties: -- google,needs-ghost-filter: True to enable a ghost filter for the matrix -keyboard. This is recommended if the EC does not have its own logic or -hardware for this. - - -Example: - -cros-ec-keyb { - compatible = "google,cros-ec-keyb"; - keypad,num-rows = <8>; - keypad,num-columns = <13>; - google,needs-ghost-filter; - /* - * Keymap entries take the form of 0xRRCCKKKK where - * RR=Row CC=Column KKKK=Key Code - * The values below are for a US keyboard layout and - * are taken from the Linux driver. Note that the - * 102ND key is not used for US keyboards. - */ - linux,keymap = < - /* CAPSLCK F1 B F10 */ - 0x0001003a 0x0002003b 0x00030030 0x00040044 - /* N = R_ALT ESC */ - 0x00060031 0x0008000d 0x000a0064 0x01010001 - /* F4 G F7 H */ - 0x0102003e 0x01030022 0x01040041 0x01060023 - /* ' F9 BKSPACE L_CTRL */ - 0x01080028 0x01090043 0x010b000e 0x0200001d - /* TAB F3 T F6 */ - 0x0201000f 0x0202003d 0x02030014 0x02040040 - /* ] Y 102ND [ */ - 0x0205001b 0x02060015 0x02070056 0x0208001a - /* F8 GRAVE F2 5 */ - 0x02090042 0x03010029 0x0302003c 0x03030006 - /* F5 6 - \ */ - 0x0304003f 0x03060007 0x0308000c 0x030b002b - /* R_CTRL A D F */ - 0x04000061 0x0401001e 0x04020020 0x04030021 - /* S K J ; */ - 0x0404001f 0x04050025 0x04060024 0x04080027 - /* L ENTER Z C */ - 0x04090026 0x040b001c 0x0501002c 0x0502002e - /* V X , M */ - 0x0503002f 0x0504002d 0x05050033 0x05060032 - /* L_SHIFT / . SPACE */ - 0x0507002a 0x05080035 0x05090034 0x050B0039 - /* 1 3 4 2 */ - 0x06010002 0x06020004 0x06030005 0x06040003 - /* 8 7 0 9 */ - 0x06050009 0x06060008 0x0608000b 0x0609000a - /* L_ALT DOWN RIGHT Q */ - 0x060a0038 0x060b006c 0x060c006a 0x07010010 - /* E R W I */ - 0x07020012 0x07030013 0x07040011 0x07050017 - /* U R_SHIFT P O */ - 0x07060016 0x07070036 0x07080019 0x07090018 - /* UP LEFT */ - 0x070b0067 0x070c0069>; -}; diff --git a/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml new file mode 100644 index 000000000000..8e50c14a9d77 --- /dev/null +++ b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/input/google,cros-ec-keyb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ChromeOS EC Keyboard + +maintainers: + - Simon Glass <sjg@chromium.org> + - Benson Leung <bleung@chromium.org> + - Enric Balletbo i Serra <enric.balletbo@collabora.com> + +description: | + Google's ChromeOS EC Keyboard is a simple matrix keyboard + implemented on a separate EC (Embedded Controller) device. It provides + a message for reading key scans from the EC. These are then converted + into keycodes for processing by the kernel. + +allOf: + - $ref: "/schemas/input/matrix-keymap.yaml#" + +properties: + compatible: + const: google,cros-ec-keyb + + google,needs-ghost-filter: + description: + Enable a ghost filter for the matrix keyboard. This is recommended + if the EC does not have its own logic or hardware for this. + type: boolean + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + cros-ec-keyb { + compatible = "google,cros-ec-keyb"; + keypad,num-rows = <8>; + keypad,num-columns = <13>; + google,needs-ghost-filter; + /* + * Keymap entries take the form of 0xRRCCKKKK where + * RR=Row CC=Column KKKK=Key Code + * The values below are for a US keyboard layout and + * are taken from the Linux driver. Note that the + * 102ND key is not used for US keyboards. + */ + linux,keymap = < + /* CAPSLCK F1 B F10 */ + 0x0001003a 0x0002003b 0x00030030 0x00040044 + /* N = R_ALT ESC */ + 0x00060031 0x0008000d 0x000a0064 0x01010001 + /* F4 G F7 H */ + 0x0102003e 0x01030022 0x01040041 0x01060023 + /* ' F9 BKSPACE L_CTRL */ + 0x01080028 0x01090043 0x010b000e 0x0200001d + /* TAB F3 T F6 */ + 0x0201000f 0x0202003d 0x02030014 0x02040040 + /* ] Y 102ND [ */ + 0x0205001b 0x02060015 0x02070056 0x0208001a + /* F8 GRAVE F2 5 */ + 0x02090042 0x03010029 0x0302003c 0x03030006 + /* F5 6 - \ */ + 0x0304003f 0x03060007 0x0308000c 0x030b002b + /* R_CTRL A D F */ + 0x04000061 0x0401001e 0x04020020 0x04030021 + /* S K J ; */ + 0x0404001f 0x04050025 0x04060024 0x04080027 + /* L ENTER Z C */ + 0x04090026 0x040b001c 0x0501002c 0x0502002e + /* V X , M */ + 0x0503002f 0x0504002d 0x05050033 0x05060032 + /* L_SHIFT / . SPACE */ + 0x0507002a 0x05080035 0x05090034 0x050B0039 + /* 1 3 4 2 */ + 0x06010002 0x06020004 0x06030005 0x06040003 + /* 8 7 0 9 */ + 0x06050009 0x06060008 0x0608000b 0x0609000a + /* L_ALT DOWN RIGHT Q */ + 0x060a0038 0x060b006c 0x060c006a 0x07010010 + /* E R W I */ + 0x07020012 0x07030013 0x07040011 0x07050017 + /* U R_SHIFT P O */ + 0x07060016 0x07070036 0x07080019 0x07090018 + /* UP LEFT */ + 0x070b0067 0x070c0069>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml index bbf79d125675..1c4c009dedd0 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml @@ -94,12 +94,12 @@ properties: instances. required: - - compatible - - reg - - interrupts - - interrupt-names - - interrupt-controller - - "#interrupt-cells" + - compatible + - reg + - interrupts + - interrupt-names + - interrupt-controller + - "#interrupt-cells" additionalProperties: false diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml index c7cd05656a3e..b5af12011499 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml @@ -32,6 +32,11 @@ description: | | | vint | bit | | 0 |.....|63| vintx | | +--------------+ +------------+ | | | + | Unmap | + | +--------------+ | + Unmapped events ---->| | umapidx |-------------------------> Globalevents + | +--------------+ | + | | +-----------------------------------------+ Configuration of these Intmap registers that maps global events to vint is @@ -70,6 +75,11 @@ properties: - description: | "limit" specifies the limit for translation + ti,unmapped-event-sources: + $ref: /schemas/types.yaml#definitions/phandle-array + description: + Array of phandles to DMA controllers where the unmapped events originate. + required: - compatible - reg @@ -79,6 +89,8 @@ required: - ti,sci-dev-id - ti,interrupt-ranges +unevaluatedProperties: false + examples: - | bus { diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml index cff6a956afb4..e12aee42b126 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml @@ -88,6 +88,8 @@ required: - ti,sci-dev-id - ti,interrupt-ranges +unevaluatedProperties: false + examples: - | main_gpio_intr: interrupt-controller0 { diff --git a/Documentation/devicetree/bindings/leds/backlight/common.yaml b/Documentation/devicetree/bindings/leds/backlight/common.yaml index 4e7e95e331a5..bc817f77d2b1 100644 --- a/Documentation/devicetree/bindings/leds/backlight/common.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/common.yaml @@ -32,3 +32,5 @@ properties: that a LED can be made so bright that it gets damaged or causes damage due to restrictions in a specific system, such as mounting conditions. $ref: /schemas/types.yaml#definitions/uint32 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index 08b6700ca61e..f1211e7045f1 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -43,7 +43,7 @@ properties: LED_COLOR_ID available, add a new one. $ref: /schemas/types.yaml#definitions/uint32 minimum: 0 - maximum: 8 + maximum: 9 function-enumerator: description: diff --git a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml index b1a53f054b89..37445c68cdef 100644 --- a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml +++ b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml @@ -16,7 +16,7 @@ description: | modules. This is achieved by adding multi-led nodes layer to the monochrome LED bindings. The nodes and properties defined in this document are unique to the multicolor - LED class. Common LED nodes and properties are inherited from the common.txt + LED class. Common LED nodes and properties are inherited from the common.yaml within this documentation directory. patternProperties: @@ -25,10 +25,11 @@ patternProperties: description: Represents the LEDs that are to be grouped. properties: color: - const: 8 # LED_COLOR_ID_MULTI description: | - For multicolor LED support this property should be defined as - LED_COLOR_ID_MULTI which can be found in include/linux/leds/common.h. + For multicolor LED support this property should be defined as either + LED_COLOR_ID_RGB or LED_COLOR_ID_MULTI which can be found in + include/linux/leds/common.h. + enum: [ 8, 9 ] $ref: "common.yaml#" diff --git a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml index 947542a253ec..c192b5feadc7 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml @@ -46,6 +46,12 @@ properties: vled-supply: description: LED supply. + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + patternProperties: '^multi-led@[0-9a-f]$': type: object @@ -69,6 +75,8 @@ required: - compatible - reg +additionalProperties: false + examples: - | #include <dt-bindings/gpio/gpio.h> diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt index cf48cd806e00..7771ecaac586 100644 --- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt +++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt @@ -47,7 +47,7 @@ Example: interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_LOW>; clocks = <&infracfg CLK_INFRA_GCE>; clock-names = "gce"; - #mbox-cells = <3>; + #mbox-cells = <2>; }; Example for a client device: diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml index 4cc1a670c986..2f7058f7760c 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml @@ -18,6 +18,8 @@ properties: - allwinner,sun7i-a20-video-engine - allwinner,sun8i-a33-video-engine - allwinner,sun8i-h3-video-engine + - allwinner,sun8i-v3s-video-engine + - allwinner,sun8i-r40-video-engine - allwinner,sun50i-a64-video-engine - allwinner,sun50i-h5-video-engine - allwinner,sun50i-h6-video-engine diff --git a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml new file mode 100644 index 000000000000..bee93bd84771 --- /dev/null +++ b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 BayLibre, SAS +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/amlogic,axg-ge2d.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic GE2D Acceleration Unit + +maintainers: + - Neil Armstrong <narmstrong@baylibre.com> + +properties: + compatible: + enum: + - amlogic,axg-ge2d + + interrupts: + minItems: 1 + + reg: + minItems: 1 + + resets: + maxItems: 1 + + clocks: + minItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - resets + +additionalProperties: false + +examples: + - | + ge2d: ge2d@ff940000 { + compatible = "amlogic,axg-ge2d"; + reg = <0xff940000 0x10000>; + interrupts = <150>; + clocks = <&clk_ge2d>; + resets = <&reset_ge2d>; + }; diff --git a/Documentation/devicetree/bindings/media/coda.txt b/Documentation/devicetree/bindings/media/coda.txt deleted file mode 100644 index 90eb74cc1993..000000000000 --- a/Documentation/devicetree/bindings/media/coda.txt +++ /dev/null @@ -1,31 +0,0 @@ -Chips&Media Coda multi-standard codec IP -======================================== - -Coda codec IPs are present in i.MX SoCs in various versions, -called VPU (Video Processing Unit). - -Required properties: -- compatible : should be "fsl,<chip>-src" for i.MX SoCs: - (a) "fsl,imx27-vpu" for CodaDx6 present in i.MX27 - (b) "fsl,imx51-vpu" for CodaHx4 present in i.MX51 - (c) "fsl,imx53-vpu" for CODA7541 present in i.MX53 - (d) "fsl,imx6q-vpu" for CODA960 present in i.MX6q -- reg: should be register base and length as documented in the - SoC reference manual -- interrupts : Should contain the VPU interrupt. For CODA960, - a second interrupt is needed for the MJPEG unit. -- clocks : Should contain the ahb and per clocks, in the order - determined by the clock-names property. -- clock-names : Should be "ahb", "per" -- iram : phandle pointing to the SRAM device node - -Example: - -vpu: vpu@63ff4000 { - compatible = "fsl,imx53-vpu"; - reg = <0x63ff4000 0x1000>; - interrupts = <9>; - clocks = <&clks 63>, <&clks 63>; - clock-names = "ahb", "per"; - iram = <&ocram>; -}; diff --git a/Documentation/devicetree/bindings/media/coda.yaml b/Documentation/devicetree/bindings/media/coda.yaml new file mode 100644 index 000000000000..7bac0057faf7 --- /dev/null +++ b/Documentation/devicetree/bindings/media/coda.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/coda.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Chips&Media Coda multi-standard codec IP + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +description: |- + Coda codec IPs are present in i.MX SoCs in various versions, + called VPU (Video Processing Unit). + +properties: + compatible: + oneOf: + - items: + - const: fsl,imx27-vpu + - const: cnm,codadx6 + - items: + - const: fsl,imx51-vpu + - const: cnm,codahx4 + - items: + - const: fsl,imx53-vpu + - const: cnm,coda7541 + - items: + - enum: + - fsl,imx6dl-vpu + - fsl,imx6q-vpu + - const: cnm,coda960 + + reg: + maxItems: 1 + + clocks: + items: + - description: PER clock + - description: AHB interface clock + + clock-names: + items: + - const: per + - const: ahb + + resets: + maxItems: 1 + + iram: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle pointing to the SRAM device node + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + const: cnm,coda960 + then: + properties: + interrupts: + items: + - description: BIT processor interrupt + - description: JPEG unit interrupt + + interrupt-names: + items: + - const: bit + - const: jpeg + else: + properties: + interrupts: + items: + - description: BIT processor interrupt + + - if: + properties: + compatible: + contains: + enum: + - fsl,imx6dl-vpu + - fsl,imx6q-vpu + then: + properties: + power-domains: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle pointing to the PU power domain + maxItems: 1 + +examples: + - | + vpu: video-codec@63ff4000 { + compatible = "fsl,imx53-vpu", "cnm,coda7541"; + reg = <0x63ff4000 0x1000>; + interrupts = <9>; + clocks = <&clks 63>, <&clks 63>; + clock-names = "per", "ahb"; + iram = <&ocram>; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt deleted file mode 100644 index b3e688b77a38..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ /dev/null @@ -1,88 +0,0 @@ -* Analog Devices ADV7604/11/12 video decoder with HDMI receiver - -The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated -HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog -input, and the ADV7611 has one HDMI input and no analog input. The 7612 is -similar to the 7611 but has 2 HDMI inputs. - -These device tree bindings support the ADV7611/12 only at the moment. - -Required Properties: - - - compatible: Must contain one of the following - - "adi,adv7611" for the ADV7611 - - "adi,adv7612" for the ADV7612 - - - reg: I2C slave addresses - The ADV76xx has up to thirteen 256-byte maps that can be accessed via the - main I2C ports. Each map has it own I2C address and acts as a standard - slave device on the I2C bus. The main address is mandatory, others are - optional and revert to defaults if not specified. - - - hpd-gpios: References to the GPIOs that control the HDMI hot-plug - detection pins, one per HDMI input. The active flag indicates the GPIO - level that enables hot-plug detection. - -The device node must contain one 'port' child node per device input and output -port, in accordance with the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes -are numbered as follows. - - Port ADV7611 ADV7612 ------------------------------------------------------------- - HDMI 0 0, 1 - Digital output 1 2 - -The digital output port node must contain at least one endpoint. - -Optional Properties: - - - reset-gpios: Reference to the GPIO connected to the device's reset pin. - - default-input: Select which input is selected after reset. - - reg-names : Names of maps with programmable addresses. - It can contain any map needing a non-default address. - Possible maps names are : - "main", "avlink", "cec", "infoframe", "esdp", "dpp", "afe", - "rep", "edid", "hdmi", "test", "cp", "vdp" - -Optional Endpoint Properties: - - The following three properties are defined in video-interfaces.txt and are - valid for source endpoints only. - - - hsync-active: Horizontal synchronization polarity. Defaults to active low. - - vsync-active: Vertical synchronization polarity. Defaults to active low. - - pclk-sample: Pixel clock polarity. Defaults to output on the falling edge. - - If none of hsync-active, vsync-active and pclk-sample is specified the - endpoint will use embedded BT.656 synchronization. - -Example: - - hdmi_receiver@4c { - compatible = "adi,adv7611"; - /* - * The edid page will be accessible @ 0x66 on the I2C bus. All - * other maps will retain their default addresses. - */ - reg = <0x4c>, <0x66>; - reg-names = "main", "edid"; - - reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; - hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; - - #address-cells = <1>; - #size-cells = <0>; - - default-input = <0>; - - port@0 { - reg = <0>; - }; - port@1 { - reg = <1>; - hdmi_in: endpoint { - remote-endpoint = <&ccdc_in>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml new file mode 100644 index 000000000000..407baddfaa1d --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml @@ -0,0 +1,178 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/adv7604.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADV7604/11/12 video decoder with HDMI receiver + +maintainers: + - Hans Verkuil <hverkuil-cisco@xs4all.nl> + +description: + The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated + HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog + input, and the ADV7611 has one HDMI input and no analog input. The 7612 is + similar to the 7611 but has 2 HDMI inputs. + + These device tree bindings support the ADV7611/12 only at the moment. + +properties: + compatible: + items: + - enum: + - adi,adv7611 + - adi,adv7612 + + reg: + minItems: 1 + maxItems: 13 + + reg-names: + minItems: 1 + maxItems: 13 + items: + - const: main + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + hpd-gpios: + minItems: 1 + description: + References to the GPIOs that control the HDMI hot-plug detection pins, + one per HDMI input. The active flag indicates the GPIO level that + enables hot-plug detection. + + default-input: + maxItems: 1 + description: + Select which input is selected after reset. + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: adi,adv7611 + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@0: + type: object + description: Input port + port@1: + type: object + description: Output port + + required: + - port@1 + + additionalProperties: false + + required: + - ports + + - if: + properties: + compatible: + contains: + const: adi,adv7612 + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@2: + type: object + description: Output port + + patternProperties: + "^port@[0-1]$": + type: object + description: Input port + + required: + - port@2 + + additionalProperties: false + + required: + - ports + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hdmi_receiver@4c { + compatible = "adi,adv7611"; + /* + * The edid page will be accessible @ 0x66 on the I2C bus. All + * other maps will retain their default addresses. + */ + reg = <0x4c>, <0x66>; + reg-names = "main", "edid"; + + reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; + hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; + default-input = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + }; + + port@1 { + reg = <1>; + hdmi_in: endpoint { + remote-endpoint = <&ccdc_in>; + }; + }; + }; + + + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt deleted file mode 100644 index bd896e9f67d1..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt +++ /dev/null @@ -1,46 +0,0 @@ -* Aptina MT9V111 CMOS sensor ----------------------------- - -The Aptina MT9V111 is a 1/4-Inch VGA-format digital image sensor with a core -based on Aptina MT9V011 sensor and an integrated Image Flow Processor (IFP). - -The sensor has an active pixel array of 640x480 pixels and can output a number -of image resolution and formats controllable through a simple two-wires -interface. - -Required properties: --------------------- - -- compatible: shall be "aptina,mt9v111". -- clocks: reference to the system clock input provider. - -Optional properties: --------------------- - -- enable-gpios: output enable signal, pin name "OE#". Active low. -- standby-gpios: low power state control signal, pin name "STANDBY". - Active high. -- reset-gpios: chip reset signal, pin name "RESET#". Active low. - -The device node must contain one 'port' child node with one 'endpoint' child -sub-node for its digital output video port, in accordance with the video -interface bindings defined in: -Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: --------- - - &i2c1 { - camera@48 { - compatible = "aptina,mt9v111"; - reg = <0x48>; - - clocks = <&camera_clk>; - - port { - mt9v111_out: endpoint { - remote-endpoint = <&ceu_in>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml new file mode 100644 index 000000000000..ff9546e95d05 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/aptina,mt9v111.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Aptina MT9V111 CMOS sensor + +maintainers: + - Jacopo Mondi <jacopo@jmondi.org> + +description: | + The Aptina MT9V111 is a 1/4-Inch VGA-format digital image sensor with a core + based on Aptina MT9V011 sensor and an integrated Image Flow Processor (IFP). + + The sensor has an active pixel array of 640x480 pixels and can output a number + of image resolutions and formats controllable through a simple two-wires + interface. + +properties: + compatible: + const: aptina,mt9v111 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + enable-gpios: + description: Enable signal, pin name "OE#". Active low. + maxItems: 1 + + standby-gpios: + description: | + Low power state control signal, pin name "STANDBY". Active high. + maxItems: 1 + + reset-gpios: + description: Chip reset signal, pin name "RESET#". Active low. + maxItems: 1 + + port: + type: object + description: | + Output video port. See ../video-interfaces.txt. + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@48 { + compatible = "aptina,mt9v111"; + reg = <0x48>; + clocks = <&camera_clk>; + + port { + mt9v111_out: endpoint { + remote-endpoint = <&ceu_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml new file mode 100644 index 000000000000..d94bd67ccea1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2014--2020 Intel Corporation + +$id: http://devicetree.org/schemas/media/i2c/mipi-ccs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPI CCS, SMIA++ and SMIA compliant camera sensors + +maintainers: + - Sakari Ailus <sakari.ailus@linux.intel.com> + +description: + + CCS (Camera Command Set) is a raw Bayer camera sensor standard defined by the + MIPI Alliance; see + <URL:https://www.mipi.org/specifications/camera-command-set>. + + SMIA (Standard Mobile Imaging Architecture) is an image sensor standard + defined jointly by Nokia and ST. SMIA++, defined by Nokia, is an extension of + that. + + More detailed documentation can be found in + Documentation/devicetree/bindings/media/video-interfaces.txt . + +properties: + compatible: + oneOf: + - items: + - const: mipi-ccs-1.1 + - const: mipi-ccs + - items: + - const: mipi-ccs-1.0 + - const: mipi-ccs + - const: nokia,smia + + reg: + maxItems: 1 + + vana-supply: + description: Analogue voltage supply (VANA), sensor dependent. + maxItems: 1 + + vcore-supply: + description: Core voltage supply (VCore), sensor dependent. + maxItems: 1 + + vio-supply: + description: I/O voltage supply (VIO), sensor dependent. + maxItems: 1 + + clocks: + description: External clock to the sensor. + maxItems: 1 + + clock-frequency: + description: Frequency of the external clock to the sensor in Hz. + + reset-gpios: + description: Reset GPIO. Also commonly called XSHUTDOWN in hardware + documentation. + maxItems: 1 + + flash-leds: + description: Flash LED phandles. See ../video-interfaces.txt for details. + + lens-focus: + description: Lens focus controller phandles. See ../video-interfaces.txt + for details. + + rotation: + description: Rotation of the sensor. See ../video-interfaces.txt for + details. + enum: [ 0, 180 ] + + port: + type: object + properties: + endpoint: + type: object + properties: + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: List of allowed data link frequencies. + data-lanes: + minItems: 1 + maxItems: 8 + bus-type: + description: The type of the data bus. + oneOf: + - const: 1 # CSI-2 C-PHY + - const: 3 # CCP2 + - const: 4 # CSI-2 D-PHY + + required: + - link-frequencies + - data-lanes + - bus-type + +required: + - compatible + - reg + - clock-frequency + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c2 { + #address-cells = <1>; + #size-cells = <0>; + + clock-frequency = <400000>; + + camera-sensor@10 { + compatible = "mipi-ccs-1.0", "mipi-ccs"; + reg = <0x10>; + reset-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>; + vana-supply = <&vaux3>; + clocks = <&omap3_isp 0>; + clock-frequency = <9600000>; + port { + ccs_ep: endpoint { + data-lanes = <1 2>; + remote-endpoint = <&csi2a_ep>; + link-frequencies = /bits/ 64 <199200000 210000000 + 499200000>; + bus-type = <4>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt deleted file mode 100644 index 10ece8108081..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt +++ /dev/null @@ -1,66 +0,0 @@ -SMIA/SMIA++ sensor - -SMIA (Standard Mobile Imaging Architecture) is an image sensor standard -defined jointly by Nokia and ST. SMIA++, defined by Nokia, is an extension -of that. These definitions are valid for both types of sensors. - -More detailed documentation can be found in -Documentation/devicetree/bindings/media/video-interfaces.txt . - -The device node should contain a "port" node which may contain one or more -endpoint nodes, in accordance with video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt . - -Mandatory properties --------------------- - -- compatible: "nokia,smia" -- reg: I2C address (0x10, or an alternative address) -- vana-supply: Analogue voltage supply (VANA), typically 2,8 volts (sensor - dependent). -- clocks: External clock to the sensor -- clock-frequency: Frequency of the external clock to the sensor -- link-frequencies: List of allowed data link frequencies. An array of - 64-bit elements. - - -Optional properties -------------------- - -- reset-gpios: XSHUTDOWN GPIO -- flash-leds: See ../video-interfaces.txt -- lens-focus: See ../video-interfaces.txt -- rotation: Integer property; valid values are 0 (sensor mounted upright) - and 180 (sensor mounted upside down). See - ../video-interfaces.txt . - - -Endpoint node mandatory properties ----------------------------------- - -- data-lanes: <1..n> - - -Example -------- - -&i2c2 { - clock-frequency = <400000>; - - camera-sensor@10 { - compatible = "nokia,smia"; - reg = <0x10>; - reset-gpios = <&gpio3 20 0>; - vana-supply = <&vaux3>; - clocks = <&omap3_isp 0>; - clock-frequency = <9600000>; - nokia,nvm-size = <512>; /* 8 * 64 */ - link-frequencies = /bits/ 64 <199200000 210000000 499200000>; - port { - smiapp_ep: endpoint { - data-lanes = <1 2>; - remote-endpoint = <&csi2a_ep>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov2680.txt b/Documentation/devicetree/bindings/media/i2c/ov2680.txt deleted file mode 100644 index 11e925ed9dad..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov2680.txt +++ /dev/null @@ -1,46 +0,0 @@ -* Omnivision OV2680 MIPI CSI-2 sensor - -Required Properties: -- compatible: should be "ovti,ov2680". -- clocks: reference to the xvclk input clock. -- clock-names: should be "xvclk". -- DOVDD-supply: Digital I/O voltage supply. -- DVDD-supply: Digital core voltage supply. -- AVDD-supply: Analog voltage supply. - -Optional Properties: -- reset-gpios: reference to the GPIO connected to the powerdown/reset pin, - if any. This is an active low signal to the OV2680. - -The device node must contain one 'port' child node for its digital output -video port, and this port must have a single endpoint in accordance with - the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Endpoint node required properties for CSI-2 connection are: -- remote-endpoint: a phandle to the bus receiver's endpoint node. -- clock-lanes: should be set to <0> (clock lane on hardware lane 0). -- data-lanes: should be set to <1> (one CSI-2 lane supported). - -Example: - -&i2c2 { - ov2680: camera-sensor@36 { - compatible = "ovti,ov2680"; - reg = <0x36>; - clocks = <&osc>; - clock-names = "xvclk"; - reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; - DOVDD-supply = <&sw2_reg>; - DVDD-supply = <&sw2_reg>; - AVDD-supply = <®_peri_3p15v>; - - port { - ov2680_to_mipi: endpoint { - remote-endpoint = <&mipi_from_sensor>; - clock-lanes = <0>; - data-lanes = <1>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov772x.txt b/Documentation/devicetree/bindings/media/i2c/ov772x.txt deleted file mode 100644 index 0b3ede5b8e6a..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov772x.txt +++ /dev/null @@ -1,40 +0,0 @@ -* Omnivision OV7720/OV7725 CMOS sensor - -The Omnivision OV7720/OV7725 sensor supports multiple resolutions output, -such as VGA, QVGA, and any size scaling down from CIF to 40x30. It also can -support the YUV422, RGB565/555/444, GRB422 or raw RGB output formats. - -Required Properties: -- compatible: shall be one of - "ovti,ov7720" - "ovti,ov7725" -- clocks: reference to the xclk input clock. - -Optional Properties: -- reset-gpios: reference to the GPIO connected to the RSTB pin which is - active low, if any. -- powerdown-gpios: reference to the GPIO connected to the PWDN pin which is - active high, if any. - -The device node shall contain one 'port' child node with one child 'endpoint' -subnode for its digital output video port, in accordance with the video -interface bindings defined in Documentation/devicetree/bindings/media/ -video-interfaces.txt. - -Example: - -&i2c0 { - ov772x: camera@21 { - compatible = "ovti,ov7725"; - reg = <0x21>; - reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_LOW>; - powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_LOW>; - clocks = <&xclk>; - - port { - ov772x_0: endpoint { - remote-endpoint = <&vcap1_in0>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml new file mode 100644 index 000000000000..1c3879ec4122 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov02a10.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV02A10 CMOS Sensor Device Tree Bindings + +maintainers: + - Dongchun Zhu <dongchun.zhu@mediatek.com> + +description: |- + The Omnivision OV02A10 is a low-cost, high performance, 1/5-inch, 2 megapixel + image sensor, which is the latest production derived from Omnivision's CMOS + image sensor technology. Ihis chip supports high frame rate speeds up to 30fps + @ 1600x1200 (UXGA) resolution transferred over a 1-lane MIPI interface. The + sensor output is available via CSI-2 serial data output. + +properties: + compatible: + const: ovti,ov02a10 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + description: + External clock for the sensor. + items: + - const: eclk + + clock-frequency: + description: + Frequency of the eclk clock in Hz. + + dovdd-supply: + description: + Definition of the regulator used as Digital I/O voltage supply. + + avdd-supply: + description: + Definition of the regulator used as Analog voltage supply. + + dvdd-supply: + description: + Definition of the regulator used as Digital core voltage supply. + + powerdown-gpios: + description: + Must be the device tree identifier of the GPIO connected to the + PD_PAD pin. This pin is used to place the OV02A10 into standby mode + or shutdown mode. As the line needs to be high for the powerdown mode + to be active, it should be marked GPIO_ACTIVE_HIGH. + maxItems: 1 + + reset-gpios: + description: + Must be the device tree identifier of the GPIO connected to the + RST_PD pin. If specified, it will be asserted during driver probe. + As the line needs to be low for the reset to be active, it should be + marked GPIO_ACTIVE_LOW. + maxItems: 1 + + rotation: + description: + Definition of the sensor's placement. + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - enum: + - 0 # Sensor Mounted Upright + - 180 # Sensor Mounted Upside Down + default: 0 + + # See ../video-interfaces.txt for details + port: + type: object + additionalProperties: false + description: + Output port node, single endpoint describing the CSI-2 transmitter. + + properties: + endpoint: + type: object + additionalProperties: false + + properties: + link-frequencies: true + ovti,mipi-clock-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + description: + Definition of MIPI clock voltage unit. This entry corresponds to + the link speed defined by the 'link-frequencies' property. + If present, the value shall be in the range of 0-4. + default: 4 + remote-endpoint: true + + required: + - link-frequencies + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - clock-names + - clock-frequency + - dovdd-supply + - avdd-supply + - dvdd-supply + - powerdown-gpios + - reset-gpios + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ov02a10: camera-sensor@3d { + compatible = "ovti,ov02a10"; + reg = <0x3d>; + + powerdown-gpios = <&pio 107 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pio 109 GPIO_ACTIVE_LOW>; + + clocks = <&ov02a10_clk>; + clock-names = "eclk"; + clock-frequency = <24000000>; + + rotation = <180>; + + dovdd-supply = <&ov02a10_dovdd>; + avdd-supply = <&ov02a10_avdd>; + dvdd-supply = <&ov02a10_dvdd>; + + port { + wcam_out: endpoint { + link-frequencies = /bits/ 64 <390000000>; + ovti,mipi-clock-voltage = <3>; + remote-endpoint = <&mipi_in_wcam>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml new file mode 100644 index 000000000000..43bf749807e1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov2680.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV2680 CMOS Sensor + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: |- + The OV2680 color sensor is a low voltage, high performance 1/5 inch UXGA (2 + megapixel) CMOS image sensor that provides a single-chip UXGA (1600 x 1200) + camera. It provides full-frame, sub-sampled, or windowed 10-bit images in + various formats via the control of the Serial Camera Control Bus (SCCB) + interface. The OV2680 has an image array capable of operating at up to 30 + frames per second (fps) in UXGA resolution. + +properties: + compatible: + const: ovti,ov2680 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: xvclk + + reset-gpios: + description: + The phandle and specifier for the GPIO that controls sensor reset. + This corresponds to the hardware pin XSHUTDOWN which is physically + active low. + maxItems: 1 + + dovdd-supply: + description: + Definition of the regulator used as interface power supply. + + avdd-supply: + description: + Definition of the regulator used as analog power supply. + + dvdd-supply: + description: + Definition of the regulator used as digital power supply. + + port: + type: object + description: + A node containing an output port node with an endpoint definition + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + - clocks + - clock-names + - dovdd-supply + - avdd-supply + - dvdd-supply + - reset-gpios + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ov2680: camera-sensor@36 { + compatible = "ovti,ov2680"; + reg = <0x36>; + clocks = <&osc>; + clock-names = "xvclk"; + reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; + + dovdd-supply = <&sw2_reg>; + dvdd-supply = <&sw2_reg>; + avdd-supply = <®_peri_3p15v>; + + port { + ov2680_to_mipi: endpoint { + remote-endpoint = <&mipi_from_sensor>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml new file mode 100644 index 000000000000..6866c2cdac50 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov772x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV7720/OV7725 CMOS sensor + +maintainers: + - Jacopo Mondi <jacopo@jmondi.org> + +description: | + The Omnivision OV7720/OV7725 sensor supports multiple resolutions output, + such as VGA, QVGA, and any size scaling down from CIF to 40x30. It also can + support the YUV422, RGB565/555/444, GRB422 or raw RGB output formats. + +properties: + compatible: + enum: + - ovti,ov7720 + - ovti,ov7725 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + reset-gpios: + description: | + Reference to the GPIO connected to the RSTB pin which is active low. + maxItems: 1 + + powerdown-gpios: + description: | + Reference to the GPIO connected to the PWDN pin which is active high. + maxItems: 1 + + port: + type: object + description: | + Video output port. See ../video-interfaces.txt. + + properties: + endpoint: + type: object + + properties: + bus-type: + enum: [5, 6] + + bus-width: + enum: [8, 10] + default: 10 + + data-shift: + enum: [0, 2] + default: 0 + + hsync-active: + enum: [0, 1] + default: 1 + + vsync-active: + enum: [0, 1] + default: 1 + + pclk-sample: + enum: [0, 1] + default: 1 + + allOf: + - if: + properties: + bus-type: + const: 6 + then: + properties: + hsync-active: false + vsync-active: false + + - if: + properties: + bus-width: + const: 10 + then: + properties: + data-shift: + const: 0 + + required: + - bus-type + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + ov772x: camera@21 { + compatible = "ovti,ov7725"; + reg = <0x21>; + reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_LOW>; + clocks = <&xclk>; + + port { + ov772x_0: endpoint { + bus-type = <5>; + vsync-active = <0>; + hsync-active = <0>; + pclk-sample = <0>; + bus-width = <8>; + data-shift = <0>; + remote-endpoint = <&vcap1_in0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt b/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt deleted file mode 100644 index f11f28a5fda4..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Sony 1/3.06-Inch 13.13Mp CMOS Digital Image Sensor - -The Sony imx214 is a 1/3.06-inch CMOS active pixel digital image sensor with -an active array size of 4224H x 3200V. It is programmable through an I2C -interface. -Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a maximum -throughput of 1.2Gbps/lane. - - -Required Properties: -- compatible: Shall be "sony,imx214". -- reg: I2C bus address of the device. Depending on how the sensor is wired, - it shall be <0x10> or <0x1a>; -- enable-gpios: GPIO descriptor for the enable pin. -- vdddo-supply: Chip digital IO regulator (1.8V). -- vdda-supply: Chip analog regulator (2.7V). -- vddd-supply: Chip digital core regulator (1.12V). -- clocks: Reference to the xclk clock. -- clock-frequency: Frequency of the xclk clock. - -Optional Properties: -- flash-leds: See ../video-interfaces.txt -- lens-focus: See ../video-interfaces.txt - -The imx214 device node shall contain one 'port' child node with -an 'endpoint' subnode. For further reading on port node refer to -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Required Properties on endpoint: -- data-lanes: check ../video-interfaces.txt -- link-frequencies: check ../video-interfaces.txt -- remote-endpoint: check ../video-interfaces.txt - -Example: - - camera-sensor@1a { - compatible = "sony,imx214"; - reg = <0x1a>; - vdddo-supply = <&pm8994_lvs1>; - vddd-supply = <&camera_vddd_1v12>; - vdda-supply = <&pm8994_l17>; - lens-focus = <&ad5820>; - enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>; - clocks = <&mmcc CAMSS_MCLK0_CLK>; - clock-frequency = <24000000>; - port { - imx214_ep: endpoint { - data-lanes = <1 2 3 4>; - link-frequencies = /bits/ 64 <480000000>; - remote-endpoint = <&csiphy0_ep>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml new file mode 100644 index 000000000000..1a3590dd0e98 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx214.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony 1/3.06-Inch 13.13MP CMOS Digital Image Sensor + +maintainers: + - Ricardo Ribalda <ribalda@kernel.org> + +description: | + The Sony IMX214 is a 1/3.06-inch CMOS active pixel digital image sensor with + an active array size of 4224H x 3200V. It is programmable through an I2C + interface. Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a + maximum throughput of 1.2Gbps/lane. + +properties: + compatible: + const: sony,imx214 + + reg: + enum: + - 0x10 + - 0x1a + + clocks: + description: Reference to the xclk clock. + maxItems: 1 + + clock-frequency: + description: Frequency of the xclk clock in Hz. + + enable-gpios: + description: GPIO descriptor for the enable pin. + maxItems: 1 + + vdddo-supply: + description: Chip digital IO regulator (1.8V). + maxItems: 1 + + vdda-supply: + description: Chip analog regulator (2.7V). + maxItems: 1 + + vddd-supply: + description: Chip digital core regulator (1.12V). + maxItems: 1 + + flash-leds: + description: See ../video-interfaces.txt + + lens-focus: + description: See ../video-interfaces.txt + + port: + type: object + description: | + Video output port. See ../video-interfaces.txt. + + properties: + endpoint: + type: object + + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: See ../video-interfaces.txt + anyOf: + - items: + - const: 1 + - const: 2 + - items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: See ../video-interfaces.txt + + required: + - data-lanes + - link-frequencies + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-frequency + - enable-gpios + - vdddo-supply + - vdda-supply + - vddd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera-sensor@1a { + compatible = "sony,imx214"; + reg = <0x1a>; + vdddo-supply = <&pm8994_lvs1>; + vddd-supply = <&camera_vddd_1v12>; + vdda-supply = <&pm8994_l17>; + lens-focus = <&ad5820>; + enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>; + clocks = <&camera_clk>; + clock-frequency = <24000000>; + + port { + imx214_ep: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <480000000>; + remote-endpoint = <&csiphy0_ep>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/imx7-csi.txt b/Documentation/devicetree/bindings/media/imx7-csi.txt deleted file mode 100644 index d80ceefa0c00..000000000000 --- a/Documentation/devicetree/bindings/media/imx7-csi.txt +++ /dev/null @@ -1,42 +0,0 @@ -Freescale i.MX7 CMOS Sensor Interface -===================================== - -csi node --------- - -This is device node for the CMOS Sensor Interface (CSI) which enables the chip -to connect directly to external CMOS image sensors. - -Required properties: - -- 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 - Documentation/devicetree/bindings/clock/clock-bindings.txt for details; -- clock-names : must contain "mclk"; - -The device node shall contain one 'port' child node with one child 'endpoint' -node, according to the bindings defined in: -Documentation/devicetree/bindings/media/video-interfaces.txt. - -In the following example a remote endpoint is a video multiplexer. - -example: - - csi: csi@30710000 { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "fsl,imx7-csi"; - reg = <0x30710000 0x10000>; - interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7D_CSI_MCLK_ROOT_CLK>; - clock-names = "mclk"; - - port { - csi_from_csi_mux: endpoint { - remote-endpoint = <&csi_mux_to_csi>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt b/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt deleted file mode 100644 index 71fd74ed3ec8..000000000000 --- a/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt +++ /dev/null @@ -1,90 +0,0 @@ -Freescale i.MX7 Mipi CSI2 -========================= - -mipi_csi2 node --------------- - -This is the device node for the MIPI CSI-2 receiver core in i.MX7 SoC. It is -compatible with previous version of Samsung D-phy. - -Required properties: - -- compatible : "fsl,imx7-mipi-csi2"; -- reg : base address and length of the register set for the device; -- interrupts : should contain MIPI CSIS interrupt; -- clocks : list of clock specifiers, see - Documentation/devicetree/bindings/clock/clock-bindings.txt for details; -- clock-names : must contain "pclk", "wrap" and "phy" entries, matching - entries in the clock property; -- power-domains : a phandle to the power domain, see - Documentation/devicetree/bindings/power/power_domain.txt for details. -- reset-names : should include following entry "mrst"; -- resets : a list of phandle, should contain reset entry of - reset-names; -- phy-supply : from the generic phy bindings, a phandle to a regulator that - provides power to MIPI CSIS core; - -Optional properties: - -- clock-frequency : The IP's main (system bus) clock frequency in Hz, default - value when this property is not specified is 166 MHz; -- fsl,csis-hs-settle : differential receiver (HS-RX) settle time; - -The device node should contain two 'port' child nodes with one child 'endpoint' -node, according to the bindings defined in: - Documentation/devicetree/bindings/ media/video-interfaces.txt. - The following are properties specific to those nodes. - -port node ---------- - -- reg : (required) can take the values 0 or 1, where 0 shall be - related to the sink port and port 1 shall be the source - one; - -endpoint node -------------- - -- data-lanes : (required) an array specifying active physical MIPI-CSI2 - data input lanes and their mapping to logical lanes; this - shall only be applied to port 0 (sink port), the array's - content is unused only its length is meaningful, - in this case the maximum length supported is 2; - -example: - - mipi_csi: mipi-csi@30750000 { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "fsl,imx7-mipi-csi2"; - reg = <0x30750000 0x10000>; - interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7D_IPG_ROOT_CLK>, - <&clks IMX7D_MIPI_CSI_ROOT_CLK>, - <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; - clock-names = "pclk", "wrap", "phy"; - clock-frequency = <166000000>; - power-domains = <&pgc_mipi_phy>; - phy-supply = <®_1p0d>; - resets = <&src IMX7_RESET_MIPI_PHY_MRST>; - reset-names = "mrst"; - fsl,csis-hs-settle = <3>; - - port@0 { - reg = <0>; - - mipi_from_sensor: endpoint { - remote-endpoint = <&ov2680_to_mipi>; - data-lanes = <1>; - }; - }; - - port@1 { - reg = <1>; - - mipi_vc0_to_csi_mux: endpoint { - remote-endpoint = <&csi_mux_from_mipi_vc0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml new file mode 100644 index 000000000000..4e81a47e60ac --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx7-csi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX7 CMOS Sensor Interface + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: | + This is device node for the CMOS Sensor Interface (CSI) which enables the + chip to connect directly to external CMOS image sensors. + +properties: + compatible: + enum: + - fsl,imx7-csi + - fsl,imx6ul-csi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: mclk + + port: + type: object + description: + A node containing input port nodes with endpoint definitions as documented + in Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7d-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + csi: csi@30710000 { + compatible = "fsl,imx7-csi"; + reg = <0x30710000 0x10000>; + interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7D_CSI_MCLK_ROOT_CLK>; + clock-names = "mclk"; + + port { + csi_from_csi_mux: endpoint { + remote-endpoint = <&csi_mux_to_csi>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml new file mode 100644 index 000000000000..0668332959e7 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx7-mipi-csi2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX7 Mipi CSI2 + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: | + This is the device node for the MIPI CSI-2 receiver core in i.MX7 soc. It is + compatible with previous version of samsung d-phy. + +properties: + compatible: + const: fsl,imx7-mipi-csi2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + maxItems: 3 + + clock-names: + items: + - const: pclk + - const: wrap + - const: phy + + power-domains: + maxItems: 1 + + phy-supply: + description: + Phandle to a regulator that provides power to the PHY. This + regulator will be managed during the PHY power on/off sequence. + + resets: + maxItems: 1 + + reset-names: + const: mrst + + clock-frequency: + description: + The IP main (system bus) clock frequency in Hertz + default: 166000000 + + fsl,csis-hs-settle: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Differential receiver (HS-RX) settle time + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@0: + type: object + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + reg: + const: 0 + + endpoint: + type: object + + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: See ../video-interfaces.txt + oneOf: + - items: + - const: 1 + - items: + - const: 1 + - const: 2 + + remote-endpoint: true + + required: + - data-lanes + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + + port@1: + type: object + description: + Output port node + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - power-domains + - phy-supply + - resets + - reset-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7d-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/reset/imx7-reset.h> + + mipi_csi: mipi-csi@30750000 { + compatible = "fsl,imx7-mipi-csi2"; + reg = <0x30750000 0x10000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&clks IMX7D_IPG_ROOT_CLK>, + <&clks IMX7D_MIPI_CSI_ROOT_CLK>, + <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; + clock-names = "pclk", "wrap", "phy"; + clock-frequency = <166000000>; + + power-domains = <&pgc_mipi_phy>; + phy-supply = <®_1p0d>; + resets = <&src IMX7_RESET_MIPI_PHY_MRST>; + reset-names = "mrst"; + fsl,csis-hs-settle = <3>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mipi_from_sensor: endpoint { + remote-endpoint = <&ov2680_to_mipi>; + data-lanes = <1>; + }; + }; + + port@1 { + reg = <1>; + + mipi_vc0_to_csi_mux: endpoint { + remote-endpoint = <&csi_mux_from_mipi_vc0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/qcom,camss.txt b/Documentation/devicetree/bindings/media/qcom,camss.txt index 09eb6ed99114..498234629e21 100644 --- a/Documentation/devicetree/bindings/media/qcom,camss.txt +++ b/Documentation/devicetree/bindings/media/qcom,camss.txt @@ -8,6 +8,7 @@ Qualcomm Camera Subsystem Definition: Should contain one of: - "qcom,msm8916-camss" - "qcom,msm8996-camss" + - "qcom,sdm660-camss" - reg: Usage: required Value type: <prop-encoded-array> @@ -64,30 +65,36 @@ Qualcomm Camera Subsystem Value type: <stringlist> Definition: Should contain the following entries: - "top_ahb" + - "throttle_axi" (660 only) - "ispif_ahb" - "csiphy0_timer" - "csiphy1_timer" - "csiphy2_timer" (8996 only) + - "csiphy_ahb2crif" (660 only) - "csi0_ahb" - "csi0" - "csi0_phy" - "csi0_pix" - "csi0_rdi" + - "cphy_csid0" (660 only) - "csi1_ahb" - "csi1" - "csi1_phy" - "csi1_pix" - "csi1_rdi" + - "cphy_csid1" (660 only) - "csi2_ahb" (8996 only) - "csi2" (8996 only) - "csi2_phy" (8996 only) - "csi2_pix" (8996 only) - "csi2_rdi" (8996 only) + - "cphy_csid2" (660 only) - "csi3_ahb" (8996 only) - "csi3" (8996 only) - "csi3_phy" (8996 only) - "csi3_pix" (8996 only) - "csi3_rdi" (8996 only) + - "cphy_csid3" (660 only) - "ahb" - "vfe0" - "csi_vfe0" diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml index 8ad2cba5f61f..946441b4e1a5 100644 --- a/Documentation/devicetree/bindings/media/rc.yaml +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -83,6 +83,7 @@ properties: - rc-it913x-v2 - rc-kaiomy - rc-khadas + - rc-khamsin - rc-kworld-315u - rc-kworld-pc150u - rc-kworld-plus-tv-analog @@ -102,6 +103,7 @@ properties: - rc-npgtech - rc-odroid - rc-pctv-sedna + - rc-pine64 - rc-pinnacle-color - rc-pinnacle-grey - rc-pinnacle-pctv-hd diff --git a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml new file mode 100644 index 000000000000..2004c054ed1a --- /dev/null +++ b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml @@ -0,0 +1,215 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR MIT) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/rockchip-isp1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip SoC Image Signal Processing unit v1 + +maintainers: + - Helen Koike <helen.koike@collabora.com> + +description: | + Rockchip ISP1 is the Camera interface for the Rockchip series of SoCs + which contains image processing, scaling, and compression functions. + +properties: + compatible: + const: rockchip,rk3399-cif-isp + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + items: + # isp0 and isp1 + - description: ISP clock + - description: ISP AXI clock + - description: ISP AHB clock + # only for isp1 + - description: ISP Pixel clock + + clock-names: + minItems: 3 + items: + # isp0 and isp1 + - const: isp + - const: aclk + - const: hclk + # only for isp1 + - const: pclk_isp + + iommus: + maxItems: 1 + + phys: + maxItems: 1 + description: phandle for the PHY port + + phy-names: + const: dphy + + power-domains: + maxItems: 1 + + # See ./video-interfaces.txt for details + ports: + type: object + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: connection point for sensors at MIPI-DPHY RX0 + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: + const: 0 + + patternProperties: + endpoint: + type: object + additionalProperties: false + + properties: + reg: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + remote-endpoint: true + + required: + - reg + - "#address-cells" + - "#size-cells" + + required: + - "#address-cells" + - "#size-cells" + - port@0 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - iommus + - phys + - phy-names + - power-domains + - ports + +if: + properties: + compatible: + contains: + const: rockchip,rk3399-cif-isp +then: + properties: + clocks: + minItems: 3 + maxItems: 4 + clock-names: + minItems: 3 + maxItems: 4 + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/rk3399-power.h> + + parent0: parent { + #address-cells = <2>; + #size-cells = <2>; + + isp0: isp0@ff910000 { + compatible = "rockchip,rk3399-cif-isp"; + reg = <0x0 0xff910000 0x0 0x4000>; + interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&cru SCLK_ISP0>, + <&cru ACLK_ISP0_WRAPPER>, + <&cru HCLK_ISP0_WRAPPER>; + clock-names = "isp", "aclk", "hclk"; + iommus = <&isp0_mmu>; + phys = <&dphy>; + phy-names = "dphy"; + power-domains = <&power RK3399_PD_ISP0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + mipi_in_wcam: endpoint@0 { + reg = <0>; + remote-endpoint = <&wcam_out>; + data-lanes = <1 2>; + }; + + mipi_in_ucam: endpoint@1 { + reg = <1>; + remote-endpoint = <&ucam_out>; + data-lanes = <1>; + }; + }; + }; + }; + + i2c7: i2c { + #address-cells = <1>; + #size-cells = <0>; + + wcam: camera@36 { + compatible = "ovti,ov5695"; + reg = <0x36>; + + port { + wcam_out: endpoint { + remote-endpoint = <&mipi_in_wcam>; + data-lanes = <1 2>; + }; + }; + }; + + ucam: camera@3c { + compatible = "ovti,ov2685"; + reg = <0x3c>; + + port { + ucam_out: endpoint { + remote-endpoint = <&mipi_in_ucam>; + data-lanes = <1>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml index 3fe778cb5cc3..c18574bb3e81 100644 --- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml @@ -44,6 +44,43 @@ properties: bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + properties: + endpoint: + type: object + + properties: + bus-type: + enum: [5, 6] + default: 5 + + bus-width: + enum: [8, 10, 12, 14] + default: 8 + + remote-endpoint: true + + allOf: + - if: + properties: + bus-type: + const: 6 + + then: + properties: + hsync-active: false + vsync-active: false + bus-width: + enum: [8] + + required: + - remote-endpoint + - bus-type + - pclk-sample + + unevaluatedProperties: false + + additionalProperties: false + required: - compatible - reg @@ -75,6 +112,7 @@ examples: port { dcmi_0: endpoint { remote-endpoint = <&ov5640_0>; + bus-type = <5>; bus-width = <8>; hsync-active = <0>; vsync-active = <0>; diff --git a/Documentation/devicetree/bindings/mfd/ene-kb3930.yaml b/Documentation/devicetree/bindings/mfd/ene-kb3930.yaml index 074243c40891..08af356f5d27 100644 --- a/Documentation/devicetree/bindings/mfd/ene-kb3930.yaml +++ b/Documentation/devicetree/bindings/mfd/ene-kb3930.yaml @@ -17,7 +17,7 @@ properties: compatible: items: - enum: - - dell,wyse-ariel-ec # Dell Wyse Ariel board (3020) + - dell,wyse-ariel-ec # Dell Wyse Ariel board (3020) - const: ene,kb3930 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index f49c0d5d31ad..76bf16ee27ec 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -59,6 +59,14 @@ properties: whether this nvram is present or not. type: boolean + mtk,rpmsg-name: + description: + Must be defined if the cros-ec is a rpmsg device for a Mediatek + ARM Cortex M4 Co-processor. Contains the name pf the rpmsg + device. Used to match the subnode to the rpmsg device announced by + the SCP. + $ref: "/schemas/types.yaml#/definitions/string" + spi-max-frequency: description: Maximum SPI frequency of the device in Hz. @@ -71,6 +79,54 @@ properties: wakeup-source: description: Button can wake-up the system. + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + typec: + $ref: "/schemas/chrome/google,cros-ec-typec.yaml#" + + ec-pwm: + $ref: "/schemas/pwm/google,cros-ec-pwm.yaml#" + + keyboard-controller: + $ref: "/schemas/input/google,cros-ec-keyb.yaml#" + + codecs: + type: object + additionalProperties: false + + properties: + '#address-cells': + const: 2 + + '#size-cells': + const: 1 + + patternProperties: + "^ec-codec@[a-f0-9]+$": + type: object + $ref: "/schemas/sound/google,cros-ec-codec.yaml#" + + required: + - "#address-cells" + - "#size-cells" + +patternProperties: + "^i2c-tunnel[0-9]*$": + type: object + $ref: "/schemas/i2c/google,cros-ec-i2c-tunnel.yaml#" + + "^regulator@[0-9]+$": + type: object + $ref: "/schemas/regulator/google,cros-ec-regulator.yaml#" + + "^extcon[0-9]*$": + type: object + $ref: "/schemas/extcon/extcon-usbc-cros-ec.yaml#" + required: - compatible diff --git a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml index dc21b4630c25..ee00d414df10 100644 --- a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml +++ b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml @@ -52,4 +52,7 @@ properties: items: - const: yna,cu2000-neo - const: ingenic,x2000e + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/mips/loongson/devices.yaml b/Documentation/devicetree/bindings/mips/loongson/devices.yaml index d25e80aa8b2a..9fee6708e6f5 100644 --- a/Documentation/devicetree/bindings/mips/loongson/devices.yaml +++ b/Documentation/devicetree/bindings/mips/loongson/devices.yaml @@ -36,4 +36,7 @@ properties: - description: Virtual Loongson64 Quad Core + VirtIO items: - const: loongson,loongson64v-4core-virtio + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml index 58fe9d02a781..0753289fba84 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -32,11 +32,11 @@ allOf: clock-output-names: oneOf: - items: - - const: clk_out_sd0 - - const: clk_in_sd0 + - const: clk_out_sd0 + - const: clk_in_sd0 - items: - - const: clk_out_sd1 - - const: clk_in_sd1 + - const: clk_out_sd1 + - const: clk_in_sd1 properties: compatible: diff --git a/Documentation/devicetree/bindings/mmc/microchip,dw-sparx5-sdhci.yaml b/Documentation/devicetree/bindings/mmc/microchip,dw-sparx5-sdhci.yaml index 55883290543b..69ff065c9a39 100644 --- a/Documentation/devicetree/bindings/mmc/microchip,dw-sparx5-sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/microchip,dw-sparx5-sdhci.yaml @@ -46,6 +46,8 @@ required: - clocks - clock-names +unevaluatedProperties: false + examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index ac79f3adf20b..1ae945434c53 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -3,7 +3,7 @@ %YAML 1.2 --- $id: "http://devicetree.org/schemas/mmc/sdhci-am654.yaml#" -$schema : "http://devicetree.org/meta-schemas/core.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" title: TI AM654 MMC Controller @@ -163,13 +163,12 @@ properties: ti,driver-strength-ohm: description: DLL drive strength in ohms $ref: "/schemas/types.yaml#/definitions/uint32" - oneOf: - - enum: - - 33 - - 40 - - 50 - - 66 - - 100 + enum: + - 33 + - 40 + - 50 + - 66 + - 100 ti,strobe-sel: description: strobe select delay for HS400 speed mode. @@ -187,6 +186,8 @@ required: - clock-names - ti,otap-del-sel-legacy +unevaluatedProperties: false + examples: - | #include <dt-bindings/interrupt-controller/irq.h> diff --git a/Documentation/devicetree/bindings/net/can/can-controller.yaml b/Documentation/devicetree/bindings/net/can/can-controller.yaml new file mode 100644 index 000000000000..9cf2ae097156 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/can-controller.yaml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/can/can-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: CAN Controller Generic Binding + +maintainers: + - Marc Kleine-Budde <mkl@pengutronix.de> + +properties: + $nodename: + pattern: "^can(@.*)?$" + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml new file mode 100644 index 000000000000..13875eab2ed6 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -0,0 +1,139 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/can/fsl,flexcan.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: + Flexcan CAN controller on Freescale's ARM and PowerPC system-on-a-chip (SOC). + +maintainers: + - Marc Kleine-Budde <mkl@pengutronix.de> + +allOf: + - $ref: can-controller.yaml# + +properties: + compatible: + oneOf: + - enum: + - fsl,imx8qm-flexcan + - fsl,imx8mp-flexcan + - fsl,imx6q-flexcan + - fsl,imx28-flexcan + - fsl,imx25-flexcan + - fsl,p1010-flexcan + - fsl,vf610-flexcan + - fsl,ls1021ar2-flexcan + - fsl,lx2160ar1-flexcan + - items: + - enum: + - fsl,imx53-flexcan + - fsl,imx35-flexcan + - const: fsl,imx25-flexcan + - items: + - enum: + - fsl,imx7d-flexcan + - fsl,imx6ul-flexcan + - fsl,imx6sx-flexcan + - const: fsl,imx6q-flexcan + - items: + - enum: + - fsl,ls1028ar1-flexcan + - const: fsl,lx2160ar1-flexcan + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: ipg + - const: per + + clock-frequency: + description: | + The oscillator frequency driving the flexcan device, filled in by the + boot loader. This property should only be used the used operating system + doesn't support the clocks and clock-names property. + + xceiver-supply: + description: Regulator that powers the CAN transceiver. + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: | + This means the registers of FlexCAN controller are big endian. This is + optional property.i.e. if this property is not present in device tree + node then controller is assumed to be little endian. If this property is + present then controller is assumed to be big endian. + + fsl,stop-mode: + description: | + Register bits of stop mode control. + + The format should be as follows: + <gpr req_gpr req_bit> + gpr is the phandle to general purpose register node. + req_gpr is the gpr register offset of CAN stop request. + req_bit is the bit offset of CAN stop request. + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: The 'gpr' is the phandle to general purpose register node. + - description: The 'req_gpr' is the gpr register offset of CAN stop request. + maximum: 0xff + - description: The 'req_bit' is the bit offset of CAN stop request. + maximum: 0x1f + + fsl,clk-source: + description: | + 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) + $ref: /schemas/types.yaml#/definitions/uint32 + default: 1 + minimum: 0 + maximum: 1 + + wakeup-source: + $ref: /schemas/types.yaml#/definitions/flag + description: + Enable CAN remote wakeup. + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + can@1c000 { + compatible = "fsl,p1010-flexcan"; + reg = <0x1c000 0x1000>; + interrupts = <48 0x2>; + interrupt-parent = <&mpic>; + clock-frequency = <200000000>; + fsl,clk-source = <0>; + }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + + can@2090000 { + compatible = "fsl,imx6q-flexcan"; + reg = <0x02090000 0x4000>; + interrupts = <0 110 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks 1>, <&clks 2>; + clock-names = "ipg", "per"; + fsl,stop-mode = <&gpr 0x34 28>; + }; diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt deleted file mode 100644 index e10b6eb955e1..000000000000 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ /dev/null @@ -1,57 +0,0 @@ -Flexcan CAN controller on Freescale's ARM and PowerPC system-on-a-chip (SOC). - -Required properties: - -- compatible : Should be "fsl,<processor>-flexcan" - - where <processor> is imx8qm, imx6q, imx28, imx53, imx35, imx25, p1010, - vf610, ls1021ar2, lx2160ar1, ls1028ar1. - - The ls1028ar1 must be followed by lx2160ar1, e.g. - - "fsl,ls1028ar1-flexcan", "fsl,lx2160ar1-flexcan" - - An implementation should also claim any of the following compatibles - that it is fully backwards compatible with: - - - fsl,p1010-flexcan - -- reg : Offset and length of the register set for this device -- interrupts : Interrupt tuple for this device - -Optional properties: - -- clock-frequency : The oscillator frequency driving the flexcan device - -- xceiver-supply: Regulator that powers the CAN transceiver - -- big-endian: This means the registers of FlexCAN controller are big endian. - This is optional property.i.e. if this property is not present in - device tree node then controller is assumed to be little endian. - if this property is present then controller is assumed to be big - endian. - -- fsl,stop-mode: register bits of stop mode control, the format is - <&gpr req_gpr req_bit>. - gpr is the phandle to general purpose register node. - req_gpr is the gpr register offset of CAN stop request. - req_bit is the bit offset of CAN stop request. - -- 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 { - compatible = "fsl,p1010-flexcan"; - reg = <0x1c000 0x1000>; - 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/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt index 3613c2c8f75d..0968b40aef1e 100644 --- a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -33,7 +33,7 @@ tcan4x5x: tcan4x5x@0 { spi-max-frequency = <10000000>; bosch,mram-cfg = <0x0 0 0 32 0 0 1 1>; interrupt-parent = <&gpio1>; - interrupts = <14 GPIO_ACTIVE_LOW>; + interrupts = <14 IRQ_TYPE_LEVEL_LOW>; device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; device-wake-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; reset-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml index fa3ebba4e635..c1948ce00081 100644 --- a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml +++ b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml @@ -46,6 +46,8 @@ required: - clocks - clock-names +unevaluatedProperties: false + examples: # FIXME: Remove defines and include the correct header file # once it is available in mainline. diff --git a/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt b/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt index cfaf88998918..9e4dc510a40a 100644 --- a/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt +++ b/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt @@ -25,7 +25,7 @@ Example (for ARM-based BeagleBone with NPC100 NFC controller on I2C2): clock-frequency = <100000>; interrupt-parent = <&gpio1>; - interrupts = <29 GPIO_ACTIVE_HIGH>; + interrupts = <29 IRQ_TYPE_LEVEL_HIGH>; enable-gpios = <&gpio0 30 GPIO_ACTIVE_HIGH>; firmware-gpios = <&gpio0 31 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/nfc/pn544.txt b/Documentation/devicetree/bindings/net/nfc/pn544.txt index 92f399ec22b8..2bd82562ce8e 100644 --- a/Documentation/devicetree/bindings/net/nfc/pn544.txt +++ b/Documentation/devicetree/bindings/net/nfc/pn544.txt @@ -25,7 +25,7 @@ Example (for ARM-based BeagleBone with PN544 on I2C2): clock-frequency = <400000>; interrupt-parent = <&gpio1>; - interrupts = <17 GPIO_ACTIVE_HIGH>; + interrupts = <17 IRQ_TYPE_LEVEL_HIGH>; enable-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; firmware-gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml index 55913534cbc2..75e8712e903a 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83822.yaml +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml @@ -65,6 +65,8 @@ properties: required: - reg +unevaluatedProperties: false + examples: - | mdio0 { diff --git a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml index f4292d2c54e3..d6cf8a560ef0 100644 --- a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml @@ -29,16 +29,16 @@ properties: reg-names: oneOf: - items: - - const: dbi - - const: dbi2 - - const: link - - const: addr_space + - const: dbi + - const: dbi2 + - const: link + - const: addr_space - items: - - const: dbi - - const: dbi2 - - const: link - - const: addr_space - - const: atu + - const: dbi + - const: dbi2 + - const: link + - const: addr_space + - const: atu clocks: maxItems: 2 diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml index bab2ff4d9dc9..34756347a14e 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml @@ -31,10 +31,10 @@ properties: clock-names: oneOf: - items: # for PXs2 - - const: link + - const: link - items: # for others - - const: link - - const: phy + - const: link + - const: phy resets: maxItems: 2 diff --git a/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml b/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml index 15207ca9548f..83d5d0aceb04 100644 --- a/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml +++ b/Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml @@ -7,23 +7,23 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: OMAP USB2 PHY maintainers: - - Kishon Vijay Abraham I <kishon@ti.com> - - Roger Quadros <rogerq@ti.com> + - Kishon Vijay Abraham I <kishon@ti.com> + - Roger Quadros <rogerq@ti.com> properties: compatible: oneOf: - items: - - enum: - - ti,dra7x-usb2 - - ti,dra7x-usb2-phy2 - - ti,am654-usb2 - - enum: - - ti,omap-usb2 + - enum: + - ti,dra7x-usb2 + - ti,dra7x-usb2-phy2 + - ti,am654-usb2 + - enum: + - ti,omap-usb2 - items: - - const: ti,am437x-usb2 + - const: ti,am437x-usb2 - items: - - const: ti,omap-usb2 + - const: ti,omap-usb2 reg: maxItems: 1 @@ -62,6 +62,8 @@ required: - clocks - clock-names +additionalProperties: false + examples: - | usb0_phy: phy@4100000 { diff --git a/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml index 33391d30c00c..ccdd9e3820d7 100644 --- a/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml @@ -76,22 +76,22 @@ patternProperties: items: oneOf: - enum: [lcd0_d18_mfp, rmii_crs_dv_mfp, rmii_txd0_mfp, - rmii_txd1_mfp, rmii_txen_mfp, rmii_rxen_mfp, rmii_rxd1_mfp, - rmii_rxd0_mfp, rmii_ref_clk_mfp, i2s_d0_mfp, i2s_pcm1_mfp, - i2s0_pcm0_mfp, i2s1_pcm0_mfp, i2s_d1_mfp, ks_in2_mfp, - ks_in1_mfp, ks_in0_mfp, ks_in3_mfp, ks_out0_mfp, - ks_out1_mfp, ks_out2_mfp, lvds_o_pn_mfp, dsi_dn0_mfp, - dsi_dp2_mfp, lcd0_d17_mfp, dsi_dp3_mfp, dsi_dn3_mfp, - dsi_dp0_mfp, lvds_ee_pn_mfp, spi0_i2c_pcm_mfp, - spi0_i2s_pcm_mfp, dsi_dnp1_cp_mfp, lvds_e_pn_mfp, - dsi_dn2_mfp, uart2_rtsb_mfp, uart2_ctsb_mfp, uart3_rtsb_mfp, - uart3_ctsb_mfp, sd0_d0_mfp, sd0_d1_mfp, sd0_d2_d3_mfp, - sd1_d0_d3_mfp, sd0_cmd_mfp, sd0_clk_mfp, sd1_cmd_mfp, - uart0_rx_mfp, clko_25m_mfp, csi_cn_cp_mfp, sens0_ckout_mfp, - uart0_tx_mfp, i2c0_mfp, csi_dn_dp_mfp, sen0_pclk_mfp, - pcm1_in_mfp, pcm1_clk_mfp, pcm1_sync_mfp, pcm1_out_mfp, - dnand_data_wr_mfp, dnand_acle_ce0_mfp, nand_ceb2_mfp, - nand_ceb3_mfp] + rmii_txd1_mfp, rmii_txen_mfp, rmii_rxen_mfp, rmii_rxd1_mfp, + rmii_rxd0_mfp, rmii_ref_clk_mfp, i2s_d0_mfp, i2s_pcm1_mfp, + i2s0_pcm0_mfp, i2s1_pcm0_mfp, i2s_d1_mfp, ks_in2_mfp, + ks_in1_mfp, ks_in0_mfp, ks_in3_mfp, ks_out0_mfp, + ks_out1_mfp, ks_out2_mfp, lvds_o_pn_mfp, dsi_dn0_mfp, + dsi_dp2_mfp, lcd0_d17_mfp, dsi_dp3_mfp, dsi_dn3_mfp, + dsi_dp0_mfp, lvds_ee_pn_mfp, spi0_i2c_pcm_mfp, + spi0_i2s_pcm_mfp, dsi_dnp1_cp_mfp, lvds_e_pn_mfp, + dsi_dn2_mfp, uart2_rtsb_mfp, uart2_ctsb_mfp, uart3_rtsb_mfp, + uart3_ctsb_mfp, sd0_d0_mfp, sd0_d1_mfp, sd0_d2_d3_mfp, + sd1_d0_d3_mfp, sd0_cmd_mfp, sd0_clk_mfp, sd1_cmd_mfp, + uart0_rx_mfp, clko_25m_mfp, csi_cn_cp_mfp, sens0_ckout_mfp, + uart0_tx_mfp, i2c0_mfp, csi_dn_dp_mfp, sen0_pclk_mfp, + pcm1_in_mfp, pcm1_clk_mfp, pcm1_sync_mfp, pcm1_out_mfp, + dnand_data_wr_mfp, dnand_acle_ce0_mfp, nand_ceb2_mfp, + nand_ceb3_mfp] minItems: 1 maxItems: 32 @@ -100,10 +100,10 @@ patternProperties: Specify the alternative function to be configured for the given gpio pin groups. enum: [nor, eth_rmii, eth_smii, spi0, spi1, spi2, spi3, sens0, - sens1, uart0, uart1, uart2, uart3, uart4, uart5, uart6, i2s0, - i2s1, pcm1, pcm0, ks, jtag, pwm0, pwm1, pwm2, pwm3, pwm4, pwm5, - p0, sd0, sd1, sd2, i2c0, i2c1, i2c3, dsi, lvds, usb30, clko_25m, - mipi_csi, nand, spdif, ts, lcd0] + sens1, uart0, uart1, uart2, uart3, uart4, uart5, uart6, i2s0, + i2s1, pcm1, pcm0, ks, jtag, pwm0, pwm1, pwm2, pwm3, pwm4, pwm5, + p0, sd0, sd1, sd2, i2c0, i2c1, i2c3, dsi, lvds, usb30, clko_25m, + mipi_csi, nand, spdif, ts, lcd0] required: - groups @@ -126,14 +126,14 @@ patternProperties: items: oneOf: - enum: [sirq_drv, rmii_txd01_txen_drv, rmii_rxer_drv, - rmii_crs_drv, rmii_rxd10_drv, rmii_ref_clk_drv, - smi_mdc_mdio_drv, i2s_d0_drv, i2s_bclk0_drv, i2s3_drv, - i2s13_drv, pcm1_drv, ks_in_drv, ks_out_drv, lvds_all_drv, - lcd_dsi_drv, dsi_drv, sd0_d0_d3_drv, sd1_d0_d3_drv, - sd0_cmd_drv, sd0_clk_drv, sd1_cmd_drv, sd1_clk_drv, - spi0_all_drv, uart0_rx_drv, uart0_tx_drv, uart2_all_drv, - i2c0_all_drv, i2c12_all_drv, sens0_pclk_drv, - sens0_ckout_drv, uart3_all_drv] + rmii_crs_drv, rmii_rxd10_drv, rmii_ref_clk_drv, + smi_mdc_mdio_drv, i2s_d0_drv, i2s_bclk0_drv, i2s3_drv, + i2s13_drv, pcm1_drv, ks_in_drv, ks_out_drv, lvds_all_drv, + lcd_dsi_drv, dsi_drv, sd0_d0_d3_drv, sd1_d0_d3_drv, + sd0_cmd_drv, sd0_clk_drv, sd1_cmd_drv, sd1_clk_drv, + spi0_all_drv, uart0_rx_drv, uart0_tx_drv, uart2_all_drv, + i2c0_all_drv, i2c12_all_drv, sens0_pclk_drv, + sens0_ckout_drv, uart3_all_drv] minItems: 1 maxItems: 32 @@ -144,29 +144,29 @@ patternProperties: items: oneOf: - enum: [dnand_dqs, dnand_dqsn, eth_txd0, eth_txd1, eth_txen, - eth_rxer, eth_crs_dv, eth_rxd1, eth_rxd0, eth_ref_clk, - eth_mdc, eth_mdio, sirq0, sirq1, sirq2, i2s_d0, i2s_bclk0, - i2s_lrclk0, i2s_mclk0, i2s_d1, i2s_bclk1, i2s_lrclk1, - i2s_mclk1, ks_in0, ks_in1, ks_in2, ks_in3, ks_out0, ks_out1, - ks_out2, lvds_oep, lvds_oen, lvds_odp, lvds_odn, lvds_ocp, - lvds_ocn, lvds_obp, lvds_obn, lvds_oap, lvds_oan, lvds_eep, - lvds_een, lvds_edp, lvds_edn, lvds_ecp, lvds_ecn, lvds_ebp, - lvds_ebn, lvds_eap, lvds_ean, lcd0_d18, lcd0_d17, dsi_dp3, - dsi_dn3, dsi_dp1, dsi_dn1, dsi_cp, dsi_cn, dsi_dp0, dsi_dn0, - dsi_dp2, dsi_dn2, sd0_d0, sd0_d1, sd0_d2, sd0_d3, sd1_d0, - sd1_d1, sd1_d2, sd1_d3, sd0_cmd, sd0_clk, sd1_cmd, sd1_clk, - spi0_sclk, spi0_ss, spi0_miso, spi0_mosi, uart0_rx, - uart0_tx, i2c0_sclk, i2c0_sdata, sensor0_pclk, - sensor0_ckout, dnand_ale, dnand_cle, dnand_ceb0, dnand_ceb1, - dnand_ceb2, dnand_ceb3, uart2_rx, uart2_tx, uart2_rtsb, - uart2_ctsb, uart3_rx, uart3_tx, uart3_rtsb, uart3_ctsb, - pcm1_in, pcm1_clk, pcm1_sync, pcm1_out, i2c1_sclk, - i2c1_sdata, i2c2_sclk, i2c2_sdata, csi_dn0, csi_dp0, - csi_dn1, csi_dp1, csi_dn2, csi_dp2, csi_dn3, csi_dp3, - csi_cn, csi_cp, dnand_d0, dnand_d1, dnand_d2, dnand_d3, - dnand_d4, dnand_d5, dnand_d6, dnand_d7, dnand_rb, dnand_rdb, - dnand_rdbn, dnand_wrb, porb, clko_25m, bsel, pkg0, pkg1, - pkg2, pkg3] + eth_rxer, eth_crs_dv, eth_rxd1, eth_rxd0, eth_ref_clk, + eth_mdc, eth_mdio, sirq0, sirq1, sirq2, i2s_d0, i2s_bclk0, + i2s_lrclk0, i2s_mclk0, i2s_d1, i2s_bclk1, i2s_lrclk1, + i2s_mclk1, ks_in0, ks_in1, ks_in2, ks_in3, ks_out0, ks_out1, + ks_out2, lvds_oep, lvds_oen, lvds_odp, lvds_odn, lvds_ocp, + lvds_ocn, lvds_obp, lvds_obn, lvds_oap, lvds_oan, lvds_eep, + lvds_een, lvds_edp, lvds_edn, lvds_ecp, lvds_ecn, lvds_ebp, + lvds_ebn, lvds_eap, lvds_ean, lcd0_d18, lcd0_d17, dsi_dp3, + dsi_dn3, dsi_dp1, dsi_dn1, dsi_cp, dsi_cn, dsi_dp0, dsi_dn0, + dsi_dp2, dsi_dn2, sd0_d0, sd0_d1, sd0_d2, sd0_d3, sd1_d0, + sd1_d1, sd1_d2, sd1_d3, sd0_cmd, sd0_clk, sd1_cmd, sd1_clk, + spi0_sclk, spi0_ss, spi0_miso, spi0_mosi, uart0_rx, + uart0_tx, i2c0_sclk, i2c0_sdata, sensor0_pclk, + sensor0_ckout, dnand_ale, dnand_cle, dnand_ceb0, dnand_ceb1, + dnand_ceb2, dnand_ceb3, uart2_rx, uart2_tx, uart2_rtsb, + uart2_ctsb, uart3_rx, uart3_tx, uart3_rtsb, uart3_ctsb, + pcm1_in, pcm1_clk, pcm1_sync, pcm1_out, i2c1_sclk, + i2c1_sdata, i2c2_sclk, i2c2_sdata, csi_dn0, csi_dp0, + csi_dn1, csi_dp1, csi_dn2, csi_dp2, csi_dn3, csi_dp3, + csi_cn, csi_cp, dnand_d0, dnand_d1, dnand_d2, dnand_d3, + dnand_d4, dnand_d5, dnand_d6, dnand_d7, dnand_rb, dnand_rdb, + dnand_rdbn, dnand_wrb, porb, clko_25m, bsel, pkg0, pkg1, + pkg2, pkg3] minItems: 1 maxItems: 64 diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml index 5556def6b99b..c4c071211611 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8192.yaml @@ -106,7 +106,7 @@ patternProperties: required: - pinmux - additionalProperties: false + additionalProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml index 1f0f5757f9e1..040d2ada3669 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml @@ -71,9 +71,9 @@ patternProperties: Specify the alternative function to be configured for the specified pins. Functions are only valid for gpio pins. enum: [ gpio, cci_i2c0, blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim5, - blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c5, blsp_spi1, - blsp_spi2, blsp_spi3, blsp_spi5, blsp_uart1, blsp_uart2, - blsp_uart3, blsp_uart5, cam_mclk0, cam_mclk1, wlan ] + blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c5, blsp_spi1, + blsp_spi2, blsp_spi3, blsp_spi5, blsp_uart1, blsp_uart2, + blsp_uart3, blsp_uart5, cam_mclk0, cam_mclk1, wlan ] drive-strength: enum: [2, 4, 6, 8, 10, 12, 14, 16] diff --git a/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml index d0d1a01140ea..9f1dab0c2430 100644 --- a/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml @@ -40,24 +40,24 @@ patternProperties: Function to mux. $ref: "/schemas/types.yaml#/definitions/string" enum: [i2c0, i2c1, i2c2, i2c3, i2c4, i2c5, i2c6, i2c7, i2c8, - spi0, spi1, spi2, spi3, spi4, spi5, spi6, - uart0, uart1, uart2, uart3, pwm, pcmif_out, pcmif_in] + spi0, spi1, spi2, spi3, spi4, spi5, spi6, + uart0, uart1, uart2, uart3, pwm, pcmif_out, pcmif_in] groups: description: Name of the pin group to use for the functions. $ref: "/schemas/types.yaml#/definitions/string" enum: [i2c0_grp, i2c1_grp, i2c2_grp, i2c3_grp, i2c4_grp, - i2c5_grp, i2c6_grp, i2c7_grp, i2c8_grp, - spi0_grp, spi0_cs0_grp, spi0_cs1_grp, spi0_cs2_grp, - spi1_grp, spi2_grp, spi3_grp, spi4_grp, spi5_grp, spi6_grp, - uart0_grp, uart1_grp, uart2_grp, uart3_grp, - pwm0_gpio4_grp, pwm0_gpio8_grp, pwm0_gpio12_grp, - pwm0_gpio16_grp, pwm1_gpio5_grp, pwm1_gpio9_grp, - pwm1_gpio13_grp, pwm1_gpio17_grp, pwm2_gpio6_grp, - pwm2_gpio10_grp, pwm2_gpio14_grp, pwm2_gpio18_grp, - pwm3_gpio7_grp, pwm3_gpio11_grp, pwm3_gpio15_grp, - pwm3_gpio19_grp, pcmif_out_grp, pcmif_in_grp] + i2c5_grp, i2c6_grp, i2c7_grp, i2c8_grp, + spi0_grp, spi0_cs0_grp, spi0_cs1_grp, spi0_cs2_grp, + spi1_grp, spi2_grp, spi3_grp, spi4_grp, spi5_grp, spi6_grp, + uart0_grp, uart1_grp, uart2_grp, uart3_grp, + pwm0_gpio4_grp, pwm0_gpio8_grp, pwm0_gpio12_grp, + pwm0_gpio16_grp, pwm1_gpio5_grp, pwm1_gpio9_grp, + pwm1_gpio13_grp, pwm1_gpio17_grp, pwm2_gpio6_grp, + pwm2_gpio10_grp, pwm2_gpio14_grp, pwm2_gpio18_grp, + pwm3_gpio7_grp, pwm3_gpio11_grp, pwm3_gpio15_grp, + pwm3_gpio19_grp, pcmif_out_grp, pcmif_in_grp] drive-strength: enum: [2, 4, 6, 8, 16, 24, 32] diff --git a/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml index a6c91026d4cc..9c6fda6b1dd9 100644 --- a/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml +++ b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml @@ -28,14 +28,16 @@ description: | properties: mode-normal: - $ref: /schemas/types.yaml#/definitions/uint32 - description: | - Default value to set on a reboot if no command was provided. + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Default value to set on a reboot if no command was provided. patternProperties: "^mode-.*$": $ref: /schemas/types.yaml#/definitions/uint32 +additionalProperties: false + examples: - | reboot-mode { diff --git a/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml b/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml index 867e3e6b7e80..76c227a7cd5c 100644 --- a/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml +++ b/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml @@ -15,10 +15,10 @@ properties: oneOf: - const: ingenic,jz4740-battery - items: - - enum: - - ingenic,jz4725b-battery - - ingenic,jz4770-battery - - const: ingenic,jz4740-battery + - enum: + - ingenic,jz4725b-battery + - ingenic,jz4770-battery + - const: ingenic,jz4740-battery io-channels: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml index 193a23af2007..983fc215c1e5 100644 --- a/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml @@ -84,12 +84,12 @@ allOf: then: properties: summit,mains-current-limit-microamp: - enum: [ 300000, 500000, 700000, 1000000, - 1500000, 1800000, 2000000] + enum: [ 300000, 500000, 700000, 1000000, + 1500000, 1800000, 2000000] summit,usb-current-limit-microamp: - enum: [ 300000, 500000, 700000, 1000000, - 1500000, 1800000, 2000000] + enum: [ 300000, 500000, 700000, 1000000, + 1500000, 1800000, 2000000] summit,charge-current-compensation-microamp: enum: [200000, 450000, 600000, 900000] @@ -97,12 +97,12 @@ allOf: else: properties: summit,mains-current-limit-microamp: - enum: [ 300000, 500000, 700000, 900000, 1200000, - 1500000, 1800000, 2000000, 2200000, 2500000] + enum: [ 300000, 500000, 700000, 900000, 1200000, + 1500000, 1800000, 2000000, 2200000, 2500000] summit,usb-current-limit-microamp: - enum: [ 300000, 500000, 700000, 900000, 1200000, - 1500000, 1800000, 2000000, 2200000, 2500000] + enum: [ 300000, 500000, 700000, 900000, 1200000, + 1500000, 1800000, 2000000, 2200000, 2500000] summit,charge-current-compensation-microamp: enum: [250000, 700000, 900000, 1200000] diff --git a/Documentation/devicetree/bindings/regulator/mps,mp886x.yaml b/Documentation/devicetree/bindings/regulator/mps,mp886x.yaml index ba175b30f468..9245b7199439 100644 --- a/Documentation/devicetree/bindings/regulator/mps,mp886x.yaml +++ b/Documentation/devicetree/bindings/regulator/mps,mp886x.yaml @@ -41,6 +41,8 @@ required: - enable-gpios - mps,fb-voltage-divider +unevaluatedProperties: false + examples: - | #include <dt-bindings/gpio/gpio.h> diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.yaml b/Documentation/devicetree/bindings/regulator/pfuze100.yaml index c6de49685db7..f578e72778a7 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.yaml +++ b/Documentation/devicetree/bindings/regulator/pfuze100.yaml @@ -80,6 +80,8 @@ required: - compatible - reg +additionalProperties: false + examples: - | i2c { diff --git a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml index 3f4a1939554d..efc0198eeb74 100644 --- a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml @@ -25,8 +25,8 @@ select: properties: compatible: items: - - enum: - - sifive,fu540-c000-ccache + - enum: + - sifive,fu540-c000-ccache required: - compatible diff --git a/Documentation/devicetree/bindings/riscv/sifive.yaml b/Documentation/devicetree/bindings/riscv/sifive.yaml index 3ab532713dc1..3a8647d1da4c 100644 --- a/Documentation/devicetree/bindings/riscv/sifive.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive.yaml @@ -22,4 +22,7 @@ properties: - sifive,hifive-unleashed-a00 - const: sifive,fu540-c000 - const: sifive,fu540 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/rng/imx-rng.yaml b/Documentation/devicetree/bindings/rng/imx-rng.yaml index 4ad1e456a801..07f6ff89bcc1 100644 --- a/Documentation/devicetree/bindings/rng/imx-rng.yaml +++ b/Documentation/devicetree/bindings/rng/imx-rng.yaml @@ -19,9 +19,9 @@ properties: - const: fsl,imx21-rnga - items: - enum: - - fsl,imx6sl-rngb - - fsl,imx6sll-rngb - - fsl,imx6ull-rngb + - fsl,imx6sl-rngb + - fsl,imx6sll-rngb + - fsl,imx6ull-rngb - const: fsl,imx25-rngb - const: fsl,imx35-rngc diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml index 9ff85bc6859c..9702c07a6b6c 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml @@ -20,30 +20,30 @@ properties: - const: fsl,imx21-uart - items: - enum: - - fsl,imx25-uart - - fsl,imx27-uart - - fsl,imx31-uart - - fsl,imx35-uart - - fsl,imx50-uart - - fsl,imx51-uart - - fsl,imx53-uart - - fsl,imx6q-uart + - fsl,imx25-uart + - fsl,imx27-uart + - fsl,imx31-uart + - fsl,imx35-uart + - fsl,imx50-uart + - fsl,imx51-uart + - fsl,imx53-uart + - fsl,imx6q-uart - const: fsl,imx21-uart - items: - enum: - - fsl,imx6sl-uart - - fsl,imx6sll-uart - - fsl,imx6sx-uart + - fsl,imx6sl-uart + - fsl,imx6sll-uart + - fsl,imx6sx-uart - const: fsl,imx6q-uart - const: fsl,imx21-uart - items: - enum: - - fsl,imx6ul-uart - - fsl,imx7d-uart - - fsl,imx8mm-uart - - fsl,imx8mn-uart - - fsl,imx8mp-uart - - fsl,imx8mq-uart + - fsl,imx6ul-uart + - fsl,imx7d-uart + - fsl,imx8mm-uart + - fsl,imx8mn-uart + - fsl,imx8mp-uart + - fsl,imx8mq-uart - const: fsl,imx6q-uart reg: diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml index 3b9143af2c7c..acfb9db021dc 100644 --- a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml +++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml @@ -11,9 +11,10 @@ maintainers: description: | Google's ChromeOS EC codec is a digital mic codec provided by the - Embedded Controller (EC) and is controlled via a host-command interface. - An EC codec node should only be found as a sub-node of the EC node (see - Documentation/devicetree/bindings/mfd/google,cros-ec.yaml). + Embedded Controller (EC) and is controlled via a host-command + interface. An EC codec node should only be found inside the "codecs" + subnode of a cros-ec node. + (see Documentation/devicetree/bindings/mfd/google,cros-ec.yaml). properties: compatible: @@ -54,14 +55,19 @@ examples: #size-cells = <0>; cros-ec@0 { compatible = "google,cros-ec-spi"; - #address-cells = <2>; - #size-cells = <1>; reg = <0>; - cros_ec_codec: ec-codec@10500000 { - compatible = "google,cros-ec-codec"; - #sound-dai-cells = <1>; - reg = <0x0 0x10500000 0x80000>; - memory-region = <&reserved_mem>; + + codecs { + #address-cells = <2>; + #size-cells = <1>; + + cros_ec_codec: ec-codec@10500000 { + compatible = "google,cros-ec-codec"; + #sound-dai-cells = <1>; + reg = <0x0 0x10500000 0x80000>; + memory-region = <&reserved_mem>; + }; + }; }; }; diff --git a/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml b/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml index 7d8bd4e14434..4a2129005c0f 100644 --- a/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml +++ b/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml @@ -10,8 +10,8 @@ maintainers: - Codrin Ciubotariu <codrin.ciubotariu@microchip.com> description: - The Microchip Sony/Philips Digital Interface Receiver is a - serial port compliant with the IEC-60958 standard. + The Microchip Sony/Philips Digital Interface Receiver is a serial port + compliant with the IEC-60958 standard. properties: "#sound-dai-cells": diff --git a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml b/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml index a03b0b871fc9..bdfb63387c53 100644 --- a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml +++ b/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml @@ -10,8 +10,8 @@ maintainers: - Codrin Ciubotariu <codrin.ciubotariu@microchip.com> description: - The Microchip Sony/Philips Digital Interface Transmitter is a - serial port compliant with the IEC-60958 standard. + The Microchip Sony/Philips Digital Interface Transmitter is a serial port + compliant with the IEC-60958 standard. properties: "#sound-dai-cells": diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml index f6f9fb49f385..1e23c0e20bc1 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml @@ -26,8 +26,10 @@ properties: reg: maxItems: 2 description: LPAIF core registers + reg-names: - maxItems: 2 + maxItems: 2 + clocks: minItems: 3 maxItems: 6 @@ -39,8 +41,10 @@ properties: interrupts: maxItems: 2 description: LPAIF DMA buffer interrupt + interrupt-names: maxItems: 2 + qcom,adsp: $ref: /schemas/types.yaml#/definitions/phandle description: Phandle for the audio DSP node @@ -141,31 +145,31 @@ allOf: properties: clock-names: oneOf: - - items: #for I2S - - const: pcnoc-sway-clk - - const: audio-core - - const: mclk0 - - const: pcnoc-mport-clk - - const: mi2s-bit-clk0 - - const: mi2s-bit-clk1 - - items: #for HDMI - - const: pcnoc-sway-clk - - const: audio-core - - const: pcnoc-mport-clk + - items: #for I2S + - const: pcnoc-sway-clk + - const: audio-core + - const: mclk0 + - const: pcnoc-mport-clk + - const: mi2s-bit-clk0 + - const: mi2s-bit-clk1 + - items: #for HDMI + - const: pcnoc-sway-clk + - const: audio-core + - const: pcnoc-mport-clk reg-names: anyOf: - items: #for I2S - - const: lpass-lpaif + - const: lpass-lpaif - items: #for I2S and HDMI - - const: lpass-hdmiif - - const: lpass-lpaif + - const: lpass-hdmiif + - const: lpass-lpaif interrupt-names: anyOf: - items: #for I2S - - const: lpass-irq-lpaif + - const: lpass-irq-lpaif - items: #for I2S and HDMI - - const: lpass-irq-lpaif - - const: lpass-irq-hdmi + - const: lpass-irq-lpaif + - const: lpass-irq-hdmi required: - iommus - power-domains diff --git a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml index def1db298eac..644b68edf3e1 100644 --- a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml +++ b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml @@ -26,6 +26,8 @@ properties: required: - compatible +additionalProperties: false + examples: - | #include <dt-bindings/gpio/gpio.h> diff --git a/Documentation/devicetree/bindings/sound/rt1015.txt b/Documentation/devicetree/bindings/sound/rt1015.txt index fcfd02d8d32f..e498966d436f 100644 --- a/Documentation/devicetree/bindings/sound/rt1015.txt +++ b/Documentation/devicetree/bindings/sound/rt1015.txt @@ -8,10 +8,16 @@ Required properties: - reg : The I2C address of the device. +Optional properties: + +- realtek,power-up-delay-ms + Set a delay time for flush work to be completed, + this value is adjustable depending on platform. Example: rt1015: codec@28 { compatible = "realtek,rt1015"; reg = <0x28>; + realtek,power-up-delay-ms = <50>; }; diff --git a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml index 6ebcbc153691..b66a07e21d1e 100644 --- a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml +++ b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml @@ -34,6 +34,9 @@ properties: - const: allwinner,sun8i-a23-system-control - const: allwinner,sun8i-h3-system-control - items: + - const: allwinner,sun8i-v3s-system-control + - const: allwinner,sun8i-h3-system-control + - items: - const: allwinner,sun8i-r40-system-control - const: allwinner,sun4i-a10-system-control - const: allwinner,sun50i-a64-sram-controller diff --git a/Documentation/devicetree/bindings/timer/arm,sp804.yaml b/Documentation/devicetree/bindings/timer/arm,sp804.yaml index e35d3053250a..960e2bd66a97 100644 --- a/Documentation/devicetree/bindings/timer/arm,sp804.yaml +++ b/Documentation/devicetree/bindings/timer/arm,sp804.yaml @@ -33,8 +33,8 @@ properties: compatible: items: - enum: - - arm,sp804 - - hisilicon,sp804 + - arm,sp804 + - hisilicon,sp804 - const: arm,primecell interrupts: @@ -58,11 +58,11 @@ properties: clock is used for all clock inputs. oneOf: - items: - - description: clock for timer 1 - - description: clock for timer 2 - - description: bus clock + - description: clock for timer 1 + - description: clock for timer 2 + - description: bus clock - items: - - description: unified clock for both timers and the bus + - description: unified clock for both timers and the bus clock-names: true # The original binding did not specify any clock names, and there is no diff --git a/Documentation/devicetree/bindings/usb/cdns,usb3.yaml b/Documentation/devicetree/bindings/usb/cdns,usb3.yaml index ac20b98e9910..d6af2794d444 100644 --- a/Documentation/devicetree/bindings/usb/cdns,usb3.yaml +++ b/Documentation/devicetree/bindings/usb/cdns,usb3.yaml @@ -44,8 +44,8 @@ properties: enum: [super-speed, high-speed, full-speed] phys: - minItems: 1 - maxItems: 2 + minItems: 1 + maxItems: 2 phy-names: minItems: 1 diff --git a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml index 5fe9e6211ba2..52ceb07294a3 100644 --- a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml +++ b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml @@ -17,7 +17,7 @@ description: |- properties: compatible: - const: ti,hd3ss3220 + const: ti,hd3ss3220 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 2735be1a8470..772b148795f4 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -29,6 +29,8 @@ patternProperties: description: Abilis Systems "^abracon,.*": description: Abracon Corporation + "^abt,.*": + description: ShenZhen Asia Better Technology Ltd. "^acer,.*": description: Acer Inc. "^acme,.*": @@ -681,6 +683,8 @@ patternProperties: description: MiraMEMS Sensing Technology Co., Ltd. "^mitsubishi,.*": description: Mitsubishi Electric Corporation + "^modtronix,.*": + description: Modtronix Engineering "^mosaixtech,.*": description: Mosaix Technologies, Inc. "^motorola,.*": @@ -1053,6 +1057,8 @@ patternProperties: description: Trusted Computing Group "^tcl,.*": description: Toby Churchill Ltd. + "^tdo,.*": + description: Shangai Top Display Optoelectronics Co., Ltd "^technexion,.*": description: TechNexion "^technologic,.*": @@ -1210,6 +1216,8 @@ patternProperties: description: Shenzhen Xunlong Software CO.,Limited "^xylon,.*": description: Xylon + "^yes-optoelectronics,.*": + description: Yes Optoelectronics Co.,Ltd. "^ylm,.*": description: Shenzhen Yangliming Electronic Technology Co., Ltd. "^yna,.*": diff --git a/Documentation/devicetree/bindings/w1/fsl-imx-owire.yaml b/Documentation/devicetree/bindings/w1/fsl-imx-owire.yaml index 1aaf3e768c81..55adea827c34 100644 --- a/Documentation/devicetree/bindings/w1/fsl-imx-owire.yaml +++ b/Documentation/devicetree/bindings/w1/fsl-imx-owire.yaml @@ -15,10 +15,10 @@ properties: - const: fsl,imx21-owire - items: - enum: - - fsl,imx27-owire - - fsl,imx50-owire - - fsl,imx51-owire - - fsl,imx53-owire + - fsl,imx27-owire + - fsl,imx50-owire + - fsl,imx51-owire + - fsl,imx53-owire - const: fsl,imx21-owire reg: diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 4144b669e80c..d6b2a195dbed 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -115,6 +115,15 @@ Kernel Functions and Structures Reference .. kernel-doc:: include/linux/dma-buf.h :internal: +Buffer Mapping Helpers +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/dma-buf-map.h + :doc: overview + +.. kernel-doc:: include/linux/dma-buf-map.h + :internal: + Reservation Objects ------------------- diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 4d1ae12b9b4d..ffb0cad8137a 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -132,3 +132,16 @@ used to obtain device's power state after the power state transition: The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to access the device. + +Controls +-------- + +For camera sensors that are connected to a bus where transmitter and receiver +require common configuration set by drivers, such as CSI-2 or parallel (BT.601 +or BT.656) bus, the ``V4L2_CID_LINK_FREQ`` control is mandatory on transmitter +drivers. Receiver drivers can use the ``V4L2_CID_LINK_FREQ`` to query the +frequency used on the bus. + +The transmitter drivers should also implement ``V4L2_CID_PIXEL_RATE`` control in +order to tell the maximum pixel rate to the receiver. This is required on raw +camera sensors. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index bc42982ac21e..a26dc87eee8f 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -143,7 +143,7 @@ To enable/disable the 'monitor all' mode:: int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); If enabled, then the adapter should be put in a mode to also monitor messages -that not for us. Not all hardware supports this and this function is only +that are not for us. Not all hardware supports this and this function is only called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional (some hardware may always be in 'monitor all' mode). @@ -335,7 +335,7 @@ So this must work: $ cat einj.txt >error-inj The first callback is called when this file is read and it should show the -the current error injection state:: +current error injection state:: int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst index e1b838014906..e3bbc6baf0f0 100644 --- a/Documentation/driver-api/media/csi2.rst +++ b/Documentation/driver-api/media/csi2.rst @@ -28,10 +28,9 @@ interface elements must be present on the sub-device represents the CSI-2 transmitter. The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the -frequency (and not the symbol rate) of the link. The -V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel -rate the transmitter uses. The -:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an +frequency (and not the symbol rate) of the link. The V4L2_CID_PIXEL_RATE +control may be used by the receiver to obtain the pixel rate the transmitter +uses. The :c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an ability to start and stop the stream. The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: diff --git a/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc new file mode 100644 index 000000000000..f2042acc8a45 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc @@ -0,0 +1,1041 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +# register rflags +# - f field LSB MSB rflags +# - e enum value # after a field +# - e enum value [LSB MSB] +# - b bool bit +# - l arg name min max elsize [discontig...] +# +# rflags +# 8, 16, 32 register bits (default is 8) +# v1.1 defined in version 1.1 +# f formula +# float_ireal iReal or IEEE 754; 32 bits +# ireal unsigned iReal + +# general status registers +module_model_id 0x0000 16 +module_revision_number_major 0x0002 8 +frame_count 0x0005 8 +pixel_order 0x0006 8 +- e GRBG 0 +- e RGGB 1 +- e BGGR 2 +- e GBRG 3 +MIPI_CCS_version 0x0007 8 +- e v1_0 0x10 +- e v1_1 0x11 +- f major 4 7 +- f minor 0 3 +data_pedestal 0x0008 16 +module_manufacturer_id 0x000e 16 +module_revision_number_minor 0x0010 8 +module_date_year 0x0012 8 +module_date_month 0x0013 8 +module_date_day 0x0014 8 +module_date_phase 0x0015 8 +- f 0 2 +- e ts 0 +- e es 1 +- e cs 2 +- e mp 3 +sensor_model_id 0x0016 16 +sensor_revision_number 0x0018 8 +sensor_firmware_version 0x001a 8 +serial_number 0x001c 32 +sensor_manufacturer_id 0x0020 16 +sensor_revision_number_16 0x0022 16 + +# frame format description registers +frame_format_model_type 0x0040 8 +- e 2-byte 1 +- e 4-byte 2 +frame_format_model_subtype 0x0041 8 +- f rows 0 3 +- f columns 4 7 +frame_format_descriptor(n) 0x0042 16 f +- l n 0 14 2 +- f pixels 0 11 +- f pcode 12 15 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 +frame_format_descriptor_4(n) 0x0060 32 f +- l n 0 7 4 +- f pixels 0 15 +- f pcode 28 31 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 + +# analog gain description registers +analog_gain_capability 0x0080 16 +- e global 0 +- e alternate_global 2 +analog_gain_code_min 0x0084 16 +analog_gain_code_max 0x0086 16 +analog_gain_code_step 0x0088 16 +analog_gain_type 0x008a 16 +analog_gain_m0 0x008c 16 +analog_gain_c0 0x008e 16 +analog_gain_m1 0x0090 16 +analog_gain_c1 0x0092 16 +analog_linear_gain_min 0x0094 16 v1.1 +analog_linear_gain_max 0x0096 16 v1.1 +analog_linear_gain_step_size 0x0098 16 v1.1 +analog_exponential_gain_min 0x009a 16 v1.1 +analog_exponential_gain_max 0x009c 16 v1.1 +analog_exponential_gain_step_size 0x009e 16 v1.1 + +# data format description registers +data_format_model_type 0x00c0 8 +- e normal 1 +- e extended 2 +data_format_model_subtype 0x00c1 8 +- f rows 0 3 +- f columns 4 7 +data_format_descriptor(n) 0x00c2 16 f +- l n 0 15 2 +- f compressed 0 7 +- f uncompressed 8 15 + +# general set-up registers +mode_select 0x0100 8 +- e software_standby 0 +- e streaming 1 +image_orientation 0x0101 8 +- b horizontal_mirror 0 +- b vertical_flip 1 +software_reset 0x0103 8 +- e off 0 +- e on 1 +grouped_parameter_hold 0x0104 8 +mask_corrupted_frames 0x0105 8 +- e allow 0 +- e mask 1 +fast_standby_ctrl 0x0106 8 +- e complete_frames 0 +- e frame_truncation 1 +CCI_address_ctrl 0x0107 8 +2nd_CCI_if_ctrl 0x0108 8 +- b enable 0 +- b ack 1 +2nd_CCI_address_ctrl 0x0109 8 +CSI_channel_identifier 0x0110 8 +CSI_signaling_mode 0x0111 8 +- e csi_2_dphy 2 +- e csi_2_cphy 3 +CSI_data_format 0x0112 16 +CSI_lane_mode 0x0114 8 +DPCM_Frame_DT 0x011d 8 +Bottom_embedded_data_DT 0x011e 8 +Bottom_embedded_data_VC 0x011f 8 + +gain_mode 0x0120 8 +- e global 0 +- e alternate 1 +ADC_bit_depth 0x0121 8 +emb_data_ctrl 0x0122 v1.1 +- b raw8_packing_for_raw16 0 +- b raw10_packing_for_raw20 1 +- b raw12_packing_for_raw24 2 + +GPIO_TRIG_mode 0x0130 8 +extclk_frequency_mhz 0x0136 16 ireal +temp_sensor_ctrl 0x0138 8 +- b enable 0 +temp_sensor_mode 0x0139 8 +temp_sensor_output 0x013a 8 + +# integration time registers +fine_integration_time 0x0200 16 +coarse_integration_time 0x0202 16 + +# analog gain registers +analog_gain_code_global 0x0204 16 +analog_linear_gain_global 0x0206 16 v1.1 +analog_exponential_gain_global 0x0208 16 v1.1 + +# digital gain registers +digital_gain_global 0x020e 16 + +# hdr control registers +Short_analog_gain_global 0x0216 16 +Short_digital_gain_global 0x0218 16 + +HDR_mode 0x0220 8 +- b enabled 0 +- b separate_analog_gain 1 +- b upscaling 2 +- b reset_sync 3 +- b timing_mode 4 +- b exposure_ctrl_direct 5 +- b separate_digital_gain 6 +HDR_resolution_reduction 0x0221 8 +- f row 0 3 +- f column 4 7 +Exposure_ratio 0x0222 8 +HDR_internal_bit_depth 0x0223 8 +Direct_short_integration_time 0x0224 16 +Short_analog_linear_gain_global 0x0226 16 v1.1 +Short_analog_exponential_gain_global 0x0228 16 v1.1 + +# clock set-up registers +vt_pix_clk_div 0x0300 16 +vt_sys_clk_div 0x0302 16 +pre_pll_clk_div 0x0304 16 +#vt_pre_pll_clk_div 0x0304 16 +pll_multiplier 0x0306 16 +#vt_pll_multiplier 0x0306 16 +op_pix_clk_div 0x0308 16 +op_sys_clk_div 0x030a 16 +op_pre_pll_clk_div 0x030c 16 +op_pll_multiplier 0x031e 16 +pll_mode 0x0310 8 +- f 0 0 +- e single 0 +- e dual 1 +op_pix_clk_div_rev 0x0312 16 v1.1 +op_sys_clk_div_rev 0x0314 16 v1.1 + +# frame timing registers +frame_length_lines 0x0340 16 +line_length_pck 0x0342 16 + +# image size registers +x_addr_start 0x0344 16 +y_addr_start 0x0346 16 +x_addr_end 0x0348 16 +y_addr_end 0x034a 16 +x_output_size 0x034c 16 +y_output_size 0x034e 16 + +# timing mode registers +Frame_length_ctrl 0x0350 8 +- b automatic 0 +Timing_mode_ctrl 0x0352 8 +- b manual_readout 0 +- b delayed_exposure 1 +Start_readout_rs 0x0353 8 +- b manual_readout_start 0 +Frame_margin 0x0354 16 + +# sub-sampling registers +x_even_inc 0x0380 16 +x_odd_inc 0x0382 16 +y_even_inc 0x0384 16 +y_odd_inc 0x0386 16 + +# monochrome readout registers +monochrome_en 0x0390 v1.1 +- e enabled 0 + +# image scaling registers +Scaling_mode 0x0400 16 +- e no_scaling 0 +- e horizontal 1 +scale_m 0x0404 16 +scale_n 0x0406 16 +digital_crop_x_offset 0x0408 16 +digital_crop_y_offset 0x040a 16 +digital_crop_image_width 0x040c 16 +digital_crop_image_height 0x040e 16 + +# image compression registers +compression_mode 0x0500 16 +- e none 0 +- e dpcm_pcm_simple 1 + +# test pattern registers +test_pattern_mode 0x0600 16 +- e none 0 +- e solid_color 1 +- e color_bars 2 +- e fade_to_grey 3 +- e pn9 4 +- e color_tile 5 +test_data_red 0x0602 16 +test_data_greenR 0x0604 16 +test_data_blue 0x0606 16 +test_data_greenB 0x0608 16 +value_step_size_smooth 0x060a 8 +value_step_size_quantised 0x060b 8 + +# phy configuration registers +tclk_post 0x0800 8 +ths_prepare 0x0801 8 +ths_zero_min 0x0802 8 +ths_trail 0x0803 8 +tclk_trail_min 0x0804 8 +tclk_prepare 0x0805 8 +tclk_zero 0x0806 8 +tlpx 0x0807 8 +phy_ctrl 0x0808 8 +- e auto 0 +- e UI 1 +- e manual 2 +tclk_post_ex 0x080a 16 +ths_prepare_ex 0x080c 16 +ths_zero_min_ex 0x080e 16 +ths_trail_ex 0x0810 16 +tclk_trail_min_ex 0x0812 16 +tclk_prepare_ex 0x0814 16 +tclk_zero_ex 0x0816 16 +tlpx_ex 0x0818 16 + +# link rate register +requested_link_rate 0x0820 32 u16.16 + +# equalization control registers +DPHY_equalization_mode 0x0824 8 v1.1 +- b eq2 0 +PHY_equalization_ctrl 0x0825 8 v1.1 +- b enable 0 + +# d-phy preamble control registers +DPHY_preamble_ctrl 0x0826 8 v1.1 +- b enable 0 +DPHY_preamble_length 0x0826 8 v1.1 + +# d-phy spread spectrum control registers +PHY_SSC_ctrl 0x0828 8 v1.1 +- b enable 0 + +# manual lp control register +manual_LP_ctrl 0x0829 8 v1.1 +- b enable 0 + +# additional phy configuration registers +twakeup 0x082a v1.1 +tinit 0x082b v1.1 +ths_exit 0x082c v1.1 +ths_exit_ex 0x082e 16 v1.1 + +# phy calibration configuration registers +PHY_periodic_calibration_ctrl 0x0830 8 +- b frame_blanking 0 +PHY_periodic_calibration_interval 0x0831 8 +PHY_init_calibration_ctrl 0x0832 8 +- b stream_start 0 +DPHY_calibration_mode 0x0833 8 v1.1 +- b also_alternate 0 +CPHY_calibration_mode 0x0834 8 v1.1 +- e format_1 0 +- e format_2 1 +- e format_3 2 +t3_calpreamble_length 0x0835 8 v1.1 +t3_calpreamble_length_per 0x0836 8 v1.1 +t3_calaltseq_length 0x0837 8 v1.1 +t3_calaltseq_length_per 0x0838 8 v1.1 +FM2_init_seed 0x083a 16 v1.1 +t3_caludefseq_length 0x083c 16 v1.1 +t3_caludefseq_length_per 0x083e 16 v1.1 + +# c-phy manual control registers +TGR_Preamble_Length 0x0841 8 +- b preamable_prog_seq 7 +- f begin_preamble_length 0 5 +TGR_Post_Length 0x0842 8 +- f post_length 0 4 +TGR_Preamble_Prog_Sequence(n2) 0x0843 +- l n2 0 6 1 +- f symbol_n_1 3 5 +- f symbol_n 0 2 +t3_prepare 0x084e 16 +t3_lpx 0x0850 16 + +# alps control register +ALPS_ctrl 0x085a 8 +- b lvlp_dphy 0 +- b lvlp_cphy 1 +- b alp_cphy 2 + +# lrte control registers +TX_REG_CSI_EPD_EN_SSP_cphy 0x0860 16 +TX_REG_CSI_EPD_OP_SLP_cphy 0x0862 16 +TX_REG_CSI_EPD_EN_SSP_dphy 0x0864 16 +TX_REG_CSI_EPD_OP_SLP_dphy 0x0866 16 +TX_REG_CSI_EPD_MISC_OPTION_cphy 0x0868 v1.1 +TX_REG_CSI_EPD_MISC_OPTION_dphy 0x0869 v1.1 + +# scrambling control registers +Scrambling_ctrl 0x0870 +- b enabled 0 +- f 2 3 +- e 1_seed_cphy 0 +- e 4_seed_cphy 3 +lane_seed_value(seed, lane) 0x0872 16 +- l seed 0 3 0x10 +- l lane 0 7 0x2 + +# usl control registers +TX_USL_REV_ENTRY 0x08c0 16 v1.1 +TX_USL_REV_Clock_Counter 0x08c2 16 v1.1 +TX_USL_REV_LP_Counter 0x08c4 16 v1.1 +TX_USL_REV_Frame_Counter 0x08c6 16 v1.1 +TX_USL_REV_Chronological_Timer 0x08c8 16 v1.1 +TX_USL_FWD_ENTRY 0x08ca 16 v1.1 +TX_USL_GPIO 0x08cc 16 v1.1 +TX_USL_Operation 0x08ce 16 v1.1 +- b reset 0 +TX_USL_ALP_ctrl 0x08d0 16 v1.1 +- b clock_pause 0 +TX_USL_APP_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +TX_USL_SNS_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +USL_Clock_Mode_d_ctrl 0x08d2 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 + +# binning configuration registers +binning_mode 0x0900 8 +binning_type 0x0901 8 +binning_weighting 0x0902 8 + +# data transfer interface registers +data_transfer_if_1_ctrl 0x0a00 8 +- b enable 0 +- b write 1 +- b clear_error 2 +data_transfer_if_1_status 0x0a01 8 +- b read_if_ready 0 +- b write_if_ready 1 +- b data_corrupted 2 +- b improper_if_usage 3 +data_transfer_if_1_page_select 0x0a02 8 +data_transfer_if_1_data(p) 0x0a04 8 f +- l p 0 63 1 + +# image processing and sensor correction configuration registers +shading_correction_en 0x0b00 8 +- b enable 0 +luminance_correction_level 0x0b01 8 +green_imbalance_filter_en 0x0b02 8 +- b enable 0 +mapped_defect_correct_en 0x0b05 8 +- b enable 0 +single_defect_correct_en 0x0b06 8 +- b enable 0 +dynamic_couplet_correct_en 0x0b08 8 +- b enable 0 +combined_defect_correct_en 0x0b0a 8 +- b enable 0 +module_specific_correction_en 0x0b0c 8 +- b enable 0 +dynamic_triplet_defect_correct_en 0x0b13 8 +- b enable 0 +NF_ctrl 0x0b15 8 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black pixel readout registers +OB_readout_control 0x0b30 8 +- b enable 0 +- b interleaving 1 +OB_virtual_channel 0x0b31 8 +OB_DT 0x0b32 8 +OB_data_format 0x0b33 8 + +# color temperature feedback registers +color_temperature 0x0b8c 16 +absolute_gain_greenr 0x0b8e 16 +absolute_gain_red 0x0b90 16 +absolute_gain_blue 0x0b92 16 +absolute_gain_greenb 0x0b94 16 + +# cfa conversion registers +CFA_conversion_ctrl 0x0ba0 v1.1 +- b bayer_conversion_enable 0 + +# flash strobe and sa strobe control registers +flash_strobe_adjustment 0x0c12 8 +flash_strobe_start_point 0x0c14 16 +tflash_strobe_delay_rs_ctrl 0x0c16 16 +tflash_strobe_width_high_rs_ctrl 0x0c18 16 +flash_mode_rs 0x0c1a 8 +- b continuous 0 +- b truncate 1 +- b async 3 +flash_trigger_rs 0x0c1b 8 +flash_status 0x0c1c 8 +- b retimed 0 +sa_strobe_mode 0x0c1d 8 +- b continuous 0 +- b truncate 1 +- b async 3 +- b adjust_edge 4 +sa_strobe_start_point 0x0c1e 16 +tsa_strobe_delay_ctrl 0x0c20 16 +tsa_strobe_width_ctrl 0x0c22 16 +sa_strobe_trigger 0x0c24 8 +sa_strobe_status 0x0c25 8 +- b retimed 0 +tSA_strobe_re_delay_ctrl 0x0c30 16 +tSA_strobe_fe_delay_ctrl 0x0c32 16 + +# pdaf control registers +PDAF_ctrl 0x0d00 16 +- b enable 0 +- b processed 1 +- b interleaved 2 +- b visible_pdaf_correction 3 +PDAF_VC 0x0d02 8 +PDAF_DT 0x0d03 8 +pd_x_addr_start 0x0d04 16 +pd_y_addr_start 0x0d06 16 +pd_x_addr_end 0x0d08 16 +pd_y_addr_end 0x0d0a 16 + +# bracketing interface configuration registers +bracketing_LUT_ctrl 0x0e00 8 +bracketing_LUT_mode 0x0e01 8 +- b continue_streaming 0 +- b loop_mode 1 +bracketing_LUT_entry_ctrl 0x0e02 8 +bracketing_LUT_frame(n) 0x0e10 v1.1 f +- l n 0 0xef 1 + +# integration time and gain parameter limit registers +integration_time_capability 0x1000 16 +- b fine 0 +coarse_integration_time_min 0x1004 16 +coarse_integration_time_max_margin 0x1006 16 +fine_integration_time_min 0x1008 16 +fine_integration_time_max_margin 0x100a 16 + +# digital gain parameter limit registers +digital_gain_capability 0x1081 +- e none 0 +- e global 2 +digital_gain_min 0x1084 16 +digital_gain_max 0x1086 16 +digital_gain_step_size 0x1088 16 + +# data pedestal capability registers +Pedestal_capability 0x10e0 8 v1.1 + +# adc capability registers +ADC_capability 0x10f0 8 +- b bit_depth_ctrl 0 +ADC_bit_depth_capability 0x10f4 32 v1.1 + +# video timing parameter limit registers +min_ext_clk_freq_mhz 0x1100 32 float_ireal +max_ext_clk_freq_mhz 0x1104 32 float_ireal +min_pre_pll_clk_div 0x1108 16 +# min_vt_pre_pll_clk_div 0x1108 16 +max_pre_pll_clk_div 0x110a 16 +# max_vt_pre_pll_clk_div 0x110a 16 +min_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +# min_vt_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +max_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +# max_vt_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +min_pll_multiplier 0x1114 16 +# min_vt_pll_multiplier 0x1114 16 +max_pll_multiplier 0x1116 16 +# max_vt_pll_multiplier 0x1116 16 +min_pll_op_clk_freq_mhz 0x1118 32 float_ireal +max_pll_op_clk_freq_mhz 0x111c 32 float_ireal + +# video timing set-up capability registers +min_vt_sys_clk_div 0x1120 16 +max_vt_sys_clk_div 0x1122 16 +min_vt_sys_clk_freq_mhz 0x1124 32 float_ireal +max_vt_sys_clk_freq_mhz 0x1128 32 float_ireal +min_vt_pix_clk_freq_mhz 0x112c 32 float_ireal +max_vt_pix_clk_freq_mhz 0x1130 32 float_ireal +min_vt_pix_clk_div 0x1134 16 +max_vt_pix_clk_div 0x1136 16 +clock_calculation 0x1138 +- b lane_speed 0 +- b link_decoupled 1 +- b dual_pll_op_sys_ddr 2 +- b dual_pll_op_pix_ddr 3 +num_of_vt_lanes 0x1139 +num_of_op_lanes 0x113a +op_bits_per_lane 0x113b 8 v1.1 + +# frame timing parameter limits +min_frame_length_lines 0x1140 16 +max_frame_length_lines 0x1142 16 +min_line_length_pck 0x1144 16 +max_line_length_pck 0x1146 16 +min_line_blanking_pck 0x1148 16 +min_frame_blanking_lines 0x114a 16 +min_line_length_pck_step_size 0x114c +timing_mode_capability 0x114d +- b auto_frame_length 0 +- b rolling_shutter_manual_readout 2 +- b delayed_exposure_start 3 +- b manual_exposure_embedded_data 4 +frame_margin_max_value 0x114e 16 +frame_margin_min_value 0x1150 +gain_delay_type 0x1151 +- e fixed 0 +- e variable 1 + +# output clock set-up capability registers +min_op_sys_clk_div 0x1160 16 +max_op_sys_clk_div 0x1162 16 +min_op_sys_clk_freq_mhz 0x1164 32 float_ireal +max_op_sys_clk_freq_mhz 0x1168 32 float_ireal +min_op_pix_clk_div 0x116c 16 +max_op_pix_clk_div 0x116e 16 +min_op_pix_clk_freq_mhz 0x1170 32 float_ireal +max_op_pix_clk_freq_mhz 0x1174 32 float_ireal + +# image size parameter limit registers +x_addr_min 0x1180 16 +y_addr_min 0x1182 16 +x_addr_max 0x1184 16 +y_addr_max 0x1186 16 +min_x_output_size 0x1188 16 +min_y_output_size 0x118a 16 +max_x_output_size 0x118c 16 +max_y_output_size 0x118e 16 + +x_addr_start_div_constant 0x1190 v1.1 +y_addr_start_div_constant 0x1191 v1.1 +x_addr_end_div_constant 0x1192 v1.1 +y_addr_end_div_constant 0x1193 v1.1 +x_size_div 0x1194 v1.1 +y_size_div 0x1195 v1.1 +x_output_div 0x1196 v1.1 +y_output_div 0x1197 v1.1 +non_flexible_resolution_support 0x1198 v1.1 +- b new_pix_addr 0 +- b new_output_res 1 +- b output_crop_no_pad 2 +- b output_size_lane_dep 3 + +min_op_pre_pll_clk_div 0x11a0 16 +max_op_pre_pll_clk_div 0x11a2 16 +min_op_pll_ip_clk_freq_mhz 0x11a4 32 float_ireal +max_op_pll_ip_clk_freq_mhz 0x11a8 32 float_ireal +min_op_pll_multiplier 0x11ac 16 +max_op_pll_multiplier 0x11ae 16 +min_op_pll_op_clk_freq_mhz 0x11b0 32 float_ireal +max_op_pll_op_clk_freq_mhz 0x11b4 32 float_ireal +clock_tree_pll_capability 0x11b8 8 +- b dual_pll 0 +- b single_pll 1 +- b ext_divider 2 +- b flexible_op_pix_clk_div 3 +clock_capa_type_capability 0x11b9 v1.1 +- b ireal 0 + +# sub-sampling parameters limit registers +min_even_inc 0x11c0 16 +min_odd_inc 0x11c2 16 +max_even_inc 0x11c4 16 +max_odd_inc 0x11c6 16 +aux_subsamp_capability 0x11c8 v1.1 +- b factor_power_of_2 1 +aux_subsamp_mono_capability 0x11c9 v1.1 +- b factor_power_of_2 1 +monochrome_capability 0x11ca v1.1 +- e inc_odd 0 +- e inc_even 1 +pixel_readout_capability 0x11cb v1.1 +- e bayer 0 +- e monochrome 1 +- e bayer_and_mono 2 +min_even_inc_mono 0x11cc 16 v1.1 +max_even_inc_mono 0x11ce 16 v1.1 +min_odd_inc_mono 0x11d0 16 v1.1 +max_odd_inc_mono 0x11d2 16 v1.1 +min_even_inc_bc2 0x11d4 16 v1.1 +max_even_inc_bc2 0x11d6 16 v1.1 +min_odd_inc_bc2 0x11d8 16 v1.1 +max_odd_inc_bc2 0x11da 16 v1.1 +min_even_inc_mono_bc2 0x11dc 16 v1.1 +max_even_inc_mono_bc2 0x11de 16 v1.1 +min_odd_inc_mono_bc2 0x11f0 16 v1.1 +max_odd_inc_mono_bc2 0x11f2 16 v1.1 + +# image scaling limit parameters +scaling_capability 0x1200 16 +- e none 0 +- e horizontal 1 +- e reserved 2 +scaler_m_min 0x1204 16 +scaler_m_max 0x1206 16 +scaler_n_min 0x1208 16 +scaler_n_max 0x120a 16 +digital_crop_capability 0x120e +- e none 0 +- e input_crop 1 + +# hdr limit registers +hdr_capability_1 0x1210 +- b 2x2_binning 0 +- b combined_analog_gain 1 +- b separate_analog_gain 2 +- b upscaling 3 +- b reset_sync 4 +- b direct_short_exp_timing 5 +- b direct_short_exp_synthesis 6 +min_hdr_bit_depth 0x1211 +hdr_resolution_sub_types 0x1212 +hdr_resolution_sub_type(n) 0x1213 +- l n 0 1 1 +- f row 0 3 +- f column 4 7 +hdr_capability_2 0x121b +- b combined_digital_gain 0 +- b separate_digital_gain 1 +- b timing_mode 3 +- b synthesis_mode 4 +max_hdr_bit_depth 0x121c + +# usl capability register +usl_support_capability 0x1230 v1.1 +- b clock_tree 0 +- b rev_clock_tree 1 +- b rev_clock_calc 2 +usl_clock_mode_d_capability 0x1231 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 +- b noncont_clock_standby 3 +- b noncont_clock_vblank 4 +- b noncont_clock_hblank 5 +min_op_sys_clk_div_rev 0x1234 v1.1 +max_op_sys_clk_div_rev 0x1236 v1.1 +min_op_pix_clk_div_rev 0x1238 v1.1 +max_op_pix_clk_div_rev 0x123a v1.1 +min_op_sys_clk_freq_rev_mhz 0x123c 32 v1.1 float_ireal +max_op_sys_clk_freq_rev_mhz 0x1240 32 v1.1 float_ireal +min_op_pix_clk_freq_rev_mhz 0x1244 32 v1.1 float_ireal +max_op_pix_clk_freq_rev_mhz 0x1248 32 v1.1 float_ireal +max_bitrate_rev_d_mode_mbps 0x124c 32 v1.1 ireal +max_symrate_rev_c_mode_msps 0x1250 32 v1.1 ireal + +# image compression capability registers +compression_capability 0x1300 +- b dpcm_pcm_simple 0 + +# test mode capability registers +test_mode_capability 0x1310 16 +- b solid_color 0 +- b color_bars 1 +- b fade_to_grey 2 +- b pn9 3 +- b color_tile 5 +pn9_data_format1 0x1312 +pn9_data_format2 0x1313 +pn9_data_format3 0x1314 +pn9_data_format4 0x1315 +pn9_misc_capability 0x1316 +- f num_pixels 0 2 +- b compression 3 +test_pattern_capability 0x1317 v1.1 +- b no_repeat 1 +pattern_size_div_m1 0x1318 v1.1 + +# fifo capability registers +fifo_support_capability 0x1502 +- e none 0 +- e derating 1 +- e derating_overrating 2 + +# csi-2 capability registers +phy_ctrl_capability 0x1600 +- b auto_phy_ctl 0 +- b ui_phy_ctl 1 +- b dphy_time_ui_reg_1_ctl 2 +- b dphy_time_ui_reg_2_ctl 3 +- b dphy_time_ctl 4 +- b dphy_ext_time_ui_reg_1_ctl 5 +- b dphy_ext_time_ui_reg_2_ctl 6 +- b dphy_ext_time_ctl 7 +csi_dphy_lane_mode_capability 0x1601 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +csi_signaling_mode_capability 0x1602 +- b csi_dphy 2 +- b csi_cphy 3 +fast_standby_capability 0x1603 +- e no_frame_truncation 0 +- e frame_truncation 1 +csi_address_control_capability 0x1604 +- b cci_addr_change 0 +- b 2nd_cci_addr 1 +- b sw_changeable_2nd_cci_addr 2 +data_type_capability 0x1605 +- b dpcm_programmable 0 +- b bottom_embedded_dt_programmable 1 +- b bottom_embedded_vc_programmable 2 +- b ext_vc_range 3 +csi_cphy_lane_mode_capability 0x1606 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +emb_data_capability 0x1607 v1.1 +- b two_bytes_per_raw16 0 +- b two_bytes_per_raw20 1 +- b two_bytes_per_raw24 2 +- b no_one_byte_per_raw16 3 +- b no_one_byte_per_raw20 4 +- b no_one_byte_per_raw24 5 +max_per_lane_bitrate_lane_d_mode_mbps(n) 0x1608 32 ireal +- l n 0 7 4 4,0x32 +temp_sensor_capability 0x1618 +- b supported 0 +- b CCS_format 1 +- b reset_0x80 2 +max_per_lane_bitrate_lane_c_mode_mbps(n) 0x161a 32 ireal +- l n 0 7 4 4,0x30 +dphy_equalization_capability 0x162b +- b equalization_ctrl 0 +- b eq1 1 +- b eq2 2 +cphy_equalization_capability 0x162c +- b equalization_ctrl 0 +dphy_preamble_capability 0x162d +- b preamble_seq_ctrl 0 +dphy_ssc_capability 0x162e +- b supported 0 +cphy_calibration_capability 0x162f +- b manual 0 +- b manual_streaming 1 +- b format_1_ctrl 2 +- b format_2_ctrl 3 +- b format_3_ctrl 4 +dphy_calibration_capability 0x1630 +- b manual 0 +- b manual_streaming 1 +- b alternate_seq 2 +phy_ctrl_capability_2 0x1631 +- b tgr_length 0 +- b tgr_preamble_prog_seq 1 +- b extra_cphy_manual_timing 2 +- b clock_based_manual_cdphy 3 +- b clock_based_manual_dphy 4 +- b clock_based_manual_cphy 5 +- b manual_lp_dphy 6 +- b manual_lp_cphy 7 +lrte_cphy_capability 0x1632 +- b pdq_short 0 +- b spacer_short 1 +- b pdq_long 2 +- b spacer_long 3 +- b spacer_no_pdq 4 +lrte_dphy_capability 0x1633 +- b pdq_short_opt1 0 +- b spacer_short_opt1 1 +- b pdq_long_opt1 2 +- b spacer_long_opt1 3 +- b spacer_short_opt2 4 +- b spacer_long_opt2 5 +- b spacer_no_pdq_opt1 6 +- b spacer_variable_opt2 7 +alps_capability_dphy 0x1634 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +alps_capability_cphy 0x1635 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +- e alp_not_supported 0xc 0xc +- e alp_supported 0xd 0xc +- e controllable_alp 0xe 0xc +scrambling_capability 0x1636 +- b scrambling_supported 0 +- f max_seeds_per_lane_c 1 2 +- e 1 0 +- e 4 3 +- f num_seed_regs 3 5 +- e 0 0 +- e 1 1 +- e 4 4 +- b num_seed_per_lane 6 +dphy_manual_constant 0x1637 +cphy_manual_constant 0x1638 +CSI2_interface_capability_misc 0x1639 v1.1 +- b eotp_short_pkt_opt2 0 +PHY_ctrl_capability_3 0x165c v1.1 +- b dphy_timing_not_multiple 0 +- b dphy_min_timing_value_1 1 +- b twakeup_supported 2 +- b tinit_supported 3 +- b ths_exit_supported 4 +- b cphy_timing_not_multiple 5 +- b cphy_min_timing_value_1 6 +dphy_sf 0x165d v1.1 +cphy_sf 0x165e v1.1 +- f twakeup 0 3 +- f tinit 4 7 +dphy_limits_1 0x165f v1.1 +- f ths_prepare 0 3 +- f ths_zero 4 7 +dphy_limits_2 0x1660 v1.1 +- f ths_trail 0 3 +- f tclk_trail_min 4 7 +dphy_limits_3 0x1661 v1.1 +- f tclk_prepare 0 3 +- f tclk_zero 4 7 +dphy_limits_4 0x1662 v1.1 +- f tclk_post 0 3 +- f tlpx 4 7 +dphy_limits_5 0x1663 v1.1 +- f ths_exit 0 3 +- f twakeup 4 7 +dphy_limits_6 0x1664 v1.1 +- f tinit 0 3 +cphy_limits_1 0x1665 v1.1 +- f t3_prepare_max 0 3 +- f t3_lpx_max 4 7 +cphy_limits_2 0x1666 v1.1 +- f ths_exit_max 0 3 +- f twakeup_max 4 7 +cphy_limits_3 0x1667 v1.1 +- f tinit_max 0 3 + +# binning capability registers +min_frame_length_lines_bin 0x1700 16 +max_frame_length_lines_bin 0x1702 16 +min_line_length_pck_bin 0x1704 16 +max_line_length_pck_bin 0x1706 16 +min_line_blanking_pck_bin 0x1708 16 +fine_integration_time_min_bin 0x170a 16 +fine_integration_time_max_margin_bin 0x170c 16 +binning_capability 0x1710 +- e unsupported 0 +- e binning_then_subsampling 1 +- e subsampling_then_binning 2 +binning_weighting_capability 0x1711 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types 0x1712 +binning_sub_type(n) 0x1713 +- l n 0 63 1 +- f row 0 3 +- f column 4 7 +binning_weighting_mono_capability 0x1771 v1.1 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types_mono 0x1772 v1.1 +binning_sub_type_mono(n) 0x1773 v1.1 f +- l n 0 63 1 + +# data transfer interface capability registers +data_transfer_if_capability 0x1800 +- b supported 0 +- b polling 2 + +# sensor correction capability registers +shading_correction_capability 0x1900 +- b color_shading 0 +- b luminance_correction 1 +green_imbalance_capability 0x1901 +- b supported 0 +module_specific_correction_capability 0x1903 +defect_correction_capability 0x1904 16 +- b mapped_defect 0 +- b dynamic_couplet 2 +- b dynamic_single 5 +- b combined_dynamic 8 +defect_correction_capability_2 0x1906 16 +- b dynamic_triplet 3 +nf_capability 0x1908 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black readout capability registers +ob_readout_capability 0x1980 +- b controllable_readout 0 +- b visible_pixel_readout 1 +- b different_vc_readout 2 +- b different_dt_readout 3 +- b prog_data_format 4 + +# color feedback capability registers +color_feedback_capability 0x1987 +- b kelvin 0 +- b awb_gain 1 + +# cfa pattern capability registers +CFA_pattern_capability 0x1990 v1.1 +- e bayer 0 +- e monochrome 1 +- e 4x4_quad_bayer 2 +- e vendor_specific 3 +CFA_pattern_conversion_capability 0x1991 v1.1 +- b bayer 0 + +# timer capability registers +flash_mode_capability 0x1a02 +- b single_strobe 0 +sa_strobe_mode_capability 0x1a03 +- b fixed_width 0 +- b edge_ctrl 1 + +# soft reset capability registers +reset_max_delay 0x1a10 v1.1 +reset_min_time 0x1a11 v1.1 + +# pdaf capability registers +pdaf_capability_1 0x1b80 +- b supported 0 +- b processed_bottom_embedded 1 +- b processed_interleaved 2 +- b raw_bottom_embedded 3 +- b raw_interleaved 4 +- b visible_pdaf_correction 5 +- b vc_interleaving 6 +- b dt_interleaving 7 +pdaf_capability_2 0x1b81 +- b ROI 0 +- b after_digital_crop 1 +- b ctrl_retimed 2 + +# bracketing interface capability registers +bracketing_lut_capability_1 0x1c00 +- b coarse_integration 0 +- b global_analog_gain 1 +- b flash 4 +- b global_digital_gain 5 +- b alternate_global_analog_gain 6 +bracketing_lut_capability_2 0x1c01 +- b single_bracketing_mode 0 +- b looped_bracketing_mode 1 +bracketing_lut_size 0x1c02 diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst new file mode 100644 index 000000000000..f49e971f2d92 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause + +.. include:: <isonum.txt> + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +<https://www.mipi.org/specifications/camera-command-set>`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) expses another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Register definition generator +----------------------------- + +The ccs-regs.asc file contains MIPI CCS register definitions that are used +to produce C source code files for definitions that can be better used by +programs written in C language. As there are many dependencies between the +produced files, please do not modify them manually as it's error-prone and +in vain, but instead change the script producing them. + +Usage +~~~~~ + +Conventionally the script is called this way to update the CCS driver +definitions: + +.. code-block:: none + + $ Documentation/driver-api/media/drivers/ccs/mk-ccs-regs -k \ + -e drivers/media/i2c/ccs/ccs-regs.h \ + -L drivers/media/i2c/ccs/ccs-limits.h \ + -l drivers/media/i2c/ccs/ccs-limits.c \ + -c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs new file mode 100755 index 000000000000..6668deaf2f19 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs @@ -0,0 +1,433 @@ +#!/usr/bin/perl -w +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +use Getopt::Long qw(:config no_ignore_case); +use File::Basename; + +my $ccsregs = "ccs-regs.asc"; +my $header; +my $regarray; +my $limitc; +my $limith; +my $kernel; +my $help; + +GetOptions("ccsregs|c=s" => \$ccsregs, + "header|e=s" => \$header, + "regarray|r=s" => \$regarray, + "limitc|l=s" => \$limitc, + "limith|L=s" => \$limith, + "kernel|k" => \$kernel, + "help|h" => \$help) or die "can't parse options"; + +$help = 1 if ! defined $header || ! defined $limitc || ! defined $limith; + +if (defined $help) { + print <<EOH +$0 - Create CCS register definitions for C + +usage: $0 -c ccs-regs.asc -e header -r regarray -l limit-c -L limit-header [-k] + + -c ccs register file + -e header file name + -r register description array file name + -l limit and capability array file name + -L limit and capability header file name + -k generate files for kernel space consumption +EOH + ; + exit 0; +} + +my $lh_hdr = ! defined $kernel + ? '#include "ccs-os.h"' . "\n" + : "#include <linux/bits.h>\n#include <linux/types.h>\n"; +my $uint32_t = ! defined $kernel ? 'uint32_t' : 'u32'; +my $uint16_t = ! defined $kernel ? 'uint16_t' : 'u16'; + +open(my $R, "< $ccsregs") or die "can't open $ccsregs"; + +open(my $H, "> $header") or die "can't open $header"; +my $A; +if (defined $regarray) { + open($A, "> $regarray") or die "can't open $regarray"; +} +open(my $LC, "> $limitc") or die "can't open $limitc"; +open(my $LH, "> $limith") or die "can't open $limith"; + +my %this; + +sub is_limit_reg($) { + my $addr = hex $_[0]; + + return 0 if $addr < 0x40; # weed out status registers + return 0 if $addr >= 0x100 && $addr < 0xfff; # weed out configuration registers + + return 1; +} + +my $uc_header = basename uc $header; +$uc_header =~ s/[^A-Z0-9]/_/g; + +my $copyright = "/* Copyright (C) 2019--2020 Intel Corporation */\n"; +my $license = "SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause"; + +for my $fh ($A, $LC) { + print $fh "// $license\n$copyright\n" if defined $fh; +} + +for my $fh ($H, $LH) { + print $fh "/* $license */\n$copyright\n"; +} + +sub bit_def($) { + my $bit = shift @_; + + return "BIT($bit)" if defined $kernel; + return "(1U << $bit)" if $bit =~ /^[a-zA-Z0-9_]+$/; + return "(1U << ($bit))"; +} + +print $H <<EOF +#ifndef __${uc_header}__ +#define __${uc_header}__ + +EOF + ; + +print $H "#include <linux/bits.h>\n\n" if defined $kernel; + +print $H <<EOF +#define CCS_FL_BASE 16 +EOF + ; + +print $H "#define CCS_FL_16BIT " . bit_def("CCS_FL_BASE") . "\n"; +print $H "#define CCS_FL_32BIT " . bit_def("CCS_FL_BASE + 1") . "\n"; +print $H "#define CCS_FL_FLOAT_IREAL " . bit_def("CCS_FL_BASE + 2") . "\n"; +print $H "#define CCS_FL_IREAL " . bit_def("CCS_FL_BASE + 3") . "\n"; + +print $H <<EOF +#define CCS_R_ADDR(r) ((r) & 0xffff) + +EOF + ; + +print $A <<EOF +#include <stdint.h> +#include <stdio.h> +#include "ccs-extra.h" +#include "ccs-regs.h" + +EOF + if defined $A; + +my $uc_limith = basename uc $limith; +$uc_limith =~ s/[^A-Z0-9]/_/g; + +print $LH <<EOF +#ifndef __${uc_limith}__ +#define __${uc_limith}__ + +$lh_hdr +struct ccs_limit { + $uint32_t reg; + $uint16_t size; + $uint16_t flags; + const char *name; +}; + +EOF + ; +print $LH "#define CCS_L_FL_SAME_REG " . bit_def(0) . "\n\n"; + +print $LH <<EOF +extern const struct ccs_limit ccs_limits[]; + +EOF + ; + +print $LC <<EOF +#include "ccs-limits.h" +#include "ccs-regs.h" + +const struct ccs_limit ccs_limits[] = { +EOF + ; + +my $limitcount = 0; +my $argdescs; +my $reglist = "const struct ccs_reg_desc ccs_reg_desc[] = {\n"; + +sub name_split($$) { + my ($name, $addr) = @_; + my $args; + + $name =~ /([^\(]+?)(\(.*)/; + ($name, $args) = ($1, $2); + $args = [split /,\s*/, $args]; + foreach my $t (@$args) { + $t =~ s/[\(\)]//g; + $t =~ s/\//\\\//g; + } + + return ($name, $addr, $args); +} + +sub tabconv($) { + $_ = shift; + + my @l = split "\n", $_; + + map { + s/ {8,8}/\t/g; + s/\t\K +//; + } @l; + + return (join "\n", @l) . "\n"; +} + +sub elem_size(@) { + my @flags = @_; + + return 2 if grep /^16$/, @flags; + return 4 if grep /^32$/, @flags; + return 1; +} + +sub arr_size($) { + my $this = $_[0]; + my $size = $this->{elsize}; + my $h = $this->{argparams}; + + foreach my $arg (@{$this->{args}}) { + my $apref = $h->{$arg}; + + $size *= $apref->{max} - $apref->{min} + 1; + } + + return $size; +} + +sub print_args($$$) { + my ($this, $postfix, $is_same_reg) = @_; + my ($args, $argparams, $name) = + ($this->{args}, $this->{argparams}, $this->{name}); + my $varname = "ccs_reg_arg_" . (lc $name) . $postfix; + my @mins; + my @sorted_args = @{$this->{sorted_args}}; + my $lim_arg; + my $size = arr_size($this); + + $argdescs .= "static const struct ccs_reg_arg " . $varname . "[] = {\n"; + + foreach my $sorted_arg (@sorted_args) { + push @mins, $argparams->{$sorted_arg}->{min}; + } + + foreach my $sorted_arg (@sorted_args) { + my $h = $argparams->{$sorted_arg}; + + $argdescs .= "\t{ \"$sorted_arg\", $h->{min}, $h->{max}, $h->{elsize} },\n"; + + $lim_arg .= defined $lim_arg ? ", $h->{min}" : "$h->{min}"; + } + + $argdescs .= "};\n\n"; + + $reglist .= "\t{ CCS_R_" . (uc $name) . "(" . (join ",", (@mins)) . + "), $size, sizeof($varname) / sizeof(*$varname)," . + " \"" . (lc $name) . "\", $varname },\n"; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . "($lim_arg), " . + $size . ", " . ($is_same_reg ? "CCS_L_FL_SAME_REG" : "0") . + ", \"$name" . (defined $this->{discontig} ? " $lim_arg" : "") . "\" },\n" + if is_limit_reg $this->{base_addr}; +} + +my $hdr_data; + +while (<$R>) { + chop; + s/^\s*//; + next if /^[#;]/ || /^$/; + if (s/^-\s*//) { + if (s/^b\s*//) { + my ($bit, $addr) = split /\t+/; + $bit = uc $bit; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) ."_$bit", bit_def($addr) . "\n"; + } elsif (s/^f\s*//) { + s/[,\.-]/_/g; + my @a = split /\s+/; + my ($msb, $lsb, $this_field) = reverse @a; + @a = ( { "name" => "SHIFT", "addr" => $lsb, "fmt" => "%uU", }, + { "name" => "MASK", "addr" => (1 << ($msb + 1)) - 1 - ((1 << $lsb) - 1), "fmt" => "0x%" . join(".", ($this{"elsize"} >> 2) x 2) . "x" } ); + $this{"field"} = $this_field; + foreach my $ar (@a) { + #print $ar->{fmt}."\n"; + $hdr_data .= sprintf "#define %-62s " . $ar->{"fmt"} . "\n", "CCS_" . (uc $this{"name"}) . (defined $this_field ? "_" . uc $this_field : "") . "_" . $ar->{"name"}, $ar->{"addr"} . "\n"; + } + } elsif (s/^e\s*//) { + s/[,\.-]/_/g; + my ($enum, $addr) = split /\s+/; + $enum = uc $enum; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) . (defined $this{"field"} ? "_" . uc $this{"field"} : "") ."_$enum", $addr . ($addr =~ /0x/i ? "" : "U") . "\n"; + } elsif (s/^l\s*//) { + my ($arg, $min, $max, $elsize, @discontig) = split /\s+/; + my $size; + + foreach my $num ($min, $max) { + $num = hex $num if $num =~ /0x/i; + } + + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MIN_$arg"), $min . ($min =~ /0x/i ? "" : "U") . "\n"; + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MAX_$arg"), $max . ($max =~ /0x/i ? "" : "U") . "\n"; + + my $h = $this{argparams}; + + $h->{$arg} = { "min" => $min, + "max" => $max, + "elsize" => $elsize =~ /^0x/ ? hex $elsize : $elsize, + "discontig" => \@discontig }; + + $this{discontig} = $arg if @discontig; + + next if $#{$this{args}} + 1 != scalar keys %{$this{argparams}}; + + my $reg_formula = "($this{addr}"; + my $lim_formula; + + foreach my $arg (@{$this{args}}) { + my $d = $h->{$arg}->{discontig}; + my $times = $h->{$arg}->{elsize} != 1 ? + " * " . $h->{$arg}->{elsize} : ""; + + if (@$d) { + my ($lim, $offset) = split /,/, $d->[0]; + + $reg_formula .= " + (($arg) < $lim ? ($arg)$times : $offset + (($arg) - $lim)$times)"; + } else { + $reg_formula .= " + ($arg)$times"; + } + + $lim_formula .= (defined $lim_formula ? " + " : "") . "($arg)$times"; + } + + $reg_formula .= ")\n"; + $lim_formula =~ s/^\(([a-z0-9]+)\)$/$1/i; + + print $H tabconv sprintf("#define %-62s %s", "CCS_R_" . (uc $this{name}) . + $this{arglist}, $reg_formula); + + print $H tabconv $hdr_data; + undef $hdr_data; + + # Sort arguments in descending order by size + @{$this{sorted_args}} = sort { + $h->{$a}->{elsize} <= $h->{$b}->{elsize} + } @{$this{args}}; + + if (defined $this{discontig}) { + my $da = $this{argparams}->{$this{discontig}}; + my ($first_discontig) = split /,/, $da->{discontig}->[0]; + my $max = $da->{max}; + + $da->{max} = $first_discontig - 1; + print_args(\%this, "", 0); + + $da->{min} = $da->{max} + 1; + $da->{max} = $max; + print_args(\%this, $first_discontig, 1); + } else { + print_args(\%this, "", 0); + } + + next unless is_limit_reg $this{base_addr}; + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}) . "_OFFSET(" . + (join ", ", @{$this{args}}) . ")", "($lim_formula)"; + } + + if (! @{$this{args}}) { + print $H tabconv($hdr_data); + undef $hdr_data; + } + + next; + } + + my ($name, $addr, @flags) = split /\t+/, $_; + my $args = []; + + my $sp; + + ($name, $addr, $args) = name_split($name, $addr) if /\(.*\)/; + + $name =~ s/[,\.-]/_/g; + + my $flagstring = ""; + my $size = elem_size(@flags); + $flagstring .= "| CCS_FL_16BIT " if $size eq "2"; + $flagstring .= "| CCS_FL_32BIT " if $size eq "4"; + $flagstring .= "| CCS_FL_FLOAT_IREAL " if grep /^float_ireal$/, @flags; + $flagstring .= "| CCS_FL_IREAL " if grep /^ireal$/, @flags; + $flagstring =~ s/^\| //; + $flagstring =~ s/ $//; + $flagstring = "($flagstring)" if $flagstring =~ /\|/; + my $base_addr = $addr; + $addr = "($addr | $flagstring)" if $flagstring ne ""; + + my $arglist = @$args ? "(" . (join ", ", @$args) . ")" : ""; + $hdr_data .= sprintf "#define %-62s %s\n", "CCS_R_" . (uc $name), $addr + if !@$args; + + $name =~ s/\(.*//; + + %this = ( name => $name, + addr => $addr, + base_addr => $base_addr, + argparams => {}, + args => $args, + arglist => $arglist, + elsize => $size, + ); + + if (!@$args) { + $reglist .= "\t{ CCS_R_" . (uc $name) . ", 1, 0, \"" . (lc $name) . "\", NULL },\n"; + print $H tabconv $hdr_data; + undef $hdr_data; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . ", " . + $this{elsize} . ", 0, \"$name\" },\n" + if is_limit_reg $this{base_addr}; + } + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}), $limitcount++ + if is_limit_reg $this{base_addr}; +} + +if (defined $A) { + print $A $argdescs, $reglist; + + print $A "\t{ 0 }\n"; + + print $A "};\n"; +} + +print $H "\n#endif /* __${uc_header}__ */\n"; + +print $LH tabconv sprintf "#define %-63s%s\n", "CCS_L_LAST", $limitcount; + +print $LH "\n#endif /* __${uc_limith}__ */\n"; + +print $LC "\t{ 0 } /* Guardian */\n"; +print $LC "};\n"; + +close($R); +close($H); +close($A) if defined $A; +close($LC); +close($LH); diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index eb7011782863..426cda633bf0 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -26,6 +26,7 @@ Video4Linux (V4L) drivers tuners vimc-devel zoran + ccs/ccs Digital TV drivers diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst index 65115448c52d..673bdff919ea 100644 --- a/Documentation/driver-api/media/drivers/vidtv.rst +++ b/Documentation/driver-api/media/drivers/vidtv.rst @@ -149,11 +149,11 @@ vidtv_psi.[ch] Because the generator is implemented in a separate file, it can be reused elsewhere in the media subsystem. - Currently vidtv supports working with 3 PSI tables: PAT, PMT and - SDT. + Currently vidtv supports working with 5 PSI tables: PAT, PMT, + SDT, NIT and EIT. The specification for PAT and PMT can be found in *ISO 13818-1: - Systems*, while the specification for the SDT can be found in *ETSI + Systems*, while the specification for the SDT, NIT, EIT can be found in *ETSI EN 300 468: Specification for Service Information (SI) in DVB systems*. @@ -197,6 +197,8 @@ vidtv_channel.[ch] #. Their programs will be concatenated to populate the PAT + #. Their events will be concatenated to populate the EIT + #. For each program in the PAT, a PMT section will be created #. The PMT section for a channel will be assigned its streams. @@ -256,6 +258,42 @@ Using dvb-fe-tool The first step to check whether the demod loaded successfully is to run:: $ dvb-fe-tool + Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities: + CAN_FEC_1_2 + CAN_FEC_2_3 + CAN_FEC_3_4 + CAN_FEC_4_5 + CAN_FEC_5_6 + CAN_FEC_6_7 + CAN_FEC_7_8 + CAN_FEC_8_9 + CAN_FEC_AUTO + CAN_GUARD_INTERVAL_AUTO + CAN_HIERARCHY_AUTO + CAN_INVERSION_AUTO + CAN_QAM_16 + CAN_QAM_32 + CAN_QAM_64 + CAN_QAM_128 + CAN_QAM_256 + CAN_QAM_AUTO + CAN_QPSK + CAN_TRANSMISSION_MODE_AUTO + DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A + Supported delivery systems: + DVBT + DVBT2 + [DVBC/ANNEX_A] + DVBS + DVBS2 + Frequency range for the current standard: + From: 51.0 MHz + To: 2.15 GHz + Step: 62.5 kHz + Tolerance: 29.5 MHz + Symbol rate ranges for the current standard: + From: 1.00 MBauds + To: 45.0 MBauds This should return what is currently set up at the demod struct, i.e.:: @@ -314,7 +352,7 @@ For this, one should provide a configuration file known as a 'scan file', here's an example:: [Channel] - FREQUENCY = 330000000 + FREQUENCY = 474000000 MODULATION = QAM/AUTO SYMBOL_RATE = 6940000 INNER_FEC = AUTO @@ -335,6 +373,14 @@ You can browse scan tables online here: `dvb-scan-tables Assuming this channel is named 'channel.conf', you can then run:: $ dvbv5-scan channel.conf + dvbv5-scan ~/vidtv.conf + ERROR command BANDWIDTH_HZ (5) not found during retrieve + Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet). + Scanning frequency #1 330000000 + (0x00) Signal= -68.00dBm + Scanning frequency #2 474000000 + Lock (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0 + Service Beethoven, provider LinuxTV.org: digital television For more information on dvb-scan, check its documentation online here: `dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_. @@ -344,23 +390,38 @@ Using dvb-zap dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The typical use is to tune into a channel and put it into record mode. The example -below - which is taken from the documentation - illustrates that:: +below - which is taken from the documentation - illustrates that\ [1]_:: - $ dvbv5-zap -c dvb_channel.conf "trilhas sonoras" -r - using demux '/dev/dvb/adapter0/demux0' + $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10 + using demux 'dvb0.demux0' reading channels from file 'dvb_channel.conf' - service has pid type 05: 204 - tuning to 573000000 Hz - audio pid 104 - dvb_set_pesfilter 104 - Lock (0x1f) Quality= Good Signal= 100.00% C/N= -13.80dB UCB= 70 postBER= 3.14x10^-3 PER= 0 - DVR interface '/dev/dvb/adapter0/dvr0' can now be opened + tuning to 474000000 Hz + pass all PID's to TS + dvb_set_pesfilter 8192 + dvb_dev_set_bufsize: buffer set to 6160384 + Lock (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Lock (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Record to file 'music.ts' started + received 24587768 bytes (2401 Kbytes/sec) + Lock (0x1f) Quality= Good Signal= -34.42dBm C/N= 33.89dB UCB= 0 postBER= 0 preBER= 2.44x10^-3 PER= 0 + +.. [1] In this example, it records 10 seconds with all program ID's stored + at the music.ts file. + -The channel can be watched by playing the contents of the DVR interface, with -some player that recognizes the MPEG-TS format, such as *mplayer* or *vlc*. +The channel can be watched by playing the contents of the stream with some +player that recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``. By playing the contents of the stream one can visually inspect the workings of -vidtv, e.g.:: +vidtv, e.g., to play a recorded TS file with:: + + $ mplayer music.ts + +or, alternatively, running this command on one terminal:: + + $ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r & + +And, on a second terminal, playing the contents from DVR interface with:: $ mplayer /dev/dvb/adapter0/dvr0 @@ -423,3 +484,30 @@ A nice addition is to simulate some noise when the signal quality is bad by: - Updating the error statistics accordingly (e.g. BER, etc). - Simulating some noise in the encoded data. + +Functions and structs used within vidtv +--------------------------------------- + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst index 91f77fe58e83..ea43cdb5b0e4 100644 --- a/Documentation/driver-api/media/dtv-frontend.rst +++ b/Documentation/driver-api/media/dtv-frontend.rst @@ -244,7 +244,7 @@ Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) Having it available after inner FEC is more common. Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors after + - Those counters measure the number of bits and bit errors after the forward error correction (FEC) on the inner coding block (after Viterbi, LDPC or other inner code). @@ -253,7 +253,7 @@ Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POS see :c:type:`fe_status`). Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors before + - Those counters measure the number of bits and bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). @@ -263,7 +263,7 @@ Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-T after ``FE_HAS_VITERBI``, see :c:type:`fe_status`). Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`) - - Those counters measure the number of blocks and block errors errors after + - Those counters measure the number of blocks and block errors after the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst index 77f42ea3bac7..b2e91804829b 100644 --- a/Documentation/driver-api/media/v4l2-controls.rst +++ b/Documentation/driver-api/media/v4l2-controls.rst @@ -335,7 +335,7 @@ current and new values: union v4l2_ctrl_ptr p_new; union v4l2_ctrl_ptr p_cur; -If the control has a simple s32 type type, then: +If the control has a simple s32 type, then: .. code-block:: c @@ -349,7 +349,7 @@ Within the control ops you can freely use these. The val and cur.val speak for themselves. The p_char pointers point to character buffers of length ctrl->maximum + 1, and are always 0-terminated. -Unless the control is marked volatile the p_cur field points to the the +Unless the control is marked volatile the p_cur field points to the current cached control value. When you create a new control this value is made identical to the default value. After calling v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally a good idea to call this diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst index 666330af31ed..99e3b5fa7444 100644 --- a/Documentation/driver-api/media/v4l2-dev.rst +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -212,7 +212,7 @@ types exist: ========================== ==================== ============================== The last argument gives you a certain amount of control over the device -device node number used (i.e. the X in ``videoX``). Normally you will pass -1 +node number used (i.e. the X in ``videoX``). Normally you will pass -1 to let the v4l2 framework pick the first free number. But sometimes users want to select a specific node number. It is common that drivers allow the user to select a specific device node number through a driver module diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index bbb0c1c0e5cf..a94f17d9b836 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -86,9 +86,6 @@ Other Functions .. kernel-doc:: fs/dax.c :export: -.. kernel-doc:: fs/direct-io.c - :export: - .. kernel-doc:: fs/libfs.c :export: diff --git a/Documentation/filesystems/debugfs.rst b/Documentation/filesystems/debugfs.rst index 728ab57a611a..0f2292e367e6 100644 --- a/Documentation/filesystems/debugfs.rst +++ b/Documentation/filesystems/debugfs.rst @@ -199,7 +199,7 @@ of its elements. Note: Once array is created its size can not be changed. There is a helper function to create device related seq_file:: - struct dentry *debugfs_create_devm_seqfile(struct device *dev, + void debugfs_create_devm_seqfile(struct device *dev, const char *name, struct dentry *parent, int (*read_fn)(struct seq_file *s, diff --git a/Documentation/filesystems/ext4/journal.rst b/Documentation/filesystems/ext4/journal.rst index 805a1e9ea3a5..849d5b119eb8 100644 --- a/Documentation/filesystems/ext4/journal.rst +++ b/Documentation/filesystems/ext4/journal.rst @@ -256,6 +256,10 @@ which is 1024 bytes long: - s\_padding2 - * - 0x54 + - \_\_be32 + - s\_num\_fc\_blocks + - Number of fast commit blocks in the journal. + * - 0x58 - \_\_u32 - s\_padding[42] - @@ -310,6 +314,8 @@ The journal incompat features are any combination of the following: - This journal uses v3 of the checksum on-disk format. This is the same as v2, but the journal block tag size is fixed regardless of the size of block numbers. (JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3) + * - 0x20 + - Journal has fast commit blocks. (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT) .. _jbd2_checksum_type: diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst index 93e55d7c1d40..2eb1ab20498d 100644 --- a/Documentation/filesystems/ext4/super.rst +++ b/Documentation/filesystems/ext4/super.rst @@ -596,6 +596,13 @@ following: - Sparse Super Block, v2. If this flag is set, the SB field s\_backup\_bgs points to the two block groups that contain backup superblocks (COMPAT\_SPARSE\_SUPER2). + * - 0x400 + - Fast commits supported. Although fast commits blocks are + backward incompatible, fast commit blocks are not always + present in the journal. If fast commit blocks are present in + the journal, JBD2 incompat feature + (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT) gets + set (COMPAT\_FAST\_COMMIT). .. _super_incompat: diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index 895e9711ed88..e0204a23e997 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -27,9 +27,9 @@ automatically verified against the file's Merkle tree. Reads of any corrupted data, including mmap reads, will fail. Userspace can use another ioctl to retrieve the root hash (actually -the "file measurement", which is a hash that includes the root hash) -that fs-verity is enforcing for the file. This ioctl executes in -constant time, regardless of the file size. +the "fs-verity file digest", which is a hash that includes the Merkle +tree root hash) that fs-verity is enforcing for the file. This ioctl +executes in constant time, regardless of the file size. fs-verity is essentially a way to hash a file in constant time, subject to the caveat that reads which would violate the hash will @@ -177,9 +177,10 @@ FS_IOC_ENABLE_VERITY can fail with the following errors: FS_IOC_MEASURE_VERITY --------------------- -The FS_IOC_MEASURE_VERITY ioctl retrieves the measurement of a verity -file. The file measurement is a digest that cryptographically -identifies the file contents that are being enforced on reads. +The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file. +The fs-verity file digest is a cryptographic digest that identifies +the file contents that are being enforced on reads; it is computed via +a Merkle tree and is different from a traditional full-file digest. This ioctl takes in a pointer to a variable-length structure:: @@ -197,7 +198,7 @@ On success, 0 is returned and the kernel fills in the structure as follows: - ``digest_algorithm`` will be the hash algorithm used for the file - measurement. It will match ``fsverity_enable_arg::hash_algorithm``. + digest. It will match ``fsverity_enable_arg::hash_algorithm``. - ``digest_size`` will be the size of the digest in bytes, e.g. 32 for SHA-256. (This can be redundant with ``digest_algorithm``.) - ``digest`` will be the actual bytes of the digest. @@ -257,25 +258,24 @@ non-verity one, with the following exceptions: with EIO (for read()) or SIGBUS (for mmap() reads). - If the sysctl "fs.verity.require_signatures" is set to 1 and the - file's verity measurement is not signed by a key in the fs-verity - keyring, then opening the file will fail. See `Built-in signature - verification`_. + file is not signed by a key in the fs-verity keyring, then opening + the file will fail. See `Built-in signature verification`_. Direct access to the Merkle tree is not supported. Therefore, if a verity file is copied, or is backed up and restored, then it will lose its "verity"-ness. fs-verity is primarily meant for files like executables that are managed by a package manager. -File measurement computation -============================ +File digest computation +======================= This section describes how fs-verity hashes the file contents using a -Merkle tree to produce the "file measurement" which cryptographically -identifies the file contents. This algorithm is the same for all -filesystems that support fs-verity. +Merkle tree to produce the digest which cryptographically identifies +the file contents. This algorithm is the same for all filesystems +that support fs-verity. Userspace only needs to be aware of this algorithm if it needs to -compute the file measurement itself, e.g. in order to sign the file. +compute fs-verity file digests itself, e.g. in order to sign files. .. _fsverity_merkle_tree: @@ -325,26 +325,22 @@ can't a distinguish a large file from a small second file whose data is exactly the top-level hash block of the first file. Ambiguities also arise from the convention of padding to the next block boundary. -To solve this problem, the verity file measurement is actually -computed as a hash of the following structure, which contains the -Merkle tree root hash as well as other fields such as the file size:: +To solve this problem, the fs-verity file digest is actually computed +as a hash of the following structure, which contains the Merkle tree +root hash as well as other fields such as the file size:: struct fsverity_descriptor { __u8 version; /* must be 1 */ __u8 hash_algorithm; /* Merkle tree hash algorithm */ __u8 log_blocksize; /* log2 of size of data and tree blocks */ __u8 salt_size; /* size of salt in bytes; 0 if none */ - __le32 sig_size; /* must be 0 */ + __le32 __reserved_0x04; /* must be 0 */ __le64 data_size; /* size of file the Merkle tree is built over */ __u8 root_hash[64]; /* Merkle tree root hash */ __u8 salt[32]; /* salt prepended to each hashed block */ __u8 __reserved[144]; /* must be 0's */ }; -Note that the ``sig_size`` field must be set to 0 for the purpose of -computing the file measurement, even if a signature was provided (or -will be provided) to `FS_IOC_ENABLE_VERITY`_. - Built-in signature verification =============================== @@ -359,20 +355,20 @@ kernel. Specifically, it adds support for: certificates from being added. 2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted - detached signature in DER format of the file measurement. On - success, this signature is persisted alongside the Merkle tree. + detached signature in DER format of the file's fs-verity digest. + On success, this signature is persisted alongside the Merkle tree. Then, any time the file is opened, the kernel will verify the - file's actual measurement against this signature, using the - certificates in the ".fs-verity" keyring. + file's actual digest against this signature, using the certificates + in the ".fs-verity" keyring. 3. A new sysctl "fs.verity.require_signatures" is made available. When set to 1, the kernel requires that all verity files have a - correctly signed file measurement as described in (2). + correctly signed digest as described in (2). -File measurements must be signed in the following format, which is -similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: +fs-verity file digests must be signed in the following format, which +is similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: - struct fsverity_signed_digest { + struct fsverity_formatted_digest { char magic[8]; /* must be "FSVerity" */ __le16 digest_algorithm; __le16 digest_size; @@ -421,8 +417,8 @@ can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared. ext4 also supports encryption, which can be used simultaneously with fs-verity. In this case, the plaintext data is verified rather than -the ciphertext. This is necessary in order to make the file -measurement meaningful, since every file is encrypted differently. +the ciphertext. This is necessary in order to make the fs-verity file +digest meaningful, since every file is encrypted differently. ext4 stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond @@ -592,8 +588,8 @@ weren't already directly answered in other parts of this document. :Q: Isn't fs-verity useless because the attacker can just modify the hashes in the Merkle tree, which is stored on-disk? :A: To verify the authenticity of an fs-verity file you must verify - the authenticity of the "file measurement", which is basically the - root hash of the Merkle tree. See `Use cases`_. + the authenticity of the "fs-verity file digest", which + incorporates the root hash of the Merkle tree. See `Use cases`_. :Q: Isn't fs-verity useless because the attacker can just replace a verity file with a non-verity one? diff --git a/Documentation/filesystems/journalling.rst b/Documentation/filesystems/journalling.rst index 5a5f70b4063e..e18f90ffc6fd 100644 --- a/Documentation/filesystems/journalling.rst +++ b/Documentation/filesystems/journalling.rst @@ -136,10 +136,8 @@ Fast commits ~~~~~~~~~~~~ JBD2 to also allows you to perform file-system specific delta commits known as -fast commits. In order to use fast commits, you first need to call -:c:func:`jbd2_fc_init` and tell how many blocks at the end of journal -area should be reserved for fast commits. Along with that, you will also need -to set following callbacks that perform correspodning work: +fast commits. In order to use fast commits, you will need to set following +callbacks that perform correspodning work: `journal->j_fc_cleanup_cb`: Cleanup function called after every full commit and fast commit. diff --git a/Documentation/firmware-guide/acpi/acpi-lid.rst b/Documentation/firmware-guide/acpi/acpi-lid.rst index 874ce0ed340d..71b9af13a048 100644 --- a/Documentation/firmware-guide/acpi/acpi-lid.rst +++ b/Documentation/firmware-guide/acpi/acpi-lid.rst @@ -19,9 +19,9 @@ report the "current" state of the lid as either "opened" or "closed". For most platforms, both the _LID method and the lid notifications are reliable. However, there are exceptions. In order to work with these -exceptional buggy platforms, special restrictions and expections should be +exceptional buggy platforms, special restrictions and exceptions should be taken into account. This document describes the restrictions and the -expections of the Linux ACPI lid device driver. +exceptions of the Linux ACPI lid device driver. Restrictions of the returning value of the _LID control method @@ -46,7 +46,7 @@ state is changed to "closed". The "closed" notification is normally used to trigger some system power saving operations on Windows. Since it is fully tested, it is reliable from all AML tables. -Expections for the userspace users of the ACPI lid device driver +Exceptions for the userspace users of the ACPI lid device driver ================================================================ The ACPI button driver exports the lid state to the userspace via the @@ -100,7 +100,7 @@ use the following kernel parameter: C. button.lid_init_state=ignore: When this option is specified, the ACPI button driver never reports the initial lid state and there is a compensation mechanism implemented to - ensure that the reliable "closed" notifications can always be delievered + ensure that the reliable "closed" notifications can always be delivered to the userspace by always pairing "closed" input events with complement "opened" input events. But there is still no guarantee that the "opened" notifications can be delivered to the userspace when the lid is actually diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index bb6d74f23ee0..59aad6138b6e 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -20,9 +20,9 @@ index, like the ASL example below shows:: Name (_CRS, ResourceTemplate () { - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, "\\_SB.GPO0", 0, ResourceConsumer) {15} - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} }) @@ -49,15 +49,41 @@ index pin Pin in the GpioIo()/GpioInt() resource. Typically this is zero. active_low - If 1 the GPIO is marked as active_low. + If 1, the GPIO is marked as active_low. Since ACPI GpioIo() resource does not have a field saying whether it is active low or high, the "active_low" argument can be used here. Setting it to 1 marks the GPIO as active low. +Note, active_low in _DSD does not make sense for GpioInt() resource and +must be 0. GpioInt() resource has its own means of defining it. + In our Bluetooth example the "reset-gpios" refers to the second GpioIo() resource, second pin in that resource with the GPIO number of 31. +The GpioIo() resource unfortunately doesn't explicitly provide an initial +state of the output pin which driver should use during its initialization. + +Linux tries to use common sense here and derives the state from the bias +and polarity settings. The table below shows the expectations: + +========= ============= ============== +Pull Bias Polarity Requested... +========= ============= ============== +Implicit x AS IS (assumed firmware configured for us) +Explicit x (no _DSD) as Pull Bias (Up == High, Down == Low), + assuming non-active (Polarity = !Pull Bias) +Down Low as low, assuming active +Down High as low, assuming non-active +Up Low as high, assuming non-active +Up High as high, assuming active +========= ============= ============== + +That said, for our above example the both GPIOs, since the bias setting +is explicit and _DSD is present, will be treated as active with a high +polarity and Linux will configure the pins in this state until a driver +reprograms them differently. + It is possible to leave holes in the array of GPIOs. This is useful in cases like with SPI host controllers where some chip selects may be implemented as GPIOs and some as native signals. For example a SPI host @@ -112,8 +138,8 @@ Example:: Package () { "gpio-line-names", Package () { - "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO", - "LVL_C_A1", "MUX0_IO", "SPI1_MISO" + "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", + "MUX7_IO", "LVL_C_A1", "MUX0_IO", "SPI1_MISO", } } @@ -137,7 +163,7 @@ to the GPIO lines it is going to use and provide the GPIO subsystem with a mapping between those names and the ACPI GPIO resources corresponding to them. To do that, the driver needs to define a mapping table as a NULL-terminated -array of struct acpi_gpio_mapping objects that each contain a name, a pointer +array of struct acpi_gpio_mapping objects that each contains a name, a pointer to an array of line data (struct acpi_gpio_params) objects and the size of that array. Each struct acpi_gpio_params object consists of three fields, crs_entry_index, line_index, active_low, representing the index of the target @@ -154,13 +180,14 @@ question would look like this:: static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { { "reset-gpios", &reset_gpio, 1 }, { "shutdown-gpios", &shutdown_gpio, 1 }, - { }, + { } }; Next, the mapping table needs to be passed as the second argument to -acpi_dev_add_driver_gpios() that will register it with the ACPI device object -pointed to by its first argument. That should be done in the driver's .probe() -routine. On removal, the driver should unregister its GPIO mapping table by +acpi_dev_add_driver_gpios() or its managed analogue that will +register it with the ACPI device object pointed to by its first +argument. That should be done in the driver's .probe() routine. +On removal, the driver should unregister its GPIO mapping table by calling acpi_dev_remove_driver_gpios() on the ACPI device object where that table was previously registered. @@ -191,12 +218,12 @@ The driver might expect to get the right GPIO when it does:: but since there is no way to know the mapping between "reset" and the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). -The driver author can solve this by passing the mapping explictly -(the recommended way and documented in the above chapter). +The driver author can solve this by passing the mapping explicitly +(this is the recommended way and it's documented in the above chapter). The ACPI GPIO mapping tables should not contaminate drivers that are not knowing about which exact device they are servicing on. It implies that -the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain +the ACPI GPIO mapping tables are hardly linked to an ACPI ID and certain objects, as listed in the above chapter, of the device in question. Getting GPIO descriptor @@ -229,5 +256,5 @@ Case 2 explicitly tells GPIO core to look for resources in _CRS. Be aware that gpiod_get_index() in cases 1 and 2, assuming that there are two versions of ACPI device description provided and no mapping is present in the driver, will return different resources. That's why a -certain driver has to handle them carefully as explained in previous +certain driver has to handle them carefully as explained in the previous chapter. diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst index 0aa7e2c5d32a..6ab6c0964042 100644 --- a/Documentation/firmware-guide/acpi/method-tracing.rst +++ b/Documentation/firmware-guide/acpi/method-tracing.rst @@ -98,7 +98,7 @@ subject to change:: [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution. Developers can utilize these special log entries to track the AML -interpretion, thus can aid issue debugging and performance tuning. Note +interpretation, thus can aid issue debugging and performance tuning. Note that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT() macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling "AML tracer" logs. diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index 1f9ea8221f80..2062a6023678 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -83,10 +83,6 @@ AMDGPU XGMI Support =================== .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c - :doc: AMDGPU XGMI Support - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c - :internal: AMDGPU RAS Support ================== @@ -124,9 +120,6 @@ RAS VRAM Bad Pages sysfs Interface .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :internal: - Sample Code ----------- Sample code for testing error injection can be found here: diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 9abee1589c1e..21be6deadc12 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -182,11 +182,11 @@ acquired and release by calling drm_gem_object_get() and drm_gem_object_put() respectively. When the last reference to a GEM object is released the GEM core calls -the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked +the :c:type:`struct drm_gem_object_funcs <gem_object_funcs>` free operation. That operation is mandatory for GEM-enabled drivers and must free the GEM object and all associated resources. -void (\*gem_free_object) (struct drm_gem_object \*obj); Drivers are +void (\*free) (struct drm_gem_object \*obj); Drivers are responsible for freeing all GEM object resources. This includes the resources created by the GEM core, which need to be released with drm_gem_object_release(). diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index cff1f154b473..20868f3d0123 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -118,6 +118,12 @@ Atomic Plane Helpers .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :internal: +Asynchronous Page Flip +---------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c + :doc: asynchronous flip implementation + Output Probing -------------- diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index b0ea17da8ff6..009d8e6c7e3c 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -105,6 +105,10 @@ converted over to the new infrastructure. One issue with the helpers is that they require that drivers handle completion events for atomic commits correctly. But fixing these bugs is good anyway. +Somewhat related is the legacy_cursor_update hack, which should be replaced with +the new atomic_async_check/commit functionality in the helpers in drivers that +still look at that flag. + Contact: Daniel Vetter, respective driver maintainers Level: Advanced @@ -149,7 +153,7 @@ have to keep track of that lock and either call ``unreference`` or ``unreference_locked`` depending upon context. Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8, -and there's a ``gem_free_object_unlocked`` callback for any drivers which are +and there's a GEM object ``free`` callback for any drivers which are entirely ``struct_mutex`` free. For drivers that need ``struct_mutex`` it should be replaced with a driver- @@ -197,13 +201,28 @@ Convert drivers to use drm_fbdev_generic_setup() ------------------------------------------------ Most drivers can use drm_fbdev_generic_setup(). Driver have to implement -atomic modesetting and GEM vmap support. Current generic fbdev emulation -expects the framebuffer in system memory (or system-like memory). +atomic modesetting and GEM vmap support. Historically, generic fbdev emulation +expected the framebuffer in system memory or system-like memory. By employing +struct dma_buf_map, drivers with frambuffers in I/O memory can be supported +as well. Contact: Maintainer of the driver you plan to convert Level: Intermediate +Reimplement functions in drm_fbdev_fb_ops without fbdev +------------------------------------------------------- + +A number of callback functions in drm_fbdev_fb_ops could benefit from +being rewritten without dependencies on the fbdev module. Some of the +helpers could further benefit from using struct dma_buf_map instead of +raw pointers. + +Contact: Thomas Zimmermann <tzimmermann@suse.de>, Daniel Vetter + +Level: Advanced + + drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup ----------------------------------------------------------------- @@ -273,6 +292,27 @@ Contact: Daniel Vetter, Noralf Tronnes Level: Advanced +Garbage collect fbdev scrolling acceleration +-------------------------------------------- + +Scroll acceleration is disabled in fbcon by hard-wiring p->scrollmode = +SCROLL_REDRAW. There's a ton of code this will allow us to remove: + +- lots of code in fbcon.c + +- a bunch of the hooks in fbcon_ops, maybe the remaining hooks could be called + directly instead of the function table (with a switch on p->rotate) + +- fb_copyarea is unused after this, and can be deleted from all drivers + +Note that not all acceleration code can be deleted, since clearing and cursor +support is still accelerated, which might be good candidates for further +deletion projects. + +Contact: Daniel Vetter + +Level: Intermediate + idr_init_base() --------------- @@ -289,11 +329,8 @@ struct drm_gem_object_funcs --------------------------- GEM objects can now have a function table instead of having the callbacks on the -DRM driver struct. This is now the preferred way and drivers can be moved over. - -We also need a 2nd version of the CMA define that doesn't require the -vmapping to be present (different hook for prime importing). Plus this needs to -be rolled out to all drivers using their own implementations, too. +DRM driver struct. This is now the preferred way. Callbacks in drivers have been +converted, except for struct drm_driver.gem_prime_mmap. Level: Intermediate @@ -449,6 +486,24 @@ Contact: Ville Syrjälä, Daniel Vetter Level: Intermediate +Use struct dma_buf_map throughout codebase +------------------------------------------ + +Pointers to shared device memory are stored in struct dma_buf_map. Each +instance knows whether it refers to system or I/O memory. Most of the DRM-wide +interface have been converted to use struct dma_buf_map, but implementations +often still use raw pointers. + +The task is to use struct dma_buf_map where it makes sense. + +* Memory managers should use struct dma_buf_map for dma-buf-imported buffers. +* TTM might benefit from using struct dma_buf_map internally. +* Framebuffer copying and blitting helpers should operate on struct dma_buf_map. + +Contact: Thomas Zimmermann <tzimmermann@suse.de>, Christian König, Daniel Vetter + +Level: Intermediate + Core refactorings ================= @@ -518,9 +573,6 @@ There's a bunch of issues with it: this (together with the drm_minor->drm_device move) would allow us to remove debugfs_init. -- Drop the return code and error checking from all debugfs functions. Greg KH is - working on this already. - Contact: Daniel Vetter Level: Intermediate diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 61586fc861bb..13bab1d93bb3 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -10,36 +10,24 @@ TODO ==== -CRC API Improvements --------------------- - -- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` - -- Use the alpha value to blend vaddr_src with vaddr_dst instead of - overwriting it in ``blend()``. - -- Add igt test to check cleared alpha value for XRGB plane format. - -- Add igt test to check extreme alpha values i.e. fully opaque and fully - transparent (intermediate values are affected by hw-specific rounding modes). - -Runtime Configuration ---------------------- - -We want to be able to reconfigure vkms instance without having to reload the -module. Use/Test-cases: - -- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling of - compositors). +If you want to do any of the items listed below, please share your interest +with VKMS maintainers. -- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of - them first). +IGT better support +------------------ -- Change output configuration: Plug/unplug screens, change EDID, allow changing - the refresh rate. +- Investigate: (1) test cases on kms_plane that are failing due to timeout on + capturing CRC; (2) when running kms_flip test cases in sequence, some + successful individual test cases are failing randomly. -The currently proposed solution is to expose vkms configuration through -configfs. All existing module options should be supported through configfs too. +- VKMS already has support for vblanks simulated via hrtimers, which can be + tested with kms_flip test; in some way, we can say that VKMS already mimics + the real hardware vblank. However, we also have virtual hardware that does + not support vblank interrupt and completes page_flip events right away; in + this case, compositor developers may end up creating a busy loop on virtual + hardware. It would be useful to support Virtual Hardware behavior in VKMS + because this can help compositor developers to test their features in + multiple scenarios. Add Plane Features ------------------ @@ -55,34 +43,50 @@ There's lots of plane features we could add support for: - Additional buffer formats, especially YUV formats for video like NV12. Low/high bpp RGB formats would also be interesting. -- Async updates (currently only possible on cursor plane using the legacy cursor - api). +- Async updates (currently only possible on cursor plane using the legacy + cursor api). + +For all of these, we also want to review the igt test coverage and make sure +all relevant igt testcases work on vkms. + +Prime Buffer Sharing +-------------------- -For all of these, we also want to review the igt test coverage and make sure all -relevant igt testcases work on vkms. +- Syzbot report - WARNING in vkms_gem_free_object: + https://syzkaller.appspot.com/bug?extid=e7ad70d406e74d8fc9d0 + +Runtime Configuration +--------------------- + +We want to be able to reconfigure vkms instance without having to reload the +module. Use/Test-cases: + +- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling + of compositors). + +- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of + them first). + +- Change output configuration: Plug/unplug screens, change EDID, allow changing + the refresh rate. + +The currently proposed solution is to expose vkms configuration through +configfs. All existing module options should be supported through configfs +too. Writeback support ----------------- -Currently vkms only computes a CRC for each frame. Once we have additional plane -features, we could write back the entire composited frame, and expose it as: +- The writeback and CRC capture operations share the use of composer_enabled + boolean to ensure vblanks. Probably, when these operations work together, + composer_enabled needs to refcounting the composer state to proper work. -- Writeback connector. This is useful for testing compositors if you don't have - hardware with writeback support. +- Add support for cloned writeback outputs and related test cases using a + cloned output in the IGT kms_writeback. - As a v4l device. This is useful for debugging compositors on special vkms configurations, so that developers see what's really going on. -Prime Buffer Sharing --------------------- - -We already have vgem, which is a gem driver for testing rendering, similar to -how vkms is for testing the modeset side. Adding buffer sharing support to vkms -allows us to test them together, to test synchronization and lots of other -features. Also, this allows compositors to test whether they work correctly on -SoC chips, where the display and rendering is very often split between 2 -drivers. - Output Features --------------- @@ -93,7 +97,10 @@ Output Features - Add support for link status, so that compositors can validate their runtime fallbacks when e.g. a Display Port link goes bad. -- All the hotplug handling describe under "Runtime Configuration". +CRC API Improvements +-------------------- + +- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` Atomic Check using eBPF ----------------------- diff --git a/Documentation/hwmon/adm1266.rst b/Documentation/hwmon/adm1266.rst index 9257f8a48650..2b877011cfdf 100644 --- a/Documentation/hwmon/adm1266.rst +++ b/Documentation/hwmon/adm1266.rst @@ -20,7 +20,7 @@ ADM1266 is a sequencer that features voltage readback from 17 channels via an integrated 12 bit SAR ADC, accessed using a PMBus interface. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Sysfs entries diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index e6b91ab12978..b797db738225 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -132,6 +132,7 @@ Hardware Monitoring Kernel Drivers mcp3021 menf21bmc mlxreg-fan + mp2975 nct6683 nct6775 nct7802 diff --git a/Documentation/hwmon/mp2975.rst b/Documentation/hwmon/mp2975.rst index 5b0609c62f48..81d816b71490 100644 --- a/Documentation/hwmon/mp2975.rst +++ b/Documentation/hwmon/mp2975.rst @@ -20,6 +20,7 @@ This driver implements support for Monolithic Power Systems, Inc. (MPS) vendor dual-loop, digital, multi-phase controller MP2975. This device: + - Supports up to two power rail. - Provides 8 pulse-width modulations (PWMs), and can be configured up to 8-phase operation for rail 1 and up to 4-phase operation for rail @@ -32,10 +33,12 @@ This device: 10-mV DAC, IMVP9 mode with 5-mV DAC. Device supports: + - SVID interface. - AVSBus interface. Device complaint with: + - PMBus rev 1.3 interface. Device supports direct format for reading output current, output voltage, @@ -45,11 +48,14 @@ Device supports VID and direct formats for reading output voltage. The below VID modes are supported: VR12, VR13, IMVP9. The driver provides the next attributes for the current: + - for current in: input, maximum alarm; - for current out input, maximum alarm and highest values; - for phase current: input and label. -attributes. + attributes. + The driver exports the following attributes via the 'sysfs' files, where + - 'n' is number of telemetry pages (from 1 to 2); - 'k' is number of configured phases (from 1 to 8); - indexes 1, 1*n for "iin"; @@ -65,11 +71,14 @@ The driver exports the following attributes via the 'sysfs' files, where **curr[1-{2n+k}]_label** The driver provides the next attributes for the voltage: + - for voltage in: input, high critical threshold, high critical alarm, all only from page 0; - for voltage out: input, low and high critical thresholds, low and high critical alarms, from pages 0 and 1; + The driver exports the following attributes via the 'sysfs' files, where + - 'n' is number of telemetry pages (from 1 to 2); - indexes 1 for "iin"; - indexes n+1, n+2 for "vout"; @@ -87,9 +96,12 @@ The driver exports the following attributes via the 'sysfs' files, where **in[2-{n+1}1_lcrit_alarm** The driver provides the next attributes for the power: + - for power in alarm and input. - for power out: highest and input. + The driver exports the following attributes via the 'sysfs' files, where + - 'n' is number of telemetry pages (from 1 to 2); - indexes 1 for "pin"; - indexes n+1, n+2 for "pout"; diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index cf3ca236d2cc..21c847890d03 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -57,9 +57,8 @@ to enable them. :: They can be enabled individually. The full list of the parameters: :: make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ - OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-size \ - READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \ - HOSTLD=ld.lld + OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ + HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld Currently, the integrated assembler is disabled by default. You can pass ``LLVM_IAS=1`` to enable it. diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index bc70c6aa7138..e5d63b940045 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -17,6 +17,7 @@ LEDs uleds leds-blinkm + leds-el15203000 leds-lm3556 leds-lp3944 leds-lp5521 @@ -24,3 +25,4 @@ LEDs leds-lp5562 leds-lp55xx leds-mlxcpld + leds-sc27xx diff --git a/Documentation/leds/leds-el15203000.rst b/Documentation/leds/leds-el15203000.rst new file mode 100644 index 000000000000..12c23d79724d --- /dev/null +++ b/Documentation/leds/leds-el15203000.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +Kernel driver for Crane EL15203000 +================================== + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the EL15203000 LED. + +The LEDs board supports only predefined patterns by firmware +for specific LEDs. + +Breathing mode for Screen frame light tube:: + + "0 4000 1 4000" + + ^ + | + Max-| --- + | / \ + | / \ + | / \ / + | / \ / + Min-|- --- + | + 0------4------8--> time (sec) + +Cascade mode for Pipe LED:: + + "1 800 2 800 4 800 8 800 16 800" + + ^ + | + 0 On -|----+ +----+ +--- + | | | | | + Off-| +-------------------+ +-------------------+ + | + 1 On -| +----+ +----+ + | | | | | + Off |----+ +-------------------+ +------------------ + | + 2 On -| +----+ +----+ + | | | | | + Off-|---------+ +-------------------+ +------------- + | + 3 On -| +----+ +----+ + | | | | | + Off-|--------------+ +-------------------+ +-------- + | + 4 On -| +----+ +----+ + | | | | | + Off-|-------------------+ +-------------------+ +--- + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Inverted cascade mode for Pipe LED:: + + "30 800 29 800 27 800 23 800 15 800" + + ^ + | + 0 On -| +-------------------+ +-------------------+ + | | | | | + Off-|----+ +----+ +--- + | + 1 On -|----+ +-------------------+ +------------------ + | | | | | + Off | +----+ +----+ + | + 2 On -|---------+ +-------------------+ +------------- + | | | | | + Off-| +----+ +----+ + | + 3 On -|--------------+ +-------------------+ +-------- + | | | | | + Off-| +----+ +----+ + | + 4 On -|-------------------+ +-------------------+ +--- + | | | | | + Off-| +----+ +----+ + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Bounce mode for Pipe LED:: + + "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800" + + ^ + | + 0 On -|----+ +-------- + | | | + Off-| +---------------------------------------+ + | + 1 On -| +----+ +----+ + | | | | | + Off |----+ +-----------------------------+ +-------- + | + 2 On -| +----+ +----+ + | | | | | + Off-|---------+ +-------------------+ +------------- + | + 3 On -| +----+ +----+ + | | | | | + Off-|--------------+ +---------+ +------------------ + | + 4 On -| +---------+ + | | | + Off-|-------------------+ +----------------------- + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Inverted bounce mode for Pipe LED:: + + "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800" + + ^ + | + 0 On -| +---------------------------------------+ + | | | + Off-|----+ +-------- + | + 1 On -|----+ +-----------------------------+ +-------- + | | | | | + Off | +----+ +----+ + | + 2 On -|---------+ +-------------------+ +------------- + | | | | | + Off-| +----+ +----+ + | + 3 On -|--------------+ +---------+ +------------------ + | | | | | + Off-| +----+ +----+ + | + 4 On -|-------------------+ +----------------------- + | | | + Off-| +---------+ + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) diff --git a/Documentation/leds/leds-sc27xx.rst b/Documentation/leds/leds-sc27xx.rst new file mode 100644 index 000000000000..6bdf6ba3c9fd --- /dev/null +++ b/Documentation/leds/leds-sc27xx.rst @@ -0,0 +1,27 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Kernel driver for Spreadtrum SC27XX +=================================== + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the SC27XX LED. For the SC27XX +LED controller, it only supports 4 stages to make a single +hardware pattern, which is used to configure the rise time, +high time, fall time and low time for the breathing mode. + +For the breathing mode, the SC27XX LED only expects one brightness +for the high stage. To be compatible with the hardware pattern +format, we should set brightness as 0 for rise stage, fall +stage and low stage. + +- Min stage duration: 125 ms +- Max stage duration: 31875 ms + +Since the stage duration step is 125 ms, the duration should be +a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms. + +Thus the format of the hardware pattern values should be: +"0 rise_duration brightness high_duration 0 fall_duration 0 low_duration". diff --git a/Documentation/locking/lockdep-design.rst b/Documentation/locking/lockdep-design.rst index cec03bd1294a..9f3cfca9f8a4 100644 --- a/Documentation/locking/lockdep-design.rst +++ b/Documentation/locking/lockdep-design.rst @@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides the usage into (4 usages * n STATEs + 1) categories: where the 4 usages can be: + - 'ever held in STATE context' - 'ever held as readlock in STATE context' - 'ever held with STATE enabled' @@ -49,10 +50,12 @@ where the 4 usages can be: where the n STATEs are coded in kernel/locking/lockdep_states.h and as of now they include: + - hardirq - softirq where the last 1 category is: + - 'ever used' [ == !unused ] When locking rules are violated, these usage bits are presented in the @@ -96,9 +99,9 @@ exact case is for the lock as of the reporting time. +--------------+-------------+--------------+ | | irq enabled | irq disabled | +--------------+-------------+--------------+ - | ever in irq | ? | - | + | ever in irq | '?' | '-' | +--------------+-------------+--------------+ - | never in irq | + | . | + | never in irq | '+' | '.' | +--------------+-------------+--------------+ The character '-' suggests irq is disabled because if otherwise the @@ -216,7 +219,7 @@ looks like this:: BD_MUTEX_PARTITION }; -mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); + mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); In this case the locking is done on a bdev object that is known to be a partition. @@ -334,7 +337,7 @@ Troubleshooting: ---------------- The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes. -Exceeding this number will trigger the following lockdep warning: +Exceeding this number will trigger the following lockdep warning:: (DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS)) @@ -420,7 +423,8 @@ the critical section of another reader of the same lock instance. The difference between recursive readers and non-recursive readers is because: recursive readers get blocked only by a write lock *holder*, while non-recursive -readers could get blocked by a write lock *waiter*. Considering the follow example: +readers could get blocked by a write lock *waiter*. Considering the follow +example:: TASK A: TASK B: @@ -448,20 +452,22 @@ There are simply four block conditions: Block condition matrix, Y means the row blocks the column, and N means otherwise. - | E | r | R | +---+---+---+---+ - E | Y | Y | Y | + | | E | r | R | + +---+---+---+---+ + | E | Y | Y | Y | + +---+---+---+---+ + | r | Y | Y | N | +---+---+---+---+ - r | Y | Y | N | + | R | Y | Y | N | +---+---+---+---+ - R | Y | Y | N | (W: writers, r: non-recursive readers, R: recursive readers) acquired recursively. Unlike non-recursive read locks, recursive read locks only get blocked by current write lock *holders* other than write lock -*waiters*, for example: +*waiters*, for example:: TASK A: TASK B: @@ -491,7 +497,7 @@ Recursive locks don't block each other, while non-recursive locks do (this is even true for two non-recursive read locks). A non-recursive lock can block the corresponding recursive lock, and vice versa. -A deadlock case with recursive locks involved is as follow: +A deadlock case with recursive locks involved is as follow:: TASK A: TASK B: @@ -510,7 +516,7 @@ because there are 3 types for lockers, there are, in theory, 9 types of lock dependencies, but we can show that 4 types of lock dependencies are enough for deadlock detection. -For each lock dependency: +For each lock dependency:: L1 -> L2 @@ -525,20 +531,25 @@ same types). With the above combination for simplification, there are 4 types of dependency edges in the lockdep graph: -1) -(ER)->: exclusive writer to recursive reader dependency, "X -(ER)-> Y" means +1) -(ER)->: + exclusive writer to recursive reader dependency, "X -(ER)-> Y" means X -> Y and X is a writer and Y is a recursive reader. -2) -(EN)->: exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means +2) -(EN)->: + exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means X -> Y and X is a writer and Y is either a writer or non-recursive reader. -3) -(SR)->: shared reader to recursive reader dependency, "X -(SR)-> Y" means +3) -(SR)->: + shared reader to recursive reader dependency, "X -(SR)-> Y" means X -> Y and X is a reader (recursive or not) and Y is a recursive reader. -4) -(SN)->: shared reader to non-recursive locker dependency, "X -(SN)-> Y" means +4) -(SN)->: + shared reader to non-recursive locker dependency, "X -(SN)-> Y" means X -> Y and X is a reader (recursive or not) and Y is either a writer or non-recursive reader. -Note that given two locks, they may have multiple dependencies between them, for example: +Note that given two locks, they may have multiple dependencies between them, +for example:: TASK A: @@ -592,11 +603,11 @@ circles that won't cause deadlocks. Proof for sufficiency (Lemma 1): -Let's say we have a strong circle: +Let's say we have a strong circle:: L1 -> L2 ... -> Ln -> L1 -, which means we have dependencies: +, which means we have dependencies:: L1 -> L2 L2 -> L3 @@ -633,7 +644,7 @@ a lock held by P2, and P2 is waiting for a lock held by P3, ... and Pn is waitin for a lock held by P1. Let's name the lock Px is waiting as Lx, so since P1 is waiting for L1 and holding Ln, so we will have Ln -> L1 in the dependency graph. Similarly, we have L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln in the dependency graph, which means we -have a circle: +have a circle:: Ln -> L1 -> L2 -> ... -> Ln diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 46072ce3d7ef..64420b3314fe 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -24,7 +24,6 @@ fit into other categories. isl29003 lis3lv02d max6875 - mic/index pci-endpoint-test spear-pcie-gadget uacce diff --git a/Documentation/misc-devices/mic/index.rst b/Documentation/misc-devices/mic/index.rst deleted file mode 100644 index 3a8d06367ef1..000000000000 --- a/Documentation/misc-devices/mic/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -============================================= -Intel Many Integrated Core (MIC) architecture -============================================= - -.. toctree:: - :maxdepth: 1 - - mic_overview - scif_overview - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/misc-devices/mic/mic_overview.rst b/Documentation/misc-devices/mic/mic_overview.rst deleted file mode 100644 index 17d956bdaf7c..000000000000 --- a/Documentation/misc-devices/mic/mic_overview.rst +++ /dev/null @@ -1,85 +0,0 @@ -====================================================== -Intel Many Integrated Core (MIC) architecture overview -====================================================== - -An Intel MIC X100 device is a PCIe form factor add-in coprocessor -card based on the Intel Many Integrated Core (MIC) architecture -that runs a Linux OS. It is a PCIe endpoint in a platform and therefore -implements the three required standard address spaces i.e. configuration, -memory and I/O. The host OS loads a device driver as is typical for -PCIe devices. The card itself runs a bootstrap after reset that -transfers control to the card OS downloaded from the host driver. The -host driver supports OSPM suspend and resume operations. It shuts down -the card during suspend and reboots the card OS during resume. -The card OS as shipped by Intel is a Linux kernel with modifications -for the X100 devices. - -Since it is a PCIe card, it does not have the ability to host hardware -devices for networking, storage and console. We provide these devices -on X100 coprocessors thus enabling a self-bootable equivalent -environment for applications. A key benefit of our solution is that it -leverages the standard virtio framework for network, disk and console -devices, though in our case the virtio framework is used across a PCIe -bus. A Virtio Over PCIe (VOP) driver allows creating user space -backends or devices on the host which are used to probe virtio drivers -for these devices on the MIC card. The existing VRINGH infrastructure -in the kernel is used to access virtio rings from the host. The card -VOP driver allows card virtio drivers to communicate with their user -space backends on the host via a device page. Ring 3 apps on the host -can add, remove and configure virtio devices. A thin MIC specific -virtio_config_ops is implemented which is borrowed heavily from -previous similar implementations in lguest and s390. - -MIC PCIe card has a dma controller with 8 channels. These channels are -shared between the host s/w and the card s/w. 0 to 3 are used by host -and 4 to 7 by card. As the dma device doesn't show up as PCIe device, -a virtual bus called mic bus is created and virtual dma devices are -created on it by the host/card drivers. On host the channels are private -and used only by the host driver to transfer data for the virtio devices. - -The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a -low level communications API across PCIe currently implemented for MIC. -More details are available at scif_overview.txt. - -The Coprocessor State Management (COSM) driver on the host allows for -boot, shutdown and reset of Intel MIC devices. It communicates with a COSM -"client" driver on the MIC cards over SCIF to perform these functions. - -Here is a block diagram of the various components described above. The -virtio backends are situated on the host rather than the card given better -single threaded performance for the host compared to MIC, the ability of -the host to initiate DMA's to/from the card using the MIC DMA engine and -the fact that the virtio block storage backend can only be on the host:: - - +----------+ | +----------+ - | Card OS | | | Host OS | - +----------+ | +----------+ - | - +-------+ +--------+ +------+ | +---------+ +--------+ +--------+ - | Virtio| |Virtio | |Virtio| | |Virtio | |Virtio | |Virtio | - | Net | |Console | |Block | | |Net | |Console | |Block | - | Driver| |Driver | |Driver| | |backend | |backend | |backend | - +---+---+ +---+----+ +--+---+ | +---------+ +----+---+ +--------+ - | | | | | | | - | | | |User | | | - | | | |------|------------|--+------|------- - +---------+---------+ |Kernel | - | | | - +---------+ +---+----+ +------+ | +------+ +------+ +--+---+ +-------+ - |MIC DMA | | VOP | | SCIF | | | SCIF | | COSM | | VOP | |MIC DMA| - +---+-----+ +---+----+ +--+---+ | +--+---+ +--+---+ +------+ +----+--+ - | | | | | | | - +---+-----+ +---+----+ +--+---+ | +--+---+ +--+---+ +------+ +----+--+ - |MIC | | VOP | |SCIF | | |SCIF | | COSM | | VOP | | MIC | - |HW Bus | | HW Bus| |HW Bus| | |HW Bus| | Bus | |HW Bus| |HW Bus | - +---------+ +--------+ +--+---+ | +--+---+ +------+ +------+ +-------+ - | | | | | | | - | +-----------+--+ | | | +---------------+ | - | |Intel MIC | | | | |Intel MIC | | - | |Card Driver | | | | |Host Driver | | - +---+--------------+------+ | +----+---------------+-----+ - | | | - +-------------------------------------------------------------+ - | | - | PCIe Bus | - +-------------------------------------------------------------+ diff --git a/Documentation/misc-devices/mic/scif_overview.rst b/Documentation/misc-devices/mic/scif_overview.rst deleted file mode 100644 index 4c8ad9e43706..000000000000 --- a/Documentation/misc-devices/mic/scif_overview.rst +++ /dev/null @@ -1,108 +0,0 @@ -======================================== -Symmetric Communication Interface (SCIF) -======================================== - -The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low -level communications API across PCIe currently implemented for MIC. Currently -SCIF provides inter-node communication within a single host platform, where a -node is a MIC Coprocessor or Xeon based host. SCIF abstracts the details of -communicating over the PCIe bus while providing an API that is symmetric -across all the nodes in the PCIe network. An important design objective for SCIF -is to deliver the maximum possible performance given the communication -abilities of the hardware. SCIF has been used to implement an offload compiler -runtime and OFED support for MPI implementations for MIC coprocessors. - -SCIF API Components -=================== - -The SCIF API has the following parts: - -1. Connection establishment using a client server model -2. Byte stream messaging intended for short messages -3. Node enumeration to determine online nodes -4. Poll semantics for detection of incoming connections and messages -5. Memory registration to pin down pages -6. Remote memory mapping for low latency CPU accesses via mmap -7. Remote DMA (RDMA) for high bandwidth DMA transfers -8. Fence APIs for RDMA synchronization - -SCIF exposes the notion of a connection which can be used by peer processes on -nodes in a SCIF PCIe "network" to share memory "windows" and to communicate. A -process in a SCIF node initiates a SCIF connection to a peer process on a -different node via a SCIF "endpoint". SCIF endpoints support messaging APIs -which are similar to connection oriented socket APIs. Connected SCIF endpoints -can also register local memory which is followed by data transfer using either -DMA, CPU copies or remote memory mapping via mmap. SCIF supports both user and -kernel mode clients which are functionally equivalent. - -SCIF Performance for MIC -======================== - -DMA bandwidth comparison between the TCP (over ethernet over PCIe) stack versus -SCIF shows the performance advantages of SCIF for HPC applications and -runtimes:: - - Comparison of TCP and SCIF based BW - - Throughput (GB/sec) - 8 + PCIe Bandwidth ****** - + TCP ###### - 7 + ************************************** SCIF %%%%%% - | %%%%%%%%%%%%%%%%%%% - 6 + %%%% - | %% - | %%% - 5 + %% - | %% - 4 + %% - | %% - 3 + %% - | % - 2 + %% - | %% - | % - 1 + - + ###################################### - 0 +++---+++--+--+-+--+--+-++-+--+-++-+--+-++-+- - 1 10 100 1000 10000 100000 - Transfer Size (KBytes) - -SCIF allows memory sharing via mmap(..) between processes on different PCIe -nodes and thus provides bare-metal PCIe latency. The round trip SCIF mmap -latency from the host to an x100 MIC for an 8 byte message is 0.44 usecs. - -SCIF has a user space library which is a thin IOCTL wrapper providing a user -space API similar to the kernel API in scif.h. The SCIF user space library -is distributed @ https://software.intel.com/en-us/mic-developer - -Here is some pseudo code for an example of how two applications on two PCIe -nodes would typically use the SCIF API:: - - Process A (on node A) Process B (on node B) - - /* get online node information */ - scif_get_node_ids(..) scif_get_node_ids(..) - scif_open(..) scif_open(..) - scif_bind(..) scif_bind(..) - scif_listen(..) - scif_accept(..) scif_connect(..) - /* SCIF connection established */ - - /* Send and receive short messages */ - scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..) - - /* Register memory */ - scif_register(..) scif_register(..) - - /* RDMA */ - scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..) - - /* Fence DMAs */ - scif_fence_signal(..) scif_fence_signal(..) - - mmap(..) mmap(..) - - /* Access remote registered memory */ - - /* Close the endpoints */ - scif_close(..) scif_close(..) diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index b165181d5d4d..a432dc419fa4 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -70,6 +70,7 @@ The ``ice`` driver reports the following versions that both the name (as reported by ``fw.app.name``) and version are required to uniquely identify the package. * - ``fw.app.bundle_id`` + - running - 0xc0000001 - Unique identifier for the DDP package loaded in the device. Also referred to as the DDP Track ID. Can be used to uniquely identify diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst index f5be243d250a..0a4b73b03b99 100644 --- a/Documentation/networking/j1939.rst +++ b/Documentation/networking/j1939.rst @@ -10,9 +10,9 @@ 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 +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 +Transport Protocol), which has been included in this implementation. This results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB. Specifications used @@ -32,15 +32,15 @@ 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 + 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 + 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 + 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. @@ -58,7 +58,7 @@ 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 +Since such a 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. @@ -77,13 +77,13 @@ is composed as follows: 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 +format (where PF >= 240). Furthermore, when using the 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 +from user space to kernel (or vice versa) and PDU2 format is used, the PS-field of the PGN shall be set to zero. The Destination Address shall be set elsewhere. @@ -96,15 +96,15 @@ Addressing Both static and dynamic addressing methods can be used. -For static addresses, no extra checks are made by the kernel, and provided +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 +in the kernel. In J1939 any ECU is known by its 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. +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 @@ -131,31 +131,31 @@ 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 +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 +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 +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 +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 +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 +Different from CAN is that the payload data is just the data that get sends, +without its 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: @@ -180,47 +180,47 @@ The sockaddr structure has extensions for use with J1939 as specified below: } can_addr; } -can_family & can_ifindex serve the same purpose as for other SocketCAN sockets. +``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 +``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.name`` contains the 64-bit J1939 NAME. -can_addr.j1939.addr contains the address. +``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 +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 +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 +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 +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. +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). +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) +- ``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: +receiving broadcast packets use the socket option ``SO_BROADCAST``: .. code-block:: C @@ -261,26 +261,26 @@ The following diagram illustrates the RX path: +---------------------------+ TX path related options: -SO_J1939_SEND_PRIO - change default send priority for the socket +``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 +``send(2)``, ``sendto(2)`` and ``sendmsg(2)`` take a 'flags' argument. Currently supported flags are: -* MSG_DONTWAIT, i.e. non-blocking operation. +* ``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 +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. +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 @@ -305,12 +305,12 @@ 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 +``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. +``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 +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: @@ -371,12 +371,12 @@ 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 +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 +``can-utils`` also include the ``j1939acd`` tool, so it can be used as code example or as default Address Claiming daemon. Send Examples @@ -403,8 +403,8 @@ Bind: 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). +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: @@ -414,8 +414,8 @@ Send: .can_family = AF_CAN, .can_addr.j1939 = { .name = J1939_NO_NAME; - .pgn = 0x30, - .addr = 0x12300, + .addr = 0x30, + .pgn = 0x12300, }, }; diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index d5c9320901c3..4b9ed5874d5a 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/networking/netdev-FAQ.rst @@ -110,7 +110,7 @@ Q: I sent a patch and I'm wondering what happened to it? Q: How can I tell whether it got merged? A: Start by looking at the main patchworks queue for netdev: - http://patchwork.ozlabs.org/project/netdev/list/ + https://patchwork.kernel.org/project/netdevbpf/list/ The "State" field will tell you exactly where things are at with your patch. @@ -152,7 +152,7 @@ networking subsystem, and then hands them off to Greg. There is a patchworks queue that you can see here: - http://patchwork.ozlabs.org/bundle/davem/stable/?state=* + https://patchwork.kernel.org/bundle/netdev/stable/?state=* It contains the patches which Dave has selected, but not yet handed off to Greg. If Greg already has the patch, then it will be here: @@ -254,6 +254,32 @@ you will have done run-time testing specific to your change, but at a minimum, your changes should survive an ``allyesconfig`` and an ``allmodconfig`` build without new warnings or failures. +Q: How do I post corresponding changes to user space components? +---------------------------------------------------------------- +A: User space code exercising kernel features should be posted +alongside kernel patches. This gives reviewers a chance to see +how any new interface is used and how well it works. + +When user space tools reside in the kernel repo itself all changes +should generally come as one series. If series becomes too large +or the user space project is not reviewed on netdev include a link +to a public repo where user space patches can be seen. + +In case user space tooling lives in a separate repository but is +reviewed on netdev (e.g. patches to `iproute2` tools) kernel and +user space patches should form separate series (threads) when posted +to the mailing list, e.g.:: + + [PATCH net-next 0/3] net: some feature cover letter + └─ [PATCH net-next 1/3] net: some feature prep + └─ [PATCH net-next 2/3] net: some feature do it + └─ [PATCH net-next 3/3] selftest: net: some feature + + [PATCH iproute2-next] ip: add support for some feature + +Posting as one thread is discouraged because it confuses patchwork +(as of patchwork 2.2.2). + Q: Any other tips to help ensure my net/net-next patch gets OK'd? ----------------------------------------------------------------- A: Attention to detail. Re-read your own work as if you were the diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index 256106054c8c..b2f7ec794bc8 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -247,8 +247,8 @@ Some of the interface modes are described below: speeds (see below.) ``PHY_INTERFACE_MODE_2500BASEX`` - This defines a variant of 1000BASE-X which is clocked 2.5 times faster, - than the 802.3 standard giving a fixed bit rate of 3.125Gbaud. + This defines a variant of 1000BASE-X which is clocked 2.5 times as fast + as the 802.3 standard, giving a fixed bit rate of 3.125Gbaud. ``PHY_INTERFACE_MODE_SGMII`` This is used for Cisco SGMII, which is a modification of 1000BASE-X diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst index 8e15bc98830b..234abedc29b2 100644 --- a/Documentation/networking/statistics.rst +++ b/Documentation/networking/statistics.rst @@ -175,5 +175,4 @@ The following structures are internal to the kernel, their members are translated to netlink attributes when dumped. Drivers must not overwrite the statistics they don't report with 0. -.. kernel-doc:: include/linux/ethtool.h - :identifiers: ethtool_pause_stats +- ethtool_pause_stats() diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 06f743b612c4..3973556250e1 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -39,7 +39,7 @@ Procedure for submitting patches to the -stable tree submission guidelines as described in :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>` after first checking the stable networking queue at - https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive= + https://patchwork.kernel.org/bundle/netdev/stable/?state=* to ensure the requested patch is not already queued up. - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 409dbc4100de..3e81ebab26ed 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -16,28 +16,36 @@ import re from itertools import chain # +# Python 2 lacks re.ASCII... +# +try: + ascii_p3 = re.ASCII +except AttributeError: + ascii_p3 = 0 + +# # Regex nastiness. Of course. # Try to identify "function()" that's not already marked up some # other way. Sphinx doesn't like a lot of stuff right after a # :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last # bit tries to restrict matches to things that won't create trouble. # -RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII) +RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=ascii_p3) # # Sphinx 2 uses the same :c:type role for struct, union, enum and typedef # RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)', - flags=re.ASCII) + flags=ascii_p3) # # Sphinx 3 uses a different C role for each one of struct, union, enum and # typedef # -RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII) -RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII) -RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII) -RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII) +RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3) # # Detects a reference to a documentation page of the form Documentation/... with diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py new file mode 100644 index 000000000000..f3da859c9878 --- /dev/null +++ b/Documentation/sphinx/kernel_abi.py @@ -0,0 +1,194 @@ +# -*- coding: utf-8; mode: python -*- +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-abi + ~~~~~~~~~~ + + Implementation of the ``kernel-abi`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2020 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the + scripts/get_abi.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-abi:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys +import re +import kernellog + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-abi", KernelCmd) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelCmd(Directive): + + u"""KernelABI (``kernel-abi``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag, + "rst" : directives.unchanged + } + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_abi.pl rest --enable-lineno --dir " + cmd += self.arguments[0] + + if 'rst' in self.options: + cmd += " --rst-source" + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, self.arguments[0]) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + ln = 0 + n = 0 + f = fname + + for line in lines.split("\n"): + n = n + 1 + match = line_regex.search(line) + if match: + new_f = match.group(1) + + # Sphinx parser is lazy: it stops parsing contents in the + # middle, if it is too big. So, handle it per input file + if new_f != f and content: + self.do_parse(content, node) + content = ViewList() + + f = new_f + + # sphinx counts lines from 0 + ln = int(match.group(2)) - 1 + else: + content.append(line, f, ln) + + kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n)) + + if content: + self.do_parse(content, node) + + return node.children + + def do_parse(self, content, node): + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf diff --git a/Documentation/sphinx/kernellog.py b/Documentation/sphinx/kernellog.py index af924f51a7dc..8ac7d274f542 100644 --- a/Documentation/sphinx/kernellog.py +++ b/Documentation/sphinx/kernellog.py @@ -25,4 +25,8 @@ def verbose(app, message): else: app.verbose(message) - +def info(app, message): + if UseLogging: + logger.info(message) + else: + app.info(message) diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 4f206cee31a7..283d62541c4f 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -46,7 +46,7 @@ Procedura per sottomettere patch per i sorgenti -stable :ref:`Documentation/translations/it_IT/networking/netdev-FAQ.rst <it_netdev-FAQ>`; ma solo dopo aver verificato al seguente indirizzo che la patch non sia già in coda: - https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive= + https://patchwork.kernel.org/bundle/netdev/stable/?state=* - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo di revisione -stable, ma dovrebbe seguire le procedure descritte in :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 69fc5167e648..acd2cc2a538d 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -22,6 +22,7 @@ place where this information is gathered. spec_ctrl accelerators/ocxl ioctl/index + iommu media/index .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 55a2d9b2ce33..a4c75a28c839 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -323,6 +323,7 @@ Code Seq# Include File Comments <mailto:tlewis@mindspring.com> 0xA3 90-9F linux/dtlk.h 0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xA4 00-1F uapi/asm/sgx.h <mailto:linux-sgx@vger.kernel.org> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst index d3387b1fa7c5..663bdef8d6da 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -188,7 +188,7 @@ Available follower modes are: in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages this CEC device transmits and all messages it receives, including - directed messages for other CEC devices will be reported. This is + directed messages for other CEC devices, will be reported. This is very useful for debugging, but not all devices support this. This mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, otherwise the ``EINVAL`` error code is returned. This is only allowed if diff --git a/Documentation/userspace-api/media/dvb/audio.rst b/Documentation/userspace-api/media/dvb/audio.rst index 071abac9d52d..eaae5675a47d 100644 --- a/Documentation/userspace-api/media/dvb/audio.rst +++ b/Documentation/userspace-api/media/dvb/audio.rst @@ -8,7 +8,7 @@ Digital TV Audio Device The Digital TV audio device controls the MPEG2 audio decoder of the Digital TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data -types and and ioctl definitions can be accessed by including +types and ioctl definitions can be accessed by including ``linux/dvb/audio.h`` in your application. Please note that some Digital TV cards don’t have their own MPEG decoder, which diff --git a/Documentation/userspace-api/media/dvb/ca.rst b/Documentation/userspace-api/media/dvb/ca.rst index 6f6821e322a9..0dc00e5e4a8c 100644 --- a/Documentation/userspace-api/media/dvb/ca.rst +++ b/Documentation/userspace-api/media/dvb/ca.rst @@ -7,7 +7,7 @@ Digital TV CA Device #################### The Digital TV CA device controls the conditional access hardware. It -can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl +can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/ca.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/demux.rst b/Documentation/userspace-api/media/dvb/demux.rst index 364ef48472ee..ef05abcf14d1 100644 --- a/Documentation/userspace-api/media/dvb/demux.rst +++ b/Documentation/userspace-api/media/dvb/demux.rst @@ -11,7 +11,7 @@ digital TV. If the driver and hardware supports, those filters are implemented at the hardware. Otherwise, the Kernel provides a software emulation. -It can be accessed through ``/dev/adapter?/demux?``. Data types and and +It can be accessed through ``/dev/adapter?/demux?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst index 17e70143c1b0..1a13a33834db 100644 --- a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -50,7 +50,7 @@ by a :ref:`DMX_QUERYBUF` ioctl will do as well. When ``DMX_QBUF`` is called with a pointer to this structure, it locks the memory pages of the buffer in physical memory, so they cannot be swapped out to disk. Buffers remain locked until dequeued, until the -the device is closed. +device is closed. Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled (capturing) buffer from the driver's outgoing queue. diff --git a/Documentation/userspace-api/media/dvb/net.rst b/Documentation/userspace-api/media/dvb/net.rst index 33368f5150c5..020a023d3b61 100644 --- a/Documentation/userspace-api/media/dvb/net.rst +++ b/Documentation/userspace-api/media/dvb/net.rst @@ -23,7 +23,7 @@ types that are present on the transport stream. This is done through virtual ``dvb?_?`` network interfaces, and will be controlled/routed via the standard ip tools (like ip, route, netstat, ifconfig, etc). -Data types and and ioctl definitions are defined via ``linux/dvb/net.h`` +Data types and ioctl definitions are defined via ``linux/dvb/net.h`` header. diff --git a/Documentation/userspace-api/media/dvb/video.rst b/Documentation/userspace-api/media/dvb/video.rst index 3ed1bbfb93c3..38a8d39a1d25 100644 --- a/Documentation/userspace-api/media/dvb/video.rst +++ b/Documentation/userspace-api/media/dvb/video.rst @@ -8,7 +8,7 @@ Digital TV Video Device The Digital TV video device controls the MPEG2 video decoder of the Digital TV hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data -types and and ioctl definitions can be accessed by including +types and ioctl definitions can be accessed by including **linux/dvb/video.h** in your application. Note that the Digital TV video device only controls decoding of the MPEG video diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/lirc.h.rst.exceptions index ac768d769113..e74b73cd0e9e 100644 --- a/Documentation/userspace-api/media/lirc.h.rst.exceptions +++ b/Documentation/userspace-api/media/lirc.h.rst.exceptions @@ -64,6 +64,7 @@ ignore symbol RC_PROTO_RCMM12 ignore symbol RC_PROTO_RCMM24 ignore symbol RC_PROTO_RCMM32 ignore symbol RC_PROTO_XBOX_DVD +ignore symbol RC_PROTO_MAX # Undocumented macros diff --git a/Documentation/userspace-api/media/rc/keytable.c.rst b/Documentation/userspace-api/media/rc/keytable.c.rst index 0b50cfaf2d86..243e02d2611f 100644 --- a/Documentation/userspace-api/media/rc/keytable.c.rst +++ b/Documentation/userspace-api/media/rc/keytable.c.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later file: uapi/v4l/keytable.c ========================= diff --git a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst index 167b354bf051..c88973732282 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev_intro: @@ -57,12 +57,12 @@ on the following table. This mode is for both sending and receiving IR. - For transmitting (aka sending), create a ``struct lirc_scancode`` with + For transmitting (aka sending), create a struct lirc_scancode with the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` 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. + 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 @@ -136,6 +136,13 @@ on the following table. This mode is used only for IR send. +************************************* +Data types used by LIRC_MODE_SCANCODE +************************************* + +.. kernel-doc:: include/uapi/linux/lirc.h + :identifiers: lirc_scancode rc_proto + ******************** BPF based IR decoder ******************** diff --git a/Documentation/userspace-api/media/rc/lirc-dev.rst b/Documentation/userspace-api/media/rc/lirc-dev.rst index 5510dc02a822..978f86d30fae 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev: diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst index 420a3dbf0d6b..793f295d3ac9 100644 --- a/Documentation/userspace-api/media/rc/lirc-func.rst +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_func: diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst index 66a243dbd437..4bf25860f932 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-features.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_features: diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst index 188478ed1233..628fe31792b2 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_rec_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst index e29445c5ce16..4dfa9c23634b 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_rec_resolution: diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst index 77472fb5608a..637871805be6 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_send_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst index f5f3e06d6206..597c3282ae12 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_min_timeout: diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index 8bd0acc9913a..54cb40b8a065 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_header: diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst index d589560214f4..ce34318698b7 100644 --- a/Documentation/userspace-api/media/rc/lirc-read.rst +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc-read: diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst index 9bf9811a905a..04ced1aa664b 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_measure_carrier_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst index 530bc223930a..7512dc86b03a 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_carrier_range: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst index 28c928f1cc14..60e321446ea7 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_carrier: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst index 83e7155c5796..aebe81012939 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_timeout_reports: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst index 8f3f9adf54ab..bf9fb2cc61c3 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_timeout: diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst index e3810ba58746..a003f9447553 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_send_carrier: diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst index 52a072529af9..2979752acbcd 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_send_duty_cycle: diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst index 68f4cc2e3ae3..38acbcd6e91c 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_transmitter_mask: diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index be5321c4a91f..c9d578e291b8 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_wideband_receiver: diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst index c1c3230d4fd6..970a8b3fa1ca 100644 --- a/Documentation/userspace-api/media/rc/lirc-write.rst +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc-write: diff --git a/Documentation/userspace-api/media/rc/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst index 1338478e2bd4..2ba62cde2369 100644 --- a/Documentation/userspace-api/media/rc/rc-intro.rst +++ b/Documentation/userspace-api/media/rc/rc-intro.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Intro: diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index 2e290584a210..a2eab3b45647 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Protocols: diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst index 43c442696438..34d6a0a1f4d3 100644 --- a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _remote_controllers_sysfs_nodes: diff --git a/Documentation/userspace-api/media/rc/rc-table-change.rst b/Documentation/userspace-api/media/rc/rc-table-change.rst index 61c77b080ae8..d7de8a56ddfe 100644 --- a/Documentation/userspace-api/media/rc/rc-table-change.rst +++ b/Documentation/userspace-api/media/rc/rc-table-change.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_table_change: diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 8dc11657fc23..aafbfda1f401 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_tables: diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst index 2d9078accb35..f89291838637 100644 --- a/Documentation/userspace-api/media/rc/remote_controllers.rst +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _remote_controllers: diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 7869b6f6ff72..64d241daf63c 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -270,7 +270,17 @@ EBU Tech 3213 ============= -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _tech3321: + +EBU Tech 3321 +============= + + +:title: E.B.U. guidelines for Consumer Flat Panel Displays (FPDs) :author: European Broadcast Union (http://www.ebu.ch) diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 7dbdfbb4a0a9..1b0fdc160533 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -604,7 +604,7 @@ Buffer Flags :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to hardware limitations, the last buffer may be empty. In this case the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the + the format. Any subsequent call to the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE`` error code. * .. _`V4L2-BUF-FLAG-REQUEST-FD`: diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 014e7c9fc655..126f66482a0d 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -674,8 +674,9 @@ Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) ========================================================= The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is +in 1975. Note that this colorspace is not supported by the HDMI interface. +Instead :ref:`tech3321` recommends that Rec. 709 is used instead for HDMI. +The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index d84aeb703165..8c263c5a85d8 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -44,6 +44,7 @@ applicable to all devices. ext-ctrls-image-source ext-ctrls-image-process ext-ctrls-codec + ext-ctrls-codec-stateless ext-ctrls-jpeg ext-ctrls-dv ext-ctrls-rf-tuner diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index d8db46886555..7041bb3d5b8d 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -32,7 +32,7 @@ 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`. More details on how to use codec memory-to-memory +See :ref:`codec-controls`. More details on how to use codec memory-to-memory devices are given in the following sections. .. toctree:: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst new file mode 100644 index 000000000000..01e3b1a3fb99 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -0,0 +1,793 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _codec-stateless-controls: + +********************************* +Stateless Codec Control Reference +********************************* + +The Stateless Codec control class is intended to support +stateless decoder and encoders (i.e. hardware accelerators). + +These drivers are typically supported by the :ref:`stateless_decoder`, +and deal with parsed pixel formats such as V4L2_PIX_FMT_H264_SLICE. + +Stateless Codec Control ID +========================== + +.. _codec-stateless-control-id: + +``V4L2_CID_CODEC_STATELESS_CLASS (class)`` + The Stateless Codec class descriptor. + +.. _v4l2-codec-stateless-h264: + +``V4L2_CID_STATELESS_H264_SPS (struct)`` + Specifies the sequence parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_sps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``profile_idc`` + - + * - __u8 + - ``constraint_set_flags`` + - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` + * - __u8 + - ``level_idc`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_frame_num_minus4`` + - + * - __u8 + - ``pic_order_cnt_type`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``max_num_ref_frames`` + - + * - __u8 + - ``num_ref_frames_in_pic_order_cnt_cycle`` + - + * - __s32 + - ``offset_for_ref_frame[255]`` + - + * - __s32 + - ``offset_for_non_ref_pic`` + - + * - __s32 + - ``offset_for_top_to_bottom_field`` + - + * - __u16 + - ``pic_width_in_mbs_minus1`` + - + * - __u16 + - ``pic_height_in_map_units_minus1`` + - + * - __u32 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` + +.. _h264_sps_constraints_set_flags: + +``Sequence Parameter Set Constraints Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` + - 0x00000020 + - + +.. _h264_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` + - 0x00000020 + - + * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` + - 0x00000040 + - + +``V4L2_CID_STATELESS_H264_PPS (struct)`` + Specifies the picture parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_pps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``num_slice_groups_minus1`` + - + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - + * - __u8 + - ``weighted_bipred_idc`` + - + * - __s8 + - ``pic_init_qp_minus26`` + - + * - __s8 + - ``pic_init_qs_minus26`` + - + * - __s8 + - ``chroma_qp_index_offset`` + - + * - __s8 + - ``second_chroma_qp_index_offset`` + - + * - __u16 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` + +.. _h264_pps_flags: + +``Picture Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` + - 0x00000001 + - + * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` + - 0x00000002 + - + * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000004 + - + * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00000008 + - + * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` + - 0x00000020 + - + * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` + - 0x00000040 + - + * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` + - 0x00000080 + - Indicates that ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + must be used for this picture. + +``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)`` + Specifies the scaling matrix (as extracted from the bitstream) for + the associated H264 slice data. The bitstream parameters are + defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling + List Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_scaling_matrix + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, + Inter Cb, Inter Cr. The values on each scaling list are + expected in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, + Intra Cr, Inter Cr. The values on each scaling list are + expected in raster scan order. + +``V4L2_CID_STATELESS_H264_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + +.. c:type:: v4l2_ctrl_h264_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``header_bit_size`` + - Offset in bits to slice_data() from the beginning of this slice. + * - __u32 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __u8 + - ``cabac_init_idc`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_qs_delta`` + - + * - __u8 + - ``disable_deblocking_filter_idc`` + - + * - __s8 + - ``slice_alpha_c0_offset_div2`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l0_default_active_minus1. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l1_default_active_minus1. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list1[32]`` + - Reference picture list after applying the per-slice modifications + * - __u32 + - ``flags`` + - See :ref:`Slice Parameter Flags <h264_slice_flags>` + +.. _h264_slice_flags: + +``Slice Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000002 + - + +``V4L2_CID_STATELESS_H264_PRED_WEIGHTS (struct)`` + Prediction weight table defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". + The prediction weight table must be passed by applications + under the conditions explained in section 7.3.3 "Slice header + syntax". + +.. c:type:: v4l2_ctrl_h264_pred_weights + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_pred_weights + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``luma_log2_weight_denom`` + - + * - __u16 + - ``chroma_log2_weight_denom`` + - + * - struct :c:type:`v4l2_h264_weight_factors` + - ``weight_factors[2]`` + - The weight factors at index 0 are the weight factors for the reference + list 0, the one at index 1 for the reference list 1. + +.. c:type:: v4l2_h264_weight_factors + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_weight_factors + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s16 + - ``luma_weight[32]`` + - + * - __s16 + - ``luma_offset[32]`` + - + * - __s16 + - ``chroma_weight[32][2]`` + - + * - __s16 + - ``chroma_offset[32][2]`` + - + +``Picture Reference`` + +.. c:type:: v4l2_h264_reference + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_reference + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``fields`` + - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``index`` + - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. + +.. _h264_ref_fields: + +``Reference Fields`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_TOP_FIELD_REF`` + - 0x1 + - The top field in field pair is used for short-term reference. + * - ``V4L2_H264_BOTTOM_FIELD_REF`` + - 0x2 + - The bottom field in field pair is used for short-term reference. + * - ``V4L2_H264_FRAME_REF`` + - 0x3 + - The frame (or the top/bottom fields, if it's a field pair) + is used for short-term reference. + +``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)`` + Specifies the decode parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`. For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_h264_dpb_entry` + - ``dpb[16]`` + - + * - __u16 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __u16 + - ``frame_num`` + - + * - __s32 + - ``top_field_order_cnt`` + - Picture Order Count for the coded top field + * - __s32 + - ``bottom_field_order_cnt`` + - Picture Order Count for the coded bottom field + * - __u16 + - ``idr_pic_id`` + - + * - __u16 + - ``pic_order_cnt_lsb`` + - + * - __s32 + - ``delta_pic_order_cnt_bottom`` + - + * - __s32 + - ``delta_pic_order_cnt0`` + - + * - __s32 + - ``delta_pic_order_cnt1`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - Size in bits of the dec_ref_pic_marking() syntax element. + * - __u32 + - ``pic_order_cnt_bit_size`` + - Combined size in bits of the picture order count related syntax + elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, + delta_pic_order_cnt0, and delta_pic_order_cnt1. + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u32 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` + +.. _h264_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000001 + - That picture is an IDR picture + * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` + - 0x00000002 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` + - 0x00000004 + - + +.. c:type:: v4l2_h264_dpb_entry + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``reference_ts`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-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. + * - __u32 + - ``pic_num`` + - + * - __u16 + - ``frame_num`` + - + * - __u8 + - ``fields`` + - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + * - __s32 + - ``top_field_order_cnt`` + - + * - __s32 + - ``bottom_field_order_cnt`` + - + * - __u32 + - ``flags`` + - See :ref:`DPB Entry Flags <h264_dpb_flags>` + +.. _h264_dpb_flags: + +``DPB Entries Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` + - 0x00000001 + - The DPB entry is valid (non-empty) and should be considered. + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is used for reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is used for long-term reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` + - 0x00000008 + - The DPB entry is a single field or a complementary field pair. + +``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + 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. + +.. c:type:: v4l2_stateless_h264_decode_mode + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + When this mode is selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall be set. When multiple slices compose a frame, + use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag + is required. + * - ``V4L2_STATELESS_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity, + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + This mode will be supported by devices that + parse the slice(s) header(s) in hardware. When this mode is + selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall not be set. + +``V4L2_CID_STATELESS_H264_START_CODE (enum)`` + Specifies the H264 slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + 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. + +.. c:type:: v4l2_stateless_h264_start_code + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. + * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that H264 slices are expected + to be prefixed by Annex B start codes. According to :ref:`h264` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + + +.. _codec-stateless-fwht: + +``V4L2_CID_STATELESS_FWHT_PARAMS (struct)`` + Specifies the FWHT (Fast Walsh Hadamard Transform) parameters (as extracted + from the bitstream) for the associated FWHT data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline for FWHT. + This codec is specific to the vicodec test driver. + +.. c:type:: v4l2_ctrl_fwht_params + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with P-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. + * - __u32 + - ``version`` + - The version of the codec. Set to ``V4L2_FWHT_VERSION``. + * - __u32 + - ``width`` + - The width of the frame. + * - __u32 + - ``height`` + - The height of the frame. + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + + + +.. _fwht-flags: + +FWHT Flags +========== + +.. cssclass:: longtable + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format. + * - ``V4L2_FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If V4L2_FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``V4L2_FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the Y' (luma) plane is uncompressed. + * - ``V4L2_FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the Cb plane is uncompressed. + * - ``V4L2_FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the Cr plane is uncompressed. + * - ``V4L2_FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane. + * - ``V4L2_FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane. + * - ``V4L2_FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed. + * - ``V4L2_FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame. + * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - The number of color components - 1. + * - ``V4L2_FWHT_FL_PIXENC_MSK`` + - 0x00180000 + - The mask for the pixel encoding. + * - ``V4L2_FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV. + * - ``V4L2_FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB. + * - ``V4L2_FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index ce728c757eaf..454ecd9a0f83 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later -.. _mpeg-controls: +.. _codec-controls: *********************** Codec Control Reference @@ -26,7 +26,7 @@ Generic Codec Controls Codec Control IDs ----------------- -``V4L2_CID_MPEG_CLASS (class)`` +``V4L2_CID_CODEC_CLASS (class)`` The Codec class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for this control will return a description of this control class. This description can be @@ -1502,698 +1502,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - Layer number -.. _v4l2-mpeg-h264: - -``V4L2_CID_MPEG_VIDEO_H264_SPS (struct)`` - Specifies the sequence parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_sps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``profile_idc`` - - - * - __u8 - - ``constraint_set_flags`` - - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` - * - __u8 - - ``level_idc`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_frame_num_minus4`` - - - * - __u8 - - ``pic_order_cnt_type`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``max_num_ref_frames`` - - - * - __u8 - - ``num_ref_frames_in_pic_order_cnt_cycle`` - - - * - __s32 - - ``offset_for_ref_frame[255]`` - - - * - __s32 - - ``offset_for_non_ref_pic`` - - - * - __s32 - - ``offset_for_top_to_bottom_field`` - - - * - __u16 - - ``pic_width_in_mbs_minus1`` - - - * - __u16 - - ``pic_height_in_map_units_minus1`` - - - * - __u32 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` - -.. _h264_sps_constraints_set_flags: - -``Sequence Parameter Set Constraints Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` - - 0x00000020 - - - -.. _h264_sps_flags: - -``Sequence Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` - - 0x00000020 - - - * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` - - 0x00000040 - - - -``V4L2_CID_MPEG_VIDEO_H264_PPS (struct)`` - Specifies the picture parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_pps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``pic_parameter_set_id`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``num_slice_groups_minus1`` - - - * - __u8 - - ``num_ref_idx_l0_default_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_default_active_minus1`` - - - * - __u8 - - ``weighted_bipred_idc`` - - - * - __s8 - - ``pic_init_qp_minus26`` - - - * - __s8 - - ``pic_init_qs_minus26`` - - - * - __s8 - - ``chroma_qp_index_offset`` - - - * - __s8 - - ``second_chroma_qp_index_offset`` - - - * - __u16 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` - -.. _h264_pps_flags: - -``Picture Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` - - 0x00000001 - - - * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` - - 0x00000002 - - - * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000004 - - - * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00000008 - - - * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` - - 0x00000020 - - - * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` - - 0x00000040 - - - * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - Indicates that ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX`` - must be used for this picture. - -``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX (struct)`` - Specifies the scaling matrix (as extracted from the bitstream) for - the associated H264 slice data. The bitstream parameters are - defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling - List Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_scaling_matrix - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``scaling_list_4x4[6][16]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, - Inter Cb, Inter Cr. The values on each scaling list are - expected in raster scan order. - * - __u8 - - ``scaling_list_8x8[6][64]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, - Intra Cr, Inter Cr. The values on each scaling list are - expected in raster scan order. - -``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further - documentation, refer to the above specification, unless there is - an explicit comment stating otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API - and it is expected to change. - -.. c:type:: v4l2_ctrl_h264_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``header_bit_size`` - - Offset in bits to slice_data() from the beginning of this slice. - * - __u32 - - ``first_mb_in_slice`` - - - * - __u8 - - ``slice_type`` - - - * - __u8 - - ``colour_plane_id`` - - - * - __u8 - - ``redundant_pic_cnt`` - - - * - __u8 - - ``cabac_init_idc`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_qs_delta`` - - - * - __u8 - - ``disable_deblocking_filter_idc`` - - - * - __s8 - - ``slice_alpha_c0_offset_div2`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. - * - __u8 - - ``reserved`` - - Applications and drivers must set this to zero. - * - struct :c:type:`v4l2_h264_reference` - - ``ref_pic_list0[32]`` - - Reference picture list after applying the per-slice modifications - * - struct :c:type:`v4l2_h264_reference` - - ``ref_pic_list1[32]`` - - Reference picture list after applying the per-slice modifications - * - __u32 - - ``flags`` - - See :ref:`Slice Parameter Flags <h264_slice_flags>` - -.. _h264_slice_flags: - -``Slice Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` - - 0x00000001 - - - * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` - - 0x00000002 - - - -``V4L2_CID_MPEG_VIDEO_H264_PRED_WEIGHTS (struct)`` - Prediction weight table defined according to :ref:`h264`, - section 7.4.3.2 "Prediction Weight Table Semantics". - The prediction weight table must be passed by applications - under the conditions explained in section 7.3.3 "Slice header - syntax". - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_pred_weights - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_pred_weights - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``luma_log2_weight_denom`` - - - * - __u16 - - ``chroma_log2_weight_denom`` - - - * - struct :c:type:`v4l2_h264_weight_factors` - - ``weight_factors[2]`` - - The weight factors at index 0 are the weight factors for the reference - list 0, the one at index 1 for the reference list 1. - -.. c:type:: v4l2_h264_weight_factors - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_weight_factors - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s16 - - ``luma_weight[32]`` - - - * - __s16 - - ``luma_offset[32]`` - - - * - __s16 - - ``chroma_weight[32][2]`` - - - * - __s16 - - ``chroma_offset[32][2]`` - - - -``Picture Reference`` - -.. c:type:: v4l2_h264_reference - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_reference - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``fields`` - - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` - * - __u8 - - ``index`` - - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. - -.. _h264_ref_fields: - -``Reference Fields`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_TOP_FIELD_REF`` - - 0x1 - - The top field in field pair is used for short-term reference. - * - ``V4L2_H264_BOTTOM_FIELD_REF`` - - 0x2 - - The bottom field in field pair is used for short-term reference. - * - ``V4L2_H264_FRAME_REF`` - - 0x3 - - The frame (or the top/bottom fields, if it's a field pair) - is used for short-term reference. - -``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS (struct)`` - Specifies the decode parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`. For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_decode_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_decode_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_h264_dpb_entry` - - ``dpb[16]`` - - - * - __u16 - - ``nal_ref_idc`` - - NAL reference ID value coming from the NAL Unit header - * - __u16 - - ``frame_num`` - - - * - __s32 - - ``top_field_order_cnt`` - - Picture Order Count for the coded top field - * - __s32 - - ``bottom_field_order_cnt`` - - Picture Order Count for the coded bottom field - * - __u16 - - ``idr_pic_id`` - - - * - __u16 - - ``pic_order_cnt_lsb`` - - - * - __s32 - - ``delta_pic_order_cnt_bottom`` - - - * - __s32 - - ``delta_pic_order_cnt0`` - - - * - __s32 - - ``delta_pic_order_cnt1`` - - - * - __u32 - - ``dec_ref_pic_marking_bit_size`` - - Size in bits of the dec_ref_pic_marking() syntax element. - * - __u32 - - ``pic_order_cnt_bit_size`` - - Combined size in bits of the picture order count related syntax - elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, - delta_pic_order_cnt0, and delta_pic_order_cnt1. - * - __u32 - - ``slice_group_change_cycle`` - - - * - __u32 - - ``reserved`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` - -.. _h264_decode_params_flags: - -``Decode Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` - - 0x00000001 - - That picture is an IDR picture - * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` - - 0x00000002 - - - * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` - - 0x00000004 - - - -.. c:type:: v4l2_h264_dpb_entry - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``reference_ts`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-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. - * - __u32 - - ``pic_num`` - - - * - __u16 - - ``frame_num`` - - - * - __u8 - - ``fields`` - - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` - * - __u8 - - ``reserved[5]`` - - Applications and drivers must set this to zero. - * - __s32 - - ``top_field_order_cnt`` - - - * - __s32 - - ``bottom_field_order_cnt`` - - - * - __u32 - - ``flags`` - - See :ref:`DPB Entry Flags <h264_dpb_flags>` - -.. _h264_dpb_flags: - -``DPB Entries Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` - - 0x00000001 - - The DPB entry is valid (non-empty) and should be considered. - * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` - - 0x00000002 - - The DPB entry is used for reference. - * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` - - 0x00000004 - - The DPB entry is used for long-term reference. - * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` - - 0x00000008 - - The DPB entry is a single field or a complementary field pair. - -``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. - The OUTPUT buffer must contain a single slice. - When this mode is selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` - control shall be set. When multiple slices compose a frame, - use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag - is required. - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity, - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - This mode will be supported by devices that - parse the slice(s) header(s) in hardware. When this mode is - selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` - control shall not be set. - -``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)`` @@ -2905,127 +2213,6 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a non-coded frame. -.. _v4l2-mpeg-fwht: - -``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` - Specifies the fwht parameters (as extracted from the bitstream) for the - associated FWHT data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for FWHT. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_fwht_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| - -.. flat-table:: struct v4l2_ctrl_fwht_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with P-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. - * - __u32 - - ``version`` - - The version of the codec - * - __u32 - - ``width`` - - The width of the frame - * - __u32 - - ``height`` - - The height of the frame - * - __u32 - - ``flags`` - - The flags of the frame, see :ref:`fwht-flags`. - * - __u32 - - ``colorspace`` - - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. - * - __u32 - - ``xfer_func`` - - The transfer function, from enum :c:type:`v4l2_xfer_func`. - * - __u32 - - ``ycbcr_enc`` - - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - * - __u32 - - ``quantization`` - - The quantization range, from enum :c:type:`v4l2_quantization`. - - - -.. _fwht-flags: - -FWHT Flags -============ - -.. cssclass:: longtable - -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``FWHT_FL_IS_INTERLACED`` - - 0x00000001 - - Set if this is an interlaced format - * - ``FWHT_FL_IS_BOTTOM_FIRST`` - - 0x00000002 - - Set if this is a bottom-first (NTSC) interlaced format - * - ``FWHT_FL_IS_ALTERNATE`` - - 0x00000004 - - Set if each 'frame' contains just one field - * - ``FWHT_FL_IS_BOTTOM_FIELD`` - - 0x00000008 - - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the - bottom field, else it is the top field. - * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` - - 0x00000010 - - Set if the luma plane is uncompressed - * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` - - 0x00000020 - - Set if the cb plane is uncompressed - * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` - - 0x00000040 - - Set if the cr plane is uncompressed - * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` - - 0x00000080 - - Set if the chroma plane has the same height as the luma plane, - else the chroma plane is half the height of the luma plane - * - ``FWHT_FL_CHROMA_FULL_WIDTH`` - - 0x00000100 - - Set if the chroma plane has the same width as the luma plane, - else the chroma plane is half the width of the luma plane - * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` - - 0x00000200 - - Set if the alpha plane is uncompressed - * - ``FWHT_FL_I_FRAME`` - - 0x00000400 - - Set if this is an I-frame - * - ``FWHT_FL_COMPONENTS_NUM_MSK`` - - 0x00070000 - - A 4-values flag - the number of components - 1 - * - ``FWHT_FL_PIXENC_YUV`` - - 0x00080000 - - Set if the pixel encoding is YUV - * - ``FWHT_FL_PIXENC_RGB`` - - 0x00100000 - - Set if the pixel encoding is RGB - * - ``FWHT_FL_PIXENC_HSV`` - - 0x00180000 - - Set if the pixel encoding is HSV - - CX2341x MPEG Controls ===================== diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst index 9457dc340c31..de43f5c8486d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst @@ -58,3 +58,17 @@ Image Source Control IDs The unit cell consists of the whole area of the pixel, sensitive and non-sensitive. This control is required for automatic calibration of sensors/cameras. + +.. c:type:: v4l2_area + +.. flat-table:: struct v4l2_area + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``width`` + - Width of the area. + * - __u32 + - ``height`` + - Height of the area. diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst index 70301538d222..44fcd67f20bf 100644 --- a/Documentation/userspace-api/media/v4l/extended-controls.rst +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst @@ -55,8 +55,8 @@ controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` -ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls -relating to MPEG encoding, etc. +ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls +relating to codecs. All controls in the control array must belong to the specified control class. An error is returned if this is not the case. @@ -130,9 +130,9 @@ control class is found: .. code-block:: c - qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; + qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { - if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index d585909bc4e2..acad5f3ca0c1 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -57,18 +57,18 @@ Compressed Formats - H264 parsed slice data, including slice headers, either with or without the start code, 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`). + H264 pipeline with the :ref:`stateless_decoder`. 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. + through the ``V4L2_CID_STATELESS_H264_DECODE_MODE`` + and ``V4L2_CID_STATELESS_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 - ``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the - :ref:`associated Codec Control IDs <v4l2-mpeg-h264>`. Exactly - one output and one capture buffer must be provided for use + required to be passed through the ``V4L2_CID_STATELESS_H264_SPS``, + ``V4L2_CID_STATELESS_H264_PPS``, + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX``, + ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` and + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs <v4l2-codec-stateless-h264>`. + 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. @@ -77,11 +77,6 @@ Compressed Formats 7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following sections. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-H263: - ``V4L2_PIX_FMT_H263`` @@ -196,10 +191,10 @@ Compressed Formats through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE`` and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls. Metadata associated with the frame to decode is required to be passed - through the following controls : - * ``V4L2_CID_MPEG_VIDEO_HEVC_SPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_PPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS`` + through the following controls: + ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``, + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``, and + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``. See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. @@ -222,4 +217,6 @@ Compressed Formats - ``V4L2_PIX_FMT_FWHT_STATELESS`` - 'SFWH' - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. + See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst b/Documentation/userspace-api/media/v4l/pixfmt-grey.rst deleted file mode 100644 index 121365b03c57..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-GREY: - -************************** -V4L2_PIX_FMT_GREY ('GREY') -************************** - -Grey-scale image - - -Description -=========== - -This is a grey-scale image. It is really a degenerate Y'CbCr format -which simply contains no Cb or Cr data. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst index 13cf36a8cd5c..c01a949e7c11 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst @@ -67,60 +67,5 @@ Each cell is one byte. **Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally and vertically. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst index 7e43837ed260..fa04f00bcd2e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst @@ -1,7 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _v4l2-meta-fmt-params-rkisp1: -.. _v4l2-meta-fmt-stat-rkisp1: +.. _v4l2-meta-fmt-rk-isp1-params: + +.. _v4l2-meta-fmt-rk-isp1-stat-3a: ***************************************************************************** V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s') @@ -46,4 +47,4 @@ important tuning tools using software control loop. rkisp1 uAPI data types ====================== -.. kernel-doc:: drivers/staging/media/rkisp1/uapi/rkisp1-config.h +.. kernel-doc:: include/uapi/linux/rkisp1-config.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst deleted file mode 100644 index dd2f38129fe6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12: -.. _V4L2-PIX-FMT-NV21: - -****************************************************** -V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') -****************************************************** - - -V4L2_PIX_FMT_NV21 -Formats with ½ horizontal and vertical chroma resolution, also known as -YUV 4:2:0. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:0 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width, in bytes, as the Y plane (and of the image), -but is half as tall in pixels. Each CbCr pair belongs to four pixels. -For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is -the same except the Cb and Cr bytes are swapped, the CrCb plane starts -with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst deleted file mode 100644 index 250f8b977605..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12M: -.. _v4l2-pix-fmt-nv12mt-16x16: -.. _V4L2-PIX-FMT-NV21M: - -*********************************************************************************** -V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 -*********************************************************************************** - - -V4L2_PIX_FMT_NV21M -V4L2_PIX_FMT_NV12MT_16X16 -Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:0 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane do not -necessarily immediately follows the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is a chrominance data with alternating chroma -samples. The CbCr plane is the same width, in bytes, as the Y plane (and -of the image), but is half as tall in pixels. Each CbCr pair belongs to -four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to -Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. -``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of -``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are -arranged in 16x16 2D tiles and tiles are arranged in linear order in -memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M`` -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr -byte. - -``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and -applications that support the multi-planar API, described in -:ref:`planar-apis`. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst deleted file mode 100644 index 46f63d793ec5..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12MT: - -**************************** -V4L2_PIX_FMT_NV12MT ('TM12') -**************************** - -Formats with ½ horizontal and vertical chroma resolution. This format -has two planes - one for luminance and one for chrominance. Chroma -samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the -memory layout. Pixels are grouped in macroblocks of 64x32 size. The -order of macroblocks in memory is also not standard. - - -Description -=========== - -This is the two-plane versions of the YUV 4:2:0 format where data is -grouped into 64x32 macroblocks. The three components are separated into -two sub-images or planes. The Y plane has one byte per pixel and pixels -are grouped into 64x32 macroblocks. The CbCr plane has the same width, -in bytes, as the Y plane (and the image), but is half as tall in pixels. -The chroma plane is also grouped into 64x32 macroblocks. - -Width of the buffer has to be aligned to the multiple of 128, and height -alignment is 32. Every four adjacent buffers - two horizontally and two -vertically are grouped together and are located in memory in Z or -flipped Z order. - -Layout of macroblocks in memory is presented in the following figure. - - -.. _nv12mt: - -.. kernel-figure:: nv12mt.svg - :alt: nv12mt.svg - :align: center - - V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout - -The requirement that width is multiple of 128 is implemented because, -the Z shape cannot be cut in half horizontally. In case the vertical -resolution of macroblocks is odd then the last row of macroblocks is -arranged in a linear order. - -In case of chroma the layout is identical. Cb and Cr samples are -interleaved. Height of the buffer is aligned to 32. - - -.. _nv12mt_ex: - -.. kernel-figure:: nv12mt_example.svg - :alt: nv12mt_example.svg - :align: center - - Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks - -Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most -extreme case. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst deleted file mode 100644 index 22295fc0c359..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV16: -.. _V4L2-PIX-FMT-NV61: - -****************************************************** -V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') -****************************************************** - -V4L2_PIX_FMT_NV61 -Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. -One luminance and one chrominance plane with alternating chroma samples -as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:2 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width and height, in bytes, as the Y plane (and of the -image). Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are -swapped, the CrCb plane starts with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - * - start + 24: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - * - start + 28: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst deleted file mode 100644 index 812bf2ccabf0..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV16M: -.. _v4l2-pix-fmt-nv61m: - -******************************************************** -V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61') -******************************************************** - -V4L2_PIX_FMT_NV61M -Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:2 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane does not -necessarily immediately follow the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is chrominance data with alternating chroma samples. -The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the -Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. - -``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - * - start1 + 8: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - * - start1 + 12: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst deleted file mode 100644 index bf1b94062fc2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV24: -.. _V4L2-PIX-FMT-NV42: - -****************************************************** -V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42') -****************************************************** - -V4L2_PIX_FMT_NV42 -Formats with full horizontal and vertical chroma resolutions, also known -as YUV 4:4:4. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:4:4 format. The three -components are separated into two sub-images or planes. The Y plane is -first, with each Y sample stored in one byte per pixel. For -``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y -plane in memory. The CbCr plane has the same width and height, in -pixels, as the Y plane (and the image). Each line contains one CbCr pair -per pixel, with each Cb and Cr sample stored in one byte. -``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are -swapped, the CrCb plane starts with a Cr sample. - -If the Y plane has pad bytes after each row, then the CbCr plane has -twice as many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - - Cb\ :sub:`03` - - Cr\ :sub:`03` - * - start + 24: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - - Cb\ :sub:`13` - - Cr\ :sub:`13` - * - start + 32: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - - Cb\ :sub:`23` - - Cr\ :sub:`23` - * - start + 40: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - Cb\ :sub:`33` - - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index 84262208dd1c..eb551b57557e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -6,12 +6,32 @@ Packed YUV formats ****************** -Description -=========== +Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and +Cr components consecutively in memory. They may apply subsampling to the chroma +components and thus differ in how they interlave the three components. -Similar to the packed RGB formats these formats store the Y, Cb and Cr -component of each pixel in one 16 or 32 bit word. +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as + 'U') and red chroma (also known as 'V') components respectively. 'A' + denotes bits of the alpha component (if supported by the format), and 'X' + denotes padding bits. + + +4:4:4 Subsampling +================= +These formats do not subsample the chroma components and store each pixels as a +full triplet of Y, Cb and Cr values. + +The next table lists the packed YUV 4:4:4 formats with less than 8 bits per +component. They are named based on the order of the Y, Cb and Cr components as +seen in a 16-bit word, which is then stored in memory in little endian byte +order, and on the number of bits for each component. For instance the YUV565 +format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0` +Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, +[Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`]. .. raw:: latex @@ -19,11 +39,9 @@ component of each pixel in one 16 or 32 bit word. \tiny \setlength{\tabcolsep}{2pt} -.. _packed-yuv-formats: - -.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| +.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| -.. flat-table:: Packed YUV Image Formats +.. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 :stub-columns: 0 @@ -34,10 +52,6 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - 7 @@ -58,24 +72,6 @@ component of each pixel in one 16 or 32 bit word. - 1 - 0 - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -99,8 +95,6 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`1` - Y'\ :sub:`0` - - :cspan:`15` - * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -124,7 +118,6 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -148,226 +141,219 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` +.. raw:: latex - * .. _V4L2-PIX-FMT-YUV32: + \endgroup - - ``V4L2_PIX_FMT_YUV32`` - - 'YUV4' +.. note:: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + For the YUV444 and YUV555 formats, the value of alpha bits is undefined + when reading from the driver, ignored when writing to the driver, except + when alpha blending has been negotiated for a :ref:`Video Overlay + <overlay>` or :ref:`Video Output Overlay <osd>`. - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +The next table lists the packed YUV 4:4:4 formats with 8 bits per component. +They are named based on the order of the Y, Cb and Cr components as stored in +memory, and on the total number of bits per pixel. For instance, the VUYX32 +format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in +the second byte and Y'\ :sub:`7-0` in the third byte. - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` +.. flat-table:: Packed YUV Image Formats (8bpc) + :header-rows: 1 + :stub-columns: 0 - * .. _V4L2-PIX-FMT-AYUV32: + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 - - ``V4L2_PIX_FMT_AYUV32`` - - 'AYUV' + * .. _V4L2-PIX-FMT-YUV32: - - 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_YUV32`` + - 'YUV4' - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` + * .. _V4L2-PIX-FMT-AYUV32: - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - ``V4L2_PIX_FMT_AYUV32`` + - 'AYUV' + + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-XYUV32: - ``V4L2_PIX_FMT_XYUV32`` - 'XYUV' - - - - - - - - - - - - - - - - - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - X\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYA32: - ``V4L2_PIX_FMT_VUYA32`` - 'VUYA' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :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` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - A\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYX32: - ``V4L2_PIX_FMT_VUYX32`` - 'VUYX' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - X\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +.. note:: - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` + - The alpha component is expected to contain a meaningful value that can be + used by drivers and applications. + - The padding bits contain undefined values that must be ignored by all + applications and drivers. + + +4:2:2 Subsampling +================= + +These formats, commonly referred to as YUYV or YUY2, subsample the chroma +components horizontally by 2, storing 2 pixels in 4 bytes. + +.. flat-table:: Packed YUV 4:2:2 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + * .. _V4L2-PIX-FMT-UYVY: + + - ``V4L2_PIX_FMT_UYVY`` + - 'UYVY' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`2` + - Y'\ :sub:`2` + - Cr\ :sub:`2` - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-VYUY: + + - ``V4L2_PIX_FMT_VYUY`` + - 'VYUY' + + - Cr\ :sub:`0` + - Y'\ :sub:`0` + - Cb\ :sub:`0` + - Y'\ :sub:`1` + - Cr\ :sub:`2` - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-YUYV: + + - ``V4L2_PIX_FMT_YUYV`` + - 'YUYV' + + - Y'\ :sub:`0` + - Cb\ :sub:`0` - Y'\ :sub:`1` + - Cr\ :sub:`0` + - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + - Cr\ :sub:`2` + * .. _V4L2-PIX-FMT-YVYU: + + - ``V4L2_PIX_FMT_YVYU`` + - 'YVYU' + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`0` + - Y'\ :sub:`2` + - Cr\ :sub:`2` + - Y'\ :sub:`3` + - Cb\ :sub:`2` - - - - - - - - - - - - - - - - +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. -.. raw:: latex - \endgroup +4:1:1 Subsampling +================= + +This format subsamples the chroma components horizontally by 4, storing 8 +pixels in 12 bytes. + +.. flat-table:: Packed YUV 4:1:1 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + - Byte 8 + - Byte 9 + - Byte 10 + - Byte 11 + * .. _V4L2-PIX-FMT-Y41P: + + - ``V4L2_PIX_FMT_Y41P`` + - 'Y41P' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`4` + - Y'\ :sub:`2` + - Cr\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`4` + - Y'\ :sub:`5` + - Y'\ :sub:`6` + - Y'\ :sub:`7` .. note:: - #) Bit 7 is the most significant bit; + Do not confuse ``V4L2_PIX_FMT_Y41P`` with + :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from + "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*". - #) The value of a = alpha bits is undefined when reading from the driver, - ignored when writing to the driver, except when alpha blending has - been negotiated for a :ref:`Video Overlay <overlay>` or - :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and - YUV4. However, for formats AYUV32 and VUYA32, the alpha component is - expected to contain a meaningful value that can be used by drivers - and applications. And, the formats XYUV32 and VUYX32 contain undefined - alpha values that must be ignored by all applications and drivers. +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 9d827097c1d9..897676ee2c9d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -6,13 +6,62 @@ 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. +These formats encode each pixel as a triplet of RGB values. They are packed +formats, meaning that the RGB values for one pixel are stored consecutively in +memory and each pixel consumes an integer number of bytes. When the number of +bits required to store a pixel is not aligned to a byte boundary, the data is +padded with additional bits to fill the remaining byte. + +The formats differ by the number of bits per RGB component (typically but not +always the same for all components), the order of components in memory, and the +presence of an alpha component or additional padding bits. + +The usage and value of the alpha bits in formats that support them (named ARGB +or a permutation thereof, 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 captures an alpha channel the alpha component will have +a meaningful value. Otherwise, when the device doesn't capture 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. + +Formats that contain padding bits are named XRGB (or a permutation thereof). +The padding bits contain undefined values and must be ignored by applications, +devices and drivers, for both :ref:`capture` and :ref:`output` devices. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'r', 'g' and 'b' denote bits of the red, green and blue components + respectively. 'a' denotes bits of the alpha component (if supported by the + format), and 'x' denotes padding bits. + + +Less Than 8 Bits Per Component +============================== + +These formats store an RGB triplet in one, two or four bytes. They are named +based on the order of the RGB components as seen in a 8-, 16- or 32-bit word, +which is then stored in memory in little endian byte order (unless otherwise +noted by the presence of bit 31 in the 4CC value), and on the number of bits +for each component. For instance, the RGB565 format stores a pixel in a 16-bit +word [15:0] laid out at as [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`], and +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2` +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` +B\ :sub:`0`]. .. raw:: latex @@ -23,7 +72,7 @@ next to each other in memory. .. 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 +.. flat-table:: RGB Formats With Less Than 8 Bits Per Component :header-rows: 2 :stub-columns: 0 @@ -121,10 +170,10 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` @@ -162,10 +211,10 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` @@ -213,10 +262,10 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` @@ -254,10 +303,10 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` @@ -305,7 +354,7 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -349,7 +398,7 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` @@ -397,7 +446,7 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` @@ -441,7 +490,7 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` @@ -503,7 +552,7 @@ next to each other in memory. - ``V4L2_PIX_FMT_XRGB555X`` - 'XR15' | (1 << 31) - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -544,538 +593,188 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - * .. _V4L2-PIX-FMT-BGR24: + * .. _V4L2-PIX-FMT-BGR666: - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' - - 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: + - x + - x + - x + - x + - x + - x - - ``V4L2_PIX_FMT_RGB24`` - - 'RGB3' + - x + - x + - x + - x + - x + - x + - x + - x - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` +.. raw:: latex - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + \endgroup - - 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' +8 Bits Per Component +==================== - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` +These formats store an RGB triplet in three or four bytes. They are named based +on the order of the RGB components as stored in memory, and on the total number +of bits per pixel. For instance, RGB24 format stores a pixel with [R\ :sub:`7` +R\ :sub:`6` R\ :sub:`5` R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0`] in the first byte, [G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` +G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` G\ :sub:`0`] in the second byte and +[B\ :sub:`7` B\ :sub:`6` B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` +B\ :sub:`1` B\ :sub:`0`] in the third byte. This differs from the DRM format +nomenclature that instead use the order of components as seen in a 24- or +32-bit little endian word. - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` +.. raw:: latex - - r\ :sub:`1` - - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ABGR32: + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}| - - 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` +.. flat-table:: RGB Formats With 8 Bits Per Component + :header-rows: 1 + :stub-columns: 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` + * - Identifier + - Code + - Byte 0 in memory + - Byte 1 + - Byte 2 + - Byte 3 + * .. _V4L2-PIX-FMT-BGR24: - - 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_BGR24`` + - 'BGR3' - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - R\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-RGB24: - - 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_RGB24`` + - 'RGB3' - - 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-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-ABGR32: - - 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_ABGR32`` + - 'AR24' - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' + + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - X\ :sub:`7-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` + - A\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-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` + - X\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-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` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - A\ :sub:`7-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` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - X\ :sub:`7-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` + - A\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-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` + - X\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-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. +Deprecated RGB Formats +====================== +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)`` is ill-defined and they are interpreted as in either +the corresponding ARGB or XRGB format, depending on the driver. .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst deleted file mode 100644 index bae975fb14f6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-UYVY: - -************************** -V4L2_PIX_FMT_UYVY ('UYVY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst deleted file mode 100644 index aff8588b67a9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-VYUY: - -************************** -V4L2_PIX_FMT_VYUY ('VYUY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cr\ :sub:`00` - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`01` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cr\ :sub:`10` - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`11` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cr\ :sub:`20` - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`21` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cr\ :sub:`30` - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`31` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10.rst deleted file mode 100644 index 05f018dd883f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10: - -************************* -V4L2_PIX_FMT_Y10 ('Y10 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 10 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst deleted file mode 100644 index 38d353b37df9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10BPACK: - -****************************** -V4L2_PIX_FMT_Y10BPACK ('Y10B') -****************************** - -Grey-scale image as a bit-packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, -with no padding between them and with the most significant bits coming -first from the left. - -**Bit-packed representation.** - -pixels cross the byte boundary and have a ratio of 5 bytes for each 4 -pixels. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]` - - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]` - - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]` - - Y'\ :sub:`03[7:0]` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst deleted file mode 100644 index dd20d3438732..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10P: - -****************************** -V4L2_PIX_FMT_Y10P ('Y10P') -****************************** - -Grey-scale image as a MIPI RAW10 packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Every four consecutive pixels are packed into 5 bytes. Each of -the first 4 bytes contain the 8 high order bits of the pixels, and -the 5th byte contains the 2 least significants bits of each pixel, -in the same order. - -**Bit-packed representation.** - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 8 8 8 8 64 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`01[9:2]` - - Y'\ :sub:`02[9:2]` - - Y'\ :sub:`03[9:2]` - - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) - Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) - -.. raw:: latex - - \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12.rst deleted file mode 100644 index 20e12a18da72..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y12: - -************************* -V4L2_PIX_FMT_Y12 ('Y12 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 12 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst b/Documentation/userspace-api/media/v4l/pixfmt-y14.rst deleted file mode 100644 index 2a4826b77105..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y14: - -************************* -V4L2_PIX_FMT_Y14 ('Y14 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 14 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst deleted file mode 100644 index 6d70cd78cbf6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y16-BE: - -**************************************** -V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31)) -**************************************** - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The most -significant byte is stored at lower memory addresses (big-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00high` - - Y'\ :sub:`00low` - - Y'\ :sub:`01high` - - Y'\ :sub:`01low` - - Y'\ :sub:`02high` - - Y'\ :sub:`02low` - - Y'\ :sub:`03high` - - Y'\ :sub:`03low` - * - start + 8: - - Y'\ :sub:`10high` - - Y'\ :sub:`10low` - - Y'\ :sub:`11high` - - Y'\ :sub:`11low` - - Y'\ :sub:`12high` - - Y'\ :sub:`12low` - - Y'\ :sub:`13high` - - Y'\ :sub:`13low` - * - start + 16: - - Y'\ :sub:`20high` - - Y'\ :sub:`20low` - - Y'\ :sub:`21high` - - Y'\ :sub:`21low` - - Y'\ :sub:`22high` - - Y'\ :sub:`22low` - - Y'\ :sub:`23high` - - Y'\ :sub:`23low` - * - start + 24: - - Y'\ :sub:`30high` - - Y'\ :sub:`30low` - - Y'\ :sub:`31high` - - Y'\ :sub:`31low` - - Y'\ :sub:`32high` - - Y'\ :sub:`32low` - - Y'\ :sub:`33high` - - Y'\ :sub:`33low` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16.rst deleted file mode 100644 index 398ad8ba5d64..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y16: - -************************* -V4L2_PIX_FMT_Y16 ('Y16 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The least -significant byte is stored at lower memory addresses (little-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst deleted file mode 100644 index d14cedf8f317..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y41P: - -************************** -V4L2_PIX_FMT_Y41P ('Y41P') -************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1 - - -Description -=========== - -In this format each 12 bytes is eight pixels. In the twelve bytes are -two CbCr pairs and eight Y's. The first CbCr pair goes with the first -four Y's, and the second CbCr pair goes with the other four Y's. The Cb -and Cr components have one fourth the horizontal resolution of the Y -component. - -Do not confuse this format with -:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived -from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 -*planar*". - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Y'\ :sub:`04` - - Y'\ :sub:`05` - - Y'\ :sub:`06` - - Y'\ :sub:`07` - * - start + 12: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Y'\ :sub:`14` - - Y'\ :sub:`15` - - Y'\ :sub:`16` - - Y'\ :sub:`17` - * - start + 24: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Y'\ :sub:`24` - - Y'\ :sub:`25` - - Y'\ :sub:`26` - - Y'\ :sub:`27` - * - start + 36: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Y'\ :sub:`34` - - Y'\ :sub:`35` - - Y'\ :sub:`36` - - Y'\ :sub:`37` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - - 4 - - 5 - - - - 6 - - 7 - * - 0 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst new file mode 100644 index 000000000000..0c8c5e0a380e --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _yuv-luma-only: + +***************** +Luma-Only Formats +***************** + +This family of formats only store the luma component of a Y'CbCr image. They +are often referred to as greyscale formats. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - Formats are described with the minimum number of pixels needed to create a + byte-aligned repeating pattern. `...` indicates repetition of the pattern. + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum + `x`. + - `0` denotes padding bits set to 0. + + +.. flat-table:: Luma-Only Image Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + + * .. _V4L2-PIX-FMT-GREY: + + - ``V4L2_PIX_FMT_GREY`` + - 'GREY' + + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10: + + - ``V4L2_PIX_FMT_Y10`` + - 'Y10 ' + + - Y'\ :sub:`0`\ [7:0] + - `000000` Y'\ :sub:`0`\ [9:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10BPACK: + + - ``V4L2_PIX_FMT_Y10BPACK`` + - 'Y10B' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`0`\ [1:0] Y'\ :sub:`1`\ [9:4] + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`2`\ [9:6] + - Y'\ :sub:`2`\ [5:0] Y'\ :sub:`3`\ [9:8] + - Y'\ :sub:`3`\ [7:0] + + * .. _V4L2-PIX-FMT-Y10P: + + - ``V4L2_PIX_FMT_Y10P`` + - 'Y10P' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`1`\ [9:8] + - Y'\ :sub:`2`\ [9:2] + - Y'\ :sub:`3`\ [9:2] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0] + + * .. _V4L2-PIX-FMT-Y12: + + - ``V4L2_PIX_FMT_Y12`` + - 'Y12 ' + + - Y'\ :sub:`0`\ [7:0] + - `0000` Y'\ :sub:`0`\ [11:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y14: + + - ``V4L2_PIX_FMT_Y14`` + - 'Y14 ' + + - Y'\ :sub:`0`\ [7:0] + - `00` Y'\ :sub:`0`\ [13:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16: + + - ``V4L2_PIX_FMT_Y16`` + - 'Y16 ' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`0`\ [15:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16-BE: + + - ``V4L2_PIX_FMT_Y16_BE`` + - 'Y16 ' | (1U << 31) + + - Y'\ :sub:`0`\ [15:8] + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + +.. note:: + + For the Y16 and Y16_BE formats, the actual sampling precision may be lower + than 16 bits. For example, 10 bits per pixel uses values in the range 0 to + 1023. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst new file mode 100644 index 000000000000..7d4d39201a3f --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -0,0 +1,950 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. planar-yuv: + +****************** +Planar YUV formats +****************** + +Planar formats split luma and chroma data in separate memory regions. They +exist in two variants: + +- Semi-planar formats use two planes. The first plane is the luma plane and + stores the Y components. The second plane is the chroma plane and stores the + Cb and Cr components interleaved. + +- Fully planar formats use three planes to store the Y, Cb and Cr components + separately. + +Within a plane, components are stored in pixel order, which may be linear or +tiled. Padding may be supported at the end of the lines, and the line stride of +the chroma planes may be constrained by the line stride of the luma plane. + +Some planar formats allow planes to be placed in independent memory locations. +They are identified by an 'M' suffix in their name (such as in +``V4L2_PIX_FMT_NV12M``). Those formats are intended to be used only in drivers +and applications that support the multi-planar API, described in +:ref:`planar-apis`. Unless explicitly documented as supporting non-contiguous +planes, formats require the planes to follow each other immediately in memory. + + +Semi-Planar YUV Formats +======================= + +These formats are commonly referred to as NV formats (NV12, NV16, ...). They +use two planes, and store the luma components in the first plane and the chroma +components in the second plane. The Cb and Cr components are interleaved in the +chroma plane, with Cb and Cr always stored in pairs. The chroma order is +exposed as different formats. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. Without horizontal +subsampling, the chroma line stride (in bytes) is thus equal to twice the luma +line stride. With horizontal subsampling by 2, the chroma line stride is equal +to the luma line stride. Vertical subsampling doesn't affect the line stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. flat-table:: Overview of Semi-Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Chroma order [1]_ + - Contiguous [2]_ + - Tiling [3]_ + * - V4L2_PIX_FMT_NV12 + - 'NV12' + - 8 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV21 + - 'NV21' + - 8 + - 4:2:0 + - Cr, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV12M + - 'NM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV21M + - 'NM21' + - 8 + - 4:2:0 + - Cr, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV12MT + - 'TM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - 64x32 macroblocks + + Horizontal Z order + * - V4L2_PIX_FMT_NV12MT_16X16 + - 'VM12' + - 8 + - 4:2:2 + - Cb, Cr + - No + - 16x16 macroblocks + * - V4L2_PIX_FMT_NV16 + - 'NV16' + - 8 + - 4:2:2 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV61 + - 'NV61' + - 8 + - 4:2:2 + - Cr, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV16M + - 'NM16' + - 8 + - 4:2:2 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV61M + - 'NM61' + - 8 + - 4:2:2 + - Cr, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV24 + - 'NV24' + - 8 + - 4:4:4 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV42 + - 'NV42' + - 8 + - 4:4:4 + - Cr, Cr + - Yes + - Linear + +.. note:: + + .. [1] Order of chroma samples in the second plane + .. [2] Indicates if planes have to be contiguous in memory or can be + disjoint + .. [3] Macroblock size in pixels + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +.. _V4L2-PIX-FMT-NV12: +.. _V4L2-PIX-FMT-NV21: +.. _V4L2-PIX-FMT-NV12M: +.. _V4L2-PIX-FMT-NV21M: + +NV12, NV21, NV12M and NV21M +--------------------------- + +Semi-planar YUV 4:2:0 formats. The chroma plane is subsampled by 2 in each +direction. Chroma lines contain half the number of pixels and the same number +of bytes as luma lines, and the chroma plane contains half the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 NV12 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 NV12M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-NV12MT: +.. _V4L2-PIX-FMT-NV12MT-16X16: + +NV12MT and MV12MT_16X16 +----------------------- + +Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is +subsampled by 2 in each direction. Chroma lines contain half the number of +pixels and the same number of bytes as luma lines, and the chroma plane +contains half the number of lines of the luma plane. + +``V4L2_PIX_FMT_NV12MT_16X16`` stores pixel in 2D 16x16 macroblocks, and stores +macroblocks linearly in memory. The line stride and image height must be +aligned to a multiple of 16. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12MT`` stores pixels in 2D 64x32 macroblocks, and stores 2x2 +groups of macroblocks in Z-order in memory, alternating Z and mirrored Z shapes +horizontally. The line stride must be a multiple of 128 pixels to ensure an +integer number of Z shapes. The image height must be a multiple of 32 pixels. +If the vertical resolution is an odd number of macroblocks, the last row of +macroblocks is stored in linear order. The layouts of the luma and chroma +planes are identical. + +.. _nv12mt: + +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg + :align: center + + V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout + +.. _nv12mt_ex: + +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg + :align: center + + Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks + + +.. _V4L2-PIX-FMT-NV16: +.. _V4L2-PIX-FMT-NV61: +.. _V4L2-PIX-FMT-NV16M: +.. _V4L2-PIX-FMT-NV61M: + +NV16, NV61, NV16M and NV61M +--------------------------- + +Semi-planar YUV 4:2:2 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV16 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + * - start + 24: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + * - start + 28: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 NV16M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + * - start1 + 8: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + * - start1 + 12: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + + +.. _V4L2-PIX-FMT-NV24: +.. _V4L2-PIX-FMT-NV42: + +NV24 and NV42 +------------- + +Semi-planar YUV 4:4:4 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV24 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + - Cb\ :sub:`03` + - Cr\ :sub:`03` + * - start + 24: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + - Cb\ :sub:`13` + - Cr\ :sub:`13` + * - start + 32: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + - Cb\ :sub:`23` + - Cr\ :sub:`23` + * - start + 40: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + - Cb\ :sub:`33` + - Cr\ :sub:`33` + + +Fully Planar YUV Formats +======================== + +These formats store the Y, Cb and Cr components in three separate planes. The +luma plane comes first, and the order of the two chroma planes varies between +formats. The two chroma planes always use the same subsampling. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. The chroma line +stride (in bytes) is thus equal to the luma line stride divided by the +horizontal subsampling factor. Vertical subsampling doesn't affect the line +stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. flat-table:: Overview of Fully Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Planes order [4]_ + - Contiguous [5]_ + + * - V4L2_PIX_FMT_YUV410 + - 'YUV9' + - 8 + - 4:1:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU410 + - 'YVU9' + - 8 + - 4:1:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV411P + - '411P' + - 8 + - 4:1:1 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV420M + - 'YM12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU420M + - 'YM21' + - 8 + - 4:2:0 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV420 + - 'YU12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU420 + - 'YV12' + - 8 + - 4:2:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV422P + - '422P' + - 8 + - 4:2:2 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV422M + - 'YM16' + - 8 + - 4:2:2 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU422M + - 'YM61' + - 8 + - 4:2:2 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV444M + - 'YM24' + - 8 + - 4:4:4 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU444M + - 'YM42' + - 8 + - 4:4:4 + - Y, Cr, Cb + - No + +.. note:: + + .. [4] Order of luma and chroma planes + .. [5] Indicates if planes have to be contiguous in memory or can be + disjoint + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + +.. _V4L2-PIX-FMT-YUV410: +.. _V4L2-PIX-FMT-YVU410: + +YUV410 and YVU410 +----------------- + +Planar YUV 4:1:0 formats. The chroma planes are subsampled by 4 in each +direction. Chroma lines contain a quarter of the number of pixels and bytes of +the luma lines, and the chroma planes contain a quarter of the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 YUV410 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + * - start + 17: + - Cb\ :sub:`00` + + +.. _V4L2-PIX-FMT-YUV411P: + +YUV411P +------- + +Planar YUV 4:1:1 formats. The chroma planes are subsampled by 4 in the +horizontal direction. Chroma lines contain a quarter of the number of pixels +and bytes of the luma lines, and the chroma planes contain the same number of +lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV411P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + * - start + 17: + - Cb\ :sub:`10` + * - start + 18: + - Cb\ :sub:`20` + * - start + 19: + - Cb\ :sub:`30` + * - start + 20: + - Cr\ :sub:`00` + * - start + 21: + - Cr\ :sub:`10` + * - start + 22: + - Cr\ :sub:`20` + * - start + 23: + - Cr\ :sub:`30` + + +.. _V4L2-PIX-FMT-YUV420: +.. _V4L2-PIX-FMT-YVU420: +.. _V4L2-PIX-FMT-YUV420M: +.. _V4L2-PIX-FMT-YVU420M: + +YUV420, YVU420, YUV420M and YVU420M +----------------------------------- + +Planar YUV 4:2:0 formats. The chroma planes are subsampled by 2 in each +direction. Chroma lines contain half of the number of pixels and bytes of the +luma lines, and the chroma planes contain half of the number of lines of the +luma plane. + +.. flat-table:: Sample 4x4 YUV420 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 18: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 20: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 22: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + +.. flat-table:: Sample 4x4 YUV420M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-YUV422P: +.. _V4L2-PIX-FMT-YUV422M: +.. _V4L2-PIX-FMT-YVU422M: + +YUV422P, YUV422M and YVU422M +---------------------------- + +Planar YUV 4:2:2 formats. The chroma planes are subsampled by 2 in the +horizontal direction. Chroma lines contain half of the number of pixels and +bytes of the luma lines, and the chroma planes contain the same number of lines +as the luma plane. + +.. flat-table:: Sample 4x4 YUV422P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 18: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start + 20: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start + 22: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - start + 24: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 26: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 28: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start + 30: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 YUV422M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start1 + 4: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start1 + 6: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start2 + 4: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start2 + 6: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + + +.. _V4L2-PIX-FMT-YUV444M: +.. _V4L2-PIX-FMT-YVU444M: + +YUV444M and YVU444M +------------------- + +Planar YUV 4:4:4 formats. The chroma planes are no subsampled. Chroma lines +contain the same number of pixels and bytes of the luma lines, and the chroma +planes contain the same number of lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV444M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + - Cb\ :sub:`02` + - Cb\ :sub:`03` + * - start1 + 4: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + - Cb\ :sub:`12` + - Cb\ :sub:`13` + * - start1 + 8: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`22` + - Cb\ :sub:`23` + * - start1 + 12: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`32` + - Cb\ :sub:`33` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + - Cr\ :sub:`02` + - Cr\ :sub:`03` + * - start2 + 4: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + - Cr\ :sub:`12` + - Cr\ :sub:`13` + * - start2 + 8: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + - Cr\ :sub:`22` + - Cr\ :sub:`23` + * - start2 + 12: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + - Cr\ :sub:`32` + - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst deleted file mode 100644 index de2e519adc60..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVU410: -.. _v4l2-pix-fmt-yuv410: - -********************************************************** -V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') -********************************************************** - - -V4L2_PIX_FMT_YUV410 -Planar formats with ¼ horizontal and vertical chroma resolution, also -known as YUV 4:1:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``, -the Cr plane immediately follows the Y plane in memory. The Cr plane is -¼ the width and ¼ the height of the Y plane (and of the image). Each Cr -belongs to 16 pixels, a four-by-four square of the image. Following the -Cr plane is the Cb plane, just like the Cr plane. -``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first, -then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four Cx rows -(including padding) are exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - * - start + 17: - - Cb\ :sub:`00` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - - - - - C - - - - - - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst deleted file mode 100644 index 998aa9b1328f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV411P: - -***************************** -V4L2_PIX_FMT_YUV411P ('411P') -***************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. -Planar layout as opposed to ``V4L2_PIX_FMT_Y41P`` - - -Description -=========== - -This format is not commonly used. This is a planar format similar to the -4:2:2 planar format except with half as many chroma. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. The Cb plane immediately -follows the Y plane in memory. The Cb plane is ¼ the width of the Y -plane (and of the image). Each Cb belongs to 4 pixels all on the same -row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane, -just like the Cb plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four C x rows -(including padding) is exactly as long as one Y row (including padding). - -**Byte Order.** -Each cell is one byte. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - * - start + 17: - - Cb\ :sub:`10` - * - start + 18: - - Cb\ :sub:`20` - * - start + 19: - - Cb\ :sub:`30` - * - start + 20: - - Cr\ :sub:`00` - * - start + 21: - - Cr\ :sub:`10` - * - start + 22: - - Cr\ :sub:`20` - * - start + 23: - - Cr\ :sub:`30` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - * - 0 - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst deleted file mode 100644 index f1c7baf32685..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVU420: -.. _V4L2-PIX-FMT-YUV420: - -********************************************************** -V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') -********************************************************** - - -V4L2_PIX_FMT_YUV420 -Planar formats with ½ horizontal and vertical chroma resolution, also -known as YUV 4:2:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub- images or planes. The Y plane -is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in -memory. The Cr plane is half the width and half the height of the Y -plane (and of the image). Each Cr belongs to four pixels, a two-by-two -square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane -is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the -same except the Cb plane comes first, then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 18: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 20: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 22: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst deleted file mode 100644 index cd20a57e0621..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV420M: -.. _v4l2-pix-fmt-yvu420m: - -************************************************************ -V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21') -************************************************************ - - -V4L2_PIX_FMT_YVU420M -Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with -planes non contiguous in memory. - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which -is half the width and half the height of the Y plane (and of the image). -Each Cb belongs to four pixels, a two-by-two square of the image. For -example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane, -is in the third plane. - -``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst deleted file mode 100644 index 32bf15e1426e..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV422M: -.. _v4l2-pix-fmt-yvu422m: - -************************************************************ -V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61') -************************************************************ - - -V4L2_PIX_FMT_YVU422M -Planar formats with ½ horizontal resolution, also known as YUV and YVU -4:2:2 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which -is half the width of the Y plane (and of the image). Each Cb belongs to -two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third -plane. - -``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start1 + 4: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start1 + 6: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start2 + 4: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start2 + 6: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst deleted file mode 100644 index b178be558361..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV422P: - -***************************** -V4L2_PIX_FMT_YUV422P ('422P') -***************************** - - -Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. -Planar layout as opposed to ``V4L2_PIX_FMT_YUYV`` - - -Description -=========== - -This format is not commonly used. This is a planar version of the YUYV -format. The three components are separated into three sub-images or -planes. The Y plane is first. The Y plane has one byte per pixel. The Cb -plane immediately follows the Y plane in memory. The Cb plane is half -the width of the Y plane (and of the image). Each Cb belongs to two -pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb -plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 18: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start + 20: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start + 22: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - start + 24: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 26: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 28: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start + 30: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst deleted file mode 100644 index 90bdee2e2b0d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV444M: -.. _v4l2-pix-fmt-yvu444m: - -************************************************************ -V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42') -************************************************************ - - -V4L2_PIX_FMT_YVU444M -Planar formats with full horizontal resolution, also known as YUV and -YVU 4:4:4 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which -is the same width and height as the Y plane (and as the image). The Cr -data, just like the Cb plane, is in the third plane. - -``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have the same number of pad bytes after their rows. - -``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - - Cb\ :sub:`02` - - Cb\ :sub:`03` - * - start1 + 4: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - Cb\ :sub:`12` - - Cb\ :sub:`13` - * - start1 + 8: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`22` - - Cb\ :sub:`23` - * - start1 + 12: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`32` - - Cb\ :sub:`33` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - - Cr\ :sub:`02` - - Cr\ :sub:`03` - * - start2 + 4: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - Cr\ :sub:`12` - - Cr\ :sub:`13` - * - start2 + 8: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - - Cr\ :sub:`22` - - Cr\ :sub:`23` - * - start2 + 12: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - Cr\ :sub:`32` - - Cr\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - 2 - - 3 - * - 0 - - YC - - YC - - YC - - YC - * - 1 - - YC - - YC - - YC - - YC - * - 2 - - YC - - YC - - YC - - YC - * - 3 - - YC - - YC - - YC - - YC diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst deleted file mode 100644 index ca073a5098a9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUYV: - -************************** -V4L2_PIX_FMT_YUYV ('YUYV') -************************** - - -Packed format with ½ horizontal chroma resolution, also known as YUV -4:2:2 - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV`` -is known in the Windows environment as YUY2. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`00` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - - Cr\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`10` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - - Cr\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`20` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - - Cr\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`30` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst deleted file mode 100644 index 81ebec525ae5..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVYU: - -************************** -V4L2_PIX_FMT_YVYU ('YVYU') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`00` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Cb\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`10` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Cb\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`20` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Cb\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`30` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Cb\ :sub:`31` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst index 37617eda2fa6..fee49bf1a1c0 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst @@ -94,7 +94,7 @@ specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given -by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the +by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index c9b7bb3ca089..7f16cbe46e5c 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -7899,3 +7899,30 @@ formats. - 0x5001 - Interleaved raw UYVY and JPEG image format with embedded meta-data used by Samsung S3C73MX camera sensors. + +.. _v4l2-mbus-metadata-fmts: + +Metadata Formats +^^^^^^^^^^^^^^^^ + +This section lists all metadata formats. + +The following table lists the existing metadata formats. + +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| + +.. flat-table:: Metadata formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Comments + * .. _MEDIA-BUS-FMT-METADATA-FIXED: + + - MEDIA_BUS_FMT_METADATA_FIXED + - 0x7001 + - This format should be used when the same driver handles + both sides of the link and the bus format is a fixed + metadata format that is not configurable from userspace. + Width and height will be set to 0 for this format. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index f2173e310d67..b9c62affbb5a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -53,7 +53,7 @@ by the ``controls`` fields. To get the current value of a set of controls applications initialize the ``id``, ``size`` and ``reserved2`` fields of each struct :c:type:`v4l2_ext_control` and call the -:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls must also set the ``string`` field. Controls of compound types (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. @@ -180,10 +180,38 @@ still cause this situation. - ``p_u32`` - A pointer to a matrix control of unsigned 32-bit values. Valid if this control is of type ``V4L2_CTRL_TYPE_U32``. - * - :c:type:`v4l2_area` * + * - struct :c:type:`v4l2_area` * - ``p_area`` - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is of type ``V4L2_CTRL_TYPE_AREA``. + * - struct :c:type:`v4l2_ctrl_h264_sps` * + - ``p_h264_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SPS``. + * - struct :c:type:`v4l2_ctrl_h264_pps` * + - ``p_h264_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PPS``. + * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` * + - ``p_h264_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_h264_pred_weights` * + - ``p_h264_pred_weights`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``. + * - struct :c:type:`v4l2_ctrl_h264_slice_params` * + - ``p_h264_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_h264_decode_params` * + - ``p_h264_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_fwht_params` * + - ``p_fwht_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -322,10 +350,10 @@ still cause this situation. :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this class. - * - ``V4L2_CTRL_CLASS_MPEG`` + * - ``V4L2_CTRL_CLASS_CODEC`` - 0x990000 - - The class containing MPEG compression controls. These controls are - described in :ref:`mpeg-controls`. + - The class containing stateful codec controls. These controls are + described in :ref:`codec-controls`. * - ``V4L2_CTRL_CLASS_CAMERA`` - 0x9a0000 - The class containing camera controls. These controls are described @@ -358,6 +386,14 @@ still cause this situation. - 0xa20000 - The class containing RF tuner controls. These controls are described in :ref:`rf-tuner-controls`. + * - ``V4L2_CTRL_CLASS_DETECT`` + - 0xa30000 + - The class containing motion or object detection controls. These controls + are described in :ref:`detect-controls`. + * - ``V4L2_CTRL_CLASS_CODEC_STATELESS`` + - 0xa40000 + - The class containing stateless codec controls. These controls are + described in :ref:`codec-stateless-controls`. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst index 3138c4cc8fe3..dbcdd51dd2a8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst @@ -46,7 +46,7 @@ To select a video output applications store the number of the desired output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly -switch the current standard. standard. Because of these possible side +switch the current standard. Because of these possible side effects applications must select an output before querying or negotiating any other parameters. diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst index fbf8c5962d8a..77e0747a6d28 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst @@ -163,7 +163,7 @@ EINVAL The buffer ``type`` is not supported, or the ``index`` is out of bounds, or no buffers have been allocated yet, or the ``userptr`` or ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was - set but the the given ``request_fd`` was invalid, or ``m.fd`` was + set but the given ``request_fd`` was invalid, or ``m.fd`` was an invalid DMABUF file descriptor. EIO diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 9b8716f90f12..82f61f1e2fb8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -462,6 +462,12 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_FWHT_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT + parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_HEVC_SPS`` - n/a - n/a diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst index 4a05a105a9e6..24b34cdfa6fe 100644 --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst @@ -14,44 +14,260 @@ reconstructed by subtracting from the brightness component. See :ref:`colorspaces` for conversion examples. YUV was chosen because early television would only transmit brightness information. To add color in a way compatible with existing receivers a new signal carrier -was added to transmit the color difference signals. Secondary in the YUV -format the U and V components usually have lower resolution than the Y -component. This is an analog video compression technique taking -advantage of a property of the human visual system, being more sensitive -to brightness information. +was added to transmit the color difference signals. + + +Subsampling +=========== + +YUV formats commonly encode images with a lower resolution for the chroma +components than for the luma component. This compression technique, taking +advantage of the human eye being more sensitive to luminance than color +differences, is called chroma subsampling. + +While many combinations of subsampling factors in the horizontal and vertical +direction are possible, common factors are 1 (no subsampling), 2 and 4, with +horizontal subsampling always larger than or equal to vertical subsampling. +Common combinations are named as follows. + +- `4:4:4`: No subsampling +- `4:2:2`: Horizontal subsampling by 2, no vertical subsampling +- `4:2:0`: Horizontal subsampling by 2, vertical subsampling by 2 +- `4:1:1`: Horizontal subsampling by 4, no vertical subsampling +- `4:1:0`: Horizontal subsampling by 4, vertical subsampling by 4 + +Subsampling the chroma component effectively creates chroma values that can be +located in different spatial locations: + +- .. _yuv-chroma-centered: + + The subsampled chroma value may be calculated by simply averaging the chroma + value of two consecutive pixels. It effectively models the chroma of a pixel + sited between the two original pixels. This is referred to as centered or + interstitially sited chroma. + +- .. _yuv-chroma-cosited: + + The other option is to subsample chroma values in a way that place them in + the same spatial sites as the pixels. This may be performed by skipping every + other chroma sample (creating aliasing artifacts), or with filters using an + odd number of taps. This is referred to as co-sited chroma. + +The following examples show different combination of chroma siting in a 4x4 +image. + +.. flat-table:: 4:2:2 subsampling, interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - C + - Y + - + - Y + - C + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - C + - Y + - + - Y + - C + - Y + +.. flat-table:: 4:2:2 subsampling, co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 1 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 2 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 3 + - Y/C + - + - Y + - + - Y/C + - + - Y + +.. flat-table:: 4:2:0 subsampling, horizontally interstitially sited, vertically co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - + - Y + - + - Y + - + - Y + +.. flat-table:: 4:1:0 subsampling, horizontally and vertically interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - C + - + - + - + * - 2 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 3 + - Y + - + - Y + - + - Y + - + - Y .. toctree:: :maxdepth: 1 pixfmt-packed-yuv - pixfmt-grey - pixfmt-y10 - pixfmt-y12 - pixfmt-y14 - pixfmt-y10b - pixfmt-y10p - pixfmt-y16 - pixfmt-y16-be + pixfmt-yuv-planar + pixfmt-yuv-luma pixfmt-y8i pixfmt-y12i pixfmt-uv8 - pixfmt-yuyv - pixfmt-uyvy - pixfmt-yvyu - pixfmt-vyuy - pixfmt-y41p - pixfmt-yuv420 - pixfmt-yuv420m - pixfmt-yuv422m - pixfmt-yuv444m - pixfmt-yuv410 - pixfmt-yuv422p - pixfmt-yuv411p - pixfmt-nv12 - pixfmt-nv12m - pixfmt-nv12mt - pixfmt-nv16 - pixfmt-nv16m - pixfmt-nv24 pixfmt-m420 diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index 121e396a2779..0ed170c6e720 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -139,12 +139,14 @@ replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTIZATION :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PRED_WEIGHTS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 36d5f1f3c6dd..e00a66d72372 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6367,7 +6367,7 @@ accesses that would usually trigger a #GP by KVM into the guest will instead get bounced to user space through the KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. -8.25 KVM_X86_SET_MSR_FILTER +8.27 KVM_X86_SET_MSR_FILTER --------------------------- :Architectures: x86 @@ -6381,8 +6381,7 @@ In combination with KVM_CAP_X86_USER_SPACE_MSR, this allows user space to trap and emulate MSRs that are outside of the scope of KVM as well as limit the attack surface on KVM's MSR emulation code. - -8.26 KVM_CAP_ENFORCE_PV_CPUID +8.28 KVM_CAP_ENFORCE_PV_CPUID ----------------------------- Architectures: x86 diff --git a/Documentation/virt/kvm/cpuid.rst b/Documentation/virt/kvm/cpuid.rst index 7d81c0aa4a59..cf62162d4be2 100644 --- a/Documentation/virt/kvm/cpuid.rst +++ b/Documentation/virt/kvm/cpuid.rst @@ -92,6 +92,10 @@ KVM_FEATURE_ASYNC_PF_INT 14 guest checks this feature bit async pf acknowledgment msr 0x4b564d07. +KVM_FEATURE_MSI_EXT_DEST_ID 15 guest checks this feature bit + before using extended destination + ID bits in MSI address bits 11-5. + KVM_FEATURE_CLOCKSOURCE_STABLE_BIT 24 host will warn if no guest-side per-cpu warps are expected in kvmclock diff --git a/Documentation/virt/kvm/mmu.rst b/Documentation/virt/kvm/mmu.rst index 1c030dbac7c4..5bfe28b0728e 100644 --- a/Documentation/virt/kvm/mmu.rst +++ b/Documentation/virt/kvm/mmu.rst @@ -455,7 +455,7 @@ If the generation number of the spte does not equal the global generation number, it will ignore the cached MMIO information and handle the page fault through the slow path. -Since only 19 bits are used to store generation-number on mmio spte, all +Since only 18 bits are used to store generation-number on mmio spte, all pages are zapped when there is an overflow. Unfortunately, a single memory access might access kvm_memslots(kvm) multiple diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst index b224d12c880b..647a570d4931 100644 --- a/Documentation/x86/index.rst +++ b/Documentation/x86/index.rst @@ -33,3 +33,4 @@ x86-specific Documentation i386/index x86_64/index sva + sgx diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst new file mode 100644 index 000000000000..eaee1368b4fd --- /dev/null +++ b/Documentation/x86/sgx.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +Software Guard eXtensions (SGX) +=============================== + +Overview +======== + +Software Guard eXtensions (SGX) hardware enables for user space applications +to set aside private memory regions of code and data: + +* Privileged (ring-0) ENCLS functions orchestrate the construction of the. + regions. +* Unprivileged (ring-3) ENCLU functions allow an application to enter and + execute inside the regions. + +These memory regions are called enclaves. An enclave can be only entered at a +fixed set of entry points. Each entry point can hold a single hardware thread +at a time. While the enclave is loaded from a regular binary file by using +ENCLS functions, only the threads inside the enclave can access its memory. The +region is denied from outside access by the CPU, and encrypted before it leaves +from LLC. + +The support can be determined by + + ``grep sgx /proc/cpuinfo`` + +SGX must both be supported in the processor and enabled by the BIOS. If SGX +appears to be unsupported on a system which has hardware support, ensure +support is enabled in the BIOS. If a BIOS presents a choice between "Enabled" +and "Software Enabled" modes for SGX, choose "Enabled". + +Enclave Page Cache +================== + +SGX utilizes an *Enclave Page Cache (EPC)* to store pages that are associated +with an enclave. It is contained in a BIOS-reserved region of physical memory. +Unlike pages used for regular memory, pages can only be accessed from outside of +the enclave during enclave construction with special, limited SGX instructions. + +Only a CPU executing inside an enclave can directly access enclave memory. +However, a CPU executing inside an enclave may access normal memory outside the +enclave. + +The kernel manages enclave memory similar to how it treats device memory. + +Enclave Page Types +------------------ + +**SGX Enclave Control Structure (SECS)** + Enclave's address range, attributes and other global data are defined + by this structure. + +**Regular (REG)** + Regular EPC pages contain the code and data of an enclave. + +**Thread Control Structure (TCS)** + Thread Control Structure pages define the entry points to an enclave and + track the execution state of an enclave thread. + +**Version Array (VA)** + Version Array pages contain 512 slots, each of which can contain a version + number for a page evicted from the EPC. + +Enclave Page Cache Map +---------------------- + +The processor tracks EPC pages in a hardware metadata structure called the +*Enclave Page Cache Map (EPCM)*. The EPCM contains an entry for each EPC page +which describes the owning enclave, access rights and page type among the other +things. + +EPCM permissions are separate from the normal page tables. This prevents the +kernel from, for instance, allowing writes to data which an enclave wishes to +remain read-only. EPCM permissions may only impose additional restrictions on +top of normal x86 page permissions. + +For all intents and purposes, the SGX architecture allows the processor to +invalidate all EPCM entries at will. This requires that software be prepared to +handle an EPCM fault at any time. In practice, this can happen on events like +power transitions when the ephemeral key that encrypts enclave memory is lost. + +Application interface +===================== + +Enclave build functions +----------------------- + +In addition to the traditional compiler and linker build process, SGX has a +separate enclave “build” process. Enclaves must be built before they can be +executed (entered). The first step in building an enclave is opening the +**/dev/sgx_enclave** device. Since enclave memory is protected from direct +access, special privileged instructions are Then used to copy data into enclave +pages and establish enclave page permissions. + +.. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c + :functions: sgx_ioc_enclave_create + sgx_ioc_enclave_add_pages + sgx_ioc_enclave_init + sgx_ioc_enclave_provision + +Enclave vDSO +------------ + +Entering an enclave can only be done through SGX-specific EENTER and ERESUME +functions, and is a non-trivial process. Because of the complexity of +transitioning to and from an enclave, enclaves typically utilize a library to +handle the actual transitions. This is roughly analogous to how glibc +implementations are used by most applications to wrap system calls. + +Another crucial characteristic of enclaves is that they can generate exceptions +as part of their normal operation that need to be handled in the enclave or are +unique to SGX. + +Instead of the traditional signal mechanism to handle these exceptions, SGX +can leverage special exception fixup provided by the vDSO. The kernel-provided +vDSO function wraps low-level transitions to/from the enclave like EENTER and +ERESUME. The vDSO function intercepts exceptions that would otherwise generate +a signal and return the fault information directly to its caller. This avoids +the need to juggle signal handlers. + +.. kernel-doc:: arch/x86/include/uapi/asm/sgx.h + :functions: vdso_sgx_enter_enclave_t + +ksgxd +===== + +SGX support includes a kernel thread called *ksgxwapd*. + +EPC sanitization +---------------- + +ksgxd is started when SGX initializes. Enclave memory is typically ready +For use when the processor powers on or resets. However, if SGX has been in +use since the reset, enclave pages may be in an inconsistent state. This might +occur after a crash and kexec() cycle, for instance. At boot, ksgxd +reinitializes all enclave pages so that they can be allocated and re-used. + +The sanitization is done by going through EPC address space and applying the +EREMOVE function to each physical page. Some enclave pages like SECS pages have +hardware dependencies on other pages which prevents EREMOVE from functioning. +Executing two EREMOVE passes removes the dependencies. + +Page reclaimer +-------------- + +Similar to the core kswapd, ksgxd, is responsible for managing the +overcommitment of enclave memory. If the system runs out of enclave memory, +*ksgxwapd* “swaps” enclave memory to normal memory. + +Launch Control +============== + +SGX provides a launch control mechanism. After all enclave pages have been +copied, kernel executes EINIT function, which initializes the enclave. Only after +this the CPU can execute inside the enclave. + +ENIT function takes an RSA-3072 signature of the enclave measurement. The function +checks that the measurement is correct and signature is signed with the key +hashed to the four **IA32_SGXLEPUBKEYHASH{0, 1, 2, 3}** MSRs representing the +SHA256 of a public key. + +Those MSRs can be configured by the BIOS to be either readable or writable. +Linux supports only writable configuration in order to give full control to the +kernel on launch control policy. Before calling EINIT function, the driver sets +the MSRs to match the enclave's signing key. + +Encryption engines +================== + +In order to conceal the enclave data while it is out of the CPU package, the +memory controller has an encryption engine to transparently encrypt and decrypt +enclave memory. + +In CPUs prior to Ice Lake, the Memory Encryption Engine (MEE) is used to +encrypt pages leaving the CPU caches. MEE uses a n-ary Merkle tree with root in +SRAM to maintain integrity of the encrypted data. This provides integrity and +anti-replay protection but does not scale to large memory sizes because the time +required to update the Merkle tree grows logarithmically in relation to the +memory size. + +CPUs starting from Icelake use Total Memory Encryption (TME) in the place of +MEE. TME-based SGX implementations do not have an integrity Merkle tree, which +means integrity and replay-attacks are not mitigated. B, it includes +additional changes to prevent cipher text from being returned and SW memory +aliases from being Created. + +DMA to enclave memory is blocked by range registers on both MEE and TME systems +(SDM section 41.10). + +Usage Models +============ + +Shared Library +-------------- + +Sensitive data and the code that acts on it is partitioned from the application +into a separate library. The library is then linked as a DSO which can be loaded +into an enclave. The application can then make individual function calls into +the enclave through special SGX instructions. A run-time within the enclave is +configured to marshal function parameters into and out of the enclave and to +call the correct library function. + +Application Container +--------------------- + +An application may be loaded into a container enclave which is specially +configured with a library OS and run-time which permits the application to run. +The enclave run-time and library OS work together to execute the application +when a thread enters the enclave. diff --git a/Documentation/x86/topology.rst b/Documentation/x86/topology.rst index e29739904e37..7f58010ea86a 100644 --- a/Documentation/x86/topology.rst +++ b/Documentation/x86/topology.rst @@ -41,6 +41,8 @@ Package Packages contain a number of cores plus shared resources, e.g. DRAM controller, shared caches etc. +Modern systems may also use the term 'Die' for package. + AMD nomenclature for package is 'Node'. Package-related topology information in the kernel: @@ -53,11 +55,18 @@ Package-related topology information in the kernel: The number of dies in a package. This information is retrieved via CPUID. + - cpuinfo_x86.cpu_die_id: + + The physical ID of the die. This information is retrieved via CPUID. + - cpuinfo_x86.phys_proc_id: The physical ID of the package. This information is retrieved via CPUID and deduced from the APIC IDs of the cores in the package. + Modern systems use this value for the socket. There may be multiple + packages within a socket. This value may differ from cpu_die_id. + - cpuinfo_x86.logical_proc_id: The logical ID of the package. As we do not trust BIOSes to enumerate the diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst index e52a12960fdc..450573afa31a 100644 --- a/Documentation/xtensa/mmu.rst +++ b/Documentation/xtensa/mmu.rst @@ -82,7 +82,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0xc8000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE @@ -124,7 +125,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0xa8000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE @@ -167,7 +169,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0x98000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE |