diff options
| author | Jiri Kosina <jkosina@suse.cz> | 2020-12-16 11:41:05 +0100 |
|---|---|---|
| committer | Jiri Kosina <jkosina@suse.cz> | 2020-12-16 11:41:05 +0100 |
| commit | e77bc7dc9af0ec53996367b2053dfafee83b7edb (patch) | |
| tree | 7850cb0cc9e0d7308992b2b983052c5f209245bd /Documentation | |
| parent | 105856b36c0cefc2fa1c1e649d75da71e2e38c31 (diff) | |
| parent | 82514ecd61435c2d47c235e1343872b38db17be4 (diff) | |
Merge branch 'for-5.11/elecom' into for-linus
- support for EX-G M-XGL20DLBK device, from YOSHIOKA Takuma
Diffstat (limited to 'Documentation')
865 files changed, 12589 insertions, 7065 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 96dfe1926b76..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 @@ -258,33 +261,18 @@ Description: userspace ABI compatibility of umad & issm devices. -What: /sys/class/infiniband_cm/ucmN/ibdev -Date: Oct, 2005 -KernelVersion: v2.6.14 -Contact: linux-rdma@vger.kernel.org -Description: - (RO) Display Infiniband (IB) device name - - -What: /sys/class/infiniband_cm/abi_version -Date: Oct, 2005 -KernelVersion: v2.6.14 -Contact: linux-rdma@vger.kernel.org -Description: - (RO) Value is incremented if any changes are made that break - userspace ABI compatibility of ucm devices. - - What: /sys/class/infiniband_verbs/uverbsN/ibdev What: /sys/class/infiniband_verbs/uverbsN/abi_version 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 @@ -306,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) @@ -324,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> @@ -354,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 @@ -382,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 @@ -393,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). @@ -415,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 @@ -423,6 +420,7 @@ Description: board_id: (RO) Manufacturing board id. (Vendor + device information) + =============== ============================================= sysfs interface for Intel IB driver qib @@ -443,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. @@ -469,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] @@ -488,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 @@ -508,6 +510,7 @@ Contact: linux-rdma@vger.kernel.org Description: [to be documented] + =============== =============================================== loopback: (WO) led_override: (WO) hrtbt_enable: (RW) @@ -518,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 @@ -566,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 @@ -578,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 @@ -622,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 @@ -640,6 +647,7 @@ Description: available. tempsense: (RO) Thermal sense information + =============== ============================================= What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin @@ -651,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] @@ -672,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 @@ -687,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 @@ -728,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 @@ -745,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 @@ -761,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 @@ -777,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 e82fc37be802..de390a010af8 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -1,3 +1,28 @@ +What: /sys/bus/event_source/devices/hv_24x7/format +Date: September 2020 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: Read-only. Attribute group to describe the magic bits + that go into perf_event_attr.config for a particular pmu. + (See ABI/testing/sysfs-bus-event_source-devices-format). + + Each attribute under this group defines a bit range of the + perf_event_attr.config. All supported attributes are listed + below:: + + chip = "config:16-31" + core = "config:16-31" + domain = "config:0-3" + lpar = "config:0-15" + offset = "config:32-63" + vcpu = "config:16-31" + + For example:: + + 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. + What: /sys/bus/event_source/devices/hv_24x7/interface/catalog Date: February 2014 Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> 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 3ca4e554d2f9..12e2bf92783f 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci @@ -1,3 +1,34 @@ +What: /sys/bus/event_source/devices/hv_gpci/format +Date: September 2020 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: Read-only. Attribute group to describe the magic bits + that go into perf_event_attr.config for a particular pmu. + (See ABI/testing/sysfs-bus-event_source-devices-format). + + Each attribute under this group defines a bit range of the + perf_event_attr.config. All supported attributes are listed + below:: + + counter_info_version = "config:16-23" + length = "config:24-31" + partition_id = "config:32-63" + request = "config:0-31" + sibling_part_id = "config:32-63" + hw_chip_id = "config:32-63" + offset = "config:32-63" + phys_processor_idx = "config:32-63" + secondary_index = "config:0-15" + starting_index = "config:32-63" + + For example:: + + processor_core_utilization_instructions_completed = "request=0x94, + phys_processor_idx=?,counter_info_version=0x8, + length=8,offset=0x18" + + In this event, '?' after phys_processor_idx specifies this value + this value will be provided by user while running this event. + What: /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged Date: February 2014 Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> @@ -5,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 @@ -41,3 +73,10 @@ Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: A number indicating the latest version of the gpci interface that the kernel is aware of. + +What: /sys/devices/hv_gpci/cpumask +Date: October 2020 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: read only + This sysfs file exposes the cpumask which is designated to make + HCALLs to retrieve hv-gpci pmu event counter data. 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 40213c73bc9c..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 @@ -34,16 +34,240 @@ Description: Describes the main type of the supply. Access: Read - Valid values: "Battery", "UPS", "Mains", "USB" + 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,38 +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 -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 + Valid values: + "Unknown", "Critical", "Low", "Normal", "High", + "Full" What: /sys/class/power_supply/<supply_name>/charge_control_limit Date: Oct 2012 @@ -137,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 @@ -146,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 @@ -166,6 +367,7 @@ Description: stop. Access: Read, Write + Valid values: 0 - 100 (percent) What: /sys/class/power_supply/<supply_name>/charge_type @@ -181,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 @@ -192,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 @@ -202,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", @@ -216,6 +423,7 @@ Description: for a battery charge cycle. Access: Read + Valid values: Represented in microamps What: /sys/class/power_supply/<supply_name>/present @@ -225,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 @@ -238,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 @@ -248,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 @@ -318,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 @@ -397,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 @@ -414,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 @@ -427,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, @@ -439,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 @@ -512,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 @@ -579,6 +596,7 @@ Description: will drop to 0 A) and will trigger interrupt. Valid values: + - 5, 6 or 7 (hours), - 0: disabled. @@ -593,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. @@ -607,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. @@ -622,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 @@ -635,6 +656,7 @@ Description: device datasheet for details. Valid values: + - 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000, 10500000 (all uV) @@ -650,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) @@ -664,6 +687,7 @@ Description: the charger operates normally. See device datasheet for details. Valid values: + - 1: enabled - 0: disabled @@ -679,6 +703,7 @@ Description: from the system. See device datasheet for details. Valid values: + - 1: enabled - 0: disabled @@ -690,6 +715,7 @@ Description: manufactured. Access: Read + Valid values: Reported as integer What: /sys/class/power_supply/<supply_name>/manufacture_month @@ -699,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 36094fbeb974..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, @@ -58,3 +58,47 @@ Description: Remote processor name Reports the name of the remote processor. This can be used by userspace in exactly identifying a remote processor and ease up the usage in modifying the 'firmware' or 'state' files. + +What: /sys/class/remoteproc/.../coredump +Date: July 2020 +Contact: Bjorn Andersson <bjorn.andersson@linaro.org>, Ohad Ben-Cohen <ohad@wizery.com> +Description: Remote processor coredump configuration + + Reports the coredump configuration of the remote processor, + which will be one of: + + "disabled" + "enabled" + "inline" + + "disabled" means no dump will be collected. + + "enabled" means when the remote processor's coredump is + collected it will be copied to a separate buffer and that + buffer is exposed to userspace. + + "inline" means when the remote processor's coredump is + collected userspace will directly read from the remote + processor's device memory. Extra buffer will not be used to + copy the dump. Also recovery process will not proceed until + all data is read by usersapce. + +What: /sys/class/remoteproc/.../recovery +Date: July 2020 +Contact: Bjorn Andersson <bjorn.andersson@linaro.org>, Ohad Ben-Cohen <ohad@wizery.com> +Description: Remote processor recovery mechanism + + Reports the recovery mechanism of the remote processor, + which will be one of: + + "enabled" + "disabled" + + "enabled" means, the remote processor will be automatically + recovered whenever it crashes. Moreover, if the remote + processor crashes while recovery is disabled, it will + be automatically recovered too as soon as recovery is enabled. + + "disabled" means, a remote processor will remain in a crashed + state if it crashes. This is useful for debugging purposes; + without it, debugging a crash is substantially harder. 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-driver-xen-blkback b/Documentation/ABI/testing/sysfs-driver-xen-blkback index ecb7942ff146..ac2947b98950 100644 --- a/Documentation/ABI/testing/sysfs-driver-xen-blkback +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkback @@ -35,3 +35,12 @@ Description: controls the duration in milliseconds that blkback will not cache any page not backed by a grant mapping. The default is 10ms. + +What: /sys/module/xen_blkback/parameters/feature_persistent +Date: September 2020 +KernelVersion: 5.10 +Contact: SeongJae Park <sjpark@amazon.de> +Description: + Whether to enable the persistent grants feature or not. Note + that this option only takes effect on newly created backends. + The default is Y (enable). diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkfront b/Documentation/ABI/testing/sysfs-driver-xen-blkfront index c0a6cb7eb314..28008905615f 100644 --- a/Documentation/ABI/testing/sysfs-driver-xen-blkfront +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkfront @@ -1,4 +1,4 @@ -What: /sys/module/xen_blkfront/parameters/max +What: /sys/module/xen_blkfront/parameters/max_indirect_segments Date: June 2013 KernelVersion: 3.11 Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> @@ -8,3 +8,12 @@ Description: is 32 - higher value means more potential throughput but more memory usage. The backend picks the minimum of the frontend and its default backend value. + +What: /sys/module/xen_blkfront/parameters/feature_persistent +Date: September 2020 +KernelVersion: 5.10 +Contact: SeongJae Park <sjpark@amazon.de> +Description: + Whether to enable the persistent grants feature or not. Note + that this option only takes effect on newly created frontends. + The default is Y (enable). 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..66800baab096 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv @@ -5,7 +5,7 @@ Description: The /sys/firmware/sgi_uv directory contains information about the SGI UV platform. - Under that directory are a number of files: + Under that directory are a number of files:: partition_id coherence_id @@ -14,7 +14,7 @@ Description: SGI 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: + partition id. To display the partition id, use the command:: cat /sys/firmware/sgi_uv/partition_id @@ -22,6 +22,6 @@ Description: 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: + command:: cat /sys/firmware/sgi_uv/coherence_id 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 7f730c4c8df2..67b3ed8e8c2f 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -20,9 +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 = 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 @@ -45,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 @@ -331,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/RCU/Design/Data-Structures/Data-Structures.rst b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst index 4a48e20a46f2..f4efd6897b09 100644 --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst @@ -963,7 +963,7 @@ exit and perhaps also vice versa. Therefore, whenever the ``->dynticks_nesting`` field is incremented up from zero, the ``->dynticks_nmi_nesting`` field is set to a large positive number, and whenever the ``->dynticks_nesting`` field is decremented down to zero, -the the ``->dynticks_nmi_nesting`` field is set to zero. Assuming that +the ``->dynticks_nmi_nesting`` field is set to zero. Assuming that the number of misnested interrupts is not sufficient to overflow the counter, this approach corrects the ``->dynticks_nmi_nesting`` field every time the corresponding CPU enters the idle loop from process diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 8f41ad0aa753..1ae79a10a8de 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -2162,7 +2162,7 @@ scheduling-clock interrupt be enabled when RCU needs it to be: this sort of thing. #. If a CPU is in a portion of the kernel that is absolutely positively no-joking guaranteed to never execute any RCU read-side critical - sections, and RCU believes this CPU to to be idle, no problem. This + sections, and RCU believes this CPU to be idle, no problem. This sort of thing is used by some architectures for light-weight exception handlers, which can then avoid the overhead of ``rcu_irq_enter()`` and ``rcu_irq_exit()`` at exception entry and @@ -2431,7 +2431,7 @@ However, there are legitimate preemptible-RCU implementations that do not have this property, given that any point in the code outside of an RCU read-side critical section can be a quiescent state. Therefore, *RCU-sched* was created, which follows “classic” RCU in that an -RCU-sched grace period waits for for pre-existing interrupt and NMI +RCU-sched grace period waits for pre-existing interrupt and NMI handlers. In kernels built with ``CONFIG_PREEMPT=n``, the RCU and RCU-sched APIs have identical implementations, while kernels built with ``CONFIG_PREEMPT=y`` provide a separate implementation for each. diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index c7f147b8034f..fb3ff76c3e73 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -360,7 +360,7 @@ order to amortize their overhead over many uses of the corresponding APIs. There are at least three flavors of RCU usage in the Linux kernel. The diagram above shows the most common one. On the updater side, the rcu_assign_pointer(), -sychronize_rcu() and call_rcu() primitives used are the same for all three +synchronize_rcu() and call_rcu() primitives used are the same for all three flavors. However for protection (on the reader side), the primitives used vary depending on the flavor: diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 7bff07ce4fdd..0ec34863c674 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -3,9 +3,9 @@ SafeSetID ========= SafeSetID is an LSM module that gates the setid family of syscalls to restrict UID/GID transitions from a given UID/GID to only those approved by a -system-wide whitelist. These restrictions also prohibit the given UIDs/GIDs +system-wide allowlist. These restrictions also prohibit the given UIDs/GIDs from obtaining auxiliary privileges associated with CAP_SET{U/G}ID, such as -allowing a user to set up user namespace UID mappings. +allowing a user to set up user namespace UID/GID mappings. Background @@ -98,10 +98,21 @@ Directions for use ================== This LSM hooks the setid syscalls to make sure transitions are allowed if an applicable restriction policy is in place. Policies are configured through -securityfs by writing to the safesetid/add_whitelist_policy and -safesetid/flush_whitelist_policies files at the location where securityfs is -mounted. The format for adding a policy is '<UID>:<UID>', using literal -numbers, such as '123:456'. To flush the policies, any write to the file is -sufficient. Again, configuring a policy for a UID will prevent that UID from -obtaining auxiliary setid privileges, such as allowing a user to set up user -namespace UID mappings. +securityfs by writing to the safesetid/uid_allowlist_policy and +safesetid/gid_allowlist_policy files at the location where securityfs is +mounted. The format for adding a policy is '<UID>:<UID>' or '<GID>:<GID>', +using literal numbers, and ending with a newline character such as '123:456\n'. +Writing an empty string "" will flush the policy. Again, configuring a policy +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 +setgroups() calls for processes with CAP_SETGID restrictions. Until we add +support in a future release for restricting setgroups() calls, these GID +policies add no meaningful security. setgroups() restrictions will be enforced +once we have the policy checking code in place, which will rely on GID policy +configuration code added in v5.9. 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/cpu-load.rst b/Documentation/admin-guide/cpu-load.rst index ebdecf864080..f3ada90e9ca8 100644 --- a/Documentation/admin-guide/cpu-load.rst +++ b/Documentation/admin-guide/cpu-load.rst @@ -61,43 +61,46 @@ will lead to quite erratic information inside ``/proc/stat``:: static volatile sig_atomic_t stop; - static void sighandler (int signr) + static void sighandler(int signr) { - (void) signr; - stop = 1; + (void) signr; + stop = 1; } + static unsigned long hog (unsigned long niters) { - stop = 0; - while (!stop && --niters); - return niters; + stop = 0; + while (!stop && --niters); + return niters; } + int main (void) { - int i; - struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 }, - .it_value = { .tv_sec = 0, .tv_usec = 1 } }; - sigset_t set; - unsigned long v[HIST]; - double tmp = 0.0; - unsigned long n; - signal (SIGALRM, &sighandler); - setitimer (ITIMER_REAL, &it, NULL); - - hog (ULONG_MAX); - for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX); - for (i = 0; i < HIST; ++i) tmp += v[i]; - tmp /= HIST; - n = tmp - (tmp / 3.0); - - sigemptyset (&set); - sigaddset (&set, SIGALRM); - - for (;;) { - hog (n); - sigwait (&set, &i); - } - return 0; + int i; + struct itimerval it = { + .it_interval = { .tv_sec = 0, .tv_usec = 1 }, + .it_value = { .tv_sec = 0, .tv_usec = 1 } }; + sigset_t set; + unsigned long v[HIST]; + double tmp = 0.0; + unsigned long n; + signal(SIGALRM, &sighandler); + setitimer(ITIMER_REAL, &it, NULL); + + hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog(ULONG_MAX); + for (i = 0; i < HIST; ++i) tmp += v[i]; + tmp /= HIST; + n = tmp - (tmp / 3.0); + + sigemptyset(&set); + sigaddset(&set, SIGALRM); + + for (;;) { + hog(n); + sigwait(&set, &i); + } + return 0; } 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 f7ac0e663976..44fde25bb221 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1343,12 +1343,18 @@ current integrity status. failslab= + fail_usercopy= fail_page_alloc= fail_make_request=[KNL] General fault injection mechanism. Format: <interval>,<probability>,<space>,<times> See also Documentation/fault-injection/. + fb_tunnels= [NET] + Format: { initns | none } + See Documentation/admin-guide/sysctl/net.rst for + fb_tunnels_only_for_init_ns + floppy= [HW] See Documentation/admin-guide/blockdev/floppy.rst. @@ -2852,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 @@ -3089,6 +3097,10 @@ and gids from such clients. This is intended to ease migration from NFSv2/v3. + nmi_backtrace.backtrace_idle [KNL] + Dump stacks even of idle CPUs in response to an + NMI stack-backtrace request. + nmi_debug= [KNL,SH] Specify one or more actions to take when a NMI is triggered. Format: [state][,regs][,debounce][,die] @@ -3176,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] @@ -3225,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. @@ -4168,46 +4185,55 @@ This wake_up() will be accompanied by a WARN_ONCE() splat and an ftrace_dump(). + rcutree.rcu_unlock_delay= [KNL] + In CONFIG_RCU_STRICT_GRACE_PERIOD=y kernels, + this specifies an rcu_read_unlock()-time delay + in microseconds. This defaults to zero. + Larger delays increase the probability of + catching RCU pointer leaks, that is, buggy use + of RCU-protected pointers after the relevant + rcu_read_unlock() has completed. + rcutree.sysrq_rcu= [KNL] Commandeer a sysrq key to dump out Tree RCU's rcu_node tree with an eye towards determining why a new grace period has not yet started. - rcuperf.gp_async= [KNL] + rcuscale.gp_async= [KNL] Measure performance of asynchronous grace-period primitives such as call_rcu(). - rcuperf.gp_async_max= [KNL] + rcuscale.gp_async_max= [KNL] Specify the maximum number of outstanding callbacks per writer thread. When a writer thread exceeds this limit, it invokes the corresponding flavor of rcu_barrier() to allow previously posted callbacks to drain. - rcuperf.gp_exp= [KNL] + rcuscale.gp_exp= [KNL] Measure performance of expedited synchronous grace-period primitives. - rcuperf.holdoff= [KNL] + rcuscale.holdoff= [KNL] Set test-start holdoff period. The purpose of this parameter is to delay the start of the test until boot completes in order to avoid interference. - rcuperf.kfree_rcu_test= [KNL] + rcuscale.kfree_rcu_test= [KNL] Set to measure performance of kfree_rcu() flooding. - rcuperf.kfree_nthreads= [KNL] + rcuscale.kfree_nthreads= [KNL] The number of threads running loops of kfree_rcu(). - rcuperf.kfree_alloc_num= [KNL] + rcuscale.kfree_alloc_num= [KNL] Number of allocations and frees done in an iteration. - rcuperf.kfree_loops= [KNL] - Number of loops doing rcuperf.kfree_alloc_num number + rcuscale.kfree_loops= [KNL] + Number of loops doing rcuscale.kfree_alloc_num number of allocations and frees. - rcuperf.nreaders= [KNL] + rcuscale.nreaders= [KNL] Set number of RCU readers. The value -1 selects N, where N is the number of CPUs. A value "n" less than -1 selects N-n+1, where N is again @@ -4216,23 +4242,23 @@ A value of "n" less than or equal to -N selects a single reader. - rcuperf.nwriters= [KNL] + rcuscale.nwriters= [KNL] Set number of RCU writers. The values operate - the same as for rcuperf.nreaders. + the same as for rcuscale.nreaders. N, where N is the number of CPUs - rcuperf.perf_type= [KNL] + rcuscale.perf_type= [KNL] Specify the RCU implementation to test. - rcuperf.shutdown= [KNL] + rcuscale.shutdown= [KNL] Shut the system down after performance tests complete. This is useful for hands-off automated testing. - rcuperf.verbose= [KNL] + rcuscale.verbose= [KNL] Enable additional printk() statements. - rcuperf.writer_holdoff= [KNL] + rcuscale.writer_holdoff= [KNL] Write-side holdoff between grace periods, in microseconds. The default of zero says no holdoff. @@ -4285,6 +4311,18 @@ are zero, rcutorture acts as if is interpreted they are all non-zero. + rcutorture.irqreader= [KNL] + Run RCU readers from irq handlers, or, more + accurately, from a timer handler. Not all RCU + flavors take kindly to this sort of thing. + + rcutorture.leakpointer= [KNL] + Leak an RCU-protected pointer out of the reader. + This can of course result in splats, and is + intended to test the ability of things like + CONFIG_RCU_STRICT_GRACE_PERIOD=y to detect + such leaks. + rcutorture.n_barrier_cbs= [KNL] Set callbacks/threads for rcu_barrier() testing. @@ -4506,8 +4544,8 @@ refscale.shutdown= [KNL] Shut down the system at the end of the performance test. This defaults to 1 (shut it down) when - rcuperf is built into the kernel and to 0 (leave - it running) when rcuperf is built as a module. + refscale is built into the kernel and to 0 (leave + it running) when refscale is built as a module. refscale.verbose= [KNL] Enable additional printk() statements. @@ -4653,6 +4691,98 @@ Format: integer between 0 and 10 Default is 0. + scftorture.holdoff= [KNL] + Number of seconds to hold off before starting + test. Defaults to zero for module insertion and + to 10 seconds for built-in smp_call_function() + tests. + + scftorture.longwait= [KNL] + Request ridiculously long waits randomly selected + up to the chosen limit in seconds. Zero (the + default) disables this feature. Please note + that requesting even small non-zero numbers of + seconds can result in RCU CPU stall warnings, + softlockup complaints, and so on. + + scftorture.nthreads= [KNL] + Number of kthreads to spawn to invoke the + smp_call_function() family of functions. + The default of -1 specifies a number of kthreads + equal to the number of CPUs. + + scftorture.onoff_holdoff= [KNL] + Number seconds to wait after the start of the + test before initiating CPU-hotplug operations. + + scftorture.onoff_interval= [KNL] + Number seconds to wait between successive + CPU-hotplug operations. Specifying zero (which + is the default) disables CPU-hotplug operations. + + scftorture.shutdown_secs= [KNL] + The number of seconds following the start of the + test after which to shut down the system. The + default of zero avoids shutting down the system. + Non-zero values are useful for automated tests. + + scftorture.stat_interval= [KNL] + The number of seconds between outputting the + current test statistics to the console. A value + of zero disables statistics output. + + scftorture.stutter_cpus= [KNL] + The number of jiffies to wait between each change + to the set of CPUs under test. + + scftorture.use_cpus_read_lock= [KNL] + Use use_cpus_read_lock() instead of the default + preempt_disable() to disable CPU hotplug + while invoking one of the smp_call_function*() + functions. + + scftorture.verbose= [KNL] + Enable additional printk() statements. + + scftorture.weight_single= [KNL] + The probability weighting to use for the + smp_call_function_single() function with a zero + "wait" parameter. A value of -1 selects the + default if all other weights are -1. However, + if at least one weight has some other value, a + value of -1 will instead select a weight of zero. + + scftorture.weight_single_wait= [KNL] + The probability weighting to use for the + smp_call_function_single() function with a + non-zero "wait" parameter. See weight_single. + + scftorture.weight_many= [KNL] + The probability weighting to use for the + smp_call_function_many() function with a zero + "wait" parameter. See weight_single. + Note well that setting a high probability for + this weighting can place serious IPI load + on the system. + + scftorture.weight_many_wait= [KNL] + The probability weighting to use for the + smp_call_function_many() function with a + non-zero "wait" parameter. See weight_single + and weight_many. + + scftorture.weight_all= [KNL] + The probability weighting to use for the + smp_call_function_all() function with a zero + "wait" parameter. See weight_single and + weight_many. + + scftorture.weight_all_wait= [KNL] + The probability weighting to use for the + smp_call_function_all() function with a + non-zero "wait" parameter. See weight_single + and weight_many. + skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate xtime_lock contention on larger systems, and/or RCU lock contention on all systems with CONFIG_MAXSMP set. @@ -5847,6 +5977,21 @@ improve timer resolution at the expense of processing more timer interrupts. + xen.event_eoi_delay= [XEN] + How long to delay EOI handling in case of event + storms (jiffies). Default is 10. + + xen.event_loop_timeout= [XEN] + After which time (jiffies) the event handling loop + should start to delay EOI handling. Default is 2. + + xen.fifo_events= [XEN] + Boolean parameter to disable using fifo event handling + even if available. Normally fifo event handling is + preferred over the 2-level event handling, as it is + fairer and the number of possible event channels is + much higher. Default is on (use fifo events). + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] Disables the PV optimizations forcing the guest to run as generic guest with no PV drivers. Currently support diff --git a/Documentation/admin-guide/nfs/fault_injection.rst b/Documentation/admin-guide/nfs/fault_injection.rst deleted file mode 100644 index eb029c0c15ce..000000000000 --- a/Documentation/admin-guide/nfs/fault_injection.rst +++ /dev/null @@ -1,70 +0,0 @@ -=================== -NFS Fault Injection -=================== - -Fault injection is a method for forcing errors that may not normally occur, or -may be difficult to reproduce. Forcing these errors in a controlled environment -can help the developer find and fix bugs before their code is shipped in a -production system. Injecting an error on the Linux NFS server will allow us to -observe how the client reacts and if it manages to recover its state correctly. - -NFSD_FAULT_INJECTION must be selected when configuring the kernel to use this -feature. - - -Using Fault Injection -===================== -On the client, mount the fault injection server through NFS v4.0+ and do some -work over NFS (open files, take locks, ...). - -On the server, mount the debugfs filesystem to <debug_dir> and ls -<debug_dir>/nfsd. This will show a list of files that will be used for -injecting faults on the NFS server. As root, write a number n to the file -corresponding to the action you want the server to take. The server will then -process the first n items it finds. So if you want to forget 5 locks, echo '5' -to <debug_dir>/nfsd/forget_locks. A value of 0 will tell the server to forget -all corresponding items. A log message will be created containing the number -of items forgotten (check dmesg). - -Go back to work on the client and check if the client recovered from the error -correctly. - - -Available Faults -================ -forget_clients: - The NFS server keeps a list of clients that have placed a mount call. If - this list is cleared, the server will have no knowledge of who the client - is, forcing the client to reauthenticate with the server. - -forget_openowners: - The NFS server keeps a list of what files are currently opened and who - they were opened by. Clearing this list will force the client to reopen - its files. - -forget_locks: - The NFS server keeps a list of what files are currently locked in the VFS. - Clearing this list will force the client to reclaim its locks (files are - unlocked through the VFS as they are cleared from this list). - -forget_delegations: - A delegation is used to assure the client that a file, or part of a file, - has not changed since the delegation was awarded. Clearing this list will - force the client to reacquire its delegation before accessing the file - again. - -recall_delegations: - Delegations can be recalled by the server when another client attempts to - access a file. This test will notify the client that its delegation has - been revoked, forcing the client to reacquire the delegation before using - the file again. - - -tools/nfs/inject_faults.sh script -================================= -This script has been created to ease the fault injection process. This script -will detect the mounted debugfs directory and write to the files located there -based on the arguments passed by the user. For example, running -`inject_faults.sh forget_locks 1` as root will instruct the server to forget -one lock. Running `inject_faults forget_locks` will instruct the server to -forgetall locks. diff --git a/Documentation/admin-guide/nfs/index.rst b/Documentation/admin-guide/nfs/index.rst index 6b5a3c90fac5..3601a708f333 100644 --- a/Documentation/admin-guide/nfs/index.rst +++ b/Documentation/admin-guide/nfs/index.rst @@ -12,4 +12,3 @@ NFS nfs-idmapper pnfs-block-server pnfs-scsi-server - fault_injection diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst index 368e612145d2..6adb7988e0eb 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -1,7 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> -.. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>` .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>` ======================= @@ -92,16 +91,16 @@ control the P-state of multiple CPUs at the same time and writing to it affects all of those CPUs simultaneously. Sets of CPUs sharing hardware P-state control interfaces are represented by -``CPUFreq`` as |struct cpufreq_policy| objects. For consistency, -|struct cpufreq_policy| is also used when there is only one CPU in the given +``CPUFreq`` as struct cpufreq_policy objects. For consistency, +struct cpufreq_policy is also used when there is only one CPU in the given set. -The ``CPUFreq`` core maintains a pointer to a |struct cpufreq_policy| object for +The ``CPUFreq`` core maintains a pointer to a struct cpufreq_policy object for every CPU in the system, including CPUs that are currently offline. If multiple CPUs share the same hardware P-state control interface, all of the pointers -corresponding to them point to the same |struct cpufreq_policy| object. +corresponding to them point to the same struct cpufreq_policy object. -``CPUFreq`` uses |struct cpufreq_policy| as its basic data type and the design +``CPUFreq`` uses struct cpufreq_policy as its basic data type and the design of its user space interface is based on the policy concept. 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/pstore-blk.rst b/Documentation/admin-guide/pstore-blk.rst index 296d5027787a..6898aba9fb5c 100644 --- a/Documentation/admin-guide/pstore-blk.rst +++ b/Documentation/admin-guide/pstore-blk.rst @@ -154,17 +154,11 @@ Configurations for driver Only a block device driver cares about these configurations. A block device driver uses ``register_pstore_blk`` to register to pstore/blk. -.. kernel-doc:: fs/pstore/blk.c - :identifiers: register_pstore_blk - A non-block device driver uses ``register_pstore_device`` with ``struct pstore_device_info`` to register to pstore/blk. .. kernel-doc:: fs/pstore/blk.c - :identifiers: register_pstore_device - -.. kernel-doc:: include/linux/pstore_blk.h - :identifiers: pstore_device_info + :export: Compression and header ---------------------- @@ -237,7 +231,7 @@ For developer reference, here are all the important structures and APIs: :internal: .. kernel-doc:: fs/pstore/blk.c - :export: + :internal: .. kernel-doc:: include/linux/pstore_blk.h :internal: diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 42cd04bca548..f2ab8a5b6a4b 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -321,11 +321,20 @@ fb_tunnels_only_for_init_net ---------------------------- Controls if fallback tunnels (like tunl0, gre0, gretap0, erspan0, -sit0, ip6tnl0, ip6gre0) are automatically created when a new -network namespace is created, if corresponding tunnel is present -in initial network namespace. -If set to 1, these devices are not automatically created, and -user space is responsible for creating them if needed. +sit0, ip6tnl0, ip6gre0) are automatically created. There are 3 possibilities +(a) value = 0; respective fallback tunnels are created when module is +loaded in every net namespaces (backward compatible behavior). +(b) value = 1; [kcmd value: initns] respective fallback tunnels are +created only in init net namespace and every other net namespace will +not have them. +(c) value = 2; [kcmd value: none] fallback tunnels are not created +when a module is loaded in any of the net namespace. Setting value to +"2" is pointless after boot if these modules are built-in, so there is +a kernel command-line option that can change this default. Please refer to +Documentation/admin-guide/kernel-parameters.txt for additional details. + +Not creating fallback tunnels gives control to userspace to create +whatever is needed only and avoid creating devices which are redundant. Default : 0 (for compatibility reasons) diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 4b9d2e8e9142..f455fa00c00f 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -27,6 +27,7 @@ Currently, these files are in /proc/sys/vm: - admin_reserve_kbytes - block_dump - compact_memory +- compaction_proactiveness - compact_unevictable_allowed - dirty_background_bytes - dirty_background_ratio @@ -37,6 +38,7 @@ Currently, these files are in /proc/sys/vm: - dirty_writeback_centisecs - drop_caches - extfrag_threshold +- highmem_is_dirtyable - hugetlb_shm_group - laptop_mode - legacy_va_layout diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index f461d6c33534..86de8a1ad91c 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -210,6 +210,28 @@ When mounting an XFS filesystem, the following options are accepted. inconsistent namespace presentation during or after a failover event. +Deprecation of V4 Format +======================== + +The V4 filesystem format lacks certain features that are supported by +the V5 format, such as metadata checksumming, strengthened metadata +verification, and the ability to store timestamps past the year 2038. +Because of this, the V4 format is deprecated. All users should upgrade +by backing up their files, reformatting, and restoring from the backup. + +Administrators and users can detect a V4 filesystem by running xfs_info +against a filesystem mountpoint and checking for a string containing +"crc=". If no such string is found, please upgrade xfsprogs to the +latest version and try again. + +The deprecation will take place in two parts. Support for mounting V4 +filesystems can now be disabled at kernel build time via Kconfig option. +The option will default to yes until September 2025, at which time it +will be changed to default to no. In September 2030, support will be +removed from the codebase entirely. + +Note: Distributors may choose to withdraw V4 format support earlier than +the dates listed above. Deprecated Mount Options ======================== @@ -217,6 +239,9 @@ Deprecated Mount Options =========================== ================ Name Removal Schedule =========================== ================ +Mounting with V4 filesystem September 2030 +ikeep/noikeep September 2025 +attr2/noattr2 September 2025 =========================== ================ @@ -331,7 +356,12 @@ The following sysctls are available for the XFS filesystem: Deprecated Sysctls ================== -None at present. +=========================== ================ + Name Removal Schedule +=========================== ================ +fs.xfs.irix_sgid_inherit September 2025 +fs.xfs.irix_symlink_mode September 2025 +=========================== ================ Removed Sysctls 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/hugetlbpage.rst b/Documentation/arm64/hugetlbpage.rst index b44f939e5210..a110124c11e3 100644 --- a/Documentation/arm64/hugetlbpage.rst +++ b/Documentation/arm64/hugetlbpage.rst @@ -1,3 +1,5 @@ +.. _hugetlbpage_index: + ==================== HugeTLBpage on ARM64 ==================== 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/block/blk-mq.rst b/Documentation/block/blk-mq.rst index 88c56afcb070..a980d23af48c 100644 --- a/Documentation/block/blk-mq.rst +++ b/Documentation/block/blk-mq.rst @@ -63,10 +63,10 @@ Software staging queues ~~~~~~~~~~~~~~~~~~~~~~~ The block IO subsystem adds requests in the software staging queues -(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent +(represented by struct blk_mq_ctx) in case that they weren't sent directly to the driver. A request is one or more BIOs. They arrived at the -block layer through the data structure struct :c:type:`bio`. The block layer -will then build a new structure from it, the struct :c:type:`request` that will +block layer through the data structure struct bio. The block layer +will then build a new structure from it, the struct request that will be used to communicate with the device driver. Each queue has its own lock and the number of queues is defined by a per-CPU or per-node basis. @@ -102,7 +102,7 @@ hardware queue will be drained in sequence according to their mapping. Hardware dispatch queues ~~~~~~~~~~~~~~~~~~~~~~~~ -The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct +The hardware queue (represented by struct blk_mq_hw_ctx) is a struct used by device drivers to map the device submission queues (or device DMA ring buffer), and are the last step of the block layer submission code before the low level device driver taking ownership of the request. To run this queue, the @@ -110,9 +110,9 @@ block layer removes requests from the associated software queues and tries to dispatch to the hardware. If it's not possible to send the requests directly to hardware, they will be -added to a linked list (:c:type:`hctx->dispatch`) of requests. Then, +added to a linked list (``hctx->dispatch``) of requests. Then, next time the block layer runs a queue, it will send the requests laying at the -:c:type:`dispatch` list first, to ensure a fairness dispatch with those +``dispatch`` list first, to ensure a fairness dispatch with those requests that were ready to be sent first. The number of hardware queues depends on the number of hardware contexts supported by the hardware and its device driver, but it will not be more than the number of cores of the system. diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst index 354817b80887..e75151e467d3 100644 --- a/Documentation/block/inline-encryption.rst +++ b/Documentation/block/inline-encryption.rst @@ -52,7 +52,7 @@ Constraints and notes Design ====== -We add a :c:type:`struct bio_crypt_ctx` to :c:type:`struct bio` that can +We add a struct bio_crypt_ctx to struct bio that can represent an encryption context, because we need to be able to pass this encryption context from the upper layers (like the fs layer) to the device driver to act upon. @@ -85,7 +85,7 @@ blk-mq changes, other block layer changes and blk-crypto-fallback ================================================================= We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to -:c:type:`struct request`. These will be referred to as the ``crypto fields`` +struct request. These will be referred to as the ``crypto fields`` for the request. This ``keyslot`` is the keyslot into which the ``bi_crypt_context`` has been programmed in the KSM of the ``request_queue`` that this request is being sent to. @@ -118,7 +118,7 @@ of the algorithm being used adheres to spec and functions correctly). If a ``request queue``'s inline encryption hardware claimed to support the encryption context specified with a bio, then it will not be handled by the ``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a -:c:type:`struct request` needs to be allocated for that bio. At that point, +struct request needs to be allocated for that bio. At that point, blk-mq tries to program the encryption context into the ``request_queue``'s keyslot_manager, and obtain a keyslot, which it stores in its newly added ``keyslot`` field. This keyslot is released when the request is completed. @@ -188,7 +188,7 @@ keyslots supported by the hardware. The device driver also needs to tell the KSM how to actually manipulate the IE hardware in the device to do things like programming the crypto key into the IE hardware into a particular keyslot. All this is achieved through the -:c:type:`struct blk_ksm_ll_ops` field in the KSM that the device driver +struct blk_ksm_ll_ops field in the KSM that the device driver must fill up after initing the ``blk_keyslot_manager``. The KSM also handles runtime power management for the device when applicable diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst index f261a5c84170..2638d3446b79 100644 --- a/Documentation/block/queue-sysfs.rst +++ b/Documentation/block/queue-sysfs.rst @@ -124,6 +124,10 @@ For zoned block devices (zoned attribute indicating "host-managed" or EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value. If this value is 0, there is no limit. +If the host attempts to exceed this limit, the driver should report this error +with BLK_STS_ZONE_ACTIVE_RESOURCE, which user space may see as the EOVERFLOW +errno. + max_open_zones (RO) ------------------- For zoned block devices (zoned attribute indicating "host-managed" or @@ -131,6 +135,10 @@ For zoned block devices (zoned attribute indicating "host-managed" or EXPLICIT OPEN or IMPLICIT OPEN, is limited by this value. If this value is 0, there is no limit. +If the host attempts to exceed this limit, the driver should report this error +with BLK_STS_ZONE_OPEN_RESOURCE, which user space may see as the ETOOMANYREFS +errno. + max_sectors_kb (RW) ------------------- This is the maximum number of kilobytes that the block layer will allow diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index a26aa1b9b259..5b613d2a5f1a 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -60,13 +60,13 @@ Q: Where can I find patches currently under discussion for BPF subsystem? A: All patches that are Cc'ed to netdev are queued for review under netdev patchwork project: - http://patchwork.ozlabs.org/project/netdev/list/ + https://patchwork.kernel.org/project/netdevbpf/list/ Those patches which target BPF, are assigned to a 'bpf' delegate for further processing from BPF maintainers. The current queue with patches under review can be found at: - https://patchwork.ozlabs.org/project/netdev/list/?delegate=77147 + https://patchwork.kernel.org/project/netdevbpf/list/?delegate=121173 Once the patches have been reviewed by the BPF community as a whole and approved by the BPF maintainers, their status in patchwork will be @@ -149,7 +149,7 @@ In case the patch or patch series has to be reworked and sent out again in a second or later revision, it is also required to add a version number (``v2``, ``v3``, ...) into the subject prefix:: - git format-patch --subject-prefix='PATCH net-next v2' start..finish + git format-patch --subject-prefix='PATCH bpf-next v2' start..finish When changes have been requested to the patch series, always send the whole patch series again with the feedback incorporated (never send @@ -479,17 +479,18 @@ LLVM's static compiler lists the supported targets through $ llc --version LLVM (http://llvm.org/): - LLVM version 6.0.0svn + LLVM version 10.0.0 Optimized build. Default target: x86_64-unknown-linux-gnu Host CPU: skylake Registered Targets: - bpf - BPF (host endian) - bpfeb - BPF (big endian) - bpfel - BPF (little endian) - x86 - 32-bit X86: Pentium-Pro and above - x86-64 - 64-bit X86: EM64T and AMD64 + aarch64 - AArch64 (little endian) + bpf - BPF (host endian) + bpfeb - BPF (big endian) + bpfel - BPF (little endian) + x86 - 32-bit X86: Pentium-Pro and above + x86-64 - 64-bit X86: EM64T and AMD64 For developers in order to utilize the latest features added to LLVM's BPF back end, it is advisable to run the latest LLVM releases. Support @@ -517,6 +518,10 @@ from the git repositories:: The built binaries can then be found in the build/bin/ directory, where you can point the PATH variable to. +Set ``-DLLVM_TARGETS_TO_BUILD`` equal to the target you wish to build, you +will find a full list of targets within the llvm-project/llvm/lib/Target +directory. + Q: Reporting LLVM BPF issues ---------------------------- Q: Should I notify BPF kernel maintainers about issues in LLVM's BPF code diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index b5361b8621c9..44dc789de2b4 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -724,6 +724,31 @@ want to define unused entry in BTF_ID_LIST, like:: BTF_ID_UNUSED BTF_ID(struct, task_struct) +The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values +and their count, with following syntax:: + + BTF_SET_START(set) + BTF_ID(type1, name1) + BTF_ID(type2, name2) + BTF_SET_END(set) + +resulting in following layout in .BTF_ids section:: + + __BTF_ID__set__set: + .zero 4 + __BTF_ID__type1__name1__3: + .zero 4 + __BTF_ID__type2__name2__4: + .zero 4 + +The ``struct btf_id_set set;`` variable is defined to access the list. + +The ``typeX`` name can be one of following:: + + struct, union, typedef, func + +and is used as a filter when resolving the BTF ID value. + All the BTF ID lists and sets are compiled in the .BTF_ids section and resolved during the linking phase of kernel build by ``resolve_btfids`` tool. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 7df2465fd108..4f2874b729c3 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -52,6 +52,7 @@ Program types prog_cgroup_sysctl prog_flow_dissector bpf_lsm + prog_sk_lookup Map types diff --git a/Documentation/bpf/prog_sk_lookup.rst b/Documentation/bpf/prog_sk_lookup.rst new file mode 100644 index 000000000000..85a305c19bcd --- /dev/null +++ b/Documentation/bpf/prog_sk_lookup.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +===================== +BPF sk_lookup program +===================== + +BPF sk_lookup program type (``BPF_PROG_TYPE_SK_LOOKUP``) introduces programmability +into the socket lookup performed by the transport layer when a packet is to be +delivered locally. + +When invoked BPF sk_lookup program can select a socket that will receive the +incoming packet by calling the ``bpf_sk_assign()`` BPF helper function. + +Hooks for a common attach point (``BPF_SK_LOOKUP``) exist for both TCP and UDP. + +Motivation +========== + +BPF sk_lookup program type was introduced to address setup scenarios where +binding sockets to an address with ``bind()`` socket call is impractical, such +as: + +1. receiving connections on a range of IP addresses, e.g. 192.0.2.0/24, when + binding to a wildcard address ``INADRR_ANY`` is not possible due to a port + conflict, +2. receiving connections on all or a wide range of ports, i.e. an L7 proxy use + case. + +Such setups would require creating and ``bind()``'ing one socket to each of the +IP address/port in the range, leading to resource consumption and potential +latency spikes during socket lookup. + +Attachment +========== + +BPF sk_lookup program can be attached to a network namespace with +``bpf(BPF_LINK_CREATE, ...)`` syscall using the ``BPF_SK_LOOKUP`` attach type and a +netns FD as attachment ``target_fd``. + +Multiple programs can be attached to one network namespace. Programs will be +invoked in the same order as they were attached. + +Hooks +===== + +The attached BPF sk_lookup programs run whenever the transport layer needs to +find a listening (TCP) or an unconnected (UDP) socket for an incoming packet. + +Incoming traffic to established (TCP) and connected (UDP) sockets is delivered +as usual without triggering the BPF sk_lookup hook. + +The attached BPF programs must return with either ``SK_PASS`` or ``SK_DROP`` +verdict code. As for other BPF program types that are network filters, +``SK_PASS`` signifies that the socket lookup should continue on to regular +hashtable-based lookup, while ``SK_DROP`` causes the transport layer to drop the +packet. + +A BPF sk_lookup program can also select a socket to receive the packet by +calling ``bpf_sk_assign()`` BPF helper. Typically, the program looks up a socket +in a map holding sockets, such as ``SOCKMAP`` or ``SOCKHASH``, and passes a +``struct bpf_sock *`` to ``bpf_sk_assign()`` helper to record the +selection. Selecting a socket only takes effect if the program has terminated +with ``SK_PASS`` code. + +When multiple programs are attached, the end result is determined from return +codes of all the programs according to the following rules: + +1. If any program returned ``SK_PASS`` and selected a valid socket, the socket + is used as the result of the socket lookup. +2. If more than one program returned ``SK_PASS`` and selected a socket, the last + selection takes effect. +3. If any program returned ``SK_DROP``, and no program returned ``SK_PASS`` and + selected a socket, socket lookup fails. +4. If all programs returned ``SK_PASS`` and none of them selected a socket, + socket lookup continues on. + +API +=== + +In its context, an instance of ``struct bpf_sk_lookup``, BPF sk_lookup program +receives information about the packet that triggered the socket lookup. Namely: + +* IP version (``AF_INET`` or ``AF_INET6``), +* L4 protocol identifier (``IPPROTO_TCP`` or ``IPPROTO_UDP``), +* source and destination IP address, +* source and destination L4 port, +* the socket that has been selected with ``bpf_sk_assign()``. + +Refer to ``struct bpf_sk_lookup`` declaration in ``linux/bpf.h`` user API +header, and `bpf-helpers(7) +<https://man7.org/linux/man-pages/man7/bpf-helpers.7.html>`_ man-page section +for ``bpf_sk_assign()`` for details. + +Example +======= + +See ``tools/testing/selftests/bpf/prog_tests/sk_lookup.c`` for the reference +implementation. diff --git a/Documentation/conf.py b/Documentation/conf.py index 0a102d57437d..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* @@ -47,9 +48,68 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', # if major >= 3: sys.stderr.write('''WARNING: The kernel documentation build process - does not work correctly with Sphinx v3.0 and above. Expect errors - in the generated output. - ''') + support for Sphinx v3.0 and above is brand new. Be prepared for + possible issues in the generated output. + ''') + 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 + c_id_attributes = [ + # GCC Compiler types not parsed by Sphinx: + "__restrict__", + + # include/linux/compiler_types.h: + "__iomem", + "__kernel", + "noinstr", + "notrace", + "__percpu", + "__rcu", + "__user", + + # include/linux/compiler_attributes.h: + "__alias", + "__aligned", + "__aligned_largest", + "__always_inline", + "__assume_aligned", + "__cold", + "__attribute_const__", + "__copy", + "__pure", + "__designated_init", + "__visible", + "__printf", + "__scanf", + "__gnu_inline", + "__malloc", + "__mode", + "__no_caller_saved_registers", + "__noclone", + "__nonstring", + "__noreturn", + "__packed", + "__pure", + "__section", + "__always_unused", + "__maybe_unused", + "__used", + "__weak", + "noinline", + + # include/linux/memblock.h: + "__init_memblock", + "__meminit", + + # include/linux/init.h: + "__init", + "__ref", + + # include/linux/linkage.h: + "asmlinkage", + ] + else: extensions.append('cdomain') diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index ea0413276ddb..75cb757bbff0 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -519,10 +519,9 @@ routines, e.g.::: Part II - Non-coherent DMA allocations -------------------------------------- -These APIs allow to allocate pages in the kernel direct mapping that are -guaranteed to be DMA addressable. This means that unlike dma_alloc_coherent, -virt_to_page can be called on the resulting address, and the resulting -struct page can be used for everything a struct page is suitable for. +These APIs allow to allocate pages that are guaranteed to be DMA addressable +by the passed in device, but which need explicit management of memory ownership +for the kernel vs the device. If you don't understand how cache line coherency works between a processor and an I/O device, you should not be using this part of the API. @@ -537,7 +536,7 @@ an I/O device, you should not be using this part of the API. This routine allocates a region of <size> bytes of consistent memory. It returns a pointer to the allocated region (in the processor's virtual address space) or NULL if the allocation failed. The returned memory may or may not -be in the kernels direct mapping. Drivers must not call virt_to_page on +be in the kernel direct mapping. Drivers must not call virt_to_page on the returned memory region. It also returns a <dma_handle> which may be cast to an unsigned integer the @@ -565,7 +564,45 @@ reused. Free a region of memory previously allocated using dma_alloc_noncoherent(). dev, size and dma_handle and dir must all be the same as those passed into dma_alloc_noncoherent(). cpu_addr must be the virtual address returned by -the dma_alloc_noncoherent(). +dma_alloc_noncoherent(). + +:: + + struct page * + dma_alloc_pages(struct device *dev, size_t size, dma_addr_t *dma_handle, + enum dma_data_direction dir, gfp_t gfp) + +This routine allocates a region of <size> bytes of non-coherent memory. It +returns a pointer to first struct page for the region, or NULL if the +allocation failed. The resulting struct page can be used for everything a +struct page is suitable for. + +It also returns a <dma_handle> which may be cast to an unsigned integer the +same width as the bus and given to the device as the DMA address base of +the region. + +The dir parameter specified if data is read and/or written by the device, +see dma_map_single() for details. + +The gfp parameter allows the caller to specify the ``GFP_`` flags (see +kmalloc()) for the allocation, but rejects flags used to specify a memory +zone such as GFP_DMA or GFP_HIGHMEM. + +Before giving the memory to the device, dma_sync_single_for_device() needs +to be called, and before reading memory written by the device, +dma_sync_single_for_cpu(), just like for streaming DMA mappings that are +reused. + +:: + + void + dma_free_pages(struct device *dev, size_t size, struct page *page, + dma_addr_t dma_handle, enum dma_data_direction dir) + +Free a region of memory previously allocated using dma_alloc_pages(). +dev, size and dma_handle and dir must all be the same as those passed into +dma_alloc_noncoherent(). page must be the pointer returned by +dma_alloc_pages(). :: diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 8f06d885c310..f959c9b53f61 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -419,6 +419,7 @@ functions which are exported. .. kernel-doc:: kernel/irq/manage.c .. kernel-doc:: kernel/irq/chip.c + :export: Internal Functions Provided =========================== @@ -431,6 +432,7 @@ functions. .. kernel-doc:: kernel/irq/handle.c .. kernel-doc:: kernel/irq/chip.c + :internal: Credits ======= diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 4ac53a1363f6..741aa37dc181 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -231,12 +231,6 @@ Refer to the file kernel/module.c for more information. Hardware Interfaces =================== -Interrupt Handling ------------------- - -.. kernel-doc:: kernel/irq/manage.c - :export: - DMA Channels ------------ diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 00a5ba51e63f..541d31de8926 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -396,3 +396,5 @@ Kernel Inline Documentations Reference ====================================== .. kernel-doc:: include/linux/workqueue.h + +.. kernel-doc:: kernel/workqueue.c diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst index 640934b6f7b4..a137a0e6d068 100644 --- a/Documentation/core-api/xarray.rst +++ b/Documentation/core-api/xarray.rst @@ -475,13 +475,15 @@ or iterations will move the index to the first index in the range. Each entry will only be returned once, no matter how many indices it occupies. -Using xas_next() or xas_prev() with a multi-index xa_state -is not supported. Using either of these functions on a multi-index entry -will reveal sibling entries; these should be skipped over by the caller. - -Storing ``NULL`` into any index of a multi-index entry will set the entry -at every index to ``NULL`` and dissolve the tie. Splitting a multi-index -entry into entries occupying smaller ranges is not yet supported. +Using xas_next() or xas_prev() with a multi-index xa_state is not +supported. Using either of these functions on a multi-index entry will +reveal sibling entries; these should be skipped over by the caller. + +Storing ``NULL`` into any index of a multi-index entry will set the +entry at every index to ``NULL`` and dissolve the tie. A multi-index +entry can be split into entries occupying smaller ranges by calling +xas_split_alloc() without the xa_lock held, followed by taking the lock +and calling xas_split(). Functions and structures ======================== 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/kgdb.rst b/Documentation/dev-tools/kgdb.rst index c908ef4d3f04..77b688e6a254 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -726,7 +726,7 @@ The kernel debugger is organized into a number of components: - contains an arch-specific trap catcher which invokes kgdb_handle_exception() to start kgdb about doing its work - - translation to and from gdb specific packet format to :c:type:`pt_regs` + - translation to and from gdb specific packet format to struct pt_regs - Registration and unregistration of architecture specific trap hooks @@ -846,7 +846,7 @@ invokes a callback in the serial core which in turn uses the callback in the UART driver. When using kgdboc with a UART, the UART driver must implement two -callbacks in the :c:type:`struct uart_ops <uart_ops>`. +callbacks in the struct uart_ops. Example from ``drivers/8250.c``:: @@ -875,7 +875,7 @@ kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration. The core polled keyboard driver for PS/2 type keyboards is in ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core when kgdboc populates the callback in the array called -:c:type:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level +:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level function which polls hardware for single character input. kgdboc and kms diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 469d115a95f1..a901def730d9 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -125,32 +125,41 @@ Note that some tests will require root privileges. Install selftests ================= -You can use the kselftest_install.sh tool to install selftests in the -default location, which is tools/testing/selftests/kselftest, or in a -user specified location. +You can use the "install" target of "make" (which calls the `kselftest_install.sh` +tool) to install selftests in the default location (`tools/testing/selftests/kselftest_install`), +or in a user specified location via the `INSTALL_PATH` "make" variable. To install selftests in default location:: - $ cd tools/testing/selftests - $ ./kselftest_install.sh + $ make -C tools/testing/selftests install To install selftests in a user specified location:: - $ cd tools/testing/selftests - $ ./kselftest_install.sh install_dir + $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path Running installed selftests =========================== -Kselftest install as well as the Kselftest tarball provide a script -named "run_kselftest.sh" to run the tests. +Found in the install directory, as well as in the Kselftest tarball, +is a script named `run_kselftest.sh` to run the tests. You can simply do the following to run the installed Kselftests. Please note some tests will require root privileges:: - $ cd kselftest + $ cd kselftest_install $ ./run_kselftest.sh +To see the list of available tests, the `-l` option can be used:: + + $ ./run_kselftest.sh -l + +The `-c` option can be used to run all the tests from a test collection, or +the `-t` option for specific single tests. Either can be used multiple times:: + + $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep + +For other features see the script usage output, seen with the `-h` option. + Packaging selftests =================== @@ -160,9 +169,9 @@ different system. To package selftests, run:: $ make -C tools/testing/selftests gen_tar This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By -default, `.gz` format is used. The tar format can be overridden by specifying -a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_ option -is supported, such as:: +default, `.gz` format is used. The tar compression format can be overridden by +specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_ +option is supported, such as:: $ make -C tools/testing/selftests gen_tar FORMAT=.xz 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/index.rst b/Documentation/dev-tools/kunit/index.rst index e93606ecfb01..c234a3ab3c34 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -11,6 +11,7 @@ KUnit - Unit Testing for the Linux Kernel usage kunit-tool api/index + style faq What is KUnit? 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 new file mode 100644 index 000000000000..8dbcdc552606 --- /dev/null +++ b/Documentation/dev-tools/kunit/style.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +Test Style and Nomenclature +=========================== + +To make finding, writing, and using KUnit tests as simple as possible, it's +strongly encouraged that they are named and written according to the guidelines +below. While it's possible to write KUnit tests which do not follow these rules, +they may break some tooling, may conflict with other tests, and may not be run +automatically by testing systems. + +It's recommended that you only deviate from these guidelines when: + +1. Porting tests to KUnit which are already known with an existing name, or +2. Writing tests which would cause serious problems if automatically run (e.g., + non-deterministically producing false positives or negatives, or taking an + extremely long time to run). + +Subsystems, Suites, and Tests +============================= + +In order to make tests as easy to find as possible, they're grouped into suites +and subsystems. A test suite is a group of tests which test a related area of +the kernel, and a subsystem is a set of test suites which test different parts +of the same kernel subsystem or driver. + +Subsystems +---------- + +Every test suite must belong to a subsystem. A subsystem is a collection of one +or more KUnit test suites which test the same driver or part of the kernel. A +rule of thumb is that a test subsystem should match a single kernel module. If +the code being tested can't be compiled as a module, in many cases the subsystem +should correspond to a directory in the source tree or an entry in the +MAINTAINERS file. If unsure, follow the conventions set by tests in similar +areas. + +Test subsystems should be named after the code being tested, either after the +module (wherever possible), or after the directory or files being tested. Test +subsystems should be named to avoid ambiguity where necessary. + +If a test subsystem name has multiple components, they should be separated by +underscores. *Do not* include "test" or "kunit" directly in the subsystem name +unless you are actually testing other tests or the kunit framework itself. + +Example subsystems could be: + +``ext4`` + Matches the module and filesystem name. +``apparmor`` + Matches the module name and LSM name. +``kasan`` + Common name for the tool, prominent part of the path ``mm/kasan`` +``snd_hda_codec_hdmi`` + Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by + underscores. Matches the module name. + +Avoid names like these: + +``linear-ranges`` + Names should use underscores, not dashes, to separate words. Prefer + ``linear_ranges``. +``qos-kunit-test`` + As well as using underscores, this name should not have "kunit-test" as a + suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a + better name. +``pc_parallel_port`` + The corresponding module name is ``parport_pc``, so this subsystem should also + be named ``parport_pc``. + +.. note:: + The KUnit API and tools do not explicitly know about subsystems. They're + simply a way of categorising test suites and naming modules which + provides a simple, consistent way for humans to find and run tests. This + may change in the future, though. + +Suites +------ + +KUnit tests are grouped into test suites, which cover a specific area of +functionality being tested. Test suites can have shared initialisation and +shutdown code which is run for all tests in the suite. +Not all subsystems will need to be split into multiple test suites (e.g. simple drivers). + +Test suites are named after the subsystem they are part of. If a subsystem +contains several suites, the specific area under test should be appended to the +subsystem name, separated by an underscore. + +In the event that there are multiple types of test using KUnit within a +subsystem (e.g., both unit tests and integration tests), they should be put into +separate suites, with the type of test as the last element in the suite name. +Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or +similar in the suite name. + +The full test suite name (including the subsystem name) should be specified as +the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the +module name (see below). + +Example test suites could include: + +``ext4_inode`` + Part of the ``ext4`` subsystem, testing the ``inode`` area. +``kunit_try_catch`` + Part of the ``kunit`` implementation itself, testing the ``try_catch`` area. +``apparmor_property_entry`` + Part of the ``apparmor`` subsystem, testing the ``property_entry`` area. +``kasan`` + The ``kasan`` subsystem has only one suite, so the suite name is the same as + the subsystem name. + +Avoid names like: + +``ext4_ext4_inode`` + There's no reason to state the subsystem twice. +``property_entry`` + The suite name is ambiguous without the subsystem name. +``kasan_integration_test`` + Because there is only one suite in the ``kasan`` subsystem, the suite should + just be called ``kasan``. There's no need to redundantly add + ``integration_test``. Should a separate test suite with, for example, unit + tests be added, then that suite could be named ``kasan_unittest`` or similar. + +Test Cases +---------- + +Individual tests consist of a single function which tests a constrained +codepath, property, or function. In the test output, individual tests' results +will show up as subtests of the suite's results. + +Tests should be named after what they're testing. This is often the name of the +function being tested, with a description of the input or codepath being tested. +As tests are C functions, they should be named and written in accordance with +the kernel coding style. + +.. note:: + As tests are themselves functions, their names cannot conflict with + other C identifiers in the kernel. This may require some creative + naming. It's a good idea to make your test functions `static` to avoid + polluting the global namespace. + +Example test names include: + +``unpack_u32_with_null_name`` + Tests the ``unpack_u32`` function when a NULL name is passed in. +``test_list_splice`` + Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a + name conflict with the macro itself. + + +Should it be necessary to refer to a test outside the context of its test suite, +the *fully-qualified* name of a test should be the suite name followed by the +test name, separated by a colon (i.e. ``suite:test``). + +Test Kconfig Entries +==================== + +Every test suite should be tied to a Kconfig entry. + +This Kconfig entry must: + +* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test + suite. +* be listed either alongside the config entries for the driver/subsystem being + tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage] +* depend on ``CONFIG_KUNIT`` +* be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled. +* have a default value of ``CONFIG_KUNIT_ALL_TESTS``. +* have a brief description of KUnit in the help text + +Unless there's a specific reason not to (e.g. the test is unable to be built as +a module), Kconfig entries for tests should be tristate. + +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. + + 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. + + +Test File and Module Names +========================== + +KUnit tests can often be compiled as a module. These modules should be named +after the test suite, followed by ``_test``. If this is likely to conflict with +non-KUnit tests, the suffix ``_kunit`` can also be used. + +The easiest way of achieving this is to name the file containing the test suite +``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be +placed next to the code under test. + +If the suite name contains some or all of the name of the test's parent +directory, it may make sense to modify the source filename to reduce redundancy. +For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c`` +file. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 3c3fe8b5fecc..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 @@ -211,6 +211,11 @@ KUnit test framework. .. note:: A test case will only be run if it is associated with a test suite. +``kunit_test_suite(...)`` is a macro which tells the linker to put the specified +test suite in a special linker section so that it can be run by KUnit either +after late_init, or when the test module is loaded (depending on whether the +test was built in or not). + For more information on these types of things see the :doc:`api/test`. Isolating Behavior @@ -224,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 @@ -454,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. @@ -556,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 ----------------------------------------- @@ -589,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 14023f0a8552..02dc72c97645 100644 --- a/Documentation/devicetree/bindings/arm/actions.yaml +++ b/Documentation/devicetree/bindings/arm/actions.yaml @@ -20,6 +20,12 @@ properties: - enum: - allo,sparky # Allo.com Sparky - cubietech,cubieboard6 # Cubietech CubieBoard6 + - roseapplepi,roseapplepi # RoseapplePi.org RoseapplePi + - const: actions,s500 + - items: + - enum: + - caninos,labrador-base-m # Labrador Base Board M v1 + - const: caninos,labrador-v2 # Labrador Core v2 - const: actions,s500 - items: - enum: @@ -30,6 +36,11 @@ properties: # The Actions Semi S700 is a quad-core ARM Cortex-A53 SoC. - items: - enum: + - caninos,labrador-base-m2 # Labrador Base Board M v2 + - const: caninos,labrador-v3 # Labrador Core v3 + - const: actions,s700 + - items: + - enum: - cubietech,cubieboard7 # Cubietech CubieBoard7 - const: actions,s700 @@ -38,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 5eba9f48823e..3341788d1096 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -96,6 +96,7 @@ properties: - hwacom,amazetv - khadas,vim - libretech,aml-s905x-cc + - libretech,aml-s905x-cc-v2 - nexbox,a95x - const: amlogic,s905x - const: amlogic,meson-gxl @@ -153,6 +154,7 @@ properties: - azw,gtking - azw,gtking-pro - hardkernel,odroid-n2 + - hardkernel,odroid-n2-plus - khadas,vim3 - ugoos,am6 - const: amlogic,s922x @@ -171,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 31b0c54fa2cf..6fc5a22ad962 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -41,6 +41,7 @@ properties: - overkiz,kizboxmini-mb # Overkiz kizbox Mini Mother Board - overkiz,kizboxmini-rd # Overkiz kizbox Mini RailDIN - overkiz,smartkiz # Overkiz SmartKiz Board + - gardena,smart-gateway-at91sam # GARDENA smart Gateway (Article No. 19000) - const: atmel,at91sam9g25 - const: atmel,at91sam9x5 - const: atmel,at91sam9 @@ -183,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 d48313c7ae45..434d3c6db61e 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -83,6 +83,11 @@ properties: - brcm,bcm953012er - brcm,bcm953012hr - brcm,bcm953012k + - meraki,mr32 - 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 6da9d734cdb7..934289446abb 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -120,6 +120,7 @@ properties: - fsl,imx6q-sabrelite - fsl,imx6q-sabresd - kontron,imx6q-samx6i # Kontron i.MX6 Dual/Quad SMARC Module + - logicpd,imx6q-logicpd - prt,prti6q # Protonic PRTI6Q board - prt,prtwd2 # Protonic WD2 board - technexion,imx6q-pico-dwarf # TechNexion i.MX6Q Pico-Dwarf @@ -156,6 +157,21 @@ properties: - const: gw,ventana - const: fsl,imx6q + - description: i.MX6Q PHYTEC phyBOARD-Mira + items: + - enum: + - phytec,imx6q-pbac06-emmc # PHYTEC phyBOARD-Mira eMMC RDK + - phytec,imx6q-pbac06-nand # PHYTEC phyBOARD-Mira NAND RDK + - const: phytec,imx6q-pbac06 # PHYTEC phyBOARD-Mira + - const: phytec,imx6qdl-pcm058 # PHYTEC phyCORE-i.MX6 + - const: fsl,imx6q + + - description: i.MX6Q PHYTEC phyFLEX-i.MX6 + items: + - const: phytec,imx6q-pbab01 # PHYTEC phyFLEX carrier board + - const: phytec,imx6q-pfla02 # PHYTEC phyFLEX-i.MX6 Quad + - const: fsl,imx6q + - description: i.MX6QP based Boards items: - enum: @@ -163,6 +179,13 @@ properties: - fsl,imx6qp-sabresd # i.MX6 Quad Plus SABRE Smart Device Board - const: fsl,imx6qp + - description: i.MX6QP PHYTEC phyBOARD-Mira + items: + - const: phytec,imx6qp-pbac06-nand + - const: phytec,imx6qp-pbac06 # PHYTEC phyBOARD-Mira + - const: phytec,imx6qdl-pcm058 # PHYTEC phyCORE-i.MX6 + - const: fsl,imx6qp + - description: i.MX6DL based Boards items: - enum: @@ -188,6 +211,7 @@ properties: - toradex,colibri_imx6dl-v1_1-eval-v3 # Colibri iMX6 Module V1.1 on Colibri Evaluation Board V3 - ysoft,imx6dl-yapp4-draco # i.MX6 DualLite Y Soft IOTA Draco board - ysoft,imx6dl-yapp4-hydra # i.MX6 DualLite Y Soft IOTA Hydra board + - ysoft,imx6dl-yapp4-orion # i.MX6 DualLite Y Soft IOTA Orion board - ysoft,imx6dl-yapp4-ursa # i.MX6 Solo Y Soft IOTA Ursa board - const: fsl,imx6dl @@ -211,10 +235,26 @@ properties: - const: gw,ventana - const: fsl,imx6dl + - description: i.MX6DL PHYTEC phyBOARD-Mira + items: + - enum: + - phytec,imx6dl-pbac06-emmc # PHYTEC phyBOARD-Mira eMMC RDK + - phytec,imx6dl-pbac06-nand # PHYTEC phyBOARD-Mira NAND RDK + - const: phytec,imx6dl-pbac06 # PHYTEC phyBOARD-Mira + - const: phytec,imx6qdl-pcm058 # PHYTEC phyCORE-i.MX6 + - const: fsl,imx6dl + + - description: i.MX6DL PHYTEC phyFLEX-i.MX6 + items: + - const: phytec,imx6dl-pbab01 # PHYTEC phyFLEX carrier board + - const: phytec,imx6dl-pfla02 # PHYTEC phyFLEX-i.MX6 Quad + - const: fsl,imx6dl + - description: i.MX6SL based Boards items: - enum: - fsl,imx6sl-evk # i.MX6 SoloLite EVK Board + - kobo,tolino-shine2hd - kobo,tolino-shine3 - const: fsl,imx6sl @@ -246,6 +286,15 @@ properties: - technexion,imx6ul-pico-pi # TechNexion i.MX6UL Pico-Pi - const: fsl,imx6ul + - description: i.MX6UL PHYTEC phyBOARD-Segin + items: + - enum: + - phytec,imx6ul-pbacd10-emmc + - phytec,imx6ul-pbacd10-nand + - const: phytec,imx6ul-pbacd10 # PHYTEC phyBOARD-Segin with i.MX6 UL + - const: phytec,imx6ul-pcl063 # PHYTEC phyCORE-i.MX 6UL + - const: fsl,imx6ul + - description: Kontron N6310 S Board items: - const: kontron,imx6ul-n6310-s @@ -277,6 +326,15 @@ properties: - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / BT Module on Colibri Eval Board - const: fsl,imx6ull + - description: i.MX6ULL PHYTEC phyBOARD-Segin + items: + - enum: + - phytec,imx6ull-pbacd10-emmc + - phytec,imx6ull-pbacd10-nand + - const: phytec,imx6ull-pbacd10 # PHYTEC phyBOARD-Segin with i.MX6 ULL + - const: phytec,imx6ull-pcl063 # PHYTEC phyCORE-i.MX 6ULL + - const: fsl,imx6ull + - description: Kontron N6411 S Board items: - const: kontron,imx6ull-n6411-s @@ -344,7 +402,16 @@ properties: - description: i.MX8MM based Boards items: - enum: + - beacon,imx8mm-beacon-kit # i.MX8MM Beacon Development Kit + - fsl,imx8mm-ddr4-evk # i.MX8MM DDR4 EVK Board - fsl,imx8mm-evk # i.MX8MM EVK Board + - variscite,var-som-mx8mm # i.MX8MM Variscite VAR-SOM-MX8MM module + - const: fsl,imx8mm + + - description: Variscite VAR-SOM-MX8MM based boards + items: + - const: variscite,var-som-mx8mm-symphony + - const: variscite,var-som-mx8mm - const: fsl,imx8mm - description: i.MX8MN based Boards @@ -354,6 +421,12 @@ properties: - fsl,imx8mn-evk # i.MX8MN LPDDR4 EVK Board - const: fsl,imx8mn + - description: Variscite VAR-SOM-MX8MN based boards + items: + - const: variscite,var-som-mx8mn-symphony + - const: variscite,var-som-mx8mn + - const: fsl,imx8mn + - description: i.MX8MP based Boards items: - enum: @@ -372,13 +445,35 @@ properties: - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk - const: fsl,imx8mq + - description: Purism Librem5 phones + items: + - enum: + - purism,librem5r2 # Purism Librem5 phone "Chestnut" + - purism,librem5r3 # Purism Librem5 phone "Dogwood" + - const: purism,librem5 + - const: fsl,imx8mq + + - description: Zodiac Inflight Innovations Ultra Boards + items: + - enum: + - zii,imx8mq-ultra-rmb3 + - zii,imx8mq-ultra-zest + - const: zii,imx8mq-ultra + - const: fsl,imx8mq + - description: i.MX8QXP based Boards items: - enum: - einfochips,imx8qxp-ai_ml # i.MX8QXP AI_ML Board - fsl,imx8qxp-mek # i.MX8QXP MEK Board - toradex,colibri-imx8x # Colibri iMX8X Module + - const: fsl,imx8qxp + + - description: Toradex Colibri i.MX8 Evaluation Board + items: + - enum: - toradex,colibri-imx8x-eval-v3 # Colibri iMX8X Module on Colibri Evaluation Board V3 + - const: toradex,colibri-imx8x - const: fsl,imx8qxp - description: @@ -526,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/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index bd7a0fa5801b..ea827e8763de 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -15,6 +15,7 @@ Required Properties: - "mediatek,mt7623-apmixedsys", "mediatek,mt2701-apmixedsys" - "mediatek,mt7629-apmixedsys" - "mediatek,mt8135-apmixedsys" + - "mediatek,mt8167-apmixedsys", "syscon" - "mediatek,mt8173-apmixedsys" - "mediatek,mt8183-apmixedsys", "syscon" - "mediatek,mt8516-apmixedsys" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index 38309db115f5..b32d374193c7 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -11,6 +11,7 @@ Required Properties: - "mediatek,mt6779-audio", "syscon" - "mediatek,mt7622-audsys", "syscon" - "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon" + - "mediatek,mt8167-audiosys", "syscon" - "mediatek,mt8183-audiosys", "syscon" - "mediatek,mt8516-audsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt index 1e1f00718a7d..dce4c9241932 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -12,6 +12,7 @@ Required Properties: - "mediatek,mt6779-imgsys", "syscon" - "mediatek,mt6797-imgsys", "syscon" - "mediatek,mt7623-imgsys", "mediatek,mt2701-imgsys", "syscon" + - "mediatek,mt8167-imgsys", "syscon" - "mediatek,mt8173-imgsys", "syscon" - "mediatek,mt8183-imgsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index 49a968be1a80..eb3523c7a7be 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -16,6 +16,7 @@ Required Properties: - "mediatek,mt7623-infracfg", "mediatek,mt2701-infracfg", "syscon" - "mediatek,mt7629-infracfg", "syscon" - "mediatek,mt8135-infracfg", "syscon" + - "mediatek,mt8167-infracfg", "syscon" - "mediatek,mt8173-infracfg", "syscon" - "mediatek,mt8183-infracfg", "syscon" - "mediatek,mt8516-infracfg", "syscon" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt index ad5f9d2f6818..054424fb64b4 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2712-mfgcfg", "syscon" - "mediatek,mt6779-mfgcfg", "syscon" + - "mediatek,mt8167-mfgcfg", "syscon" - "mediatek,mt8183-mfgcfg", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index 9b0394cbbdc9..5ce7578cf274 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -15,6 +15,7 @@ Required Properties: - "mediatek,mt7623-topckgen", "mediatek,mt2701-topckgen" - "mediatek,mt7629-topckgen" - "mediatek,mt8135-topckgen" + - "mediatek,mt8167-topckgen", "syscon" - "mediatek,mt8173-topckgen" - "mediatek,mt8183-topckgen", "syscon" - "mediatek,mt8516-topckgen" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt index 7894558b7a1c..98195169176a 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt @@ -11,6 +11,7 @@ Required Properties: - "mediatek,mt6779-vdecsys", "syscon" - "mediatek,mt6797-vdecsys", "syscon" - "mediatek,mt7623-vdecsys", "mediatek,mt2701-vdecsys", "syscon" + - "mediatek,mt8167-vdecsys", "syscon" - "mediatek,mt8173-vdecsys", "syscon" - "mediatek,mt8183-vdecsys", "syscon" - #clock-cells: Must be 1 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/omap/prm-inst.txt b/Documentation/devicetree/bindings/arm/omap/prm-inst.txt index fcd3456afbbe..42db138e091a 100644 --- a/Documentation/devicetree/bindings/arm/omap/prm-inst.txt +++ b/Documentation/devicetree/bindings/arm/omap/prm-inst.txt @@ -18,6 +18,7 @@ Required properties: (base address and length) Optional properties: +- #power-domain-cells: Should be 0 if the instance is a power domain provider. - #reset-cells: Should be 1 if the PRM instance in question supports resets. Example: @@ -25,5 +26,6 @@ Example: prm_dsp2: prm@1b00 { compatible = "ti,dra7-prm-inst", "ti,omap-prm-inst"; reg = <0x1b00 0x40>; + #power-domain-cells = <0>; #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index ae6284be9fef..c97d4a580f47 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -40,6 +40,7 @@ description: | sdm630 sdm660 sdm845 + sm8250 The 'board' element must be one of the following strings: @@ -47,6 +48,8 @@ description: | cp01-c1 dragonboard hk01 + hk10-c1 + hk10-c2 idp liquid mtp @@ -150,6 +153,8 @@ properties: - items: - enum: - qcom,ipq8074-hk01 + - qcom,ipq8074-hk10-c1 + - qcom,ipq8074-hk10-c2 - const: qcom,ipq8074 - items: @@ -167,4 +172,12 @@ properties: - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 + - items: + - enum: + - qcom,qrb5165-rb5 + - 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 0d4dabb4a164..ff94c45eefb0 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -281,10 +281,24 @@ properties: - renesas,draak # Draak (RTP0RC77995SEB0010S) - const: renesas,r8a77995 + - description: R-Car V3U (R8A779A0) + items: + - enum: + - renesas,falcon-cpu # Falcon CPU board (RTP0RC779A0CPB0010S) + - const: renesas,r8a779a0 + + - items: + - enum: + - renesas,falcon-breakout # Falcon BreakOut board (RTP0RC779A0BOB0010S) + - const: renesas,falcon-cpu + - const: renesas,r8a779a0 + - description: RZ/N1D (R9A06G032) items: - enum: - 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 db2e35796795..b621752aaa65 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -104,6 +104,11 @@ properties: - firefly,roc-rk3399-pc-mezzanine - const: rockchip,rk3399 + - description: FriendlyElec NanoPi R2S + items: + - const: friendlyarm,nanopi-r2s + - const: rockchip,rk3328 + - description: FriendlyElec NanoPi4 series boards items: - enum: @@ -430,8 +435,12 @@ properties: - const: radxa,rock - const: rockchip,rk3188 - - description: Radxa ROCK Pi 4 + - description: Radxa ROCK Pi 4A/B/C items: + - enum: + - radxa,rockpi4a + - radxa,rockpi4b + - radxa,rockpi4c - const: radxa,rockpi4 - const: rockchip,rk3399 @@ -555,4 +564,12 @@ properties: items: - const: tronsmart,orion-r68-meta - const: rockchip,rk3368 + + - description: Zkmagic A95X Z2 + items: + - const: zkmagic,a95x-z2 + - const: rockchip,rk3318 + +additionalProperties: true + ... diff --git a/Documentation/devicetree/bindings/arm/samsung/pmu.yaml b/Documentation/devicetree/bindings/arm/samsung/pmu.yaml index cde9c5ec28c8..17678d9686c1 100644 --- a/Documentation/devicetree/bindings/arm/samsung/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/samsung/pmu.yaml @@ -24,6 +24,7 @@ select: - samsung,exynos5420-pmu - samsung,exynos5433-pmu - samsung,exynos7-pmu + - samsung-s5pv210-pmu required: - compatible @@ -40,6 +41,7 @@ properties: - samsung,exynos5420-pmu - samsung,exynos5433-pmu - samsung,exynos7-pmu + - samsung-s5pv210-pmu - const: syscon reg: @@ -88,12 +90,28 @@ properties: required: - compatible - reg - - '#clock-cells' - - clock-names - - clocks additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos3250-pmu + - samsung,exynos4210-pmu + - samsung,exynos4412-pmu + - samsung,exynos5250-pmu + - samsung,exynos5410-pmu + - samsung,exynos5420-pmu + - samsung,exynos5433-pmu + then: + required: + - '#clock-cells' + - clock-names + - clocks + examples: - | #include <dt-bindings/clock/exynos5250.h> 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 696a0101ebcc..009b424e456e 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -52,4 +52,13 @@ properties: - const: st,stm32mp157c-ev1 - const: st,stm32mp157c-ed1 - const: st,stm32mp157 + - description: Odyssey STM32MP1 SoM based Boards + items: + - 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 efc9118233b4..cab8e1b6417b 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -16,6 +16,11 @@ properties: compatible: oneOf: + - description: Allwinner A100 Perf1 Board + items: + - const: allwinner,a100-perf1 + - const: allwinner,sun50i-a100 + - description: Allwinner A23 Evaluation Board items: - const: allwinner,sun8i-a23-evb @@ -626,6 +631,11 @@ properties: - const: pine64,pine64-plus - const: allwinner,sun50i-a64 + - description: Pine64 PineCube + items: + - const: pine64,pinecube + - const: allwinner,sun8i-s3 + - description: Pine64 PineH64 model A items: - const: pine64,pine-h64 @@ -883,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 b4d53290c5f0..767e86354c8e 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -121,3 +121,9 @@ properties: items: - const: nvidia,p3509-0000+p3668-0000 - const: nvidia,tegra194 + - items: + - enum: + - nvidia,tegra234-vdk + - const: nvidia,tegra234 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt index 2d89cdc39eb0..576462fae27f 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Should contain one of the following: - "nvidia,tegra186-pmc": for Tegra186 - "nvidia,tegra194-pmc": for Tegra194 + - "nvidia,tegra234-pmc": for Tegra234 - reg: Must contain an (offset, length) pair of the register set for each entry in reg-names. - reg-names: Must include the following entries: @@ -11,7 +12,7 @@ Required properties: - "wake" - "aotag" - "scratch" - - "misc" (Only for Tegra194) + - "misc" (Only for Tegra194 and later) Optional properties: - nvidia,invert-interrupt: If present, inverts the PMU interrupt signal. diff --git a/Documentation/devicetree/bindings/arm/ti/k3.txt b/Documentation/devicetree/bindings/arm/ti/k3.txt deleted file mode 100644 index 333e7256126a..000000000000 --- a/Documentation/devicetree/bindings/arm/ti/k3.txt +++ /dev/null @@ -1,26 +0,0 @@ -Texas Instruments K3 Multicore SoC architecture device tree bindings --------------------------------------------------------------------- - -Platforms based on Texas Instruments K3 Multicore SoC architecture -shall follow the following scheme: - -SoCs ----- - -Each device tree root node must specify which exact SoC in K3 Multicore SoC -architecture it uses, using one of the following compatible values: - -- AM654 - compatible = "ti,am654"; - -- J721E - compatible = "ti,j721e"; - -Boards ------- - -In addition, each device tree root node must specify which one or more -of the following board-specific compatible values: - -- AM654 EVM - compatible = "ti,am654-evm", "ti,am654"; diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml new file mode 100644 index 000000000000..c6e1c1e63e43 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/ti/k3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments K3 Multicore SoC architecture device tree bindings + +maintainers: + - Nishanth Menon <nm@ti.com> + +description: | + Platforms based on Texas Instruments K3 Multicore SoC architecture + shall have the following properties. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: K3 AM654 SoC + items: + - enum: + - ti,am654-evm + - const: ti,am654 + + - description: K3 J721E SoC + items: + - const: ti,j721e + + - 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 new file mode 100644 index 000000000000..001bbbcd1432 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/toshiba.yaml @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/toshiba.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba Visconti Platform Device Tree Bindings + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Visconti5 TMPV7708 + items: + - 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/bus/brcm,gisb-arb.txt b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt index 729def62f0c5..10f6d0a8159d 100644 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt @@ -10,7 +10,8 @@ Required properties: "brcm,bcm7038-gisb-arb" for 130nm chips - reg: specifies the base physical address and size of the registers - interrupts: specifies the two interrupts (timeout and TEA) to be used from - the parent interrupt controller + the parent interrupt controller. A third optional interrupt may be specified + for breakpoints. Optional properties: diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml index 4d382128b711..3b45344ed758 100644 --- a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml @@ -36,6 +36,8 @@ properties: - allwinner,sun9i-a80-ccu - allwinner,sun50i-a64-ccu - allwinner,sun50i-a64-r-ccu + - allwinner,sun50i-a100-ccu + - allwinner,sun50i-a100-r-ccu - allwinner,sun50i-h5-ccu - allwinner,sun50i-h6-ccu - allwinner,sun50i-h6-r-ccu @@ -78,6 +80,7 @@ if: - allwinner,sun8i-a83t-r-ccu - allwinner,sun8i-h3-r-ccu - allwinner,sun50i-a64-r-ccu + - allwinner,sun50i-a100-r-ccu - allwinner,sun50i-h6-r-ccu then: @@ -94,7 +97,9 @@ else: if: properties: compatible: - const: allwinner,sun50i-h6-ccu + enum: + - allwinner,sun50i-a100-ccu + - allwinner,sun50i-h6-ccu then: properties: 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/clock/qcom,dispcc-sm8x50.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml new file mode 100644 index 000000000000..0cdf53f41f84 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,dispcc-sm8x50.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SM8150/SM8250 + +maintainers: + - Jonathan Marek <jonathan@marek.ca> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains on SM8150 and SM8250. + + See also: + dt-bindings/clock/qcom,dispcc-sm8150.h + dt-bindings/clock/qcom,dispcc-sm8250.h + +properties: + compatible: + enum: + - qcom,sm8150-dispcc + - qcom,sm8250-dispcc + + clocks: + items: + - description: Board XO source + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY0 + - description: Byte clock from DSI PHY1 + - description: Pixel clock from DSI PHY1 + - description: Link clock from DP PHY + - description: VCO DIV clock from DP PHY + + clock-names: + items: + - const: bi_tcxo + - const: dsi0_phy_pll_out_byteclk + - const: dsi0_phy_pll_out_dsiclk + - const: dsi1_phy_pll_out_byteclk + - const: dsi1_phy_pll_out_dsiclk + - const: dp_phy_pll_link_clk + - const: dp_phy_pll_vco_div_clk + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@af00000 { + compatible = "qcom,sm8250-dispcc"; + reg = <0x0af00000 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&dsi0_phy 0>, + <&dsi0_phy 1>, + <&dsi1_phy 0>, + <&dsi1_phy 1>, + <&dp_phy 0>, + <&dp_phy 1>; + clock-names = "bi_tcxo", + "dsi0_phy_pll_out_byteclk", + "dsi0_phy_pll_out_dsiclk", + "dsi1_phy_pll_out_byteclk", + "dsi1_phy_pll_out_dsiclk", + "dp_phy_pll_link_clk", + "dp_phy_pll_vco_div_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml deleted file mode 100644 index 2feea2b91aa9..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-videocc.yaml +++ /dev/null @@ -1,65 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/clock/qcom,sc7180-videocc.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Video Clock & Reset Controller Binding for SC7180 - -maintainers: - - Taniya Das <tdas@codeaurora.org> - -description: | - Qualcomm video clock control module which supports the clocks, resets and - power domains on SC7180. - - See also dt-bindings/clock/qcom,videocc-sc7180.h. - -properties: - compatible: - const: qcom,sc7180-videocc - - clocks: - items: - - description: Board XO source - - clock-names: - items: - - const: bi_tcxo - - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - - reg: - maxItems: 1 - -required: - - compatible - - reg - - clocks - - clock-names - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,rpmh.h> - clock-controller@ab00000 { - compatible = "qcom,sc7180-videocc"; - reg = <0x0ab00000 0x10000>; - clocks = <&rpmhcc RPMH_CXO_CLK>; - clock-names = "bi_tcxo"; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - }; -... diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml index f7a0cf53d5f0..567202942b88 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sdm845-videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml @@ -1,23 +1,31 @@ # SPDX-License-Identifier: GPL-2.0-only %YAML 1.2 --- -$id: http://devicetree.org/schemas/clock/qcom,sdm845-videocc.yaml# +$id: http://devicetree.org/schemas/clock/qcom,videocc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Video Clock & Reset Controller Binding for SDM845 +title: Qualcomm Video Clock & Reset Controller Binding maintainers: - Taniya Das <tdas@codeaurora.org> description: | Qualcomm video clock control module which supports the clocks, resets and - power domains on SDM845. + power domains on SDM845/SC7180/SM8150/SM8250. - See also dt-bindings/clock/qcom,videocc-sdm845.h. + See also: + dt-bindings/clock/qcom,videocc-sc7180.h + dt-bindings/clock/qcom,videocc-sdm845.h + dt-bindings/clock/qcom,videocc-sm8150.h + dt-bindings/clock/qcom,videocc-sm8250.h properties: compatible: - const: qcom,sdm845-videocc + enum: + - qcom,sc7180-videocc + - qcom,sdm845-videocc + - qcom,sm8150-videocc + - qcom,sm8250-videocc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml index e13aee8ab61a..9b414fbde6d7 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -47,6 +47,7 @@ properties: - renesas,r8a77980-cpg-mssr # R-Car V3H - renesas,r8a77990-cpg-mssr # R-Car E3 - renesas,r8a77995-cpg-mssr # R-Car D3 + - renesas,r8a779a0-cpg-mssr # R-Car V3U reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml index fc823572bcff..0429fb774f10 100644 --- a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml +++ b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml @@ -23,7 +23,9 @@ properties: - items: - const: allwinner,sun7i-a20-crypto - const: allwinner,sun4i-a10-crypto + - const: allwinner,sun8i-a33-crypto - items: + - const: allwinner,sun8i-v3s-crypto - const: allwinner,sun8i-a33-crypto reg: @@ -59,7 +61,9 @@ if: properties: compatible: contains: - const: allwinner,sun6i-a31-crypto + enum: + - allwinner,sun6i-a31-crypto + - allwinner,sun8i-a33-crypto then: required: 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/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/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt index 8b2a71395647..3e64075ac7ec 100644 --- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt @@ -37,7 +37,7 @@ Optional nodes: supports a single port with a single endpoint. - See also Documentation/devicetree/bindings/display/tilcdc/panel.txt and - Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt for connecting + Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml for connecting tfp410 DVI encoder or lcd panel to lcdc [1] There is an errata about AM335x color wiring. For 16-bit color mode diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml index 9e53472be194..372679dbd216 100644 --- a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml +++ b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml @@ -19,9 +19,12 @@ properties: description: The cell is the request line number. compatible: - enum: - - allwinner,sun50i-a64-dma - - allwinner,sun50i-h6-dma + oneOf: + - const: allwinner,sun50i-a64-dma + - const: allwinner,sun50i-h6-dma + - items: + - const: allwinner,sun8i-r40-dma + - const: allwinner,sun50i-a64-dma reg: maxItems: 1 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/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index 4cee72d53318..6edfa705b486 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -114,6 +114,9 @@ properties: - const: renesas,r1ex24128 - const: atmel,24c128 + label: + description: Descriptive name of the EEPROM. + reg: maxItems: 1 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/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt index 2aaf661c04ee..b109911669e4 100644 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt @@ -7,6 +7,7 @@ Required properties: For Tegra132 must contain "nvidia,tegra132-efuse", "nvidia,tegra124-efuse". For Tegra210 must contain "nvidia,tegra210-efuse". For Tegra186 must contain "nvidia,tegra186-efuse". For Tegra194 must contain "nvidia,tegra194-efuse". + For Tegra234 must contain "nvidia,tegra234-efuse". Details: nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data due to a hardware bug. Tegra20 also lacks certain information which is 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/gpu/arm,mali-utgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml index 53708fe9e004..eceaa176bd57 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml @@ -25,6 +25,7 @@ properties: - allwinner,sun4i-a10-mali - allwinner,sun7i-a20-mali - allwinner,sun8i-h3-mali + - allwinner,sun8i-r40-mali - allwinner,sun50i-a64-mali - rockchip,rk3036-mali - rockchip,rk3066-mali @@ -131,6 +132,7 @@ allOf: enum: - allwinner,sun4i-a10-mali - allwinner,sun7i-a20-mali + - allwinner,sun8i-r40-mali - allwinner,sun50i-a64-mali - allwinner,sun50i-h5-mali - amlogic,meson8-mali 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/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml index ac0bc5dd64d6..29b9447f3b84 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml @@ -9,12 +9,18 @@ title: Freescale Low Power Inter IC (LPI2C) for i.MX maintainers: - Anson Huang <Anson.Huang@nxp.com> +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + properties: compatible: - enum: - - fsl,imx7ulp-lpi2c - - fsl,imx8qxp-lpi2c - - fsl,imx8qm-lpi2c + oneOf: + - enum: + - fsl,imx7ulp-lpi2c + - fsl,imx8qm-lpi2c + - items: + - const: fsl,imx8qxp-lpi2c + - const: fsl,imx7ulp-lpi2c reg: maxItems: 1 @@ -22,23 +28,34 @@ properties: interrupts: maxItems: 1 + assigned-clock-parents: true + assigned-clock-rates: true + assigned-clocks: true + clock-frequency: true + + clock-names: + maxItems: 1 + clocks: maxItems: 1 + power-domains: + maxItems: 1 + required: - compatible - reg - interrupts - clocks -additionalProperties: false +unevaluatedProperties: false examples: - | #include <dt-bindings/clock/imx7ulp-clock.h> #include <dt-bindings/interrupt-controller/arm-gic.h> - lpi2c7@40a50000 { + i2c@40a50000 { compatible = "fsl,imx7ulp-lpi2c"; reg = <0x40A50000 0x10000>; interrupt-parent = <&intc>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml index 810536953177..f23966b0d6c6 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml @@ -9,6 +9,9 @@ title: Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX maintainers: - Wolfram Sang <wolfram@the-dreams.de> +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + properties: compatible: oneOf: @@ -19,6 +22,9 @@ properties: - const: fsl,imx35-i2c - const: fsl,imx1-i2c - items: + - const: fsl,imx7d-i2c + - const: fsl,imx21-i2c + - items: - enum: - fsl,imx25-i2c - fsl,imx27-i2c @@ -75,7 +81,7 @@ required: - interrupts - clocks -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt index a21c359b9f02..df41f72afc87 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -87,6 +87,11 @@ wants to support one of the below features, it should adapt these bindings. this information to detect a stalled bus more reliably, for example. Can not be combined with 'multi-master'. +- smbus + states that additional SMBus restrictions and features apply to this bus. + Examples of features are SMBusHostNotify and SMBusAlert. Examples of + restrictions are more reserved addresses and timeout definitions. + Required properties (per child device) -------------------------------------- diff --git a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml index 682ed1bbf5c6..e1e65eb4f795 100644 --- a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml @@ -17,9 +17,13 @@ properties: pattern: "^i2c@[0-9a-f]+$" compatible: - enum: - - ingenic,jz4780-i2c - - ingenic,x1000-i2c + oneOf: + - enum: + - ingenic,jz4770-i2c + - ingenic,x1000-i2c + - items: + - const: ingenic,jz4780-i2c + - const: ingenic,jz4770-i2c reg: maxItems: 1 @@ -60,7 +64,7 @@ examples: #include <dt-bindings/dma/jz4780-dma.h> #include <dt-bindings/interrupt-controller/irq.h> i2c@10054000 { - compatible = "ingenic,jz4780-i2c"; + compatible = "ingenic,jz4780-i2c", "ingenic,jz4770-i2c"; #address-cells = <1>; #size-cells = <0>; reg = <0x10054000 0x1000>; diff --git a/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.txt b/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.txt new file mode 100644 index 000000000000..566ea861aa00 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.txt @@ -0,0 +1,42 @@ +Device tree configuration for the Mellanox I2C SMBus on BlueField SoCs + +Required Properties: + +- compatible : should be "mellanox,i2c-mlxbf1" or "mellanox,i2c-mlxbf2". + +- reg : address offset and length of the device registers. The + registers consist of the following set of resources: + 1) Smbus block registers. + 2) Cause master registers. + 3) Cause slave registers. + 4) Cause coalesce registers (if compatible isn't set + to "mellanox,i2c-mlxbf1"). + +- interrupts : interrupt number. + +Optional Properties: + +- clock-frequency : bus frequency used to configure timing registers; + allowed values are 100000, 400000 and 1000000; + those are expressed in Hz. Default is 100000. + +Example: + +i2c@2804000 { + compatible = "mellanox,i2c-mlxbf1"; + reg = <0x02804000 0x800>, + <0x02801200 0x020>, + <0x02801260 0x020>; + interrupts = <57>; + clock-frequency = <100000>; +}; + +i2c@2808800 { + compatible = "mellanox,i2c-mlxbf2"; + reg = <0x02808800 0x600>, + <0x02808e00 0x020>, + <0x02808e20 0x020>, + <0x02808e40 0x010>; + interrupts = <57>; + clock-frequency = <400000>; +}; 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/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml new file mode 100644 index 000000000000..054406bbd22b --- /dev/null +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019-2020 Artur Rojek +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/input/adc-joystick.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: ADC attached joystick + +maintainers: + - Artur Rojek <contact@artur-rojek.eu> + +description: > + Bindings for joystick devices connected to ADC controllers supporting + the Industrial I/O subsystem. + +properties: + compatible: + const: adc-joystick + + io-channels: + minItems: 1 + maxItems: 1024 + description: > + List of phandle and IIO specifier pairs. + Each pair defines one ADC channel to which a joystick axis is connected. + See Documentation/devicetree/bindings/iio/iio-bindings.txt for details. + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - io-channels + - '#address-cells' + - '#size-cells' + +additionalProperties: false + +patternProperties: + "^axis@[0-9a-f]+$": + type: object + description: > + Represents a joystick axis bound to the given ADC channel. + For each entry in the io-channels list, one axis subnode with a matching + reg property must be specified. + + properties: + reg: + minimum: 0 + maximum: 1023 + description: Index of an io-channels list entry bound to this axis. + + linux,code: + $ref: /schemas/types.yaml#/definitions/uint32 + description: EV_ABS specific event code generated by the axis. + + abs-range: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + - items: + - description: minimum value + - description: maximum value + description: > + Minimum and maximum values produced by the axis. + For an ABS_X axis this will be the left-most and right-most + inclination of the joystick. If min > max, it is left to userspace to + treat the axis as inverted. + This property is interpreted as two signed 32 bit values. + + abs-fuzz: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + Amount of noise in the input value. + Omitting this property indicates the axis is precise. + + abs-flat: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + Axial "deadzone", or area around the center position, where the axis + is considered to be at rest. + Omitting this property indicates the axis always returns to exactly + the center position. + + required: + - reg + - linux,code + - abs-range + + additionalProperties: false + +examples: + - | + #include <dt-bindings/iio/adc/ingenic,adc.h> + #include <dt-bindings/input/input.h> + + joystick: adc-joystick { + compatible = "adc-joystick"; + io-channels = <&adc INGENIC_ADC_TOUCH_XP>, + <&adc INGENIC_ADC_TOUCH_YP>; + #address-cells = <1>; + #size-cells = <0>; + + axis@0 { + reg = <0>; + linux,code = <ABS_X>; + abs-range = <3300 0>; + abs-fuzz = <4>; + abs-flat = <200>; + }; + axis@1 { + reg = <1>; + linux,code = <ABS_Y>; + abs-range = <0 3300>; + abs-fuzz = <4>; + abs-flat = <200>; + }; + }; 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/input/touchscreen/zinitix.txt b/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt new file mode 100644 index 000000000000..446efb9f5f55 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt @@ -0,0 +1,40 @@ +Device tree bindings for Zinitx BT541 touchscreen controller + +Required properties: + + - compatible : Should be "zinitix,bt541" + - reg : I2C address of the chip. Should be 0x20 + - interrupts : Interrupt to which the chip is connected + +Optional properties: + + - vdd-supply : Analog power supply regulator on VCCA pin + - vddo-supply : Digital power supply regulator on VDD pin + - zinitix,mode : Mode of reporting touch points. Some modes may not work + with a particular ts firmware for unknown reasons. Available + modes are 1 and 2. Mode 2 is the default and preferred. + +The touchscreen-* properties are documented in touchscreen.txt in this +directory. + +Example: + + i2c@00000000 { + /* ... */ + + bt541@20 { + compatible = "zinitix,bt541"; + reg = <0x20>; + interrupt-parent = <&msmgpio>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + pinctrl-names = "default"; + pinctrl-0 = <&tsp_default>; + vdd-supply = <®_vdd_tsp>; + vddo-supply = <&pm8916_l6>; + touchscreen-size-x = <540>; + touchscreen-size-y = <960>; + zinitix,mode = <2>; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml index 7cd6b8bacfa0..8acca0ae3129 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml @@ -29,11 +29,14 @@ properties: - items: - const: allwinner,sun8i-a83t-r-intc - const: allwinner,sun6i-a31-r-intc - - const: allwinner,sun9i-a80-sc-nmi + - const: allwinner,sun9i-a80-nmi - items: - const: allwinner,sun50i-a64-r-intc - const: allwinner,sun6i-a31-r-intc - items: + - const: allwinner,sun50i-a100-nmi + - const: allwinner,sun9i-a80-nmi + - items: - const: allwinner,sun50i-h6-r-intc - const: allwinner,sun6i-a31-r-intc 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/arm,mhu.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml new file mode 100644 index 000000000000..d43791a2dde7 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/arm,mhu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM MHU Mailbox Controller + +maintainers: + - Jassi Brar <jaswinder.singh@linaro.org> + +description: | + The ARM's Message-Handling-Unit (MHU) is a mailbox controller that has 3 + independent channels/links to communicate with remote processor(s). MHU links + are hardwired on a platform. A link raises interrupt for any received data. + However, there is no specified way of knowing if the sent data has been read + by the remote. This driver assumes the sender polls STAT register and the + remote clears it after having read the data. The last channel is specified to + be a 'Secure' resource, hence can't be used by Linux running NS. + + The MHU hardware also allows operations in doorbell mode. The MHU drives the + interrupt signal using a 32-bit register, with all 32-bits logically ORed + together. It provides a set of registers to enable software to set, clear and + check the status of each of the bits of this register independently. The use + of 32 bits per interrupt line enables software to provide more information + about the source of the interrupt. For example, each bit of the register can + be associated with a type of event that can contribute to raising the + interrupt. Each of the 32-bits can be used as "doorbell" to alert the remote + processor. + +# We need a select here so we don't match all nodes with 'arm,primecell' +select: + properties: + compatible: + contains: + enum: + - arm,mhu + - arm,mhu-doorbell + required: + - compatible + +properties: + compatible: + oneOf: + - description: Data transfer mode + items: + - const: arm,mhu + - const: arm,primecell + + - description: Doorbell mode + items: + - const: arm,mhu-doorbell + - const: arm,primecell + + + reg: + maxItems: 1 + + interrupts: + items: + - description: low-priority non-secure + - description: high-priority non-secure + - description: Secure + maxItems: 3 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: apb_pclk + + '#mbox-cells': + description: | + Set to 1 in data transfer mode and represents index of the channel. + Set to 2 in doorbell mode and represents index of the channel and doorbell + number. + enum: [ 1, 2 ] + +required: + - compatible + - reg + - interrupts + - '#mbox-cells' + +additionalProperties: false + +examples: + # Data transfer mode. + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + mhuA: mailbox@2b1f0000 { + #mbox-cells = <1>; + compatible = "arm,mhu", "arm,primecell"; + reg = <0 0x2b1f0000 0 0x1000>; + interrupts = <0 36 4>, /* LP-NonSecure */ + <0 35 4>, /* HP-NonSecure */ + <0 37 4>; /* Secure */ + clocks = <&clock 0 2 1>; + clock-names = "apb_pclk"; + }; + + mhu_client_scb: scb@2e000000 { + compatible = "fujitsu,mb86s70-scb-1.0"; + reg = <0 0x2e000000 0 0x4000>; + mboxes = <&mhuA 1>; /* HP-NonSecure */ + }; + }; + + # Doorbell mode. + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + mhuB: mailbox@2b2f0000 { + #mbox-cells = <2>; + compatible = "arm,mhu-doorbell", "arm,primecell"; + reg = <0 0x2b2f0000 0 0x1000>; + interrupts = <0 36 4>, /* LP-NonSecure */ + <0 35 4>, /* HP-NonSecure */ + <0 37 4>; /* Secure */ + clocks = <&clock 0 2 1>; + clock-names = "apb_pclk"; + }; + + mhu_client_scpi: scpi@2f000000 { + compatible = "arm,scpi"; + reg = <0 0x2f000000 0 0x200>; + mboxes = <&mhuB 1 4>; /* HP-NonSecure, 5th doorbell */ + }; + }; diff --git a/Documentation/devicetree/bindings/mailbox/arm-mhu.txt b/Documentation/devicetree/bindings/mailbox/arm-mhu.txt deleted file mode 100644 index 4971f03f0b33..000000000000 --- a/Documentation/devicetree/bindings/mailbox/arm-mhu.txt +++ /dev/null @@ -1,43 +0,0 @@ -ARM MHU Mailbox Driver -====================== - -The ARM's Message-Handling-Unit (MHU) is a mailbox controller that has -3 independent channels/links to communicate with remote processor(s). - MHU links are hardwired on a platform. A link raises interrupt for any -received data. However, there is no specified way of knowing if the sent -data has been read by the remote. This driver assumes the sender polls -STAT register and the remote clears it after having read the data. -The last channel is specified to be a 'Secure' resource, hence can't be -used by Linux running NS. - -Mailbox Device Node: -==================== - -Required properties: --------------------- -- compatible: Shall be "arm,mhu" & "arm,primecell" -- reg: Contains the mailbox register address range (base - address and length) -- #mbox-cells Shall be 1 - the index of the channel needed. -- interrupts: Contains the interrupt information corresponding to - each of the 3 links of MHU. - -Example: --------- - - mhu: mailbox@2b1f0000 { - #mbox-cells = <1>; - compatible = "arm,mhu", "arm,primecell"; - reg = <0 0x2b1f0000 0x1000>; - interrupts = <0 36 4>, /* LP-NonSecure */ - <0 35 4>, /* HP-NonSecure */ - <0 37 4>; /* Secure */ - clocks = <&clock 0 2 1>; - clock-names = "apb_pclk"; - }; - - mhu_client: scb@2e000000 { - compatible = "fujitsu,mb86s70-scb-1.0"; - reg = <0 0x2e000000 0x4000>; - mboxes = <&mhu 1>; /* HP-NonSecure */ - }; 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/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index 35c3f56b7f7b..5fe80c1c19fc 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -69,7 +69,7 @@ The following are mandatory properties for the K3 AM65x and J721E SoCs only: the interrupt routes between the IP and the main GIC controllers. See the following binding for additional details, - Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt + Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml Child Nodes: ============ diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml index 8f810fc5c183..ffd09b664ff5 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml @@ -16,6 +16,7 @@ maintainers: properties: compatible: enum: + - qcom,ipq6018-apcs-apps-global - qcom,ipq8074-apcs-apps-global - qcom,msm8916-apcs-kpss-global - qcom,msm8994-apcs-kpss-global diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml index 7838804700d6..5fa19d4aeaf3 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml @@ -18,10 +18,13 @@ properties: oneOf: - const: allwinner,sun4i-a10-ir - const: allwinner,sun5i-a13-ir + - const: allwinner,sun6i-a31-ir - items: - const: allwinner,sun8i-a83t-ir - const: allwinner,sun6i-a31-ir - - const: allwinner,sun6i-a31-ir + - items: + - const: allwinner,sun8i-r40-ir + - const: allwinner,sun6i-a31-ir - items: - const: allwinner,sun50i-a64-ir - const: allwinner,sun6i-a31-ir diff --git a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt index 6c88ce858d08..719b2995dc17 100644 --- a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt +++ b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt @@ -56,7 +56,7 @@ Optional Connector Properties: instead of using the autodetection mechnism. Please look at [1] for more information. -[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt. +[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml. Example - three input sources: #include <dt-bindings/display/sdtv-standards.h> diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt index b64573680b42..dbafffe3f41e 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt @@ -5,7 +5,7 @@ The hardware block diagram please check bindings/iommu/mediatek,iommu.txt Mediatek SMI have two generations of HW architecture, here is the list which generation the SoCs use: generation 1: mt2701 and mt7623. -generation 2: mt2712, mt6779, mt8173 and mt8183. +generation 2: mt2712, mt6779, mt8167, mt8173 and mt8183. There's slight differences between the two SMI, for generation 2, the register which control the iommu port is at each larb's register base. But @@ -20,6 +20,7 @@ Required properties: "mediatek,mt2712-smi-common" "mediatek,mt6779-smi-common" "mediatek,mt7623-smi-common", "mediatek,mt2701-smi-common" + "mediatek,mt8167-smi-common" "mediatek,mt8173-smi-common" "mediatek,mt8183-smi-common" - reg : the register and size of the SMI block. diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt index 8f19dfe7d80e..0c5de12b5496 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt @@ -8,6 +8,7 @@ Required properties: "mediatek,mt2712-smi-larb" "mediatek,mt6779-smi-larb" "mediatek,mt7623-smi-larb", "mediatek,mt2701-smi-larb" + "mediatek,mt8167-smi-larb" "mediatek,mt8173-smi-larb" "mediatek,mt8183-smi-larb" - reg : the register and size of this local arbiter. @@ -22,7 +23,7 @@ Required properties: - "gals": the clock for GALS(Global Async Local Sync). Here is the list which has this GALS: mt8183. -Required property for mt2701, mt2712, mt6779 and mt7623: +Required property for mt2701, mt2712, mt6779, mt7623 and mt8167: - mediatek,larb-id :the hardware id of this larb. Example: 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 83c86cbe4716..ee00d414df10 100644 --- a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml +++ b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml @@ -47,4 +47,12 @@ properties: items: - const: yna,cu1830-neo - const: ingenic,x1830 + + - description: YSH & ATIL General Board, CU2000 Module with Neo Backplane + 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/misc/nvidia,tegra186-misc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt index 892ba4384abc..43d777ed8316 100644 --- a/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt @@ -1,11 +1,13 @@ -NVIDIA Tegra186 MISC register block +NVIDIA Tegra186 (and later) MISC register block -The MISC register block found on Tegra186 SoCs contains registers that can be -used to identify a given chip and various strapping options. +The MISC register block found on Tegra186 and later SoCs contains registers +that can be used to identify a given chip and various strapping options. Required properties: - compatible: Must be: - Tegra186: "nvidia,tegra186-misc" + - Tegra194: "nvidia,tegra194-misc" + - Tegra234: "nvidia,tegra234-misc" - reg: Should contain 2 entries: The first entry gives the physical address and length of the register region which contains revision and debug features. The second entry specifies the physical address and length diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt index 4556359c5876..83f6a251ba3e 100644 --- a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt @@ -1,10 +1,13 @@ -NVIDIA Tegra20/Tegra30/Tegr114/Tegra124 apbmisc block +NVIDIA Tegra APBMISC block Required properties: -- compatible : For Tegra20, must be "nvidia,tegra20-apbmisc". For Tegra30, - must be "nvidia,tegra30-apbmisc". Otherwise, must contain - "nvidia,<chip>-apbmisc", plus one of the above, where <chip> is tegra114, - tegra124, tegra132. +- compatible: Must be: + - Tegra20: "nvidia,tegra20-apbmisc" + - Tegra30: "nvidia,tegra30-apbmisc", "nvidia,tegra20-apbmisc" + - Tegra114: "nvidia,tegra114-apbmisc", "nvidia,tegra20-apbmisc" + - Tegra124: "nvidia,tegra124-apbmisc", "nvidia,tegra20-apbmisc" + - Tegra132: "nvidia,tegra124-apbmisc", "nvidia,tegra20-apbmisc" + - Tegra210: "nvidia,tegra210-apbmisc", "nvidia,tegra20-apbmisc" - reg: Should contain 2 entries: the first entry gives the physical address and length of the registers which contain revision and debug features. The second entry gives the physical address and length of the 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/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index 274bbe6a365e..b29050fd7470 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -55,6 +55,37 @@ patternProperties: $ref: /schemas/types.yaml#/definitions/string enum: [none, soft, hw, hw_syndrome, hw_oob_first, on-die] + nand-ecc-engine: + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + description: | + A phandle on the hardware ECC engine if any. There are + basically three possibilities: + 1/ The ECC engine is part of the NAND controller, in this + case the phandle should reference the parent node. + 2/ The ECC engine is part of the NAND part (on-die), in this + case the phandle should reference the node itself. + 3/ The ECC engine is external, in this case the phandle should + reference the specific ECC engine node. + + nand-use-soft-ecc-engine: + type: boolean + description: Use a software ECC engine. + + nand-no-ecc-engine: + type: boolean + description: Do not use any ECC correction. + + nand-ecc-placement: + allOf: + - $ref: /schemas/types.yaml#/definitions/string + - enum: [ oob, interleaved ] + description: + Location of the ECC bytes. This location is unknown by default + but can be explicitly set to "oob", if all ECC bytes are + known to be stored in the OOB area, or "interleaved" if ECC + bytes will be interleaved with regular data in the main area. + nand-ecc-algo: description: Desired ECC algorithm. diff --git a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index 88b57b0ca1f4..97ca62b0e14d 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -50,6 +50,13 @@ Optional properties: - reset-names: If the "reset" property is specified, this property should have the value "switch" to denote the switch reset line. +- clocks: when provided, the first phandle is to the switch's main clock and + is valid for both BCM7445 and BCM7278. The second phandle is only applicable + to BCM7445 and is to support dividing the switch core clock. + +- clock-names: when provided, the first phandle must be "sw_switch", and the + second must be named "sw_switch_mdiv". + Port subnodes: Optional properties: diff --git a/Documentation/devicetree/bindings/net/brcm,systemport.txt b/Documentation/devicetree/bindings/net/brcm,systemport.txt index 83f29e0e11ba..75736739bfdd 100644 --- a/Documentation/devicetree/bindings/net/brcm,systemport.txt +++ b/Documentation/devicetree/bindings/net/brcm,systemport.txt @@ -20,6 +20,11 @@ Optional properties: - systemport,num-tier1-arb: number of tier 1 arbiters, an integer - systemport,num-txq: number of HW transmit queues, an integer - systemport,num-rxq: number of HW receive queues, an integer +- clocks: When provided, must be two phandles to the functional clocks nodes of + the SYSTEMPORT block. The first phandle is the main SYSTEMPORT clock used + during normal operation, while the second phandle is the Wake-on-LAN clock. +- clock-names: When provided, names of the functional clock phandles, first + name should be "sw_sysport" and second should be "sw_sysportwol". Example: ethernet@f04a0000 { 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 94c0f8bf4deb..000000000000 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ /dev/null @@ -1,53 +0,0 @@ -Flexcan CAN controller on Freescale's ARM and PowerPC system-on-a-chip (SOC). - -Required properties: - -- compatible : Should be "fsl,<processor>-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 ack_gpr ack_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. - ack_gpr is the gpr register offset of CAN stop acknowledge. - ack_bit is the bit offset of CAN stop acknowledge. - -- fsl,clk-source: Select the clock source to the CAN Protocol Engine (PE). - It's SoC Implementation dependent. Refer to RM for detailed - definition. If this property is not set in device tree node - then driver selects clock source 1 by default. - 0: clock source 0 (oscillator clock) - 1: clock source 1 (peripheral clock) - -- wakeup-source: enable CAN remote wakeup - -Example: - - can@1c000 { - 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/microchip,mcp251x.txt b/Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt index 5a0111d4de58..381f8fb3e865 100644 --- a/Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt +++ b/Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt @@ -12,6 +12,9 @@ Required properties: Optional properties: - vdd-supply: Regulator that powers the CAN controller. - xceiver-supply: Regulator that powers the CAN transceiver. + - gpio-controller: Indicates this device is a GPIO controller. + - #gpio-cells: Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity. Example: can0: can@1 { @@ -19,7 +22,9 @@ Example: reg = <1>; clocks = <&clk24m>; interrupt-parent = <&gpio4>; - interrupts = <13 0x2>; + interrupts = <13 IRQ_TYPE_LEVEL_LOW>; vdd-supply = <®5v0>; xceiver-supply = <®5v0>; + gpio-controller; + #gpio-cells = <2>; }; diff --git a/Documentation/devicetree/bindings/net/can/microchip,mcp251xfd.yaml b/Documentation/devicetree/bindings/net/can/microchip,mcp251xfd.yaml new file mode 100644 index 000000000000..2a884c1fe0e0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/microchip,mcp251xfd.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/can/microchip,mcp251xfd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: + Microchip MCP2517FD and MCP2518FD stand-alone CAN controller device tree + bindings + +maintainers: + - Marc Kleine-Budde <mkl@pengutronix.de> + +properties: + compatible: + oneOf: + - const: microchip,mcp2517fd + description: for MCP2517FD + - const: microchip,mcp2518fd + description: for MCP2518FD + - const: microchip,mcp251xfd + description: to autodetect chip variant + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + vdd-supply: + description: Regulator that powers the CAN controller. + + xceiver-supply: + description: Regulator that powers the CAN transceiver. + + microchip,rx-int-gpios: + description: + GPIO phandle of GPIO connected to to INT1 pin of the MCP251XFD, which + signals a pending RX interrupt. + maxItems: 1 + + spi-max-frequency: + description: + Must be half or less of "clocks" frequency. + maximum: 20000000 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + can@0 { + compatible = "microchip,mcp251xfd"; + reg = <0>; + clocks = <&can0_osc>; + pinctrl-names = "default"; + pinctrl-0 = <&can0_pins>; + spi-max-frequency = <20000000>; + interrupts-extended = <&gpio 13 IRQ_TYPE_LEVEL_LOW>; + microchip,rx-int-gpios = <&gpio 27 GPIO_ACTIVE_LOW>; + vdd-supply = <®5v0>; + xceiver-supply = <®5v0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 85c6551b602a..6a5956347816 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -2,13 +2,15 @@ Renesas R-Car CAN controller Device Tree Bindings ------------------------------------------------- Required properties: -- compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. +- compatible: "renesas,can-r8a7742" if CAN controller is a part of R8A7742 SoC. + "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. "renesas,can-r8a7744" if CAN controller is a part of R8A7744 SoC. "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. "renesas,can-r8a77470" if CAN controller is a part of R8A77470 SoC. "renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC. "renesas,can-r8a774b1" if CAN controller is a part of R8A774B1 SoC. "renesas,can-r8a774c0" if CAN controller is a part of R8A774C0 SoC. + "renesas,can-r8a774e1" if CAN controller is a part of R8A774E1 SoC. "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. "renesas,can-r8a7790" if CAN controller is a part of R8A7790 SoC. @@ -37,8 +39,8 @@ Required properties: - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". -Required properties for R8A774A1, R8A774B1, R8A774C0, R8A7795, R8A7796, -R8A77965, R8A77990, and R8A77995: +Required properties for R8A774A1, R8A774B1, R8A774C0, R8A774E1, R8A7795, +R8A7796, R8A77965, R8A77990, and R8A77995: For the denoted SoCs, "clkp2" can be CANFD clock. This is a div6 clock and can be used by both CAN and CAN FD controller at the same time. It needs to be scaled to maximum frequency if any of these controllers use it. This is done diff --git a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt index 13a4e34c0c73..22cf2a889b2c 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt @@ -7,6 +7,7 @@ Required properties: - "renesas,r8a774a1-canfd" for R8A774A1 (RZ/G2M) compatible controller. - "renesas,r8a774b1-canfd" for R8A774B1 (RZ/G2N) compatible controller. - "renesas,r8a774c0-canfd" for R8A774C0 (RZ/G2E) compatible controller. + - "renesas,r8a774e1-canfd" for R8A774E1 (RZ/G2H) compatible controller. - "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller. - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller. - "renesas,r8a77965-canfd" for R8A77965 (R-Car M3-N) compatible controller. @@ -32,8 +33,8 @@ The name of the child nodes are "channel0" and "channel1" respectively. Each child node supports the "status" property only, which is used to enable/disable the respective channel. -Required properties for R8A774A1, R8A774B1, R8A774C0, R8A7795, R8A7796, -R8A77965, R8A77990, and R8A77995: +Required properties for R8A774A1, R8A774B1, R8A774C0, R8A774E1, R8A7795, +R8A7796, R8A77965, R8A77990, and R8A77995: In the denoted SoCs, canfd clock is a div6 clock and can be used by both CAN and CAN FD controller at the same time. It needs to be scaled to maximum frequency if any of these controllers use it. This is done using the below diff --git a/Documentation/devicetree/bindings/net/dsa/b53.txt b/Documentation/devicetree/bindings/net/dsa/b53.txt index cfd1afdc6e94..f1487a751b1a 100644 --- a/Documentation/devicetree/bindings/net/dsa/b53.txt +++ b/Documentation/devicetree/bindings/net/dsa/b53.txt @@ -95,7 +95,7 @@ Ethernet switch connected via MDIO to the host, CPU port wired to eth0: fixed-link { speed = <1000>; - duplex-full; + full-duplex; }; }; @@ -104,8 +104,9 @@ Ethernet switch connected via MDIO to the host, CPU port wired to eth0: #address-cells = <1>; #size-cells = <0>; - switch0: ethernet-switch@30 { + switch0: ethernet-switch@1e { compatible = "brcm,bcm53125"; + reg = <30>; #address-cells = <1>; #size-cells = <0>; @@ -128,7 +129,7 @@ Ethernet switch connected via MDIO to the host, CPU port wired to eth0: label = "cable-modem"; fixed-link { speed = <1000>; - duplex-full; + full-duplex; }; phy-mode = "rgmii-txid"; }; @@ -138,7 +139,7 @@ Ethernet switch connected via MDIO to the host, CPU port wired to eth0: label = "cpu"; fixed-link { speed = <1000>; - duplex-full; + full-duplex; }; phy-mode = "rgmii-txid"; ethernet = <ð0>; diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt index c5ed5d25f642..560369efad6c 100644 --- a/Documentation/devicetree/bindings/net/dsa/mt7530.txt +++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt @@ -5,6 +5,7 @@ Required properties: - compatible: may be compatible = "mediatek,mt7530" or compatible = "mediatek,mt7621" + or compatible = "mediatek,mt7531" - #address-cells: Must be 1. - #size-cells: Must be 0. - mediatek,mcm: Boolean; if defined, indicates that either MT7530 is the part @@ -32,10 +33,14 @@ Required properties for the child nodes within ports container: - reg: Port address described must be 6 for CPU port and from 0 to 5 for user ports. -- phy-mode: String, must be either "trgmii" or "rgmii" for port labeled - "cpu". - -Port 5 of the switch is muxed between: +- phy-mode: String, the following values are acceptable for port labeled + "cpu": + If compatible mediatek,mt7530 or mediatek,mt7621 is set, + must be either "trgmii" or "rgmii" + If compatible mediatek,mt7531 is set, + must be either "sgmii", "1000base-x" or "2500base-x" + +Port 5 of mt7530 and mt7621 switch is muxed between: 1. GMAC5: GMAC5 can interface with another external MAC or PHY. 2. PHY of port 0 or port 4: PHY interfaces with an external MAC like 2nd GMAC of the SOC. Used in many setups where port 0/4 becomes the WAN port. diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index 3fd85ce37e9c..fdf709817218 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -120,6 +120,13 @@ properties: and is useful for determining certain configuration settings such as flow control thresholds. + rx-internal-delay-ps: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + RGMII Receive Clock Delay defined in pico seconds. + This is used for controllers that have configurable RX internal delays. + If this property is present then the MAC applies the RX delay. + sfp: $ref: /schemas/types.yaml#definitions/phandle description: @@ -131,6 +138,13 @@ properties: The size of the controller\'s transmit fifo in bytes. This is used for components that can have configurable fifo sizes. + tx-internal-delay-ps: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + RGMII Transmit Clock Delay defined in pico seconds. + This is used for controllers that have configurable TX internal delays. + If this property is present then the MAC applies the TX delay. + managed: description: Specifies the PHY management type. If auto is set and fixed-link diff --git a/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml new file mode 100644 index 000000000000..c1948ce00081 --- /dev/null +++ b/Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/intel,dwmac-plat.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel DWMAC glue layer Device Tree Bindings + +maintainers: + - Vineetha G. Jaya Kumaran <vineetha.g.jaya.kumaran@intel.com> + +select: + properties: + compatible: + contains: + enum: + - intel,keembay-dwmac + required: + - compatible + +allOf: + - $ref: "snps,dwmac.yaml#" + +properties: + compatible: + oneOf: + - items: + - enum: + - intel,keembay-dwmac + - const: snps,dwmac-4.10a + + clocks: + items: + - description: GMAC main clock + - description: PTP reference clock + - description: Tx clock + + clock-names: + items: + - const: stmmaceth + - const: ptp_ref + - const: tx_clk + +required: + - compatible + - clocks + - clock-names + +unevaluatedProperties: false + +examples: +# FIXME: Remove defines and include the correct header file +# once it is available in mainline. + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #define MOVISOC_KMB_PSS_GBE + #define MOVISOC_KMB_PSS_AUX_GBE_PTP + #define MOVISOC_KMB_PSS_AUX_GBE_TX + + stmmac_axi_setup: stmmac-axi-config { + snps,lpi_en; + snps,wr_osr_lmt = <0x0>; + snps,rd_osr_lmt = <0x2>; + snps,blen = <0 0 0 0 16 8 4>; + }; + + mtl_rx_setup: rx-queues-config { + snps,rx-queues-to-use = <2>; + snps,rx-sched-sp; + queue0 { + snps,dcb-algorithm; + snps,map-to-dma-channel = <0x0>; + snps,priority = <0x0>; + }; + + queue1 { + snps,dcb-algorithm; + snps,map-to-dma-channel = <0x1>; + snps,priority = <0x1>; + }; + }; + + mtl_tx_setup: tx-queues-config { + snps,tx-queues-to-use = <2>; + snps,tx-sched-wrr; + queue0 { + snps,weight = <0x10>; + snps,dcb-algorithm; + snps,priority = <0x0>; + }; + + queue1 { + snps,weight = <0x10>; + snps,dcb-algorithm; + snps,priority = <0x1>; + }; + }; + + gmac0: ethernet@3a000000 { + compatible = "intel,keembay-dwmac", "snps,dwmac-4.10a"; + interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + reg = <0x3a000000 0x8000>; + snps,perfect-filter-entries = <128>; + phy-handle = <ð_phy0>; + phy-mode = "rgmii"; + rx-fifo-depth = <4096>; + tx-fifo-depth = <4096>; + clock-names = "stmmaceth", "ptp_ref", "tx_clk"; + clocks = <&scmi_clk MOVISOC_KMB_PSS_GBE>, + <&scmi_clk MOVISOC_KMB_PSS_AUX_GBE_PTP>, + <&scmi_clk MOVISOC_KMB_PSS_AUX_GBE_TX>; + snps,pbl = <0x4>; + snps,axi-config = <&stmmac_axi_setup>; + snps,mtl-rx-config = <&mtl_rx_setup>; + snps,mtl-tx-config = <&mtl_tx_setup>; + snps,tso; + status = "okay"; + + mdio0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + + ethernet-phy@0 { + reg = <0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/net/marvell,prestera.txt b/Documentation/devicetree/bindings/net/marvell,prestera.txt index 83370ebf5b89..e28938ddfdf5 100644 --- a/Documentation/devicetree/bindings/net/marvell,prestera.txt +++ b/Documentation/devicetree/bindings/net/marvell,prestera.txt @@ -45,3 +45,37 @@ dfx-server { ranges = <0 MBUS_ID(0x08, 0x00) 0 0x100000>; reg = <MBUS_ID(0x08, 0x00) 0 0x100000>; }; + +Marvell Prestera SwitchDev bindings +----------------------------------- +Optional properties: +- compatible: must be "marvell,prestera" +- base-mac-provider: describes handle to node which provides base mac address, + might be a static base mac address or nvme cell provider. + +Example: + +eeprom_mac_addr: eeprom-mac-addr { + compatible = "eeprom,mac-addr-cell"; + status = "okay"; + + nvmem = <&eeprom_at24>; +}; + +prestera { + compatible = "marvell,prestera"; + status = "okay"; + + base-mac-provider = <&eeprom_mac_addr>; +}; + +The current implementation of Prestera Switchdev PCI interface driver requires +that BAR2 is assigned to 0xf6000000 as base address from the PCI IO range: + +&cp0_pcie0 { + ranges = <0x81000000 0x0 0xfb000000 0x0 0xfb000000 0x0 0xf0000 + 0x82000000 0x0 0xf6000000 0x0 0xf6000000 0x0 0x2000000 + 0x82000000 0x0 0xf9000000 0x0 0xf9000000 0x0 0x100000>; + phys = <&cp0_comphy0 0>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/net/nfc/s3fwrn5.txt b/Documentation/devicetree/bindings/net/nfc/s3fwrn5.txt deleted file mode 100644 index f02f6fb7f81c..000000000000 --- a/Documentation/devicetree/bindings/net/nfc/s3fwrn5.txt +++ /dev/null @@ -1,25 +0,0 @@ -* Samsung S3FWRN5 NCI NFC Controller - -Required properties: -- compatible: Should be "samsung,s3fwrn5-i2c". -- reg: address on the bus -- interrupts: GPIO interrupt to which the chip is connected -- s3fwrn5,en-gpios: Output GPIO pin used for enabling/disabling the chip -- s3fwrn5,fw-gpios: Output GPIO pin used to enter firmware mode and - sleep/wakeup control - -Example: - -&hsi2c_4 { - s3fwrn5@27 { - compatible = "samsung,s3fwrn5-i2c"; - - reg = <0x27>; - - interrupt-parent = <&gpa1>; - interrupts = <3 0 0>; - - s3fwrn5,en-gpios = <&gpf1 4 0>; - s3fwrn5,fw-gpios = <&gpj0 2 0>; - }; -}; diff --git a/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml b/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml new file mode 100644 index 000000000000..cb0b8a560282 --- /dev/null +++ b/Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/nfc/samsung,s3fwrn5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S3FWRN5 NCI NFC Controller + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + - Krzysztof Opasiak <k.opasiak@samsung.com> + +properties: + compatible: + const: samsung,s3fwrn5-i2c + + en-gpios: + maxItems: 1 + description: + Output GPIO pin used for enabling/disabling the chip + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + wake-gpios: + maxItems: 1 + description: + Output GPIO pin used to enter firmware mode and sleep/wakeup control + + s3fwrn5,en-gpios: + maxItems: 1 + deprecated: true + description: + Use en-gpios + + s3fwrn5,fw-gpios: + maxItems: 1 + deprecated: true + description: + Use wake-gpios + +additionalProperties: false + +required: + - compatible + - en-gpios + - interrupts + - reg + - wake-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c4 { + #address-cells = <1>; + #size-cells = <0>; + + s3fwrn5@27 { + compatible = "samsung,s3fwrn5-i2c"; + reg = <0x27>; + + interrupt-parent = <&gpa1>; + interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; + + en-gpios = <&gpf1 4 GPIO_ACTIVE_HIGH>; + wake-gpios = <&gpj0 2 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml new file mode 100644 index 000000000000..244befb6402a --- /dev/null +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -0,0 +1,262 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/renesas,etheravb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Ethernet AVB + +maintainers: + - Sergei Shtylyov <sergei.shtylyov@gmail.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,etheravb-r8a7742 # RZ/G1H + - renesas,etheravb-r8a7743 # RZ/G1M + - renesas,etheravb-r8a7744 # RZ/G1N + - renesas,etheravb-r8a7745 # RZ/G1E + - renesas,etheravb-r8a77470 # RZ/G1C + - renesas,etheravb-r8a7790 # R-Car H2 + - renesas,etheravb-r8a7791 # R-Car M2-W + - renesas,etheravb-r8a7792 # R-Car V2H + - renesas,etheravb-r8a7793 # R-Car M2-N + - renesas,etheravb-r8a7794 # R-Car E2 + - const: renesas,etheravb-rcar-gen2 # R-Car Gen2 and RZ/G1 + + - items: + - enum: + - renesas,etheravb-r8a774a1 # RZ/G2M + - renesas,etheravb-r8a774b1 # RZ/G2N + - renesas,etheravb-r8a774c0 # RZ/G2E + - renesas,etheravb-r8a774e1 # RZ/G2H + - renesas,etheravb-r8a7795 # R-Car H3 + - renesas,etheravb-r8a7796 # R-Car M3-W + - renesas,etheravb-r8a77961 # R-Car M3-W+ + - renesas,etheravb-r8a77965 # R-Car M3-N + - renesas,etheravb-r8a77970 # R-Car V3M + - renesas,etheravb-r8a77980 # R-Car V3H + - renesas,etheravb-r8a77990 # R-Car E3 + - renesas,etheravb-r8a77995 # R-Car D3 + - const: renesas,etheravb-rcar-gen3 # R-Car Gen3 and RZ/G2 + + reg: true + + interrupts: true + + interrupt-names: true + + clocks: + maxItems: 1 + + iommus: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + phy-mode: true + + phy-handle: true + + '#address-cells': + description: Number of address cells for the MDIO bus. + const: 1 + + '#size-cells': + description: Number of size cells on the MDIO bus. + const: 0 + + renesas,no-ether-link: + type: boolean + description: + Specify when a board does not provide a proper AVB_LINK signal. + + renesas,ether-link-active-low: + type: boolean + description: + Specify when the AVB_LINK signal is active-low instead of normal + active-high. + + rx-internal-delay-ps: + enum: [0, 1800] + + tx-internal-delay-ps: + enum: [0, 2000] + +patternProperties: + "^ethernet-phy@[0-9a-f]$": + type: object + $ref: ethernet-phy.yaml# + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + - phy-mode + - phy-handle + - '#address-cells' + - '#size-cells' + +allOf: + - $ref: ethernet-controller.yaml# + + - if: + properties: + compatible: + contains: + enum: + - renesas,etheravb-rcar-gen2 + - renesas,etheravb-r8a7795 + - renesas,etheravb-r8a7796 + - renesas,etheravb-r8a77961 + - renesas,etheravb-r8a77965 + then: + properties: + reg: + items: + - description: MAC register block + - description: Stream buffer + else: + properties: + reg: + items: + - description: MAC register block + + - if: + properties: + compatible: + contains: + const: renesas,etheravb-rcar-gen2 + then: + properties: + interrupts: + maxItems: 1 + interrupt-names: + items: + - const: mux + rx-internal-delay-ps: false + else: + properties: + interrupts: + minItems: 25 + maxItems: 25 + interrupt-names: + items: + pattern: '^ch[0-9]+$' + required: + - interrupt-names + - rx-internal-delay-ps + + - if: + properties: + compatible: + contains: + enum: + - renesas,etheravb-r8a774a1 + - renesas,etheravb-r8a774b1 + - renesas,etheravb-r8a7795 + - renesas,etheravb-r8a7796 + - renesas,etheravb-r8a77961 + - renesas,etheravb-r8a77965 + - renesas,etheravb-r8a77970 + - renesas,etheravb-r8a77980 + then: + required: + - tx-internal-delay-ps + else: + properties: + tx-internal-delay-ps: false + + - if: + properties: + compatible: + contains: + const: renesas,etheravb-r8a77995 + then: + properties: + rx-internal-delay-ps: + const: 1800 + + - if: + properties: + compatible: + contains: + const: renesas,etheravb-r8a77980 + then: + properties: + tx-internal-delay-ps: + const: 2000 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + #include <dt-bindings/gpio/gpio.h> + aliases { + ethernet0 = &avb; + }; + + avb: ethernet@e6800000 { + compatible = "renesas,etheravb-r8a7795", + "renesas,etheravb-rcar-gen3"; + reg = <0xe6800000 0x800>, <0xe6a00000 0x10000>; + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 45 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 46 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 63 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "ch0", "ch1", "ch2", "ch3", "ch4", "ch5", "ch6", + "ch7", "ch8", "ch9", "ch10", "ch11", "ch12", + "ch13", "ch14", "ch15", "ch16", "ch17", "ch18", + "ch19", "ch20", "ch21", "ch22", "ch23", "ch24"; + clocks = <&cpg CPG_MOD 812>; + iommus = <&ipmmu_ds0 16>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 812>; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + rx-internal-delay-ps = <0>; + tx-internal-delay-ps = <2000>; + #address-cells = <1>; + #size-cells = <0>; + + phy0: ethernet-phy@0 { + rxc-skew-ps = <1500>; + reg = <0>; + interrupt-parent = <&gpio2>; + interrupts = <11 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&gpio2 10 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt deleted file mode 100644 index 9119f1caf391..000000000000 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ /dev/null @@ -1,135 +0,0 @@ -* Renesas Electronics Ethernet AVB - -This file provides information on what the device node for the Ethernet AVB -interface contains. - -Required properties: -- compatible: Must contain one or more of the following: - - "renesas,etheravb-r8a7742" for the R8A7742 SoC. - - "renesas,etheravb-r8a7743" for the R8A7743 SoC. - - "renesas,etheravb-r8a7744" for the R8A7744 SoC. - - "renesas,etheravb-r8a7745" for the R8A7745 SoC. - - "renesas,etheravb-r8a77470" for the R8A77470 SoC. - - "renesas,etheravb-r8a7790" for the R8A7790 SoC. - - "renesas,etheravb-r8a7791" for the R8A7791 SoC. - - "renesas,etheravb-r8a7792" for the R8A7792 SoC. - - "renesas,etheravb-r8a7793" for the R8A7793 SoC. - - "renesas,etheravb-r8a7794" for the R8A7794 SoC. - - "renesas,etheravb-rcar-gen2" as a fallback for the above - R-Car Gen2 and RZ/G1 devices. - - - "renesas,etheravb-r8a774a1" for the R8A774A1 SoC. - - "renesas,etheravb-r8a774b1" for the R8A774B1 SoC. - - "renesas,etheravb-r8a774c0" for the R8A774C0 SoC. - - "renesas,etheravb-r8a774e1" for the R8A774E1 SoC. - - "renesas,etheravb-r8a7795" for the R8A7795 SoC. - - "renesas,etheravb-r8a7796" for the R8A77960 SoC. - - "renesas,etheravb-r8a77961" for the R8A77961 SoC. - - "renesas,etheravb-r8a77965" for the R8A77965 SoC. - - "renesas,etheravb-r8a77970" for the R8A77970 SoC. - - "renesas,etheravb-r8a77980" for the R8A77980 SoC. - - "renesas,etheravb-r8a77990" for the R8A77990 SoC. - - "renesas,etheravb-r8a77995" for the R8A77995 SoC. - - "renesas,etheravb-rcar-gen3" as a fallback for the above - R-Car Gen3 and RZ/G2 devices. - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first followed by - the generic version. - -- reg: Offset and length of (1) the register block and (2) the stream buffer. - The region for the register block is mandatory. - The region for the stream buffer is optional, as it is only present on - R-Car Gen2 and RZ/G1 SoCs, and on R-Car H3 (R8A7795), M3-W (R8A77960), - M3-W+ (R8A77961), and M3-N (R8A77965). -- interrupts: A list of interrupt-specifiers, one for each entry in - interrupt-names. - If interrupt-names is not present, an interrupt specifier - for a single muxed interrupt. -- phy-mode: see ethernet.txt file in the same directory. -- phy-handle: see ethernet.txt file in the same directory. -- #address-cells: number of address cells for the MDIO bus, must be equal to 1. -- #size-cells: number of size cells on the MDIO bus, must be equal to 0. -- clocks: clock phandle and specifier pair. -- pinctrl-0: phandle, referring to a default pin configuration node. - -Optional properties: -- interrupt-names: A list of interrupt names. - For the R-Car Gen 3 SoCs this property is mandatory; - it should include one entry per channel, named "ch%u", - where %u is the channel number ranging from 0 to 24. - For other SoCs this property is optional; if present - it should contain "mux" for a single muxed interrupt. -- pinctrl-names: pin configuration state name ("default"). -- renesas,no-ether-link: boolean, specify when a board does not provide a proper - AVB_LINK signal. -- renesas,ether-link-active-low: boolean, specify when the AVB_LINK signal is - active-low instead of normal active-high. - -Example: - - ethernet@e6800000 { - compatible = "renesas,etheravb-r8a7795", "renesas,etheravb-rcar-gen3"; - reg = <0 0xe6800000 0 0x800>, <0 0xe6a00000 0 0x10000>; - interrupt-parent = <&gic>; - interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 45 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 46 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 63 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "ch0", "ch1", "ch2", "ch3", - "ch4", "ch5", "ch6", "ch7", - "ch8", "ch9", "ch10", "ch11", - "ch12", "ch13", "ch14", "ch15", - "ch16", "ch17", "ch18", "ch19", - "ch20", "ch21", "ch22", "ch23", - "ch24"; - clocks = <&cpg CPG_MOD 812>; - power-domains = <&cpg>; - phy-mode = "rgmii-id"; - phy-handle = <&phy0>; - - pinctrl-0 = <ðer_pins>; - pinctrl-names = "default"; - renesas,no-ether-link; - #address-cells = <1>; - #size-cells = <0>; - - phy0: ethernet-phy@0 { - rxc-skew-ps = <900>; - rxdv-skew-ps = <0>; - rxd0-skew-ps = <0>; - rxd1-skew-ps = <0>; - rxd2-skew-ps = <0>; - rxd3-skew-ps = <0>; - txc-skew-ps = <900>; - txen-skew-ps = <0>; - txd0-skew-ps = <0>; - txd1-skew-ps = <0>; - txd2-skew-ps = <0>; - txd3-skew-ps = <0>; - reg = <0>; - interrupt-parent = <&gpio2>; - interrupts = <11 IRQ_TYPE_LEVEL_LOW>; - }; - }; diff --git a/Documentation/devicetree/bindings/net/smsc-lan87xx.txt b/Documentation/devicetree/bindings/net/smsc-lan87xx.txt index 8b7c719b0bb9..a8d0dc9a8c0e 100644 --- a/Documentation/devicetree/bindings/net/smsc-lan87xx.txt +++ b/Documentation/devicetree/bindings/net/smsc-lan87xx.txt @@ -5,6 +5,10 @@ through an Ethernet OF device node. Optional properties: +- clocks: + The clock used as phy reference clock and is connected to phy + pin XTAL1/CLKIN. + - smsc,disable-energy-detect: If set, do not enable energy detect mode for the SMSC phy. default: enable energy detect mode diff --git a/Documentation/devicetree/bindings/net/socionext-netsec.txt b/Documentation/devicetree/bindings/net/socionext-netsec.txt index 9d6c9feb12ff..a3c1dffaa4bb 100644 --- a/Documentation/devicetree/bindings/net/socionext-netsec.txt +++ b/Documentation/devicetree/bindings/net/socionext-netsec.txt @@ -30,7 +30,9 @@ Optional properties: (See ethernet.txt file in the same directory) - max-frame-size: See ethernet.txt in the same directory. The MAC address will be determined using the optional properties -defined in ethernet.txt. +defined in ethernet.txt. The 'phy-mode' property is required, but may +be set to the empty string if the PHY configuration is programmed by +the firmware or set by hardware straps, and needs to be preserved. Example: eth0: ethernet@522d0000 { diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml new file mode 100644 index 000000000000..75e8712e903a --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause) +# Copyright (C) 2020 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/ti,dp83822.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TI DP83822 ethernet PHY + +maintainers: + - Dan Murphy <dmurphy@ti.com> + +description: | + The DP83822 is a low-power, single-port, 10/100 Mbps Ethernet PHY. It + provides all of the physical layer functions needed to transmit and receive + data over standard, twisted-pair cables or to connect to an external, + fiber-optic transceiver. Additionally, the DP83822 provides flexibility to + connect to a MAC through a standard MII, RMII, or RGMII interface + + Specifications about the Ethernet PHY can be found at: + http://www.ti.com/lit/ds/symlink/dp83822i.pdf + +allOf: + - $ref: "ethernet-phy.yaml#" + +properties: + reg: + maxItems: 1 + + ti,link-loss-low: + type: boolean + description: | + DP83822 PHY in Fiber mode only. + Sets the DP83822 to detect a link drop condition when the signal goes + high. If not set then link drop will occur when the signal goes low. + This property is only applicable if the fiber mode support is strapped + to on. + + ti,fiber-mode: + type: boolean + description: | + DP83822 PHY only. + If present the DP83822 PHY is configured to operate in fiber mode + Fiber mode support can also be strapped. If the strap pin is not set + correctly or not set at all then this boolean can be used to enable it. + If the fiber mode is not strapped then signal detection for the PHY + is disabled. + In fiber mode, auto-negotiation is disabled and the PHY can only work in + 100base-fx (full and half duplex) modes. + + rx-internal-delay-ps: + description: | + DP83822 PHY only. + Setting this property to a non-zero number sets the RX internal delay + for the PHY. The internal delay for the PHY is fixed to 3.5ns relative + to receive data. + + tx-internal-delay-ps: + description: | + DP83822 PHY only. + Setting this property to a non-zero number sets the TX internal delay + for the PHY. The internal delay for the PHY is fixed to 3.5ns relative + to transmit data. + +required: + - reg + +unevaluatedProperties: false + +examples: + - | + mdio0 { + #address-cells = <1>; + #size-cells = <0>; + ethphy0: ethernet-phy@0 { + reg = <0>; + rx-internal-delay-ps = <1>; + tx-internal-delay-ps = <1>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 65ee68efd574..b61c2d5a0ff7 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -65,7 +65,8 @@ Optional properties: the length can vary between hw versions. - <supply-name>-supply: handle to the regulator device tree node optional "supply-name" are "vdd-0.8-cx-mx", - "vdd-1.8-xo", "vdd-1.3-rfa" and "vdd-3.3-ch0". + "vdd-1.8-xo", "vdd-1.3-rfa", "vdd-3.3-ch0", + and "vdd-3.3-ch1". - memory-region: Usage: optional Value type: <phandle> @@ -204,6 +205,7 @@ wifi@18000000 { vdd-1.8-xo-supply = <&vreg_l7a_1p8>; vdd-1.3-rfa-supply = <&vreg_l17a_1p3>; vdd-3.3-ch0-supply = <&vreg_l25a_3p3>; + vdd-3.3-ch1-supply = <&vreg_l26a_3p3>; memory-region = <&wifi_msa_mem>; iommus = <&apps_smmu 0x0040 0x1>; qcom,msa-fixed-perm; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml index a1717db36dba..4b365c9d9378 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -17,7 +17,9 @@ description: | properties: compatible: - const: qcom,ipq8074-wifi + enum: + - qcom,ipq8074-wifi + - qcom,ipq6018-wifi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt b/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt index 56ed481c3e26..72ba628f6d0b 100644 --- a/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt @@ -2,7 +2,7 @@ On-Chip OTP Memory for Freescale Vybrid Required Properties: compatible: - - "fsl,vf610-ocotp" for VF5xx/VF6xx + - "fsl,vf610-ocotp", "syscon" for VF5xx/VF6xx #address-cells : Should be 1 #size-cells : Should be 1 reg : Address and length of OTP controller and fuse map registers @@ -11,7 +11,7 @@ Required Properties: Example for Vybrid VF5xx/VF6xx: ocotp: ocotp@400a5000 { - compatible = "fsl,vf610-ocotp"; + compatible = "fsl,vf610-ocotp", "syscon"; #address-cells = <1>; #size-cells = <1>; reg = <0x400a5000 0xCF0>; diff --git a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml index 8680a0f86c5a..807694b4f41f 100644 --- a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml @@ -9,12 +9,15 @@ title: Brcmstb PCIe Host Controller Device Tree Bindings maintainers: - Nicolas Saenz Julienne <nsaenzjulienne@suse.de> -allOf: - - $ref: /schemas/pci/pci-bus.yaml# - properties: compatible: - const: brcm,bcm2711-pcie # The Raspberry Pi 4 + items: + - enum: + - brcm,bcm2711-pcie # The Raspberry Pi 4 + - brcm,bcm7211-pcie # Broadcom STB version of RPi4 + - brcm,bcm7278-pcie # Broadcom 7278 Arm + - brcm,bcm7216-pcie # Broadcom 7216 Arm + - brcm,bcm7445-pcie # Broadcom 7445 Arm reg: maxItems: 1 @@ -34,10 +37,12 @@ properties: - const: msi ranges: - maxItems: 1 + minItems: 1 + maxItems: 4 dma-ranges: - maxItems: 1 + minItems: 1 + maxItems: 6 clocks: maxItems: 1 @@ -58,8 +63,31 @@ properties: aspm-no-l0s: true + resets: + description: for "brcm,bcm7216-pcie", must be a valid reset + phandle pointing to the RESCAL reset controller provider node. + $ref: "/schemas/types.yaml#/definitions/phandle" + + reset-names: + items: + - const: rescal + + brcm,scb-sizes: + description: u64 giving the 64bit PCIe memory + viewport size of a memory controller. There may be up to + three controllers, and each size must be a power of two + with a size greater or equal to the amount of memory the + controller supports. Note that each memory controller + may have two component regions -- base and extended -- so + this information cannot be deduced from the dma-ranges. + $ref: /schemas/types.yaml#/definitions/uint64-array + items: + minItems: 1 + maxItems: 3 + required: - reg + - ranges - dma-ranges - "#interrupt-cells" - interrupts @@ -68,6 +96,18 @@ required: - interrupt-map - msi-controller +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - if: + properties: + compatible: + contains: + const: brcm,bcm7216-pcie + then: + required: + - resets + - reset-names + unevaluatedProperties: false examples: @@ -93,7 +133,9 @@ examples: msi-parent = <&pcie0>; msi-controller; ranges = <0x02000000 0x0 0xf8000000 0x6 0x00000000 0x0 0x04000000>; - dma-ranges = <0x02000000 0x0 0x00000000 0x0 0x00000000 0x0 0x80000000>; + dma-ranges = <0x42000000 0x1 0x00000000 0x0 0x40000000 0x0 0x80000000>, + <0x42000000 0x1 0x80000000 0x3 0x00000000 0x0 0x80000000>; brcm,enable-ssc; + brcm,scb-sizes = <0x0000000080000000 0x0000000080000000>; }; }; diff --git a/Documentation/devicetree/bindings/pci/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt index 99a386ea691c..daa99f7d4c3f 100644 --- a/Documentation/devicetree/bindings/pci/layerscape-pci.txt +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -24,6 +24,8 @@ Required properties: "fsl,ls1028a-pcie" EP mode: "fsl,ls1046a-pcie-ep", "fsl,ls-pcie-ep" + "fsl,ls1088a-pcie-ep", "fsl,ls-pcie-ep" + "fsl,ls2088a-pcie-ep", "fsl,ls-pcie-ep" - reg: base addresses and lengths of the PCIe controller register blocks. - interrupts: A list of interrupt outputs of the controller. Must contain an entry for each entry in the interrupt-names property. diff --git a/Documentation/devicetree/bindings/pci/rcar-pci-ep.yaml b/Documentation/devicetree/bindings/pci/rcar-pci-ep.yaml index 53d5952b7e57..84eeb7fe6e01 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci-ep.yaml +++ b/Documentation/devicetree/bindings/pci/rcar-pci-ep.yaml @@ -14,8 +14,12 @@ maintainers: properties: compatible: items: - - const: renesas,r8a774c0-pcie-ep - - const: renesas,rcar-gen3-pcie-ep + - enum: + - renesas,r8a774a1-pcie-ep # RZ/G2M + - renesas,r8a774b1-pcie-ep # RZ/G2N + - renesas,r8a774c0-pcie-ep # RZ/G2E + - renesas,r8a774e1-pcie-ep # RZ/G2H + - const: renesas,rcar-gen3-pcie-ep # R-Car Gen3 and RZ/G2 reg: maxItems: 5 diff --git a/Documentation/devicetree/bindings/pci/rcar-pci.txt b/Documentation/devicetree/bindings/pci/rcar-pci.txt index 1041c44a614f..14d307deff06 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -1,7 +1,8 @@ * Renesas R-Car PCIe interface Required properties: -compatible: "renesas,pcie-r8a7743" for the R8A7743 SoC; +compatible: "renesas,pcie-r8a7742" for the R8A7742 SoC; + "renesas,pcie-r8a7743" for the R8A7743 SoC; "renesas,pcie-r8a7744" for the R8A7744 SoC; "renesas,pcie-r8a774a1" for the R8A774A1 SoC; "renesas,pcie-r8a774b1" for the R8A774B1 SoC; diff --git a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml index f0558b9cf9e9..d6cf8a560ef0 100644 --- a/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml @@ -23,14 +23,22 @@ properties: const: socionext,uniphier-pro5-pcie-ep reg: - maxItems: 4 + minItems: 4 + maxItems: 5 reg-names: - items: - - const: dbi - - const: dbi2 - - const: link - - const: addr_space + oneOf: + - items: + - const: dbi + - const: dbi2 + - const: link + - const: addr_space + - items: + - const: dbi + - const: dbi2 + - const: link + - const: addr_space + - const: atu clocks: maxItems: 2 diff --git a/Documentation/devicetree/bindings/pci/uniphier-pcie.txt b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt index 1fa2c5906d4d..c4b7381733a0 100644 --- a/Documentation/devicetree/bindings/pci/uniphier-pcie.txt +++ b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt @@ -16,6 +16,7 @@ Required properties: "dbi" - controller configuration registers "link" - SoC-specific glue layer registers "config" - PCIe configuration space + "atu" - iATU registers for DWC version 4.80 or later - clocks: A phandle to the clock gate for PCIe glue layer including the host controller. - resets: A phandle to the reset line for PCIe glue layer including 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/amlogic,meson-ee-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml index 4f524f822e84..d30f85cc395e 100644 --- a/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml +++ b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml @@ -27,6 +27,7 @@ properties: - amlogic,meson8b-pwrc - amlogic,meson8m2-pwrc - amlogic,meson-gxbb-pwrc + - amlogic,meson-axg-pwrc - amlogic,meson-g12a-pwrc - amlogic,meson-sm1-pwrc @@ -42,11 +43,11 @@ properties: - const: vapb resets: - minItems: 11 + minItems: 5 maxItems: 12 reset-names: - minItems: 11 + minItems: 5 maxItems: 12 "#power-domain-cells": @@ -111,6 +112,24 @@ allOf: properties: compatible: enum: + - amlogic,meson-axg-pwrc + then: + properties: + reset-names: + items: + - const: viu + - const: venc + - const: vcbus + - const: vencl + - const: vid_lock + required: + - resets + - reset-names + + - if: + properties: + compatible: + enum: - amlogic,meson-g12a-pwrc - amlogic,meson-sm1-pwrc then: diff --git a/Documentation/devicetree/bindings/power/brcm,bcm63xx-power.yaml b/Documentation/devicetree/bindings/power/brcm,bcm63xx-power.yaml new file mode 100644 index 000000000000..63b15ac6dde4 --- /dev/null +++ b/Documentation/devicetree/bindings/power/brcm,bcm63xx-power.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/brcm,bcm63xx-power.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: BCM63xx power domain driver + +maintainers: + - Álvaro Fernández Rojas <noltari@gmail.com> + +description: | + BCM6318, BCM6328, BCM6362 and BCM63268 SoCs have a power domain controller + to enable/disable certain components in order to save power. + +properties: + compatible: + items: + - enum: + - brcm,bcm6318-power-controller + - brcm,bcm6328-power-controller + - brcm,bcm6362-power-controller + - brcm,bcm63268-power-controller + + reg: + maxItems: 1 + + "#power-domain-cells": + const: 1 + +required: + - compatible + - reg + - "#power-domain-cells" + +additionalProperties: false + +examples: + - | + periph_pwr: power-controller@10001848 { + compatible = "brcm,bcm6328-power-controller"; + reg = <0x10001848 0x4>; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml index ec2aaeee78dc..99e8042ac111 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml @@ -40,6 +40,7 @@ properties: - renesas,r8a77980-sysc # R-Car V3H - renesas,r8a77990-sysc # R-Car E3 - renesas,r8a77995-sysc # R-Car D3 + - renesas,r8a779a0-sysc # R-Car V3U reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt index 1b4213eb3473..4d530d815484 100644 --- a/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt +++ b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt @@ -1,10 +1,13 @@ Microsemi Ocelot reset controller The DEVCPU_GCB:CHIP_REGS have a SOFT_RST register that can be used to reset the -SoC MIPS core. +SoC core. + +The reset registers are both present in the MSCC vcoreiii MIPS and +microchip Sparx5 armv8 SoC's. Required Properties: - - compatible: "mscc,ocelot-chip-reset" + - compatible: "mscc,ocelot-chip-reset" or "microchip,sparx5-chip-reset" Example: reset@1070008 { diff --git a/Documentation/devicetree/bindings/power/reset/reboot-mode.txt b/Documentation/devicetree/bindings/power/reset/reboot-mode.txt deleted file mode 100644 index de34f27d509e..000000000000 --- a/Documentation/devicetree/bindings/power/reset/reboot-mode.txt +++ /dev/null @@ -1,25 +0,0 @@ -Generic reboot mode core map driver - -This driver get reboot mode arguments and call the write -interface to store the magic value in special register -or ram. Then the bootloader can read it and take different -action according to the argument stored. - -All mode properties are vendor specific, it is a indication to tell -the bootloader what to do when the system reboots, and should be named -as mode-xxx = <magic> (xxx is mode name, magic should be a none-zero value). - -For example modes common on Android platform: -- mode-normal: Normal reboot mode, system reboot with command "reboot". -- mode-recovery: Android Recovery mode, it is a mode to format the device or update a new image. -- mode-bootloader: Android fastboot mode, it's a mode to re-flash partitions on the Android based device. -- mode-loader: A bootloader mode, it's a mode used to download image on Rockchip platform, - usually used in development. - -Example: - reboot-mode { - mode-normal = <BOOT_NORMAL>; - mode-recovery = <BOOT_RECOVERY>; - mode-bootloader = <BOOT_FASTBOOT>; - mode-loader = <BOOT_BL_DOWNLOAD>; - } diff --git a/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml new file mode 100644 index 000000000000..9c6fda6b1dd9 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/reboot-mode.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/reboot-mode.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic reboot mode core map + +maintainers: + - Andy Yan <andy.yan@rock-chips.com> + +description: | + This driver get reboot mode arguments and call the write + interface to store the magic value in special register + or ram. Then the bootloader can read it and take different + action according to the argument stored. + + All mode properties are vendor specific, it is a indication to tell + the bootloader what to do when the system reboots, and should be named + as mode-xxx = <magic> (xxx is mode name, magic should be a non-zero value). + + For example, modes common Android platform are: + - normal: Normal reboot mode, system reboot with command "reboot". + - recovery: Android Recovery mode, it is a mode to format the device or update a new image. + - bootloader: Android fastboot mode, it's a mode to re-flash partitions on the Android based device. + - loader: A bootloader mode, it's a mode used to download image on Rockchip platform, + usually used in development. + +properties: + mode-normal: + $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 { + mode-normal = <0>; + mode-recovery = <1>; + mode-bootloader = <2>; + mode-loader = <3>; + }; +... diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml index 932b736ce5c0..0c7e2e44793b 100644 --- a/Documentation/devicetree/bindings/power/supply/battery.yaml +++ b/Documentation/devicetree/bindings/power/supply/battery.yaml @@ -82,6 +82,27 @@ properties: An array containing the temperature in degree Celsius, for each of the battery capacity lookup table. + operating-range-celsius: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: operating temperature range of a battery + items: + - description: minimum temperature at which battery can operate + - description: maximum temperature at which battery can operate + + ambient-celsius: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: safe range of ambient temperature + items: + - description: alert when ambient temperature is lower than this value + - description: alert when ambient temperature is higher than this value + + alert-celsius: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: safe range of battery temperature + items: + - description: alert when battery temperature is lower than this value + - description: alert when battery temperature is higher than this value + required: - compatible @@ -130,6 +151,9 @@ examples: /* table for 10 degree Celsius */ ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>; resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>; + operating-range-celsius = <(-30) 50>; + ambient-celsius = <(-5) 50>; + alert-celsius = <0 40>; }; charger@11 { diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.txt b/Documentation/devicetree/bindings/power/supply/bq25890.txt index 3b4c69a7fa70..805040c6fff9 100644 --- a/Documentation/devicetree/bindings/power/supply/bq25890.txt +++ b/Documentation/devicetree/bindings/power/supply/bq25890.txt @@ -33,6 +33,10 @@ Optional properties: - ti,thermal-regulation-threshold: integer, temperature above which the charge current is lowered, to avoid overheating (in degrees Celsius). If omitted, the default setting will be used (120 degrees); +- ti,ibatcomp-micro-ohms: integer, value of a resistor in series with + the battery; +- ti,ibatcomp-clamp-microvolt: integer, maximum charging voltage adjustment due + to expected voltage drop on in-series resistor; Example: diff --git a/Documentation/devicetree/bindings/power/supply/bq25980.yaml b/Documentation/devicetree/bindings/power/supply/bq25980.yaml new file mode 100644 index 000000000000..f6b3dd4093ca --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq25980.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/bq25980.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: TI BQ25980 Flash Charger + +maintainers: + - Dan Murphy <dmurphy@ti.com> + - Ricardo Rivera-Matos <r-rivera-matos@ti.com> + +description: | + The BQ25980, BQ25975, and BQ25960 are a series of flash chargers intended + for use in high-power density portable electronics. These inductorless + switching chargers can provide over 97% efficiency by making use of the + switched capacitor architecture. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + enum: + - ti,bq25980 + - ti,bq25975 + - ti,bq25960 + + reg: + maxItems: 1 + + ti,watchdog-timeout-ms: + description: | + Watchdog timer in milli seconds. 0 disables the watchdog. + default: 0 + minimum: 0 + maximum: 300000 + enum: [ 0, 5000, 10000, 50000, 300000] + + ti,sc-ovp-limit-microvolt: + description: | + Minimum input voltage limit in micro volts with a when the charger is in + switch cap mode. 100000 micro volt step. + default: 17800000 + minimum: 14000000 + maximum: 22000000 + + ti,sc-ocp-limit-microamp: + description: | + Maximum input current limit in micro amps with a 100000 micro amp step. + minimum: 100000 + maximum: 3300000 + + ti,bypass-ovp-limit-microvolt: + description: | + Minimum input voltage limit in micro volts with a when the charger is in + switch cap mode. 50000 micro volt step. + minimum: 7000000 + maximum: 12750000 + + ti,bypass-ocp-limit-microamp: + description: | + Maximum input current limit in micro amps with a 100000 micro amp step. + minimum: 100000 + maximum: 3300000 + + ti,bypass-enable: + type: boolean + description: Enables bypass mode at boot time + + interrupts: + description: | + Indicates that the device state has changed. + + monitored-battery: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the battery node being monitored + +required: + - compatible + - reg + - monitored-battery + +unevaluatedProperties: false + +examples: + - | + bat: battery { + compatible = "simple-battery"; + constant-charge-current-max-microamp = <4000000>; + constant-charge-voltage-max-microvolt = <8400000>; + precharge-current-microamp = <160000>; + charge-term-current-microamp = <160000>; + }; + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + bq25980: charger@65 { + compatible = "ti,bq25980"; + reg = <0x65>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_FALLING>; + ti,watchdog-timer = <0>; + ti,sc-ocp-limit-microamp = <2000000>; + ti,sc-ovp-limit-microvolt = <17800000>; + monitored-battery = <&bat>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml index 82f682705f44..45beefccf31a 100644 --- a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml +++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml @@ -51,6 +51,7 @@ properties: - ti,bq27621 - ti,bq27z561 - ti,bq28z610 + - ti,bq34z100 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/supply/charger-manager.txt b/Documentation/devicetree/bindings/power/supply/charger-manager.txt index ec4fe9de3137..b5ae9061b7a0 100644 --- a/Documentation/devicetree/bindings/power/supply/charger-manager.txt +++ b/Documentation/devicetree/bindings/power/supply/charger-manager.txt @@ -3,24 +3,32 @@ charger-manager bindings Required properties : - compatible : "charger-manager" - - <>-supply : for regulator consumer - - cm-num-chargers : number of chargers + - <>-supply : for regulator consumer, named according to cm-regulator-name - cm-chargers : name of chargers - cm-fuel-gauge : name of battery fuel gauge - subnode <regulator> : - cm-regulator-name : name of charger regulator - subnode <cable> : - - cm-cable-name : name of charger cable + - cm-cable-name : name of charger cable - one of USB, USB-HOST, + SDP, DCP, CDP, ACA, FAST-CHARGER, SLOW-CHARGER, WPT, + PD, DOCK, JIG, or MECHANICAL - cm-cable-extcon : name of extcon dev (optional) - cm-cable-min : minimum current of cable (optional) - cm-cable-max : maximum current of cable Optional properties : - cm-name : charger manager's name (default : "battery") - - cm-poll-mode : polling mode (enum polling_modes) - - cm-poll-interval : polling interval - - cm-battery-stat : battery status (enum data_source) - - cm-fullbatt-* : data for full battery checking + - cm-poll-mode : polling mode - 0 for disabled, 1 for always, 2 for when + external power is connected, or 3 for when charging. If not present, + then polling is disabled + - cm-poll-interval : polling interval (in ms) + - cm-battery-stat : battery status - 0 for battery always present, 1 for no + battery, 2 to check presence via fuel gauge, or 3 to check presence + via charger + - cm-fullbatt-vchkdrop-volt : voltage drop (in uV) before restarting charging + - cm-fullbatt-voltage : voltage (in uV) of full battery + - cm-fullbatt-soc : state of charge to consider as full battery + - cm-fullbatt-capacity : capcity (in uAh) to consider as full battery - cm-thermal-zone : name of external thermometer's thermal zone - cm-battery-* : threshold battery temperature for charging -cold : critical cold temperature of battery for charging @@ -29,6 +37,10 @@ Optional properties : -temp-diff : temperature difference to allow recharging - cm-dis/charging-max = limits of charging duration +Deprecated properties: + - cm-num-chargers + - cm-fullbatt-vchkdrop-ms + Example : charger-manager@0 { compatible = "charger-manager"; @@ -39,13 +51,11 @@ Example : cm-poll-mode = <1>; cm-poll-interval = <30000>; - cm-fullbatt-vchkdrop-ms = <30000>; cm-fullbatt-vchkdrop-volt = <150000>; cm-fullbatt-soc = <100>; cm-battery-stat = <3>; - cm-num-chargers = <3>; cm-chargers = "charger0", "charger1", "charger2"; cm-fuel-gauge = "fuelgauge0"; @@ -71,7 +81,7 @@ Example : cm-cable-max = <500000>; }; cable@1 { - cm-cable-name = "TA"; + cm-cable-name = "SDP"; cm-cable-extcon = "extcon-dev.0"; cm-cable-min = <650000>; cm-cable-max = <675000>; diff --git a/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml b/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml index 6244b8ee9402..89f8e2bcb2d7 100644 --- a/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml @@ -39,6 +39,25 @@ properties: maxItems: 1 description: GPIO indicating the charging status + charge-current-limit-gpios: + minItems: 1 + maxItems: 32 + description: GPIOs used for current limiting + + charge-current-limit-mapping: + description: List of tuples with current in uA and a GPIO bitmap (in + this order). The tuples must be provided in descending order of the + current limit. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: + Current limit in uA + - description: + Encoded GPIO setting. Bit 0 represents last GPIO from the + charge-current-limit-gpios property. Bit 1 second to last + GPIO and so on. + required: - compatible @@ -47,6 +66,12 @@ anyOf: - gpios - required: - charge-status-gpios + - required: + - charge-current-limit-gpios + +dependencies: + charge-current-limit-gpios: [ charge-current-limit-mapping ] + charge-current-limit-mapping: [ charge-current-limit-gpios ] additionalProperties: false @@ -60,4 +85,10 @@ examples: gpios = <&gpd 28 GPIO_ACTIVE_LOW>; charge-status-gpios = <&gpc 27 GPIO_ACTIVE_LOW>; + + charge-current-limit-gpios = <&gpioA 11 GPIO_ACTIVE_HIGH>, + <&gpioA 12 GPIO_ACTIVE_HIGH>; + charge-current-limit-mapping = <2500000 0x00>, // 2.5 A => both GPIOs low + <700000 0x01>, // 700 mA => GPIO A.12 high + <0 0x02>; // 0 mA => GPIO A.11 high }; diff --git a/Documentation/devicetree/bindings/power/supply/ingenic,battery.txt b/Documentation/devicetree/bindings/power/supply/ingenic,battery.txt deleted file mode 100644 index 66430bf73815..000000000000 --- a/Documentation/devicetree/bindings/power/supply/ingenic,battery.txt +++ /dev/null @@ -1,31 +0,0 @@ -* Ingenic JZ47xx battery bindings - -Required properties: - -- compatible: Must be "ingenic,jz4740-battery". -- io-channels: phandle and IIO specifier pair to the IIO device. - Format described in iio-bindings.txt. -- monitored-battery: phandle to a "simple-battery" compatible node. - -The "monitored-battery" property must be a phandle to a node using the format -described in battery.txt, with the following properties being required: - -- voltage-min-design-microvolt: Drained battery voltage. -- voltage-max-design-microvolt: Fully charged battery voltage. - -Example: - -#include <dt-bindings/iio/adc/ingenic,adc.h> - -simple_battery: battery { - compatible = "simple-battery"; - voltage-min-design-microvolt = <3600000>; - voltage-max-design-microvolt = <4200000>; -}; - -ingenic_battery { - compatible = "ingenic,jz4740-battery"; - io-channels = <&adc INGENIC_ADC_BATTERY>; - io-channel-names = "battery"; - monitored-battery = <&simple_battery>; -}; diff --git a/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml b/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml new file mode 100644 index 000000000000..76c227a7cd5c --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019-2020 Artur Rojek +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/ingenic,battery.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Ingenic JZ47xx battery bindings + +maintainers: + - Artur Rojek <contact@artur-rojek.eu> + +properties: + compatible: + oneOf: + - const: ingenic,jz4740-battery + - items: + - enum: + - ingenic,jz4725b-battery + - ingenic,jz4770-battery + - const: ingenic,jz4740-battery + + io-channels: + maxItems: 1 + + io-channel-names: + const: battery + + monitored-battery: + description: > + phandle to a "simple-battery" compatible node. + + This property must be a phandle to a node using the format described + in battery.yaml, with the following properties being required: + - voltage-min-design-microvolt: drained battery voltage, + - voltage-max-design-microvolt: fully charged battery voltage. + +required: + - compatible + - io-channels + - io-channel-names + - monitored-battery + +additionalProperties: false + +examples: + - | + #include <dt-bindings/iio/adc/ingenic,adc.h> + + simple_battery: battery { + compatible = "simple-battery"; + voltage-min-design-microvolt = <3600000>; + voltage-max-design-microvolt = <4200000>; + }; + + ingenic-battery { + compatible = "ingenic,jz4740-battery"; + io-channels = <&adc INGENIC_ADC_BATTERY>; + io-channel-names = "battery"; + monitored-battery = <&simple_battery>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/max17040_battery.txt b/Documentation/devicetree/bindings/power/supply/max17040_battery.txt index 4e0186b8380f..c802f664b508 100644 --- a/Documentation/devicetree/bindings/power/supply/max17040_battery.txt +++ b/Documentation/devicetree/bindings/power/supply/max17040_battery.txt @@ -2,7 +2,9 @@ max17040_battery ~~~~~~~~~~~~~~~~ Required properties : - - compatible : "maxim,max17040" or "maxim,max77836-battery" + - compatible : "maxim,max17040", "maxim,max17041", "maxim,max17043", + "maxim,max17044", "maxim,max17048", "maxim,max17049", + "maxim,max17058", "maxim,max17059" or "maxim,max77836-battery" - reg: i2c slave address Optional properties : @@ -11,6 +13,15 @@ Optional properties : generated. Can be configured from 1 up to 32 (%). If skipped the power up default value of 4 (%) will be used. +- maxim,double-soc : Certain devices return double the capacity. + Specify this boolean property to divide the + reported value in 2 and thus normalize it. + SOC == State of Charge == Capacity. +- maxim,rcomp : A value to compensate readings for various + battery chemistries and operating temperatures. + max17040,41 have 2 byte rcomp, default to + 0x97 0x00. All other devices have one byte + rcomp, default to 0x97. - interrupts : Interrupt line see Documentation/devicetree/ bindings/interrupt-controller/interrupts.txt - wakeup-source : This device has wakeup capabilities. Use this @@ -31,3 +42,11 @@ Example: interrupts = <2 IRQ_TYPE_EDGE_FALLING>; wakeup-source; }; + + battery-fuel-gauge@36 { + compatible = "maxim,max17048"; + reg = <0x36>; + maxim,rcomp = /bits/ 8 <0x56>; + maxim,alert-low-soc-level = <10>; + maxim,double-soc; + }; diff --git a/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml new file mode 100644 index 000000000000..983fc215c1e5 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml @@ -0,0 +1,152 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/power/supply/summit,smb347-charger.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Battery charger driver for SMB345, SMB347 and SMB358 + +maintainers: + - David Heidelberg <david@ixit.cz> + - Dmitry Osipenko <digetx@gmail.com> + +properties: + compatible: + enum: + - summit,smb345 + - summit,smb347 + - summit,smb358 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + monitored-battery: + description: phandle to the battery node + $ref: /schemas/types.yaml#/definitions/phandle + + summit,enable-usb-charging: + type: boolean + description: Enable charging through USB. + + summit,enable-otg-charging: + type: boolean + description: Provide power for USB OTG + + summit,enable-mains-charging: + type: boolean + description: Enable charging through mains + + summit,enable-charge-control: + description: Enable charging control + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # SMB3XX_CHG_ENABLE_SW SW (I2C interface) + - 1 # SMB3XX_CHG_ENABLE_PIN_ACTIVE_LOW Pin control (Active Low) + - 2 # SMB3XX_CHG_ENABLE_PIN_ACTIVE_HIGH Pin control (Active High) + + summit,fast-voltage-threshold-microvolt: + description: Voltage threshold to transit to fast charge mode (in uV) + minimum: 2400000 + maximum: 3000000 + + summit,mains-current-limit-microamp: + description: Maximum input current from AC/DC input (in uA) + + summit,usb-current-limit-microamp: + description: Maximum input current from USB input (in uA) + + summit,charge-current-compensation-microamp: + description: Charge current compensation (in uA) + + summit,chip-temperature-threshold-celsius: + description: Chip temperature for thermal regulation in °C. + enum: [100, 110, 120, 130] + + summit,soft-compensation-method: + description: Soft temperature limit compensation method + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # SMB3XX_SOFT_TEMP_COMPENSATE_NONE Compensation none + - 1 # SMB3XX_SOFT_TEMP_COMPENSATE_CURRENT Current compensation + - 2 # SMB3XX_SOFT_TEMP_COMPENSATE_VOLTAGE Voltage compensation + +allOf: + - if: + properties: + compatible: + enum: + - summit,smb345 + - summit,smb358 + + then: + properties: + summit,mains-current-limit-microamp: + enum: [ 300000, 500000, 700000, 1000000, + 1500000, 1800000, 2000000] + + summit,usb-current-limit-microamp: + enum: [ 300000, 500000, 700000, 1000000, + 1500000, 1800000, 2000000] + + summit,charge-current-compensation-microamp: + enum: [200000, 450000, 600000, 900000] + + else: + properties: + summit,mains-current-limit-microamp: + 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] + + summit,charge-current-compensation-microamp: + enum: [250000, 700000, 900000, 1200000] + +required: + - compatible + - reg + +anyOf: + - required: + - summit,enable-usb-charging + - required: + - summit,enable-otg-charging + - required: + - summit,enable-mains-charging + +additionalProperties: false + +examples: + - | + #include <dt-bindings/power/summit,smb347-charger.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@7f { + compatible = "summit,smb347"; + reg = <0x7f>; + + summit,enable-charge-control = <SMB3XX_CHG_ENABLE_PIN_ACTIVE_HIGH>; + summit,chip-temperature-threshold-celsius = <110>; + summit,mains-current-limit-microamp = <2000000>; + summit,usb-current-limit-microamp = <500000>; + summit,enable-usb-charging; + summit,enable-mains-charging; + + monitored-battery = <&battery>; + }; + }; + + battery: battery-cell { + compatible = "simple-battery"; + constant-charge-current-max-microamp = <1800000>; + operating-range-celsius = <0 45>; + alert-celsius = <3 42>; + }; diff --git a/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt index d48f9eb3636e..743eda754e65 100644 --- a/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt +++ b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt @@ -18,6 +18,8 @@ Clock Properties: - fsl,tmr-add Frequency compensation value. - fsl,tmr-fiper1 Fixed interval period pulse generator. - fsl,tmr-fiper2 Fixed interval period pulse generator. + - fsl,tmr-fiper3 Fixed interval period pulse generator. + Supported only on DPAA2 and ENETC hardware. - fsl,max-adj Maximum frequency adjustment in parts per billion. - fsl,extts-fifo The presence of this property indicates hardware support for the external trigger stamp FIFO. diff --git a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml index 41ece1d85315..4cfbffd8414a 100644 --- a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml @@ -14,7 +14,7 @@ description: | Google's ChromeOS EC PWM is a simple PWM attached to the Embedded Controller (EC) and controlled via a host-command interface. An EC PWM node should be only found as a sub-node of the EC node (see - Documentation/devicetree/bindings/mfd/cros-ec.txt). + Documentation/devicetree/bindings/mfd/google,cros-ec.yaml). properties: compatible: diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml index daadde9ff9c4..3c2fa2e93d1b 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml @@ -13,6 +13,7 @@ properties: compatible: items: - enum: + - renesas,pwm-r8a7742 # RZ/G1H - renesas,pwm-r8a7743 # RZ/G1M - renesas,pwm-r8a7744 # RZ/G1N - renesas,pwm-r8a7745 # RZ/G1E @@ -20,6 +21,7 @@ properties: - renesas,pwm-r8a774a1 # RZ/G2M - renesas,pwm-r8a774b1 # RZ/G2N - renesas,pwm-r8a774c0 # RZ/G2E + - renesas,pwm-r8a774e1 # RZ/G2H - renesas,pwm-r8a7778 # R-Car M1A - renesas,pwm-r8a7779 # R-Car H1 - renesas,pwm-r8a7790 # R-Car H2 diff --git a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml index 4bf62a3d5bba..aa9a4570c906 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml @@ -15,6 +15,7 @@ properties: - enum: - renesas,tpu-r8a73a4 # R-Mobile APE6 - renesas,tpu-r8a7740 # R-Mobile A1 + - renesas,tpu-r8a7742 # RZ/G1H - renesas,tpu-r8a7743 # RZ/G1M - renesas,tpu-r8a7744 # RZ/G1N - renesas,tpu-r8a7745 # RZ/G1E 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/remoteproc/ti,k3-r5f-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml new file mode 100644 index 000000000000..4069f0f5e8fa --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml @@ -0,0 +1,281 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/ti,k3-r5f-rproc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI K3 R5F processor subsystems + +maintainers: + - Suman Anna <s-anna@ti.com> + +description: | + The TI K3 family of SoCs usually have one or more dual-core Arm Cortex R5F + processor subsystems/clusters (R5FSS). The dual core cluster can be used + either in a LockStep mode providing safety/fault tolerance features or in a + Split mode providing two individual compute cores for doubling the compute + capacity. These are used together with other processors present on the SoC + to achieve various system level goals. + + Each Dual-Core R5F sub-system is represented as a single DTS node + representing the cluster, with a pair of child DT nodes representing + the individual R5F cores. Each node has a number of required or optional + properties that enable the OS running on the host processor to perform + the device management of the remote processor and to communicate with the + remote processor. + +properties: + $nodename: + pattern: "^r5fss(@.*)?" + + compatible: + enum: + - ti,am654-r5fss + - ti,j721e-r5fss + + power-domains: + description: | + Should contain a phandle to a PM domain provider node and an args + specifier containing the R5FSS device id value. + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: + description: | + Standard ranges definition providing address translations for + local R5F TCM address spaces to bus addresses. + +# Optional properties: +# -------------------- + + ti,cluster-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Configuration Mode for the Dual R5F cores within the R5F cluster. + Should be either a value of 1 (LockStep mode) or 0 (Split mode), + default is LockStep mode if omitted. + +# R5F Processor Child Nodes: +# ========================== + +patternProperties: + "^r5f@[a-f0-9]+$": + type: object + description: | + The R5F Sub-System device node should define two R5F child nodes, each + node representing a TI instantiation of the Arm Cortex R5F core. There + are some specific integration differences for the IP like the usage of + a Region Address Translator (RAT) for translating the larger SoC bus + addresses into a 32-bit address space for the processor. + + Each R5F core has an associated 64 KB of Tightly-Coupled Memory (TCM) + internal memories split between two banks - TCMA and TCMB (further + interleaved into two banks TCMB0 and TCMB1). These memories (also called + ATCM and BTCM) provide read/write performance on par with the core's L1 + caches. Each of the TCMs can be enabled or disabled independently and + either of them can be configured to appear at that R5F's address 0x0. + + The cores do not use an MMU, but has a Region Address Translater + (RAT) module that is accessible only from the R5Fs for providing + translations between 32-bit CPU addresses into larger system bus + addresses. Cache and memory access settings are provided through a + Memory Protection Unit (MPU), programmable only from the R5Fs. + + allOf: + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# + + properties: + compatible: + enum: + - ti,am654-r5f + - ti,j721e-r5f + + reg: + items: + - description: Address and Size of the ATCM internal memory region + - description: Address and Size of the BTCM internal memory region + + reg-names: + items: + - const: atcm + - const: btcm + + resets: + description: | + Should contain the phandle to the reset controller node managing the + local resets for this device, and a reset specifier. + maxItems: 1 + + firmware-name: + description: | + Should contain the name of the default firmware image + file located on the firmware search path + +# The following properties are mandatory for R5F Core0 in both LockStep and Split +# modes, and are mandatory for R5F Core1 _only_ in Split mode. They are unused for +# R5F Core1 in LockStep mode: + + mboxes: + description: | + OMAP Mailbox specifier denoting the sub-mailbox, to be used for + communication with the remote processor. This property should match + with the sub-mailbox node used in the firmware image. + maxItems: 1 + + memory-region: + description: | + phandle to the reserved memory nodes to be associated with the + remoteproc device. There should be at least two reserved memory nodes + defined. The reserved memory nodes should be carveout nodes, and + should be defined with a "no-map" property as per the bindings in + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + minItems: 2 + maxItems: 8 + items: + - description: region used for dynamic DMA allocations like vrings and + vring buffers + - description: region reserved for firmware image sections + additionalItems: true + + +# Optional properties: +# -------------------- +# The following properties are optional properties for each of the R5F cores: + + ti,atcm-enable: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + R5F core configuration mode dictating if ATCM should be enabled. The + R5F address of ATCM is dictated by ti,loczrama property. Should be + either a value of 1 (enabled) or 0 (disabled), default is disabled + if omitted. Recommended to enable it for maximizing TCMs. + + ti,btcm-enable: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + R5F core configuration mode dictating if BTCM should be enabled. The + R5F address of BTCM is dictated by ti,loczrama property. Should be + either a value of 1 (enabled) or 0 (disabled), default is enabled if + omitted. + + ti,loczrama: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + R5F core configuration mode dictating which TCM should appear at + address 0 (from core's view). Should be either a value of 1 (ATCM + at 0x0) or 0 (BTCM at 0x0), default value is 1 if omitted. + + sram: + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 4 + description: | + phandles to one or more reserved on-chip SRAM regions. The regions + should be defined as child nodes of the respective SRAM node, and + should be defined as per the generic bindings in, + Documentation/devicetree/bindings/sram/sram.yaml + + required: + - compatible + - reg + - reg-names + - ti,sci + - ti,sci-dev-id + - ti,sci-proc-ids + - resets + - firmware-name + + unevaluatedProperties: false + +required: + - compatible + - power-domains + - "#address-cells" + - "#size-cells" + - ranges + +additionalProperties: false + +examples: + - | + / { + model = "Texas Instruments K3 AM654 SoC"; + compatible = "ti,am654-evm", "ti,am654"; + #address-cells = <2>; + #size-cells = <2>; + + bus@100000 { + compatible = "simple-bus"; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0x00 0x00100000 0x00 0x00100000 0x00 0x00020000>, /* ctrl mmr */ + <0x00 0x41000000 0x00 0x41000000 0x00 0x00020000>, + <0x00 0x41400000 0x00 0x41400000 0x00 0x00020000>, + <0x00 0x41c00000 0x00 0x41c00000 0x00 0x00080000>; + + bus@28380000 { + compatible = "simple-bus"; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0x00 0x28380000 0x00 0x28380000 0x00 0x03880000>, /* MCU NAVSS */ + <0x00 0x41000000 0x00 0x41000000 0x00 0x00020000>, /* MCU R5F Core0 */ + <0x00 0x41400000 0x00 0x41400000 0x00 0x00020000>, /* MCU R5F Core1 */ + <0x00 0x41c00000 0x00 0x41c00000 0x00 0x00080000>; /* MCU SRAM */ + + /* AM65x MCU R5FSS node */ + mcu_r5fss0: r5fss@41000000 { + compatible = "ti,am654-r5fss"; + power-domains = <&k3_pds 129>; + ti,cluster-mode = <1>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x41000000 0x00 0x41000000 0x20000>, + <0x41400000 0x00 0x41400000 0x20000>; + + mcu_r5f0: r5f@41000000 { + compatible = "ti,am654-r5f"; + reg = <0x41000000 0x00008000>, + <0x41010000 0x00008000>; + reg-names = "atcm", "btcm"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <159>; + ti,sci-proc-ids = <0x01 0xFF>; + resets = <&k3_reset 159 1>; + firmware-name = "am65x-mcu-r5f0_0-fw"; + ti,atcm-enable = <1>; + ti,btcm-enable = <1>; + ti,loczrama = <1>; + mboxes = <&mailbox0 &mbox_mcu_r5fss0_core0>; + memory-region = <&mcu_r5fss0_core0_dma_memory_region>, + <&mcu_r5fss0_core0_memory_region>; + sram = <&mcu_r5fss0_core0_sram>; + }; + + mcu_r5f1: r5f@41400000 { + compatible = "ti,am654-r5f"; + reg = <0x41400000 0x00008000>, + <0x41410000 0x00008000>; + reg-names = "atcm", "btcm"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <245>; + ti,sci-proc-ids = <0x02 0xFF>; + resets = <&k3_reset 245 1>; + firmware-name = "am65x-mcu-r5f0_1-fw"; + ti,atcm-enable = <1>; + ti,btcm-enable = <1>; + ti,loczrama = <1>; + mboxes = <&mailbox1 &mbox_mcu_r5fss0_core1>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.yaml b/Documentation/devicetree/bindings/reset/renesas,rst.yaml index 2849ce45703c..620cd0538bbe 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.yaml +++ b/Documentation/devicetree/bindings/reset/renesas,rst.yaml @@ -47,6 +47,7 @@ properties: - renesas,r8a77980-rst # R-Car V3H - renesas,r8a77990-rst # R-Car E3 - renesas,r8a77995-rst # R-Car D3 + - renesas,r8a779a0-rst # R-Car V3U reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt index 27a45fe5ecf1..ed836868dbf1 100644 --- a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt +++ b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt @@ -1,7 +1,7 @@ -------------------------------------------------------------------------- - = Zynq UltraScale+ MPSoC reset driver binding = + = Zynq UltraScale+ MPSoC and Versal reset driver binding = -------------------------------------------------------------------------- -The Zynq UltraScale+ MPSoC has several different resets. +The Zynq UltraScale+ MPSoC and Versal has several different resets. See Chapter 36 of the Zynq UltraScale+ MPSoC TRM (UG) for more information about zynqmp resets. @@ -10,7 +10,8 @@ Please also refer to reset.txt in this directory for common reset controller binding usage. Required Properties: -- compatible: "xlnx,zynqmp-reset" +- compatible: "xlnx,zynqmp-reset" for Zynq UltraScale+ MPSoC platform + "xlnx,versal-reset" for Versal platform - #reset-cells: Specifies the number of cells needed to encode reset line, should be 1 @@ -37,8 +38,10 @@ Device nodes that need access to reset lines should specify them as a reset phandle in their corresponding node as specified in reset.txt. -For list of all valid reset indicies see +For list of all valid reset indices for Zynq UltraScale+ MPSoC see <dt-bindings/reset/xlnx-zynqmp-resets.h> +For list of all valid reset indices for Versal see +<dt-bindings/reset/xlnx-versal-resets.h> Example: 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/rtc/microcrystal,rv3032.yaml b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml new file mode 100644 index 000000000000..a2c55303810d --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/microcrystal,rv3032.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip RV-3032 RTC Device Tree Bindings + +allOf: + - $ref: "rtc.yaml#" + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +properties: + compatible: + const: microcrystal,rv3032 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + start-year: true + + trickle-resistor-ohms: + enum: + - 1000 + - 2000 + - 7000 + - 11000 + + trickle-voltage-millivolt: + enum: + - 1750 + - 3000 + - 4400 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + rtc@51 { + compatible = "microcrystal,rv3032"; + reg = <0x51>; + status = "okay"; + pinctrl-0 = <&rtc_nint_pins>; + interrupts-extended = <&gpio1 16 IRQ_TYPE_LEVEL_HIGH>; + trickle-resistor-ohms = <7000>; + trickle-voltage-millivolt = <1750>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt index 66f0a31ae9ce..36f610bb051e 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt @@ -31,9 +31,16 @@ Optional properties: Selected resistor for trickle charger Possible values are 250, 2000, 4000 Should be given if trickle charger should be enabled -- trickle-diode-disable : ds1339, ds1340 and ds 1388 only +- aux-voltage-chargeable: ds1339, ds1340, ds1388 and rx8130 only + Tells whether the battery/supercap of the RTC (if any) is + chargeable or not. + Possible values are 0 (not chargeable), 1 (chargeable) + +Deprecated properties: +- trickle-diode-disable : ds1339, ds1340 and ds1388 only Do not use internal trickle charger diode Should be given if internal trickle charger diode should be disabled + (superseded by aux-voltage-chargeable) Example: ds1339: rtc@68 { diff --git a/Documentation/devicetree/bindings/rtc/rtc.yaml b/Documentation/devicetree/bindings/rtc/rtc.yaml index 2d055e37e6f7..8acd2de3de3a 100644 --- a/Documentation/devicetree/bindings/rtc/rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/rtc.yaml @@ -17,6 +17,15 @@ properties: $nodename: pattern: "^rtc(@.*|-[0-9a-f])*$" + aux-voltage-chargeable: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Tells whether the battery/supercap of the RTC (if any) is + chargeable or not: + 0: not chargeable + 1: chargeable + quartz-load-femtofarads: $ref: /schemas/types.yaml#/definitions/uint32 description: @@ -35,6 +44,7 @@ properties: description: Do not use internal trickle charger diode. Should be given if internal trickle charger diode should be disabled. + deprecated: true trickle-resistor-ohms: $ref: /schemas/types.yaml#/definitions/uint32 @@ -42,6 +52,12 @@ properties: Selected resistor for trickle charger. Should be given if trickle charger should be enabled. + trickle-voltage-millivolt: + description: + Selected voltage for trickle charger. Should be given + if trickle charger should be enabled and the trickle voltage is different + from the RTC main power supply. + wakeup-source: $ref: /schemas/types.yaml#/definitions/flag description: 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/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml index 468d658ce3e7..2684f22a1d85 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -20,7 +20,7 @@ description: | present and this subnode may contain children that designate regulator resources. - Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt + Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml for information on the regulator subnodes that can exist under the rpm_requests. diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml index ae33fc957141..c3c595e235a8 100644 --- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml @@ -62,11 +62,6 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 description: TI-SCI device id of the ring accelerator - ti,dma-ring-reset-quirk: - $ref: /schemas/types.yaml#definitions/flag - description: | - enable ringacc/udma ring state interoperability issue software w/a - required: - compatible - reg @@ -94,7 +89,6 @@ examples: reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target"; ti,num-rings = <818>; ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */ - ti,dma-ring-reset-quirk; ti,sci = <&dmsc>; ti,sci-dev-id = <187>; msi-parent = <&inta_main_udmass>; diff --git a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml new file mode 100644 index 000000000000..037c51b2f972 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml @@ -0,0 +1,439 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/ti/ti,pruss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: |+ + TI Programmable Real-Time Unit and Industrial Communication Subsystem + +maintainers: + - Suman Anna <s-anna@ti.com> + +description: |+ + + The Programmable Real-Time Unit and Industrial Communication Subsystem + (PRU-ICSS a.k.a. PRUSS) is present on various TI SoCs such as AM335x, AM437x, + Keystone 66AK2G, OMAP-L138/DA850 etc. A PRUSS consists of dual 32-bit RISC + cores (Programmable Real-Time Units, or PRUs), shared RAM, data and + instruction RAMs, some internal peripheral modules to facilitate industrial + communication, and an interrupt controller. + + The programmable nature of the PRUs provide flexibility to implement custom + peripheral interfaces, fast real-time responses, or specialized data handling. + The common peripheral modules include the following, + - an Ethernet MII_RT module with two MII ports + - an MDIO port to control external Ethernet PHYs + - an Industrial Ethernet Peripheral (IEP) to manage/generate Industrial + Ethernet functions + - an Enhanced Capture Module (eCAP) + - an Industrial Ethernet Timer with 7/9 capture and 16 compare events + - a 16550-compatible UART to support PROFIBUS + - Enhanced GPIO with async capture and serial support + + A PRU-ICSS subsystem can have up to three shared data memories. A PRU core + acts on a primary Data RAM (there are usually 2 Data RAMs) at its address + 0x0, but also has access to a secondary Data RAM (primary to the other PRU + core) at its address 0x2000. A shared Data RAM, if present, can be accessed + by both the PRU cores. The Interrupt Controller (INTC) and a CFG module are + common to both the PRU cores. Each PRU core also has a private instruction + RAM, and specific register spaces for Control and Debug functionalities. + + Various sub-modules within a PRU-ICSS subsystem are represented as individual + nodes and are defined using a parent-child hierarchy depending on their + integration within the IP and the SoC. These nodes are described in the + following sections. + + + PRU-ICSS Node + ============== + Each PRU-ICSS instance is represented as its own node with the individual PRU + processor cores, the memories node, an INTC node and an MDIO node represented + as child nodes within this PRUSS node. This node shall be a child of the + corresponding interconnect bus nodes or target-module nodes. + + See ../../mfd/syscon.yaml for generic SysCon binding details. + + +properties: + $nodename: + pattern: "^(pruss|icssg)@[0-9a-f]+$" + + compatible: + enum: + - ti,am3356-pruss # for AM335x SoC family + - ti,am4376-pruss0 # for AM437x SoC family and PRUSS unit 0 + - ti,am4376-pruss1 # for AM437x SoC family and PRUSS unit 1 + - ti,am5728-pruss # for AM57xx SoC family + - ti,k2g-pruss # for 66AK2G SoC family + - ti,am654-icssg # for K3 AM65x SoC family + - ti,j721e-icssg # for K3 J721E SoC family + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: + maxItems: 1 + + power-domains: + description: | + This property is as per sci-pm-domain.txt. + +patternProperties: + + memories@[a-f0-9]+$: + description: | + The various Data RAMs within a single PRU-ICSS unit are represented as a + single node with the name 'memories'. + + type: object + + properties: + reg: + minItems: 2 # On AM437x one of two PRUSS units don't contain Shared RAM. + maxItems: 3 + items: + - description: Address and size of the Data RAM0. + - description: Address and size of the Data RAM1. + - description: | + Address and size of the Shared Data RAM. Note that on AM437x one + of two PRUSS units don't contain Shared RAM, while the second one + has it. + + reg-names: + minItems: 2 + maxItems: 3 + items: + - const: dram0 + - const: dram1 + - const: shrdram2 + + required: + - reg + - reg-names + + additionalProperties: false + + cfg@[a-f0-9]+$: + description: | + PRU-ICSS configuration space. CFG sub-module represented as a SysCon. + + type: object + + properties: + compatible: + items: + - const: ti,pruss-cfg + - const: syscon + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + reg: + maxItems: 1 + + ranges: + maxItems: 1 + + clocks: + type: object + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + patternProperties: + coreclk-mux@[a-f0-9]+$: + description: | + This is applicable only for ICSSG (K3 SoCs). The ICSSG modules + core clock can be set to one of the 2 sources: ICSSG_CORE_CLK or + ICSSG_ICLK. This node models this clock mux and should have the + name "coreclk-mux". + + type: object + + properties: + '#clock-cells': + const: 0 + + clocks: + items: + - description: ICSSG_CORE Clock + - description: ICSSG_ICLK Clock + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + description: | + Standard assigned-clocks-parents definition used for selecting + mux parent (one of the mux input). + + reg: + maxItems: 1 + + required: + - clocks + + additionalProperties: false + + iepclk-mux@[a-f0-9]+$: + description: | + The IEP module can get its clock from 2 sources: ICSSG_IEP_CLK or + CORE_CLK (OCP_CLK in older SoCs). This node models this clock + mux and should have the name "iepclk-mux". + + type: object + + properties: + '#clock-cells': + const: 0 + + clocks: + items: + - description: ICSSG_IEP Clock + - description: Core Clock (OCP Clock in older SoCs) + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + description: | + Standard assigned-clocks-parents definition used for selecting + mux parent (one of the mux input). + + reg: + maxItems: 1 + + required: + - clocks + + additionalProperties: false + + additionalProperties: false + + iep@[a-f0-9]+$: + description: | + Industrial Ethernet Peripheral to manage/generate Industrial Ethernet + functions such as time stamping. Each PRUSS has either 1 IEP (on AM335x, + AM437x, AM57xx & 66AK2G SoCs) or 2 IEPs (on K3 AM65x & J721E SoCs ). IEP + is used for creating PTP clocks and generating PPS signals. + + type: object + + mii-rt@[a-f0-9]+$: + description: | + Real-Time Ethernet to support multiple industrial communication protocols. + MII-RT sub-module represented as a SysCon. + + type: object + + properties: + compatible: + items: + - const: ti,pruss-mii + - const: syscon + + reg: + maxItems: 1 + + additionalProperties: false + + mii-g-rt@[a-f0-9]+$: + description: | + The Real-time Media Independent Interface to support multiple industrial + communication protocols (G stands for Gigabit). MII-G-RT sub-module + represented as a SysCon. + + type: object + + properties: + compatible: + items: + - const: ti,pruss-mii-g + - const: syscon + + reg: + maxItems: 1 + + additionalProperties: false + + interrupt-controller@[a-f0-9]+$: + description: | + PRUSS INTC Node. Each PRUSS has a single interrupt controller instance + that is common to all the PRU cores. This should be represented as an + interrupt-controller node. + + type: object + + mdio@[a-f0-9]+$: + description: | + MDIO Node. Each PRUSS has an MDIO module that can be used to control + external PHYs. The MDIO module used within the PRU-ICSS is an instance of + the MDIO Controller used in TI Davinci SoCs. + + allOf: + - $ref: /schemas/net/ti,davinci-mdio.yaml# + + type: object + + "^(pru|rtu|txpru)@[0-9a-f]+$": + description: | + PRU Node. Each PRUSS has dual PRU cores, each represented as a RemoteProc + device through a PRU child node each. Each node can optionally be rendered + inactive by using the standard DT string property, "status". The ICSSG IP + present on K3 SoCs have additional auxiliary PRU cores with slightly + different IP integration. + + type: object + +required: + - compatible + - reg + - ranges + +additionalProperties: false + +# Due to inability of correctly verifying sub-nodes with an @address through +# the "required" list, the required sub-nodes below are commented out for now. + +#required: +# - memories +# - interrupt-controller +# - pru + +if: + properties: + compatible: + contains: + enum: + - ti,k2g-pruss + - ti,am654-icssg + - ti,j721e-icssg +then: + required: + - power-domains + +examples: + - | + + /* Example 1 AM33xx PRU-ICSS */ + pruss: pruss@0 { + compatible = "ti,am3356-pruss"; + reg = <0x0 0x80000>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + pruss_mem: memories@0 { + reg = <0x0 0x2000>, + <0x2000 0x2000>, + <0x10000 0x3000>; + reg-names = "dram0", "dram1", "shrdram2"; + }; + + pruss_cfg: cfg@26000 { + compatible = "ti,pruss-cfg", "syscon"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x26000 0x2000>; + ranges = <0x00 0x26000 0x2000>; + + clocks { + #address-cells = <1>; + #size-cells = <0>; + + pruss_iepclk_mux: iepclk-mux@30 { + reg = <0x30>; + #clock-cells = <0>; + clocks = <&l3_gclk>, /* icss_iep */ + <&pruss_ocp_gclk>; /* icss_ocp */ + }; + }; + }; + + pruss_mii_rt: mii-rt@32000 { + compatible = "ti,pruss-mii", "syscon"; + reg = <0x32000 0x58>; + }; + + pruss_mdio: mdio@32400 { + compatible = "ti,davinci_mdio"; + reg = <0x32400 0x90>; + clocks = <&dpll_core_m4_ck>; + clock-names = "fck"; + bus_freq = <1000000>; + #address-cells = <1>; + #size-cells = <0>; + }; + }; + + - | + + /* Example 2 AM43xx PRU-ICSS with PRUSS1 node */ + #include <dt-bindings/interrupt-controller/arm-gic.h> + pruss1: pruss@0 { + compatible = "ti,am4376-pruss1"; + reg = <0x0 0x40000>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + pruss1_mem: memories@0 { + reg = <0x0 0x2000>, + <0x2000 0x2000>, + <0x10000 0x8000>; + reg-names = "dram0", "dram1", "shrdram2"; + }; + + pruss1_cfg: cfg@26000 { + compatible = "ti,pruss-cfg", "syscon"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x26000 0x2000>; + ranges = <0x00 0x26000 0x2000>; + + clocks { + #address-cells = <1>; + #size-cells = <0>; + + pruss1_iepclk_mux: iepclk-mux@30 { + reg = <0x30>; + #clock-cells = <0>; + clocks = <&sysclk_div>, /* icss_iep */ + <&pruss_ocp_gclk>; /* icss_ocp */ + }; + }; + }; + + pruss1_mii_rt: mii-rt@32000 { + compatible = "ti,pruss-mii", "syscon"; + reg = <0x32000 0x58>; + }; + + pruss1_mdio: mdio@32400 { + compatible = "ti,davinci_mdio"; + reg = <0x32400 0x90>; + clocks = <&dpll_core_m4_ck>; + clock-names = "fck"; + bus_freq = <1000000>; + #address-cells = <1>; + #size-cells = <0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml index c84e656afb0a..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/cros-ec.txt). + 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 f5825935fd22..b66a07e21d1e 100644 --- a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml +++ b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml @@ -33,6 +33,12 @@ properties: - const: allwinner,sun4i-a10-system-control - 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 deprecated: true - const: allwinner,sun50i-a64-system-control @@ -87,6 +93,9 @@ patternProperties: - const: allwinner,sun8i-h3-sram-c1 - const: allwinner,sun4i-a10-sram-c1 - items: + - const: allwinner,sun8i-r40-sram-c1 + - const: allwinner,sun4i-a10-sram-c1 + - items: - const: allwinner,sun50i-a64-sram-c1 - const: allwinner,sun4i-a10-sram-c1 - items: diff --git a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml index 44ba6765697d..31edd051295a 100644 --- a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml +++ b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml @@ -17,6 +17,7 @@ properties: - allwinner,sun8i-h3-ths - allwinner,sun8i-r40-ths - allwinner,sun50i-a64-ths + - allwinner,sun50i-a100-ths - allwinner,sun50i-h5-ths - allwinner,sun50i-h6-ths @@ -61,7 +62,9 @@ allOf: properties: compatible: contains: - const: allwinner,sun50i-h6-ths + enum: + - allwinner,sun50i-a100-ths + - allwinner,sun50i-h6-ths then: properties: @@ -103,6 +106,7 @@ allOf: - const: allwinner,sun8i-h3-ths - const: allwinner,sun8i-r40-ths - const: allwinner,sun50i-a64-ths + - const: allwinner,sun50i-a100-ths - const: allwinner,sun50i-h5-ths - const: allwinner,sun50i-h6-ths diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml index b1a55ae497de..f386f2a7c06c 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml @@ -20,6 +20,7 @@ properties: enum: - renesas,r8a774a1-thermal # RZ/G2M - renesas,r8a774b1-thermal # RZ/G2N + - renesas,r8a774e1-thermal # RZ/G2H - renesas,r8a7795-thermal # R-Car H3 - renesas,r8a7796-thermal # R-Car M3-W - renesas,r8a77961-thermal # R-Car M3-W+ 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 ad38504f4358..2735be1a8470 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -179,6 +179,8 @@ patternProperties: description: CALAO Systems SAS "^calxeda,.*": description: Calxeda + "^caninos,.*": + description: Caninos Loucos Program "^capella,.*": description: Capella Microsystems, Inc "^cascoda,.*": @@ -912,6 +914,8 @@ patternProperties: description: Ronbo Electronics "^roofull,.*": description: Shenzhen Roofull Technology Co, Ltd + "^roseapplepi,.*": + description: RoseapplePi.org "^samsung,.*": description: Samsung Semiconductor "^samtec,.*": @@ -928,6 +932,8 @@ patternProperties: description: Schindler "^seagate,.*": description: Seagate Technology PLC + "^seeed,.*": + description: Seeed Technology Co., Ltd "^seirobotics,.*": description: Shenzhen SEI Robotics Co., Ltd "^semtech,.*": @@ -1222,6 +1228,10 @@ patternProperties: description: Shenzhen Zidoo Technology Co., Ltd. "^zii,.*": description: Zodiac Inflight Innovations + "^zinitix,.*": + description: Zinitix Co., Ltd + "^zkmagic,.*": + description: Shenzhen Zkmagic Technology Co., Ltd. "^zte,.*": description: ZTE Corp. "^zyxel,.*": 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/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml b/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml new file mode 100644 index 000000000000..690e19ce4b87 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 Toshiba Electronic Devices & Storage Corporation +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/watchdog/toshiba,visconti-wdt.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Toshiba Visconti SoCs PIUWDT Watchdog timer + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + enum: + - toshiba,visconti-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + timeout-sec: true + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + wdt_clk: wdt-clk { + compatible = "fixed-clock"; + clock-frequency = <150000000>; + #clock-cells = <0>; + }; + + watchdog@28330000 { + compatible = "toshiba,visconti-wdt"; + reg = <0 0x28330000 0 0x1000>; + clocks = <&wdt_clk>; + timeout-sec = <20>; + }; + }; diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 4fd86c21397b..52a87ab4c99f 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -490,6 +490,14 @@ identifiers: *[ function/type ...]* .. kernel-doc:: lib/idr.c :identifiers: +no-identifiers: *[ function/type ...]* + Exclude documentation for each *function* and *type* in *source*. + + Example:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + functions: *[ function/type ...]* This is an alias of the 'identifiers' directive and deprecated. diff --git a/Documentation/driver-api/80211/cfg80211.rst b/Documentation/driver-api/80211/cfg80211.rst index eeab91b59457..836f609c3f75 100644 --- a/Documentation/driver-api/80211/cfg80211.rst +++ b/Documentation/driver-api/80211/cfg80211.rst @@ -12,79 +12,32 @@ Device registration :doc: Device registration .. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_channel_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_channel - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_rate_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_rate - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_sta_ht_cap - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_supported_band - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_signal_type - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_params_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy - -.. kernel-doc:: include/net/cfg80211.h - :functions: wireless_dev - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_new - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_read_of_freq_limits - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_register - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_unregister - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_free - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_name - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_dev - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_priv - -.. kernel-doc:: include/net/cfg80211.h - :functions: priv_to_wiphy - -.. kernel-doc:: include/net/cfg80211.h - :functions: set_wiphy_dev - -.. kernel-doc:: include/net/cfg80211.h - :functions: wdev_priv - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_iface_limit - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_iface_combination - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_check_combinations + :functions: + ieee80211_channel_flags + ieee80211_channel + ieee80211_rate_flags + ieee80211_rate + ieee80211_sta_ht_cap + ieee80211_supported_band + cfg80211_signal_type + wiphy_params_flags + wiphy_flags + wiphy + wireless_dev + wiphy_new + wiphy_read_of_freq_limits + wiphy_register + wiphy_unregister + wiphy_free + wiphy_name + wiphy_dev + wiphy_priv + priv_to_wiphy + set_wiphy_dev + wdev_priv + ieee80211_iface_limit + ieee80211_iface_combination + cfg80211_check_combinations Actions and configuration ========================= @@ -93,139 +46,52 @@ Actions and configuration :doc: Actions and configuration .. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ops - -.. kernel-doc:: include/net/cfg80211.h - :functions: vif_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: key_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: survey_info_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: survey_info - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_beacon_data - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ap_settings - -.. kernel-doc:: include/net/cfg80211.h - :functions: station_parameters - -.. kernel-doc:: include/net/cfg80211.h - :functions: rate_info_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: rate_info - -.. kernel-doc:: include/net/cfg80211.h - :functions: station_info - -.. kernel-doc:: include/net/cfg80211.h - :functions: monitor_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: mpath_info_flags - -.. kernel-doc:: include/net/cfg80211.h - :functions: mpath_info - -.. kernel-doc:: include/net/cfg80211.h - :functions: bss_parameters - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_txq_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_crypto_settings - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_auth_request - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_assoc_request - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_deauth_request - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_disassoc_request - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ibss_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_pmksa - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_rx_mlme_mgmt - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_auth_timeout - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_rx_assoc_resp - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_assoc_timeout - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_tx_mlme_mgmt - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ibss_joined - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_resp_params - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_done - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_result - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_bss - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_connect_timeout - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_roamed - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_disconnected - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ready_on_channel - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_remain_on_channel_expired - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_new_sta - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_rx_mgmt - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_mgmt_tx_status - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_cqm_rssi_notify - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_cqm_pktloss_notify - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_michael_mic_failure + :functions: + cfg80211_ops + vif_params + key_params + survey_info_flags + survey_info + cfg80211_beacon_data + cfg80211_ap_settings + station_parameters + rate_info_flags + rate_info + station_info + monitor_flags + mpath_info_flags + mpath_info + bss_parameters + ieee80211_txq_params + cfg80211_crypto_settings + cfg80211_auth_request + cfg80211_assoc_request + cfg80211_deauth_request + cfg80211_disassoc_request + cfg80211_ibss_params + cfg80211_connect_params + cfg80211_pmksa + cfg80211_rx_mlme_mgmt + cfg80211_auth_timeout + cfg80211_rx_assoc_resp + cfg80211_assoc_timeout + cfg80211_tx_mlme_mgmt + cfg80211_ibss_joined + cfg80211_connect_resp_params + cfg80211_connect_done + cfg80211_connect_result + cfg80211_connect_bss + cfg80211_connect_timeout + cfg80211_roamed + cfg80211_disconnected + cfg80211_ready_on_channel + cfg80211_remain_on_channel_expired + cfg80211_new_sta + cfg80211_rx_mgmt + cfg80211_mgmt_tx_status + cfg80211_cqm_rssi_notify + cfg80211_cqm_pktloss_notify + cfg80211_michael_mic_failure Scanning and BSS list handling ============================== @@ -234,34 +100,17 @@ Scanning and BSS list handling :doc: Scanning and BSS list handling .. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_ssid - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_scan_request - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_scan_done - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_bss - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_inform_bss - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_inform_bss_frame_data - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_inform_bss_data - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_unlink_bss - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_find_ie - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_bss_get_ie + :functions: + cfg80211_ssid + cfg80211_scan_request + cfg80211_scan_done + cfg80211_bss + cfg80211_inform_bss + cfg80211_inform_bss_frame_data + cfg80211_inform_bss_data + cfg80211_unlink_bss + cfg80211_find_ie + ieee80211_bss_get_ie Utility functions ================= @@ -270,25 +119,14 @@ Utility functions :doc: Utility functions .. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_channel_to_frequency - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_frequency_to_channel - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_get_channel - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_get_response_rate - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_hdrlen - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_get_hdrlen_from_skb - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_radiotap_iterator + :functions: + ieee80211_channel_to_frequency + ieee80211_frequency_to_channel + ieee80211_get_channel + ieee80211_get_response_rate + ieee80211_hdrlen + ieee80211_get_hdrlen_from_skb + ieee80211_radiotap_iterator Data path helpers ================= @@ -297,13 +135,10 @@ Data path helpers :doc: Data path helpers .. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_data_to_8023 - -.. kernel-doc:: include/net/cfg80211.h - :functions: ieee80211_amsdu_to_8023s - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_classify8021d + :functions: + ieee80211_data_to_8023 + ieee80211_amsdu_to_8023s + cfg80211_classify8021d Regulatory enforcement infrastructure ===================================== @@ -312,13 +147,10 @@ Regulatory enforcement infrastructure :doc: Regulatory enforcement infrastructure .. kernel-doc:: include/net/cfg80211.h - :functions: regulatory_hint - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_apply_custom_regulatory - -.. kernel-doc:: include/net/cfg80211.h - :functions: freq_reg_info + :functions: + regulatory_hint + wiphy_apply_custom_regulatory + freq_reg_info RFkill integration ================== @@ -327,13 +159,10 @@ RFkill integration :doc: RFkill integration .. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_rfkill_set_hw_state - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_rfkill_start_polling - -.. kernel-doc:: include/net/cfg80211.h - :functions: wiphy_rfkill_stop_polling + :functions: + wiphy_rfkill_set_hw_state + wiphy_rfkill_start_polling + wiphy_rfkill_stop_polling Test mode ========= @@ -342,13 +171,8 @@ Test mode :doc: Test mode .. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_testmode_alloc_reply_skb - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_testmode_reply - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_testmode_alloc_event_skb - -.. kernel-doc:: include/net/cfg80211.h - :functions: cfg80211_testmode_event + :functions: + cfg80211_testmode_alloc_reply_skb + cfg80211_testmode_reply + cfg80211_testmode_alloc_event_skb + cfg80211_testmode_event diff --git a/Documentation/driver-api/80211/mac80211-advanced.rst b/Documentation/driver-api/80211/mac80211-advanced.rst index 24cb64b3b715..f8df7b3af8f5 100644 --- a/Documentation/driver-api/80211/mac80211-advanced.rst +++ b/Documentation/driver-api/80211/mac80211-advanced.rst @@ -15,25 +15,14 @@ appropriate trigger, which will then be triggered appropriately by mac80211. .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_tx_led_name - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_rx_led_name - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_assoc_led_name - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_radio_led_name - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tpt_blink - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tpt_led_trigger_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_create_tpt_led_trigger + :functions: + ieee80211_get_tx_led_name + ieee80211_get_rx_led_name + ieee80211_get_assoc_led_name + ieee80211_get_radio_led_name + ieee80211_tpt_blink + ieee80211_tpt_led_trigger_flags + ieee80211_create_tpt_led_trigger Hardware crypto acceleration ============================ @@ -42,22 +31,13 @@ Hardware crypto acceleration :doc: Hardware crypto acceleration .. kernel-doc:: include/net/mac80211.h - :functions: set_key_cmd - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_key_conf - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_key_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_tkip_p1k - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_tkip_p1k_iv - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_tkip_p2k + :functions: + set_key_cmd + ieee80211_key_conf + ieee80211_key_flags + ieee80211_get_tkip_p1k + ieee80211_get_tkip_p1k_iv + ieee80211_get_tkip_p2k Powersave support ================= @@ -99,28 +79,15 @@ support for powersaving clients :doc: AP support for powersaving clients .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_get_buffered_bc - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_beacon_get - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta_eosp - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_frame_release_type - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta_ps_transition - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta_ps_transition_ni - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta_set_buffered - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta_block_awake + :functions: + ieee80211_get_buffered_bc + ieee80211_beacon_get + ieee80211_sta_eosp + ieee80211_frame_release_type + ieee80211_sta_ps_transition + ieee80211_sta_ps_transition_ni + ieee80211_sta_set_buffered + ieee80211_sta_block_awake Supporting multiple virtual interfaces ====================================== @@ -134,10 +101,9 @@ addresses here, note which configurations are supported by mac80211, add notes about supporting hw crypto with it. .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_iterate_active_interfaces - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_iterate_active_interfaces_atomic + :functions: + ieee80211_iterate_active_interfaces + ieee80211_iterate_active_interfaces_atomic Station handling ================ @@ -145,16 +111,11 @@ Station handling TODO .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_sta - -.. kernel-doc:: include/net/mac80211.h - :functions: sta_notify_cmd - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_find_sta - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_find_sta_by_ifaddr + :functions: + ieee80211_sta + sta_notify_cmd + ieee80211_find_sta + ieee80211_find_sta_by_ifaddr Hardware scan offload ===================== @@ -193,10 +154,9 @@ Spatial Multiplexing Powersave (SMPS) :doc: Spatial multiplexing power save .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_request_smps - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_smps_mode + :functions: + ieee80211_request_smps + ieee80211_smps_mode TBD @@ -209,22 +169,13 @@ Rate Control API TBD .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_start_tx_ba_session - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_start_tx_ba_cb_irqsafe - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_stop_tx_ba_session - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_stop_tx_ba_cb_irqsafe - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rate_control_changed - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_rate_control + :functions: + ieee80211_start_tx_ba_session + ieee80211_start_tx_ba_cb_irqsafe + ieee80211_stop_tx_ba_session + ieee80211_stop_tx_ba_cb_irqsafe + ieee80211_rate_control_changed + ieee80211_tx_rate_control TBD @@ -261,10 +212,9 @@ Programming information ----------------------- .. kernel-doc:: net/mac80211/sta_info.h - :functions: sta_info - -.. kernel-doc:: net/mac80211/sta_info.h - :functions: ieee80211_sta_info_flags + :functions: + sta_info + ieee80211_sta_info_flags STA information lifetime rules ------------------------------ @@ -276,13 +226,10 @@ Aggregation Functions ===================== .. kernel-doc:: net/mac80211/sta_info.h - :functions: sta_ampdu_mlme - -.. kernel-doc:: net/mac80211/sta_info.h - :functions: tid_ampdu_tx - -.. kernel-doc:: net/mac80211/sta_info.h - :functions: tid_ampdu_rx + :functions: + sta_ampdu_mlme + tid_ampdu_tx + tid_ampdu_rx Synchronisation Functions ========================= diff --git a/Documentation/driver-api/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst index eab40bcf3987..67d2e58b45e4 100644 --- a/Documentation/driver-api/80211/mac80211.rst +++ b/Documentation/driver-api/80211/mac80211.rst @@ -30,31 +30,16 @@ Finally, a discussion of hardware capabilities should be done with references to other parts of the book. .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_hw - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_hw_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: SET_IEEE80211_DEV - -.. kernel-doc:: include/net/mac80211.h - :functions: SET_IEEE80211_PERM_ADDR - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_ops - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_alloc_hw - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_register_hw - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_unregister_hw - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_free_hw + :functions: + ieee80211_hw + ieee80211_hw_flags + SET_IEEE80211_DEV + SET_IEEE80211_PERM_ADDR + ieee80211_ops + ieee80211_alloc_hw + ieee80211_register_hw + ieee80211_unregister_hw + ieee80211_free_hw PHY configuration ================= @@ -65,10 +50,9 @@ This chapter should describe PHY handling including start/stop callbacks and the various structures used. .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_conf - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_conf_flags + :functions: + ieee80211_conf + ieee80211_conf_flags Virtual interfaces ================== @@ -123,79 +107,32 @@ functions/definitions --------------------- .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rx_status - -.. kernel-doc:: include/net/mac80211.h - :functions: mac80211_rx_encoding_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: mac80211_rx_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: mac80211_tx_info_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: mac80211_tx_control_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: mac80211_rate_control_flags - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_rate - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_info - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_info_clear_status - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rx - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rx_ni - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rx_irqsafe - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_status - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_status_ni - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_tx_status_irqsafe - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rts_get - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_rts_duration - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_ctstoself_get - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_ctstoself_duration - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_generic_frame_duration - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_wake_queue - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_stop_queue - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_wake_queues - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_stop_queues - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_queue_stopped + :functions: + ieee80211_rx_status + mac80211_rx_encoding_flags + mac80211_rx_flags + mac80211_tx_info_flags + mac80211_tx_control_flags + mac80211_rate_control_flags + ieee80211_tx_rate + ieee80211_tx_info + ieee80211_tx_info_clear_status + ieee80211_rx + ieee80211_rx_ni + ieee80211_rx_irqsafe + ieee80211_tx_status + ieee80211_tx_status_ni + ieee80211_tx_status_irqsafe + ieee80211_rts_get + ieee80211_rts_duration + ieee80211_ctstoself_get + ieee80211_ctstoself_duration + ieee80211_generic_frame_duration + ieee80211_wake_queue + ieee80211_stop_queue + ieee80211_wake_queues + ieee80211_stop_queues + ieee80211_queue_stopped Frame filtering =============== @@ -213,7 +150,6 @@ The mac80211 workqueue :doc: mac80211 workqueue .. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_queue_work - -.. kernel-doc:: include/net/mac80211.h - :functions: ieee80211_queue_delayed_work + :functions: + ieee80211_queue_work + ieee80211_queue_delayed_work diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 1ba88c7b3984..3e2dae954898 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -12,6 +12,8 @@ Driver device table .. kernel-doc:: include/linux/mod_devicetable.h :internal: + :no-identifiers: pci_device_id + Delaying, scheduling, and timer routines ---------------------------------------- @@ -55,15 +57,6 @@ High-resolution timers .. kernel-doc:: kernel/time/hrtimer.c :export: -Workqueues and Kevents ----------------------- - -.. kernel-doc:: include/linux/workqueue.h - :internal: - -.. kernel-doc:: kernel/workqueue.c - :export: - Internal Functions ------------------ @@ -105,19 +98,15 @@ Kernel utility functions .. kernel-doc:: include/linux/kernel.h :internal: + :no-identifiers: kstrtol kstrtoul .. kernel-doc:: kernel/printk/printk.c :export: + :no-identifiers: printk .. kernel-doc:: kernel/panic.c :export: -.. kernel-doc:: kernel/rcu/tree.c - :export: - -.. kernel-doc:: kernel/rcu/update.c - :export: - .. kernel-doc:: include/linux/overflow.h :internal: diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst index bc2d89af88ce..ee913ae16371 100644 --- a/Documentation/driver-api/device_link.rst +++ b/Documentation/driver-api/device_link.rst @@ -1,7 +1,3 @@ -.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` -.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>` - - .. _device_link: ============ @@ -166,7 +162,7 @@ Examples is the same as if the MMU was the parent of the master device. The fact that both devices share the same power domain would normally - suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|, + suggest usage of a struct dev_pm_domain or struct generic_pm_domain, however these are not independent devices that happen to share a power switch, but rather the MMU device serves the busmaster device and is useless without it. A device link creates a synthetic hierarchical @@ -202,7 +198,7 @@ Examples Alternatives ============ -* A |struct dev_pm_domain| can be used to override the bus, +* A struct dev_pm_domain can be used to override the bus, class or device type callbacks. It is intended for devices sharing a single on/off switch, however it does not guarantee a specific suspend/resume ordering, this needs to be implemented separately. @@ -211,7 +207,7 @@ Alternatives suspended. Furthermore it cannot be used to enforce a specific shutdown ordering or a driver presence dependency. -* A |struct generic_pm_domain| is a lot more heavyweight than a +* A struct generic_pm_domain is a lot more heavyweight than a device link and does not allow for shutdown ordering or driver presence dependencies. It also cannot be used on ACPI systems. @@ -321,5 +317,4 @@ State machine API === -.. kernel-doc:: drivers/base/core.c - :functions: device_link_add device_link_del device_link_remove +See device_link_add(), device_link_del() and device_link_remove(). diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst index ccd677ba7d76..198aadafd3e7 100644 --- a/Documentation/driver-api/fpga/fpga-bridge.rst +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -4,8 +4,8 @@ FPGA Bridge API to implement a new FPGA bridge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* struct :c:type:`fpga_bridge` — The FPGA Bridge structure -* struct :c:type:`fpga_bridge_ops` — Low level Bridge driver ops +* struct fpga_bridge — The FPGA Bridge structure +* struct fpga_bridge_ops — Low level Bridge driver ops * devm_fpga_bridge_create() — Allocate and init a bridge struct * fpga_bridge_register() — Register a bridge * fpga_bridge_unregister() — Unregister a bridge diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index af5382af1379..917ee22db429 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -101,9 +101,9 @@ in state. API for implementing a new FPGA Manager driver ---------------------------------------------- -* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`. -* struct :c:type:`fpga_manager` — the FPGA manager struct -* struct :c:type:`fpga_manager_ops` — Low level FPGA manager driver ops +* ``fpga_mgr_states`` — Values for :c:expr:`fpga_manager->state`. +* struct fpga_manager — the FPGA manager struct +* struct fpga_manager_ops — Low level FPGA manager driver ops * devm_fpga_mgr_create() — Allocate and init a manager struct * fpga_mgr_register() — Register an FPGA manager * fpga_mgr_unregister() — Unregister an FPGA manager diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst index f487ad64dfb9..002392dab04f 100644 --- a/Documentation/driver-api/fpga/fpga-programming.rst +++ b/Documentation/driver-api/fpga/fpga-programming.rst @@ -15,7 +15,7 @@ the FPGA manager and bridges. It will: * lock the mutex of the region's FPGA manager * build a list of FPGA bridges if a method has been specified to do so * disable the bridges - * program the FPGA using info passed in :c:member:`fpga_region->info`. + * program the FPGA using info passed in :c:expr:`fpga_region->info`. * re-enable the bridges * release the locks diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst index 31118a8ba218..363a8171ab0a 100644 --- a/Documentation/driver-api/fpga/fpga-region.rst +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -45,7 +45,7 @@ An example of usage can be seen in the probe function of [#f2]_. API to add a new FPGA region ---------------------------- -* struct :c:type:`fpga_region` — The FPGA region struct +* struct fpga_region — The FPGA region struct * devm_fpga_region_create() — Allocate and init a region struct * fpga_region_register() — Register an FPGA region * fpga_region_unregister() — Unregister an FPGA region @@ -61,9 +61,9 @@ during the region's probe function. The FPGA region will need to specify which bridges to control while programming the FPGA. The region driver can build a list of bridges during probe time -(:c:member:`fpga_region->bridge_list`) or it can have a function that creates +(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates the list of bridges to program just before programming -(:c:member:`fpga_region->get_bridges`). The FPGA bridge framework supplies the +(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the following APIs to handle building or tearing down that list. * fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index dd64c9c5fb1e..3ddebddc02ca 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -2,7 +2,7 @@ Buffers ======= -* struct :c:type:`iio_buffer` — general buffer structure +* struct iio_buffer — general buffer structure * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel is selected * :c:func:`iio_buffer_get` — Grab a reference to the buffer diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst index 51b21e002396..715cf29482a1 100644 --- a/Documentation/driver-api/iio/core.rst +++ b/Documentation/driver-api/iio/core.rst @@ -10,7 +10,7 @@ applications manipulating sensors. The implementation can be found under Industrial I/O Devices ---------------------- -* struct :c:type:`iio_dev` - industrial I/O device +* struct iio_dev - industrial I/O device * iio_device_alloc() - allocate an :c:type:`iio_dev` from a driver * iio_device_free() - free an :c:type:`iio_dev` from a driver * iio_device_register() - register a device with the IIO subsystem @@ -66,7 +66,7 @@ Common attributes are: IIO device channels =================== -struct :c:type:`iio_chan_spec` - specification of a single channel +struct iio_chan_spec - specification of a single channel An IIO device channel is a representation of a data channel. An IIO device can have one or multiple channels. For example: @@ -77,7 +77,7 @@ have one or multiple channels. For example: * an accelerometer can have up to 3 channels representing acceleration on X, Y and Z axes. -An IIO channel is described by the struct :c:type:`iio_chan_spec`. +An IIO channel is described by the struct iio_chan_spec. A thermometer driver for the temperature sensor in the example above would have to describe its channel as follows:: diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst index 819fb9edc005..76133a3796f2 100644 --- a/Documentation/driver-api/iio/hw-consumer.rst +++ b/Documentation/driver-api/iio/hw-consumer.rst @@ -8,7 +8,7 @@ software buffer for data. The implementation can be found under :file:`drivers/iio/buffer/hw-consumer.c` -* struct :c:type:`iio_hw_consumer` — Hardware consumer structure +* struct iio_hw_consumer — Hardware consumer structure * :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer * :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer * :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer diff --git a/Documentation/driver-api/iio/triggered-buffers.rst b/Documentation/driver-api/iio/triggered-buffers.rst index 0db12660cc90..417555dbbdf4 100644 --- a/Documentation/driver-api/iio/triggered-buffers.rst +++ b/Documentation/driver-api/iio/triggered-buffers.rst @@ -10,7 +10,7 @@ IIO triggered buffer setup * :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc * :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by :c:func:`iio_triggered_buffer_setup` -* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks +* struct iio_buffer_setup_ops — buffer setup related callbacks A typical triggered buffer setup looks like this:: diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst index dfd7ba3eabde..288625e40672 100644 --- a/Documentation/driver-api/iio/triggers.rst +++ b/Documentation/driver-api/iio/triggers.rst @@ -2,7 +2,7 @@ Triggers ======== -* struct :c:type:`iio_trigger` — industrial I/O trigger device +* struct iio_trigger — industrial I/O trigger device * :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc * :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register iio_trigger_unregister @@ -63,7 +63,7 @@ Let's see a simple example of how to setup a trigger to be used by a driver:: IIO trigger ops =============== -* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger. +* struct iio_trigger_ops — operations structure for an iio_trigger. Notice that a trigger has a set of operations attached: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6e7c702e0268..f357f3eb400c 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -27,7 +27,6 @@ available subsections can be seen below. component message-based infiniband - sound frame-buffer regulator iio/index @@ -78,7 +77,6 @@ available subsections can be seen below. console dcdbas eisa - ipmb isa isapnp io-mapping diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 06d98c4526df..683bd460e222 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -6,6 +6,7 @@ The Basic Device Driver-Model Structures .. kernel-doc:: include/linux/device.h :internal: + :no-identifiers: device_link_state Device Drivers Base ------------------- @@ -28,9 +29,6 @@ Device Drivers Base .. kernel-doc:: drivers/base/node.c :internal: -.. kernel-doc:: drivers/base/firmware_loader/main.c - :export: - .. kernel-doc:: drivers/base/transport_class.c :export: diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst index e2f87b82b074..d477e296bda5 100644 --- a/Documentation/driver-api/libata.rst +++ b/Documentation/driver-api/libata.rst @@ -508,7 +508,7 @@ also complete commands. 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. -3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the +3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the callback is not zero. Completion is short circuited and :c:func:`ata_qc_complete` returns. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index 03016eeaf8f4..bc42982ac21e 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -98,7 +98,7 @@ Implementing the Low-Level CEC Adapter The following low-level adapter operations have to be implemented in your driver: -.. c:type:: struct cec_adap_ops +.. c:struct:: cec_adap_ops .. code-block:: none diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst index b362109bb131..91f77fe58e83 100644 --- a/Documentation/driver-api/media/dtv-frontend.rst +++ b/Documentation/driver-api/media/dtv-frontend.rst @@ -125,7 +125,7 @@ responsible for tuning the device. It supports multiple algorithms to detect a channel, as defined at enum :c:func:`dvbfe_algo`. The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver -doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to +doesn't fill its field at struct dvb_frontend_ops, it will default to ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning, e. g. it will try first to use the specified center frequency ``f``, then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|, @@ -140,7 +140,7 @@ define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``. a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to define its own hardware-assisted algorithm. Very few hardware need to use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other - function callbacks at struct :c:type:`dvb_frontend_ops`. + function callbacks at struct dvb_frontend_ops. Attaching frontend driver to the bridge driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst index 05bba0b61748..57b5bbba944e 100644 --- a/Documentation/driver-api/media/mc-core.rst +++ b/Documentation/driver-api/media/mc-core.rst @@ -36,7 +36,7 @@ pad to a sink pad. Media device ^^^^^^^^^^^^ -A media device is represented by a struct :c:type:`media_device` +A media device is represented by a struct media_device instance, defined in ``include/media/media-device.h``. Allocation of the structure is handled by the media device driver, usually by embedding the :c:type:`media_device` instance in a larger driver-specific @@ -49,7 +49,7 @@ and unregistered by calling :c:func:`media_device_unregister()`. Entities ^^^^^^^^ -Entities are represented by a struct :c:type:`media_entity` +Entities are represented by a struct media_entity instance, defined in ``include/media/media-entity.h``. The structure is usually embedded into a higher-level structure, such as :c:type:`v4l2_subdev` or :c:type:`video_device` @@ -67,10 +67,10 @@ Interfaces ^^^^^^^^^^ Interfaces are represented by a -struct :c:type:`media_interface` instance, defined in +struct media_interface instance, defined in ``include/media/media-entity.h``. Currently, only one type of interface is defined: a device node. Such interfaces are represented by a -struct :c:type:`media_intf_devnode`. +struct media_intf_devnode. Drivers initialize and create device node interfaces by calling :c:func:`media_devnode_create()` @@ -79,7 +79,7 @@ and remove them by calling: Pads ^^^^ -Pads are represented by a struct :c:type:`media_pad` instance, +Pads are represented by a struct media_pad instance, defined in ``include/media/media-entity.h``. Each entity stores its pads in a pads array managed by the entity driver. Drivers usually embed the array in a driver-specific structure. @@ -87,8 +87,8 @@ a driver-specific structure. Pads are identified by their entity and their 0-based index in the pads array. -Both information are stored in the struct :c:type:`media_pad`, -making the struct :c:type:`media_pad` pointer the canonical way +Both information are stored in the struct media_pad, +making the struct media_pad pointer the canonical way to store and pass link references. Pads have flags that describe the pad capabilities and state. @@ -104,7 +104,7 @@ Pads have flags that describe the pad capabilities and state. Links ^^^^^ -Links are represented by a struct :c:type:`media_link` instance, +Links are represented by a struct media_link instance, defined in ``include/media/media-entity.h``. There are two types of links: **1. pad to pad links**: @@ -187,7 +187,7 @@ Use count and power handling Due to the wide differences between drivers regarding power management needs, the media controller does not implement power management. However, -the struct :c:type:`media_entity` includes a ``use_count`` +the struct media_entity includes a ``use_count`` field that media drivers can use to track the number of users of every entity for power management needs. @@ -213,11 +213,11 @@ prevent link states from being modified during streaming by calling The function will mark all entities connected to the given entity through enabled links, either directly or indirectly, as streaming. -The struct :c:type:`media_pipeline` instance pointed to by +The struct media_pipeline instance pointed to by the pipe argument will be stored in every entity in the pipeline. -Drivers should embed the struct :c:type:`media_pipeline` +Drivers should embed the struct media_pipeline in higher-level pipeline structures and can then access the -pipeline through the struct :c:type:`media_entity` +pipeline through the struct media_entity pipe field. Calls to :c:func:`media_pipeline_start()` can be nested. diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst index 5129019afb49..77f42ea3bac7 100644 --- a/Documentation/driver-api/media/v4l2-controls.rst +++ b/Documentation/driver-api/media/v4l2-controls.rst @@ -27,7 +27,7 @@ V4L2 specification with respect to controls in a central place. And to make life as easy as possible for the driver developer. Note that the control framework relies on the presence of a struct -:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for sub-device drivers. diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst index 63c064837c00..666330af31ed 100644 --- a/Documentation/driver-api/media/v4l2-dev.rst +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -67,7 +67,7 @@ You should also set these fields of :c:type:`video_device`: file operation is called this lock will be taken by the core and released afterwards. See the next section for more details. -- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue` +- :c:type:`video_device`->queue: a pointer to the struct vb2_queue associated with this device node. If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``, @@ -81,7 +81,7 @@ You should also set these fields of :c:type:`video_device`: - :c:type:`video_device`->prio: keeps track of the priorities. Used to implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. - If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state` + If left to ``NULL``, then it will use the struct v4l2_prio_state in :c:type:`v4l2_device`. If you want to have a separate priority state per (group of) device node(s), then you can point it to your own struct :c:type:`v4l2_prio_state`. @@ -95,7 +95,7 @@ You should also set these fields of :c:type:`video_device`: but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI devices at the same time it is setup without a parent device. But when the - struct :c:type:`video_device` is initialized you **do** know which parent + struct video_device is initialized you **do** know which parent PCI device to use and so you set ``dev_device`` to the correct PCI device. If you use :c:type:`v4l2_ioctl_ops`, then you should set @@ -138,7 +138,7 @@ ioctls and locking ------------------ The V4L core provides optional locking services. The main service is the -lock field in struct :c:type:`video_device`, which is a pointer to a mutex. +lock field in struct video_device, which is a pointer to a mutex. If you set this pointer, then that will be used by unlocked_ioctl to serialize all ioctls. diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst index 5e25bf182c18..7bd9c45f551b 100644 --- a/Documentation/driver-api/media/v4l2-device.rst +++ b/Documentation/driver-api/media/v4l2-device.rst @@ -3,7 +3,7 @@ V4L2 device instance -------------------- -Each device instance is represented by a struct :c:type:`v4l2_device`. +Each device instance is represented by a struct v4l2_device. Very simple devices can just allocate this struct, but most of the time you would embed this struct inside a larger struct. @@ -18,9 +18,9 @@ dev->driver_data field is ``NULL``, it will be linked to Drivers that want integration with the media device framework need to set dev->driver_data manually to point to the driver-specific device structure -that embed the struct :c:type:`v4l2_device` instance. This is achieved by a +that embed the struct v4l2_device instance. This is achieved by a ``dev_set_drvdata()`` call before registering the V4L2 device instance. -They must also set the struct :c:type:`v4l2_device` mdev field to point to a +They must also set the struct v4l2_device mdev field to point to a properly initialized and registered :c:type:`media_device` instance. If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst index a4b7ae2b94d8..5b8254eba7da 100644 --- a/Documentation/driver-api/media/v4l2-event.rst +++ b/Documentation/driver-api/media/v4l2-event.rst @@ -44,18 +44,18 @@ such objects. So to summarize: -- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, +- struct v4l2_fh has two lists: one of the ``subscribed`` events, and one of the ``available`` events. -- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised +- struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of that particular type. -- If struct :c:type:`v4l2_subscribed_event` is associated with a specific +- If struct v4l2_subscribed_event is associated with a specific object, then that object will have an internal list of - struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an + struct v4l2_subscribed_event so it knows who subscribed an event to that object. -Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has +Furthermore, the internal struct v4l2_subscribed_event has ``merge()`` and ``replace()`` callbacks which drivers can set. These callbacks are called when a new event is raised and there is no more room. diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst index 4c62b19af744..3eeaa8da0c9e 100644 --- a/Documentation/driver-api/media/v4l2-fh.rst +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -3,11 +3,11 @@ V4L2 File handlers ------------------ -struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific +struct v4l2_fh provides a way to easily keep file handle specific data that is used by the V4L2 framework. .. attention:: - New drivers must use struct :c:type:`v4l2_fh` + New drivers must use struct v4l2_fh since it is also used to implement priority handling (:ref:`VIDIOC_G_PRIORITY`). @@ -16,11 +16,11 @@ whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. This bit is set whenever :c:func:`v4l2_fh_init` is called. -struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle +struct v4l2_fh is allocated as a part of the driver's own file handle structure and ``file->private_data`` is set to it in the driver's ``open()`` function by the driver. -In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger +In many cases the struct v4l2_fh will be embedded in a larger structure. In that case you should call: #) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()`` @@ -102,18 +102,18 @@ Below is a short description of the :c:type:`v4l2_fh` functions used: memory can be freed. -If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: +If struct v4l2_fh is not embedded, then you can use these helper functions: :c:func:`v4l2_fh_open <v4l2_fh_open>` (struct file \*filp) -- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to - the struct :c:type:`video_device` associated with the file struct. +- This allocates a struct v4l2_fh, initializes it and adds it to + the struct video_device associated with the file struct. :c:func:`v4l2_fh_release <v4l2_fh_release>` (struct file \*filp) -- This deletes it from the struct :c:type:`video_device` associated with the +- This deletes it from the struct video_device associated with the file struct, uninitialised the :c:type:`v4l2_fh` and frees it. These two functions can be plugged into the v4l2_file_operation's ``open()`` diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 6248ea99e979..bb5b1a7cdfd9 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -110,7 +110,7 @@ pads: err = media_entity_pads_init(&sd->entity, npads, pads); The pads array must have been previously initialized. There is no need to -manually set the struct :c:type:`media_entity` function and name fields, but the +manually set the struct media_entity function and name fields, but the revision field must be initialized if needed. A reference to the entity will be automatically acquired/released when the diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-api/mei/mei.rst index cea0b69ec216..4f2ced4ccdc6 100644 --- a/Documentation/driver-api/mei/mei.rst +++ b/Documentation/driver-api/mei/mei.rst @@ -38,7 +38,7 @@ Because some of the Intel ME features can change the system configuration, the driver by default allows only a privileged user to access it. -The session is terminated calling :c:func:`close(int fd)`. +The session is terminated calling :c:expr:`close(fd)`. A code snippet for an application communicating with Intel AMTHI client: diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst index 3588bf078566..d477208604b8 100644 --- a/Documentation/driver-api/pm/cpuidle.rst +++ b/Documentation/driver-api/pm/cpuidle.rst @@ -1,11 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> -.. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` -.. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>` -.. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>` -.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` - ======================== CPU Idle Time Management ======================== @@ -54,7 +49,7 @@ platform that the Linux kernel can run on. For this reason, data structures operated on by them cannot depend on any hardware architecture or platform design details as well. -The governor itself is represented by a |struct cpuidle_governor| object +The governor itself is represented by a struct cpuidle_governor object containing four callback pointers, :c:member:`enable`, :c:member:`disable`, :c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described below, and a name (string) used for identifying it. @@ -83,11 +78,11 @@ callbacks: int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); The role of this callback is to prepare the governor for handling the - (logical) CPU represented by the |struct cpuidle_device| object pointed - to by the ``dev`` argument. The |struct cpuidle_driver| object pointed + (logical) CPU represented by the struct cpuidle_device object pointed + to by the ``dev`` argument. The struct cpuidle_driver object pointed to by the ``drv`` argument represents the ``CPUIdle`` driver to be used with that CPU (among other things, it should contain the list of - |struct cpuidle_state| objects representing idle states that the + struct cpuidle_state objects representing idle states that the processor holding the given CPU can be asked to enter). It may fail, in which case it is expected to return a negative error @@ -102,7 +97,7 @@ callbacks: void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); Called to make the governor stop handling the (logical) CPU represented - by the |struct cpuidle_device| object pointed to by the ``dev`` + by the struct cpuidle_device object pointed to by the ``dev`` argument. It is expected to reverse any changes made by the ``->enable()`` @@ -116,12 +111,12 @@ callbacks: bool *stop_tick); Called to select an idle state for the processor holding the (logical) - CPU represented by the |struct cpuidle_device| object pointed to by the + CPU represented by the struct cpuidle_device object pointed to by the ``dev`` argument. The list of idle states to take into consideration is represented by the - :c:member:`states` array of |struct cpuidle_state| objects held by the - |struct cpuidle_driver| object pointed to by the ``drv`` argument (which + :c:member:`states` array of struct cpuidle_state objects held by the + struct cpuidle_driver object pointed to by the ``drv`` argument (which represents the ``CPUIdle`` driver to be used with the CPU at hand). The value returned by this callback is interpreted as an index into that array (unless it is a negative error code). @@ -136,7 +131,7 @@ callbacks: asking the processor to enter the idle state). This callback is mandatory (i.e. the :c:member:`select` callback pointer - in |struct cpuidle_governor| must not be ``NULL`` for the registration + in struct cpuidle_governor must not be ``NULL`` for the registration of the governor to succeed). :c:member:`reflect` @@ -167,21 +162,21 @@ CPU idle time management (``CPUIdle``) drivers provide an interface between the other parts of ``CPUIdle`` and the hardware. First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array -of |struct cpuidle_state| objects included in the |struct cpuidle_driver| object +of struct cpuidle_state objects included in the struct cpuidle_driver object representing it. Going forward this array will represent the list of available idle states that the processor hardware can be asked to enter shared by all of the logical CPUs handled by the given driver. The entries in the :c:member:`states` array are expected to be sorted by the -value of the :c:member:`target_residency` field in |struct cpuidle_state| in +value of the :c:member:`target_residency` field in struct cpuidle_state in the ascending order (that is, index 0 should correspond to the idle state with the minimum value of :c:member:`target_residency`). [Since the :c:member:`target_residency` value is expected to reflect the "depth" of the -idle state represented by the |struct cpuidle_state| object holding it, this +idle state represented by the struct cpuidle_state object holding it, this sorting order should be the same as the ascending sorting order by the idle state "depth".] -Three fields in |struct cpuidle_state| are used by the existing ``CPUIdle`` +Three fields in struct cpuidle_state are used by the existing ``CPUIdle`` governors for computations related to idle state selection: :c:member:`target_residency` @@ -203,7 +198,7 @@ governors for computations related to idle state selection: any idle state at all. [There are other flags used by the ``CPUIdle`` core in special situations.] -The :c:member:`enter` callback pointer in |struct cpuidle_state|, which must not +The :c:member:`enter` callback pointer in struct cpuidle_state, which must not be ``NULL``, points to the routine to execute in order to ask the processor to enter this particular idle state: @@ -212,14 +207,14 @@ enter this particular idle state: void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv, int index); -The first two arguments of it point to the |struct cpuidle_device| object +The first two arguments of it point to the struct cpuidle_device object representing the logical CPU running this callback and the -|struct cpuidle_driver| object representing the driver itself, respectively, -and the last one is an index of the |struct cpuidle_state| entry in the driver's +struct cpuidle_driver object representing the driver itself, respectively, +and the last one is an index of the struct cpuidle_state entry in the driver's :c:member:`states` array representing the idle state to ask the processor to enter. -The analogous ``->enter_s2idle()`` callback in |struct cpuidle_state| is used +The analogous ``->enter_s2idle()`` callback in struct cpuidle_state is used only for implementing the suspend-to-idle system-wide power management feature. The difference between in and ``->enter()`` is that it must not re-enable interrupts at any point (even temporarily) or attempt to change the states of @@ -227,48 +222,48 @@ clock event devices, which the ``->enter()`` callback may do sometimes. Once the :c:member:`states` array has been populated, the number of valid entries in it has to be stored in the :c:member:`state_count` field of the -|struct cpuidle_driver| object representing the driver. Moreover, if any +struct cpuidle_driver object representing the driver. Moreover, if any entries in the :c:member:`states` array represent "coupled" idle states (that is, idle states that can only be asked for if multiple related logical CPUs are -idle), the :c:member:`safe_state_index` field in |struct cpuidle_driver| needs +idle), the :c:member:`safe_state_index` field in struct cpuidle_driver needs to be the index of an idle state that is not "coupled" (that is, one that can be asked for if only one logical CPU is idle). In addition to that, if the given ``CPUIdle`` driver is only going to handle a subset of logical CPUs in the system, the :c:member:`cpumask` field in its -|struct cpuidle_driver| object must point to the set (mask) of CPUs that will be +struct cpuidle_driver object must point to the set (mask) of CPUs that will be handled by it. A ``CPUIdle`` driver can only be used after it has been registered. If there are no "coupled" idle state entries in the driver's :c:member:`states` array, -that can be accomplished by passing the driver's |struct cpuidle_driver| object +that can be accomplished by passing the driver's struct cpuidle_driver object to :c:func:`cpuidle_register_driver()`. Otherwise, :c:func:`cpuidle_register()` should be used for this purpose. -However, it also is necessary to register |struct cpuidle_device| objects for +However, it also is necessary to register struct cpuidle_device objects for all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the help of :c:func:`cpuidle_register_device()` after the driver has been registered and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`, does not do that automatically. For this reason, the drivers that use :c:func:`cpuidle_register_driver()` to register themselves must also take care -of registering the |struct cpuidle_device| objects as needed, so it is generally +of registering the struct cpuidle_device objects as needed, so it is generally recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver registration in all cases. -The registration of a |struct cpuidle_device| object causes the ``CPUIdle`` +The registration of a struct cpuidle_device object causes the ``CPUIdle`` ``sysfs`` interface to be created and the governor's ``->enable()`` callback to be invoked for the logical CPU represented by it, so it must take place after registering the driver that will handle the CPU in question. -``CPUIdle`` drivers and |struct cpuidle_device| objects can be unregistered +``CPUIdle`` drivers and struct cpuidle_device objects can be unregistered when they are not necessary any more which allows some resources associated with them to be released. Due to dependencies between them, all of the -|struct cpuidle_device| objects representing CPUs handled by the given +struct cpuidle_device objects representing CPUs handled by the given ``CPUIdle`` driver must be unregistered, with the help of :c:func:`cpuidle_unregister_device()`, before calling :c:func:`cpuidle_unregister_driver()` to unregister the driver. Alternatively, :c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver -along with all of the |struct cpuidle_device| objects representing CPUs handled +along with all of the struct cpuidle_device objects representing CPUs handled by it. ``CPUIdle`` drivers can respond to runtime system configuration changes that @@ -277,8 +272,8 @@ happen, for example, when the system's power source is switched from AC to battery or the other way around). Upon a notification of such a change, a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for -all of the |struct cpuidle_device| objects representing CPUs affected by that +all of the struct cpuidle_device objects representing CPUs affected by that change. Next, it can update its :c:member:`states` array in accordance with the new configuration of the system, call :c:func:`cpuidle_enable_device()` for -all of the relevant |struct cpuidle_device| objects and invoke +all of the relevant struct cpuidle_device objects and invoke :c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 946ad0b94e31..6b3bfd29fd84 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -1,14 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> -.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` -.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` -.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>` -.. |struct device_type| replace:: :c:type:`struct device_type <device_type>` -.. |struct class| replace:: :c:type:`struct class <class>` -.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>` -.. |struct device| replace:: :c:type:`struct device <device>` - .. _driverapi_pm_devices: ============================== @@ -107,7 +99,7 @@ Device Power Management Operations Device power management operations, at the subsystem level as well as at the device driver level, are implemented by defining and populating objects of type -|struct dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the +struct dev_pm_ops defined in :file:`include/linux/pm.h`. The roles of the methods included in it will be explained in what follows. For now, it should be sufficient to remember that the last three methods are specific to runtime power management while the remaining ones are used during system-wide power @@ -115,7 +107,7 @@ transitions. There also is a deprecated "old" or "legacy" interface for power management operations available at least for some subsystems. This approach does not use -|struct dev_pm_ops| objects and it is suitable only for implementing system +struct dev_pm_ops objects and it is suitable only for implementing system sleep power management methods in a limited way. Therefore it is not described in this document, so please refer directly to the source code for more information about it. @@ -125,9 +117,9 @@ Subsystem-Level Methods ----------------------- The core methods to suspend and resume devices reside in -|struct dev_pm_ops| pointed to by the :c:member:`ops` member of -|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|, -|struct device_type| and |struct class|. They are mostly of interest to the +struct dev_pm_ops pointed to by the :c:member:`ops` member of +struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type, +struct device_type and struct class. They are mostly of interest to the people writing infrastructure for platforms and buses, like PCI or USB, or device type and device class drivers. They also are relevant to the writers of device drivers whose subsystems (PM domains, device types, device classes and @@ -156,7 +148,7 @@ The :c:member:`power.can_wakeup` flag just records whether the device (and its driver) can physically support wakeup events. The :c:func:`device_set_wakeup_capable()` routine affects this flag. The :c:member:`power.wakeup` field is a pointer to an object of type -|struct wakeup_source| used for controlling whether or not the device should use +struct wakeup_source used for controlling whether or not the device should use its system wakeup mechanism and for notifying the PM core of system wakeup events signaled by the device. This object is only present for wakeup-capable devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created @@ -418,7 +410,7 @@ On many platforms they will gate off one or more clock sources; sometimes they will also switch off power supplies or reduce voltages. [Drivers supporting runtime PM may already have performed some or all of these steps.] -If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be +If :c:func:`device_may_wakeup()` returns ``true``, the device should be prepared for generating hardware wakeup signals to trigger a system wakeup event when the system is in the sleep state. For example, :c:func:`enable_irq_wake()` might identify GPIO signals hooked up to a switch or other external hardware, @@ -713,8 +705,8 @@ nested inside another power domain. The nested domain is referred to as the sub-domain of the parent domain. Support for power domains is provided through the :c:member:`pm_domain` field of -|struct device|. This field is a pointer to an object of type -|struct dev_pm_domain|, defined in :file:`include/linux/pm.h`, providing a set +struct device. This field is a pointer to an object of type +struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set of power management callbacks analogous to the subsystem-level and device driver callbacks that are executed for the given device during all power transitions, instead of the respective subsystem-level callbacks. Specifically, if a diff --git a/Documentation/driver-api/regulator.rst b/Documentation/driver-api/regulator.rst index 520da0a5251d..b43c78eb24d8 100644 --- a/Documentation/driver-api/regulator.rst +++ b/Documentation/driver-api/regulator.rst @@ -116,7 +116,7 @@ core, providing operations structures to the core. A notifier interface allows error conditions to be reported to the core. Registration should be triggered by explicit setup done by the platform, -supplying a struct :c:type:`regulator_init_data` for the regulator +supplying a struct regulator_init_data for the regulator containing constraint and supply information. Machine interface @@ -144,7 +144,7 @@ a given system, for example supporting higher supply voltages than the consumers are rated for. This is done at driver registration time` by providing a -struct :c:type:`regulation_constraints`. +struct regulation_constraints. The constraints may also specify an initial configuration for the regulator in the constraints, which is particularly useful for use with diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst deleted file mode 100644 index afef6eabc073..000000000000 --- a/Documentation/driver-api/sound.rst +++ /dev/null @@ -1,54 +0,0 @@ -Sound Devices -============= - -.. kernel-doc:: include/sound/core.h - :internal: - -.. kernel-doc:: sound/sound_core.c - :export: - -.. kernel-doc:: include/sound/pcm.h - :internal: - -.. kernel-doc:: sound/core/pcm.c - :export: - -.. kernel-doc:: sound/core/device.c - :export: - -.. kernel-doc:: sound/core/info.c - :export: - -.. kernel-doc:: sound/core/rawmidi.c - :export: - -.. kernel-doc:: sound/core/sound.c - :export: - -.. kernel-doc:: sound/core/memory.c - :export: - -.. kernel-doc:: sound/core/pcm_memory.c - :export: - -.. kernel-doc:: sound/core/init.c - :export: - -.. kernel-doc:: sound/core/isadma.c - :export: - -.. kernel-doc:: sound/core/control.c - :export: - -.. kernel-doc:: sound/core/pcm_lib.c - :export: - -.. kernel-doc:: sound/core/hwdep.c - :export: - -.. kernel-doc:: sound/core/pcm_native.c - :export: - -.. kernel-doc:: sound/core/memalloc.c - :export: - diff --git a/Documentation/driver-api/target.rst b/Documentation/driver-api/target.rst index 620ec6173a93..c70ca25171c0 100644 --- a/Documentation/driver-api/target.rst +++ b/Documentation/driver-api/target.rst @@ -41,18 +41,6 @@ iSCSI boot information .. kernel-doc:: drivers/scsi/iscsi_boot_sysfs.c :export: - -iSCSI transport class -===================== - -The file drivers/scsi/scsi_transport_iscsi.c defines transport -attributes for the iSCSI class, which sends SCSI packets over TCP/IP -connections. - -.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c - :export: - - iSCSI TCP interfaces ==================== diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst index 1e4abc896a0d..a182c0f5e38a 100644 --- a/Documentation/driver-api/usb/URB.rst +++ b/Documentation/driver-api/usb/URB.rst @@ -47,7 +47,7 @@ called USB Request Block, or URB for short. The URB structure ================= -Some of the fields in struct :c:type:`urb` are:: +Some of the fields in struct urb are:: struct urb { diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst index 3e8a3809c0b8..09396edd6131 100644 --- a/Documentation/driver-api/usb/gadget.rst +++ b/Documentation/driver-api/usb/gadget.rst @@ -176,9 +176,9 @@ Kernel Mode Gadget API Gadget drivers declare themselves through a struct :c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration -for a struct :c:type:`usb_gadget`. The response to a set_configuration usually -involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by -the gadget, and submitting one or more struct :c:type:`usb_request` buffers to +for a struct usb_gadget. The response to a set_configuration usually +involves enabling one or more of the struct usb_ep objects exposed by +the gadget, and submitting one or more struct usb_request buffers to transfer data. Understand those four data types, and their operations, and you will understand how this API works. @@ -339,8 +339,8 @@ multi-configuration devices (also more than one function, but not necessarily sharing a given configuration). There is however an optional framework which makes it easier to reuse and combine functions. -Devices using this framework provide a struct :c:type:`usb_composite_driver`, -which in turn provides one or more struct :c:type:`usb_configuration` +Devices using this framework provide a struct usb_composite_driver, +which in turn provides one or more struct usb_configuration instances. Each such configuration includes at least one struct :c:type:`usb_function`, which packages a user visible role such as "network link" or "mass storage device". Management functions may also exist, diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst index 79663e653ca1..c1e13107c50e 100644 --- a/Documentation/driver-api/usb/hotplug.rst +++ b/Documentation/driver-api/usb/hotplug.rst @@ -122,7 +122,7 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this:: Most USB device drivers should pass these tables to the USB subsystem as well as to the module management subsystem. Not all, though: some driver frameworks connect using interfaces layered over USB, and so they won't -need such a struct :c:type:`usb_driver`. +need such a struct usb_driver. Drivers that connect directly to the USB subsystem should be declared something like this:: diff --git a/Documentation/driver-api/usb/typec_bus.rst b/Documentation/driver-api/usb/typec_bus.rst index 03dfa9c018b7..21c890ae17e5 100644 --- a/Documentation/driver-api/usb/typec_bus.rst +++ b/Documentation/driver-api/usb/typec_bus.rst @@ -91,10 +91,16 @@ their control. Driver API ---------- +Alternate mode structs +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/usb/typec_altmode.h + :functions: typec_altmode_driver typec_altmode_ops + Alternate mode driver registering/unregistering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/usb/typec/bus.c +.. kernel-doc:: include/linux/usb/typec_altmode.h :functions: typec_altmode_register_driver typec_altmode_unregister_driver Alternate mode driver operations diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index f850ad018b70..31ecfe44e5b4 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -16,6 +16,10 @@ Available fault injection capabilities injects page allocation failures. (alloc_pages(), get_free_pages(), ...) +- fail_usercopy + + injects failures in user memory access functions. (copy_from_user(), get_user(), ...) + - fail_futex injects futex deadlock and uaddr fault errors. @@ -177,6 +181,7 @@ use the boot option:: failslab= fail_page_alloc= + fail_usercopy= fail_make_request= fail_futex= mmc_core.fail_request=<interval>,<probability>,<space>,<times> @@ -222,7 +227,7 @@ How to add new fault injection capability - debugfs entries - failslab, fail_page_alloc, and fail_make_request use this way. + failslab, fail_page_alloc, fail_usercopy, and fail_make_request use this way. Helper functions: fault_create_debugfs_attr(name, parent, attr); diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst index 9279a3e12278..a20ba5d93932 100644 --- a/Documentation/fault-injection/provoke-crashes.rst +++ b/Documentation/fault-injection/provoke-crashes.rst @@ -1,16 +1,19 @@ -=============== -Provoke crashes -=============== +.. SPDX-License-Identifier: GPL-2.0 -The lkdtm module provides an interface to crash or injure the kernel at -predefined crashpoints to evaluate the reliability of crash dumps obtained -using different dumping solutions. The module uses KPROBEs to instrument -crashing points, but can also crash the kernel directly without KRPOBE -support. +============================================================ +Provoking crashes with Linux Kernel Dump Test Module (LKDTM) +============================================================ +The lkdtm module provides an interface to disrupt (and usually crash) +the kernel at predefined code locations to evaluate the reliability of +the kernel's exception handling and to test crash dumps obtained using +different dumping solutions. The module uses KPROBEs to instrument the +trigger location, but can also trigger the kernel directly without KPROBE +support via debugfs. -You can provide the way either through module arguments when inserting -the module, or through a debugfs interface. +You can select the location of the trigger ("crash point name") and the +type of action ("crash point type") either through module arguments when +inserting the module, or through the debugfs interface. Usage:: @@ -18,31 +21,38 @@ Usage:: [cpoint_count={>0}] recur_count - Recursion level for the stack overflow test. Default is 10. + Recursion level for the stack overflow test. By default this is + dynamically calculated based on kernel configuration, with the + goal of being just large enough to exhaust the kernel stack. The + value can be seen at `/sys/module/lkdtm/parameters/recur_count`. cpoint_name - Crash point where the kernel is to be crashed. It can be + Where in the kernel to trigger the action. It can be one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY, FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD, - IDE_CORE_CP, DIRECT + IDE_CORE_CP, or DIRECT cpoint_type Indicates the action to be taken on hitting the crash point. - It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW, - CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION, - WRITE_AFTER_FREE, + These are numerous, and best queried directly from debugfs. Some + of the common ones are PANIC, BUG, EXCEPTION, LOOP, and OVERFLOW. + See the contents of `/sys/kernel/debug/provoke-crash/DIRECT` for + a complete list. cpoint_count Indicates the number of times the crash point is to be hit - to trigger an action. The default is 10. + before triggering the action. The default is 10 (except for + DIRECT, which always fires immediately). You can also induce failures by mounting debugfs and writing the type to -<mountpoint>/provoke-crash/<crashpoint>. E.g.:: +<debugfs>/provoke-crash/<crashpoint>. E.g.:: - mount -t debugfs debugfs /mnt - echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY + mount -t debugfs debugfs /sys/kernel/debug + echo EXCEPTION > /sys/kernel/debug/provoke-crash/INT_HARDWARE_ENTRY +The special file `DIRECT` will induce the action directly without KPROBE +instrumentation. This mode is the only one available when the module is +built for a kernel without KPROBEs support:: -A special file is `DIRECT` which will induce the crash directly without -KPROBE instrumentation. This mode is the only one available when the module -is built on a kernel without KPROBEs support. + # Instead of having a BUG kill your shell, have it kill "cat": + cat <(echo WRITE_RO) >/sys/kernel/debug/provoke-crash/DIRECT diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 9aad964b767c..57f66de2f7e1 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -81,7 +81,7 @@ C. Boot options 1. fbcon=font:<name> Select the initial font to use. The value 'name' can be any of the - compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6, + compiled-in fonts: 10x18, 6x10, 6x8, 7x14, Acorn8x8, MINI4x6, PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, TER16x32, VGA8x16, VGA8x8. Note, not all drivers can handle font with widths not divisible by 8, diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 1cb7406cd858..b5fb37c28cc6 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -24,7 +24,7 @@ | parisc: | TODO | | powerpc: | ok | | riscv: | TODO | - | s390: | TODO | + | s390: | ok | | sh: | ok | | sparc: | TODO | | um: | TODO | 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/ceph.rst b/Documentation/filesystems/ceph.rst index 0aa70750df0f..7d2ef4e27273 100644 --- a/Documentation/filesystems/ceph.rst +++ b/Documentation/filesystems/ceph.rst @@ -163,14 +163,14 @@ Mount Options to the default VFS implementation if this option is used. recover_session=<no|clean> - Set auto reconnect mode in the case where the client is blacklisted. The + Set auto reconnect mode in the case where the client is blocklisted. The available modes are "no" and "clean". The default is "no". * no: never attempt to reconnect when client detects that it has been - blacklisted. Operations will generally fail after being blacklisted. + blocklisted. Operations will generally fail after being blocklisted. * clean: client reconnects to the ceph cluster automatically when it - detects that it has been blacklisted. During reconnect, client drops + detects that it has been blocklisted. During reconnect, client drops dirty data/metadata, invalidates page caches and writable file handles. After reconnect, file locks become stale because the MDS loses track of them. If an inode contains any stale file locks, read/write on the 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 ea613ee701f5..849d5b119eb8 100644 --- a/Documentation/filesystems/ext4/journal.rst +++ b/Documentation/filesystems/ext4/journal.rst @@ -28,6 +28,17 @@ metadata are written to disk through the journal. This is slower but safest. If ``data=writeback``, dirty data blocks are not flushed to the disk before the metadata are written to disk through the journal. +In case of ``data=ordered`` mode, Ext4 also supports fast commits which +help reduce commit latency significantly. The default ``data=ordered`` +mode works by logging metadata blocks to the journal. In fast commit +mode, Ext4 only stores the minimal delta needed to recreate the +affected metadata in fast commit space that is shared with JBD2. +Once the fast commit area fills in or if fast commit is not possible +or if JBD2 commit timer goes off, Ext4 performs a traditional full commit. +A full commit invalidates all the fast commits that happened before +it and thus it makes the fast commit area empty for further fast +commits. This feature needs to be enabled at mkfs time. + The journal inode is typically inode 8. The first 68 bytes of the journal inode are replicated in the ext4 superblock. The journal itself is normal (but hidden) file within the filesystem. The file usually @@ -245,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] - @@ -299,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: @@ -609,3 +626,58 @@ bytes long (but uses a full block): - h\_commit\_nsec - Nanoseconds component of the above timestamp. +Fast commits +~~~~~~~~~~~~ + +Fast commit area is organized as a log of tag length values. Each TLV has +a ``struct ext4_fc_tl`` in the beginning which stores the tag and the length +of the entire field. It is followed by variable length tag specific value. +Here is the list of supported tags and their meanings: + +.. list-table:: + :widths: 8 20 20 32 + :header-rows: 1 + + * - Tag + - Meaning + - Value struct + - Description + * - EXT4_FC_TAG_HEAD + - Fast commit area header + - ``struct ext4_fc_head`` + - Stores the TID of the transaction after which these fast commits should + be applied. + * - EXT4_FC_TAG_ADD_RANGE + - Add extent to inode + - ``struct ext4_fc_add_range`` + - Stores the inode number and extent to be added in this inode + * - EXT4_FC_TAG_DEL_RANGE + - Remove logical offsets to inode + - ``struct ext4_fc_del_range`` + - Stores the inode number and the logical offset range that needs to be + removed + * - EXT4_FC_TAG_CREAT + - Create directory entry for a newly created file + - ``struct ext4_fc_dentry_info`` + - Stores the parent inode number, inode number and directory entry of the + newly created file + * - EXT4_FC_TAG_LINK + - Link a directory entry to an inode + - ``struct ext4_fc_dentry_info`` + - Stores the parent inode number, inode number and directory entry + * - EXT4_FC_TAG_UNLINK + - Unlink a directory entry of an inode + - ``struct ext4_fc_dentry_info`` + - Stores the parent inode number, inode number and directory entry + + * - EXT4_FC_TAG_PAD + - Padding (unused area) + - None + - Unused bytes in the fast commit area. + + * - EXT4_FC_TAG_TAIL + - Mark the end of a fast commit + - ``struct ext4_fc_tail`` + - Stores the TID of the commit, CRC of the fast commit of which this tag + represents the end of + 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/f2fs.rst b/Documentation/filesystems/f2fs.rst index ec8d99703ecb..b8ee761c9922 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -127,14 +127,14 @@ active_logs=%u Support configuring the number of active logs. In the current design, f2fs supports only 2, 4, and 6 logs. Default number is 6. disable_ext_identify Disable the extension list configured by mkfs, so f2fs - does not aware of cold files such as media files. + is not aware of cold files such as media files. inline_xattr Enable the inline xattrs feature. noinline_xattr Disable the inline xattrs feature. inline_xattr_size=%u Support configuring inline xattr size, it depends on flexible inline xattr feature. -inline_data Enable the inline data feature: New created small(<~3.4k) +inline_data Enable the inline data feature: Newly created small (<~3.4k) files can be written into inode block. -inline_dentry Enable the inline dir feature: data in new created +inline_dentry Enable the inline dir feature: data in newly created directory entries can be written into inode block. The space of inode block which is used to store inline dentries is limited to ~3.4k. @@ -203,9 +203,9 @@ usrjquota=<file> Appoint specified file and type during mount, so that quota grpjquota=<file> information can be properly updated during recovery flow, prjjquota=<file> <quota file>: must be in root directory; jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. -offusrjquota Turn off user journelled quota. -offgrpjquota Turn off group journelled quota. -offprjjquota Turn off project journelled quota. +offusrjquota Turn off user journalled quota. +offgrpjquota Turn off group journalled quota. +offprjjquota Turn off project journalled quota. quota Enable plain user disk quota accounting. noquota Disable all plain disk quota option. whint_mode=%s Control which write hints are passed down to block @@ -266,6 +266,8 @@ inlinecrypt When possible, encrypt/decrypt the contents of encrypted inline encryption hardware. The on-disk format is unaffected. For more details, see Documentation/block/inline-encryption.rst. +atgc Enable age-threshold garbage collection, it provides high + effectiveness and efficiency on background GC. ======================== ============================================================ Debugfs Entries @@ -301,7 +303,7 @@ Usage # insmod f2fs.ko -3. Create a directory trying to mount:: +3. Create a directory to use when mounting:: # mkdir /mnt/f2fs @@ -315,7 +317,7 @@ mkfs.f2fs The mkfs.f2fs is for the use of formatting a partition as the f2fs filesystem, which builds a basic on-disk layout. -The options consist of: +The quick options consist of: =============== =========================================================== ``-l [label]`` Give a volume label, up to 512 unicode name. @@ -337,6 +339,8 @@ The options consist of: 1 is set by default, which conducts discard. =============== =========================================================== +Note: please refer to the manpage of mkfs.f2fs(8) to get full option list. + fsck.f2fs --------- The fsck.f2fs is a tool to check the consistency of an f2fs-formatted @@ -344,10 +348,12 @@ partition, which examines whether the filesystem metadata and user-made data are cross-referenced correctly or not. Note that, initial version of the tool does not fix any inconsistency. -The options consist of:: +The quick options consist of:: -d debug level [default:0] +Note: please refer to the manpage of fsck.f2fs(8) to get full option list. + dump.f2fs --------- The dump.f2fs shows the information of specific inode and dumps SSA and SIT to @@ -371,6 +377,37 @@ Examples:: # dump.f2fs -s 0~-1 /dev/sdx (SIT dump) # dump.f2fs -a 0~-1 /dev/sdx (SSA dump) +Note: please refer to the manpage of dump.f2fs(8) to get full option list. + +sload.f2fs +---------- +The sload.f2fs gives a way to insert files and directories in the exisiting disk +image. This tool is useful when building f2fs images given compiled files. + +Note: please refer to the manpage of sload.f2fs(8) to get full option list. + +resize.f2fs +----------- +The resize.f2fs lets a user resize the f2fs-formatted disk image, while preserving +all the files and directories stored in the image. + +Note: please refer to the manpage of resize.f2fs(8) to get full option list. + +defrag.f2fs +----------- +The defrag.f2fs can be used to defragment scattered written data as well as +filesystem metadata across the disk. This can improve the write speed by giving +more free consecutive space. + +Note: please refer to the manpage of defrag.f2fs(8) to get full option list. + +f2fs_io +------- +The f2fs_io is a simple tool to issue various filesystem APIs as well as +f2fs-specific ones, which is very useful for QA tests. + +Note: please refer to the manpage of f2fs_io(8) to get full option list. + Design ====== @@ -383,7 +420,7 @@ consists of a set of sections. By default, section and zone sizes are set to one segment size identically, but users can easily modify the sizes by mkfs. F2FS splits the entire volume into six areas, and all the areas except superblock -consists of multiple segments as described below:: +consist of multiple segments as described below:: align with the zone size <-| |-> align with the segment size @@ -486,7 +523,7 @@ one inode block (i.e., a file) covers:: `- direct node (1018) `- data (1018) -Note that, all the node blocks are mapped by NAT which means the location of +Note that all the node blocks are mapped by NAT which means the location of each node is translated by the NAT table. In the consideration of the wandering tree problem, F2FS is able to cut off the propagation of node updates caused by leaf data writes. @@ -566,7 +603,7 @@ When F2FS finds a file name in a directory, at first a hash value of the file name is calculated. Then, F2FS scans the hash table in level #0 to find the dentry consisting of the file name and its inode number. If not found, F2FS scans the next hash table in level #1. In this way, F2FS scans hash tables in -each levels incrementally from 1 to N. In each levels F2FS needs to scan only +each levels incrementally from 1 to N. In each level F2FS needs to scan only one bucket determined by the following equation, which shows O(log(# of files)) complexity:: @@ -707,7 +744,7 @@ WRITE_LIFE_LONG " WRITE_LIFE_LONG Fallocate(2) Policy ------------------- -The default policy follows the below posix rule. +The default policy follows the below POSIX rule. Allocating disk space The default operation (i.e., mode is zero) of fallocate() allocates @@ -720,7 +757,7 @@ Allocating disk space as a method of optimally implementing that function. However, once F2FS receives ioctl(fd, F2FS_IOC_SET_PIN_FILE) in prior to -fallocate(fd, DEFAULT_MODE), it allocates on-disk blocks addressess having +fallocate(fd, DEFAULT_MODE), it allocates on-disk block addressess having zero or random data, which is useful to the below scenario where: 1. create(fd) @@ -739,7 +776,7 @@ Compression implementation cluster can be compressed or not. - In cluster metadata layout, one special block address is used to indicate - cluster is compressed one or normal one, for compressed cluster, following + a cluster is a compressed one or normal one; for compressed cluster, following metadata maps cluster to [1, 4 << n - 1] physical blocks, in where f2fs stores data including compress header and compressed data. @@ -772,3 +809,18 @@ Compress metadata layout:: +-------------+-------------+----------+----------------------------+ | data length | data chksum | reserved | compressed data | +-------------+-------------+----------+----------------------------+ + +NVMe Zoned Namespace devices +---------------------------- + +- ZNS defines a per-zone capacity which can be equal or less than the + zone-size. Zone-capacity is the number of usable blocks in the zone. + F2FS checks if zone-capacity is less than zone-size, if it is, then any + segment which starts after the zone-capacity is marked as not-free in + the free segment bitmap at initial mount time. These segments are marked + as permanently used so they are not allocated for writes and + consequently are not needed to be garbage collected. In case the + zone-capacity is not aligned to default segment size(2MB), then a segment + can start before the zone-capacity and span across zone-capacity boundary. + Such spanning segments are also considered as usable segments. All blocks + past the zone-capacity are considered unusable in these segments. diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 423c5a0daf45..44b67ebd6e40 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -436,9 +436,9 @@ FS_IOC_SET_ENCRYPTION_POLICY The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an empty directory or verifies that a directory or regular file already -has the specified encryption policy. It takes in a pointer to a -:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct -fscrypt_policy_v2`, defined as follows:: +has the specified encryption policy. It takes in a pointer to +struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as +follows:: #define FSCRYPT_POLICY_V1 0 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 @@ -464,11 +464,11 @@ fscrypt_policy_v2`, defined as follows:: This structure must be initialized as follows: -- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is - :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct - is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original - policy version as "v1", though its version code is really 0.) For - new encrypted directories, use v2 policies. +- ``version`` must be FSCRYPT_POLICY_V1 (0) if + struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if + struct fscrypt_policy_v2 is used. (Note: we refer to the original + policy version as "v1", though its version code is really 0.) + For new encrypted directories, use v2 policies. - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must be set to constants from ``<linux/fscrypt.h>`` which identify the @@ -508,9 +508,9 @@ This structure must be initialized as follows: replaced with ``master_key_identifier``, which is longer and cannot be arbitrarily chosen. Instead, the key must first be added using `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` - the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must - be used as the ``master_key_identifier`` in the :c:type:`struct - fscrypt_policy_v2`. + the kernel returned in the struct fscrypt_add_key_arg must + be used as the ``master_key_identifier`` in + struct fscrypt_policy_v2. If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY verifies that the file is an empty directory. If so, the specified @@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption policy, if any, for a directory or regular file. No additional permissions are required beyond the ability to open the file. It -takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`, +takes in a pointer to struct fscrypt_get_policy_ex_arg, defined as follows:: struct fscrypt_get_policy_ex_arg { @@ -637,9 +637,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the encryption policy, if any, for a directory or regular file. However, unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy -version. It takes in a pointer directly to a :c:type:`struct -fscrypt_policy_v1` rather than a :c:type:`struct -fscrypt_get_policy_ex_arg`. +version. It takes in a pointer directly to struct fscrypt_policy_v1 +rather than struct fscrypt_get_policy_ex_arg. The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that @@ -680,8 +679,7 @@ the filesystem, making all files on the filesystem which were encrypted using that key appear "unlocked", i.e. in plaintext form. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is recommended. It takes in -a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as -follows:: +a pointer to struct fscrypt_add_key_arg, defined as follows:: struct fscrypt_add_key_arg { struct fscrypt_key_specifier key_spec; @@ -710,17 +708,16 @@ follows:: __u8 raw[]; }; -:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized +struct fscrypt_add_key_arg must be zeroed, then initialized as follows: - If the key is being added for use by v1 encryption policies, then ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and ``key_spec.u.descriptor`` must contain the descriptor of the key being added, corresponding to the value in the - ``master_key_descriptor`` field of :c:type:`struct - fscrypt_policy_v1`. To add this type of key, the calling process - must have the CAP_SYS_ADMIN capability in the initial user - namespace. + ``master_key_descriptor`` field of struct fscrypt_policy_v1. + To add this type of key, the calling process must have the + CAP_SYS_ADMIN capability in the initial user namespace. Alternatively, if the key is being added for use by v2 encryption policies, then ``key_spec.type`` must contain @@ -737,12 +734,13 @@ as follows: - ``key_id`` is 0 if the raw key is given directly in the ``raw`` field. Otherwise ``key_id`` is the ID of a Linux keyring key of - type "fscrypt-provisioning" whose payload is a :c:type:`struct - fscrypt_provisioning_key_payload` whose ``raw`` field contains the - raw key and whose ``type`` field matches ``key_spec.type``. Since - ``raw`` is variable-length, the total size of this key's payload - must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the - raw key size. The process must have Search permission on this key. + type "fscrypt-provisioning" whose payload is + struct fscrypt_provisioning_key_payload whose ``raw`` field contains + the raw key and whose ``type`` field matches ``key_spec.type``. + Since ``raw`` is variable-length, the total size of this key's + payload must be ``sizeof(struct fscrypt_provisioning_key_payload)`` + plus the raw key size. The process must have Search permission on + this key. Most users should leave this 0 and specify the raw key directly. The support for specifying a Linux keyring key is intended mainly to @@ -860,8 +858,8 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master encryption key from the filesystem, and possibly removes the key itself. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is recommended. -It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`, -defined as follows:: +It takes in a pointer to struct fscrypt_remove_key_arg, defined +as follows:: struct fscrypt_remove_key_arg { struct fscrypt_key_specifier key_spec; @@ -956,8 +954,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a master encryption key. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is -recommended. It takes in a pointer to a :c:type:`struct -fscrypt_get_key_status_arg`, defined as follows:: +recommended. It takes in a pointer to +struct fscrypt_get_key_status_arg, defined as follows:: struct fscrypt_get_key_status_arg { /* input */ @@ -1148,10 +1146,10 @@ Implementation details Encryption context ------------------ -An encryption policy is represented on-disk by a :c:type:`struct -fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is -up to individual filesystems to decide where to store it, but normally -it would be stored in a hidden extended attribute. It should *not* be +An encryption policy is represented on-disk by +struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to +individual filesystems to decide where to store it, but normally it +would be stored in a hidden extended attribute. It should *not* be exposed by the xattr-related system calls such as getxattr() and setxattr() because of the special semantics of the encryption xattr. (In particular, there would be much confusion if an encryption policy @@ -1249,8 +1247,8 @@ a strong "hash" of the ciphertext filename, along with the optional filesystem-specific hash(es) needed for directory lookups. This allows the filesystem to still, with a high degree of confidence, map the filename given in ->lookup() back to a particular directory entry -that was previously listed by readdir(). See :c:type:`struct -fscrypt_nokey_name` in the source for more details. +that was previously listed by readdir(). See +struct fscrypt_nokey_name in the source for more details. Note that the precise way that filenames are presented to userspace without the key is subject to change in the future. It is only meant diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index 6c8944f6f0f7..895e9711ed88 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -84,7 +84,7 @@ FS_IOC_ENABLE_VERITY -------------------- The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes -in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as +in a pointer to a struct fsverity_enable_arg, defined as follows:: struct fsverity_enable_arg { diff --git a/Documentation/filesystems/fuse.rst b/Documentation/filesystems/fuse.rst index cd717f9bf940..8120c3c0cb4e 100644 --- a/Documentation/filesystems/fuse.rst +++ b/Documentation/filesystems/fuse.rst @@ -47,7 +47,7 @@ filesystems. A good example is sshfs: a secure network filesystem using the sftp protocol. The userspace library and utilities are available from the -`FUSE homepage: <http://fuse.sourceforge.net/>`_ +`FUSE homepage: <https://github.com/libfuse/>`_ Filesystem type =============== diff --git a/Documentation/filesystems/journalling.rst b/Documentation/filesystems/journalling.rst index 7e2be2faf653..e18f90ffc6fd 100644 --- a/Documentation/filesystems/journalling.rst +++ b/Documentation/filesystems/journalling.rst @@ -132,6 +132,37 @@ The opportunities for abuse and DOS attacks with this should be obvious, if you allow unprivileged userspace to trigger codepaths containing these calls. +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 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. + +`journal->j_fc_replay_cb`: Replay function called for replay of fast commit +blocks. + +File system is free to perform fast commits as and when it wants as long as it +gets permission from JBD2 to do so by calling the function +:c:func:`jbd2_fc_begin_commit()`. Once a fast commit is done, the client +file system should tell JBD2 about it by calling +:c:func:`jbd2_fc_end_commit()`. If file system wants JBD2 to perform a full +commit immediately after stopping the fast commit it can do so by calling +:c:func:`jbd2_fc_end_commit_fallback()`. This is useful if fast commit operation +fails for some reason and the only way to guarantee consistency is for JBD2 to +perform the full traditional commit. + +JBD2 helper functions to manage fast commit buffers. File system can use +:c:func:`jbd2_fc_get_buf()` and :c:func:`jbd2_fc_wait_bufs()` to allocate +and wait on IO completion of fast commit buffers. + +Currently, only Ext4 implements fast commits. For details of its implementation +of fast commits, please refer to the top level comments in +fs/ext4/fast_commit.c. + Summary ~~~~~~~ diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst index abed4a2b1b82..ccaea9e7cea2 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.rst +++ b/Documentation/filesystems/nfs/rpc-server-gss.rst @@ -13,10 +13,9 @@ RPCGSS is specified in a few IETF documents: - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt -and there is a 3rd version being proposed: +There is a third version that we don't currently implement: - - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt - (At draft n. 02 at the time of writing) + - RFC7861 v3: https://tools.ietf.org/rfc/rfc7861.txt Background ========== diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 8ea83a51c266..580ab9a0fe31 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -564,6 +564,25 @@ Note: the mount options index=off,nfs_export=on are conflicting for a read-write mount and will result in an error. +Volatile mount +-------------- + +This is enabled with the "volatile" mount option. Volatile mounts are not +guaranteed to survive a crash. It is strongly recommended that volatile +mounts are only used if data written to the overlay can be recreated +without significant effort. + +The advantage of mounting with the "volatile" option is that all forms of +sync calls to the upper filesystem are omitted. + +When overlay is mounted with "volatile" option, the directory +"$workdir/work/incompat/volatile" is created. During next mount, overlay +checks for this directory and refuses to mount if present. This is a strong +indicator that user should throw away upper and work directories and create +fresh one. In very limited cases where the user knows that the system has +not crashed and contents of upperdir are intact, The "volatile" directory +can be removed. + Testsuite --------- diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst index 6c18bc8ce332..6b213fe9a33e 100644 --- a/Documentation/filesystems/zonefs.rst +++ b/Documentation/filesystems/zonefs.rst @@ -326,6 +326,21 @@ discover the amount of data that has been written to the zone. In the case of a read-only zone discovered at run-time, as indicated in the previous section. The size of the zone file is left unchanged from its last updated value. +A zoned block device (e.g. an NVMe Zoned Namespace device) may have limits on +the number of zones that can be active, that is, zones that are in the +implicit open, explicit open or closed conditions. This potential limitation +translates into a risk for applications to see write IO errors due to this +limit being exceeded if the zone of a file is not already active when a write +request is issued by the user. + +To avoid these potential errors, the "explicit-open" mount option forces zones +to be made active using an open zone command when a file is opened for writing +for the first time. If the zone open command succeeds, the application is then +guaranteed that write requests can be processed. Conversely, the +"explicit-open" mount option will result in a zone close command being issued +to the device on the last close() of a zone file if the zone is not full nor +empty. + Zonefs User Space Tools ======================= 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 57047dcb8d19..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: @@ -206,8 +199,8 @@ pp_power_profile_mode .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: pp_power_profile_mode -*_busy_percent -~~~~~~~~~~~~~~ +\*_busy_percent +~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: gpu_busy_percent diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 33cc6ddf8f64..cff1f154b473 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c :functions: i915_oa_poll_wait -All i915 Perf Internals ------------------------ +Other i915 Perf Internals +------------------------- -This section simply includes all currently documented i915 perf internals, in -no particular order, but may include some more minor utilities or platform +This section simply includes all other currently documented i915 perf internals, +in no particular order, but may include some more minor utilities or platform specific details than found in the more high-level sections. .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c :internal: + :no-identifiers: + i915_perf_init + i915_perf_fini + i915_perf_register + i915_perf_unregister + i915_perf_open_ioctl + i915_perf_release + i915_perf_add_config_ioctl + i915_perf_remove_config_ioctl + read_properties_unlocked + i915_perf_open_ioctl_locked + i915_perf_destroy_locked + i915_perf_read i915_perf_ioctl + i915_perf_enable_locked + i915_perf_disable_locked + i915_perf_poll i915_perf_poll_locked + i915_oa_stream_init i915_oa_read + i915_oa_stream_enable + i915_oa_stream_disable + i915_oa_wait_unlocked + i915_oa_poll_wait Style ===== 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/i2c/busses/i2c-i801.rst b/Documentation/i2c/busses/i2c-i801.rst index faf32330c335..42bbdd6e7fd8 100644 --- a/Documentation/i2c/busses/i2c-i801.rst +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -44,6 +44,7 @@ Supported adapters: * Intel Tiger Lake (PCH) * Intel Jasper Lake (SOC) * Intel Emmitsburg (PCH) + * Intel Alder Lake (PCH) Datasheets: Publicly available at the Intel website diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index 8a2ad3845191..8b76217e370a 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -47,6 +47,7 @@ Slave I2C slave-interface slave-eeprom-backend + slave-testunit-backend Advanced topics =============== diff --git a/Documentation/i2c/slave-testunit-backend.rst b/Documentation/i2c/slave-testunit-backend.rst new file mode 100644 index 000000000000..2c38e64f0bac --- /dev/null +++ b/Documentation/i2c/slave-testunit-backend.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +Linux I2C slave testunit backend +================================ + +by Wolfram Sang <wsa@sang-engineering.com> in 2020 + +This backend can be used to trigger test cases for I2C bus masters which +require a remote device with certain capabilities (and which are usually not so +easy to obtain). Examples include multi-master testing, and SMBus Host Notify +testing. For some tests, the I2C slave controller must be able to switch +between master and slave mode because it needs to send data, too. + +Note that this is a device for testing and debugging. It should not be enabled +in a production build. And while there is some versioning and we try hard to +keep backward compatibility, there is no stable ABI guaranteed! + +Instantiating the device is regular. Example for bus 0, address 0x30: + +# echo "slave-testunit 0x1030" > /sys/bus/i2c/devices/i2c-0/new_device + +After that, you will have a write-only device listening. Reads will just return +an 8-bit version number of the testunit. When writing, the device consists of 4 +8-bit registers and all must be written to start a testcase, i.e. you must +always write 4 bytes to the device. The registers are: + +0x00 CMD - which test to trigger +0x01 DATAL - configuration byte 1 for the test +0x02 DATAH - configuration byte 2 for the test +0x03 DELAY - delay in n * 10ms until test is started + +Using 'i2cset' from the i2c-tools package, the generic command looks like: + +# i2cset -y <bus_num> <testunit_address> <CMD> <DATAL> <DATAH> <DELAY> i + +DELAY is a generic parameter which will delay the execution of the test in CMD. +While a command is running (including the delay), new commands will not be +acknowledged. You need to wait until the old one is completed. + +The commands are described in the following section. An invalid command will +result in the transfer not being acknowledged. + +Commands +-------- + +0x00 NOOP (reserved for future use) + +0x01 READ_BYTES (also needs master mode) + DATAL - address to read data from (lower 7 bits, highest bit currently unused) + DATAH - number of bytes to read + +This is useful to test if your bus master driver is handling multi-master +correctly. You can trigger the testunit to read bytes from another device on +the bus. If the bus master under test also wants to access the bus at the same +time, the bus will be busy. Example to read 128 bytes from device 0x50 after +50ms of delay: + +# i2cset -y 0 0x30 0x01 0x50 0x80 0x05 i + +0x02 SMBUS_HOST_NOTIFY (also needs master mode) + DATAL - low byte of the status word to send + DATAH - high byte of the status word to send + +This test will send an SMBUS_HOST_NOTIFY message to the host. Note that the +status word is currently ignored in the Linux Kernel. Example to send a +notification after 10ms: + +# i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i 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/af_xdp.rst b/Documentation/networking/af_xdp.rst index 5bc55a4e3bce..2ccc5644cc98 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -258,14 +258,21 @@ socket into zero-copy mode or fail. XDP_SHARED_UMEM bind flag ------------------------- -This flag enables you to bind multiple sockets to the same UMEM, but -only if they share the same queue id. In this mode, each socket has -their own RX and TX rings, but the UMEM (tied to the fist socket -created) only has a single FILL ring and a single COMPLETION -ring. To use this mode, create the first socket and bind it in the normal -way. Create a second socket and create an RX and a TX ring, or at -least one of them, but no FILL or COMPLETION rings as the ones from -the first socket will be used. In the bind call, set he +This flag enables you to bind multiple sockets to the same UMEM. It +works on the same queue id, between queue ids and between +netdevs/devices. In this mode, each socket has their own RX and TX +rings as usual, but you are going to have one or more FILL and +COMPLETION ring pairs. You have to create one of these pairs per +unique netdev and queue id tuple that you bind to. + +Starting with the case were we would like to share a UMEM between +sockets bound to the same netdev and queue id. The UMEM (tied to the +fist socket created) will only have a single FILL ring and a single +COMPLETION ring as there is only on unique netdev,queue_id tuple that +we have bound to. To use this mode, create the first socket and bind +it in the normal way. Create a second socket and create an RX and a TX +ring, or at least one of them, but no FILL or COMPLETION rings as the +ones from the first socket will be used. In the bind call, set he XDP_SHARED_UMEM option and provide the initial socket's fd in the sxdp_shared_umem_fd field. You can attach an arbitrary number of extra sockets this way. @@ -305,11 +312,41 @@ concurrently. There are no synchronization primitives in the libbpf code that protects multiple users at this point in time. Libbpf uses this mode if you create more than one socket tied to the -same umem. However, note that you need to supply the +same UMEM. However, note that you need to supply the XSK_LIBBPF_FLAGS__INHIBIT_PROG_LOAD libbpf_flag with the xsk_socket__create calls and load your own XDP program as there is no built in one in libbpf that will route the traffic for you. +The second case is when you share a UMEM between sockets that are +bound to different queue ids and/or netdevs. In this case you have to +create one FILL ring and one COMPLETION ring for each unique +netdev,queue_id pair. Let us say you want to create two sockets bound +to two different queue ids on the same netdev. Create the first socket +and bind it in the normal way. Create a second socket and create an RX +and a TX ring, or at least one of them, and then one FILL and +COMPLETION ring for this socket. Then in the bind call, set he +XDP_SHARED_UMEM option and provide the initial socket's fd in the +sxdp_shared_umem_fd field as you registered the UMEM on that +socket. These two sockets will now share one and the same UMEM. + +There is no need to supply an XDP program like the one in the previous +case where sockets were bound to the same queue id and +device. Instead, use the NIC's packet steering capabilities to steer +the packets to the right queue. In the previous example, there is only +one queue shared among sockets, so the NIC cannot do this steering. It +can only steer between queues. + +In libbpf, you need to use the xsk_socket__create_shared() API as it +takes a reference to a FILL ring and a COMPLETION ring that will be +created for you and bound to the shared UMEM. You can use this +function for all the sockets you create, or you can use it for the +second and following ones and use xsk_socket__create() for the first +one. Both methods yield the same result. + +Note that a UMEM can be shared between sockets on the same queue id +and device, as well as between queues on the same device and between +devices at the same time. + XDP_USE_NEED_WAKEUP bind flag ----------------------------- @@ -364,7 +401,7 @@ resources by only setting up one of them. Both the FILL ring and the COMPLETION ring are mandatory as you need to have a UMEM tied to your socket. But if the XDP_SHARED_UMEM flag is used, any socket after the first one does not have a UMEM and should in that case not have any -FILL or COMPLETION rings created as the ones from the shared umem will +FILL or COMPLETION rings created as the ones from the shared UMEM will be used. Note, that the rings are single-producer single-consumer, so do not try to access them from multiple processes at the same time. See the XDP_SHARED_UMEM section. @@ -567,6 +604,17 @@ A: The short answer is no, that is not supported at the moment. The switch, or other distribution mechanism, in your NIC to direct traffic to the correct queue id and socket. +Q: My packets are sometimes corrupted. What is wrong? + +A: Care has to be taken not to feed the same buffer in the UMEM into + more than one ring at the same time. If you for example feed the + same buffer into the FILL ring and the TX ring at the same time, the + NIC might receive data into the buffer at the same time it is + sending it. This will cause some packets to become corrupted. Same + thing goes for feeding the same buffer into the FILL rings + belonging to different queue ids or netdevs bound with the + XDP_SHARED_UMEM flag. + Credits ======= diff --git a/Documentation/networking/caif/index.rst b/Documentation/networking/caif/index.rst index 86e5b7832ec3..ec29b6f4bdb4 100644 --- a/Documentation/networking/caif/index.rst +++ b/Documentation/networking/caif/index.rst @@ -10,4 +10,3 @@ Contents: linux_caif caif - spi_porting diff --git a/Documentation/networking/caif/spi_porting.rst b/Documentation/networking/caif/spi_porting.rst deleted file mode 100644 index d49f874b20ac..000000000000 --- a/Documentation/networking/caif/spi_porting.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================ -CAIF SPI porting -================ - -CAIF SPI basics -=============== - -Running CAIF over SPI needs some extra setup, owing to the nature of SPI. -Two extra GPIOs have been added in order to negotiate the transfers -between the master and the slave. The minimum requirement for running -CAIF over SPI is a SPI slave chip and two GPIOs (more details below). -Please note that running as a slave implies that you need to keep up -with the master clock. An overrun or underrun event is fatal. - -CAIF SPI framework -================== - -To make porting as easy as possible, the CAIF SPI has been divided in -two parts. The first part (called the interface part) deals with all -generic functionality such as length framing, SPI frame negotiation -and SPI frame delivery and transmission. The other part is the CAIF -SPI slave device part, which is the module that you have to write if -you want to run SPI CAIF on a new hardware. This part takes care of -the physical hardware, both with regard to SPI and to GPIOs. - -- Implementing a CAIF SPI device: - - - Functionality provided by the CAIF SPI slave device: - - In order to implement a SPI device you will, as a minimum, - need to implement the following - functions: - - :: - - int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev): - - This function is called by the CAIF SPI interface to give - you a chance to set up your hardware to be ready to receive - a stream of data from the master. The xfer structure contains - both physical and logical addresses, as well as the total length - of the transfer in both directions.The dev parameter can be used - to map to different CAIF SPI slave devices. - - :: - - void (*sig_xfer) (bool xfer, struct cfspi_dev *dev): - - This function is called by the CAIF SPI interface when the output - (SPI_INT) GPIO needs to change state. The boolean value of the xfer - variable indicates whether the GPIO should be asserted (HIGH) or - deasserted (LOW). The dev parameter can be used to map to different CAIF - SPI slave devices. - - - Functionality provided by the CAIF SPI interface: - - :: - - void (*ss_cb) (bool assert, struct cfspi_ifc *ifc); - - This function is called by the CAIF SPI slave device in order to - signal a change of state of the input GPIO (SS) to the interface. - Only active edges are mandatory to be reported. - This function can be called from IRQ context (recommended in order - not to introduce latency). The ifc parameter should be the pointer - returned from the platform probe function in the SPI device structure. - - :: - - void (*xfer_done_cb) (struct cfspi_ifc *ifc); - - This function is called by the CAIF SPI slave device in order to - report that a transfer is completed. This function should only be - called once both the transmission and the reception are completed. - This function can be called from IRQ context (recommended in order - not to introduce latency). The ifc parameter should be the pointer - returned from the platform probe function in the SPI device structure. - - - Connecting the bits and pieces: - - - Filling in the SPI slave device structure: - - Connect the necessary callback functions. - - Indicate clock speed (used to calculate toggle delays). - - Chose a suitable name (helps debugging if you use several CAIF - SPI slave devices). - - Assign your private data (can be used to map to your - structure). - - - Filling in the SPI slave platform device structure: - - Add name of driver to connect to ("cfspi_sspi"). - - Assign the SPI slave device structure as platform data. - -Padding -======= - -In order to optimize throughput, a number of SPI padding options are provided. -Padding can be enabled independently for uplink and downlink transfers. -Padding can be enabled for the head, the tail and for the total frame size. -The padding needs to be correctly configured on both sides of the link. -The padding can be changed via module parameters in cfspi_sspi.c or via -the sysfs directory of the cfspi_sspi driver (before device registration). - -- CAIF SPI device template:: - - /* - * Copyright (C) ST-Ericsson AB 2010 - * Author: Daniel Martensson / Daniel.Martensson@stericsson.com - * License terms: GNU General Public License (GPL), version 2. - * - */ - - #include <linux/init.h> - #include <linux/module.h> - #include <linux/device.h> - #include <linux/wait.h> - #include <linux/interrupt.h> - #include <linux/dma-mapping.h> - #include <net/caif/caif_spi.h> - - MODULE_LICENSE("GPL"); - - struct sspi_struct { - struct cfspi_dev sdev; - struct cfspi_xfer *xfer; - }; - - static struct sspi_struct slave; - static struct platform_device slave_device; - - static irqreturn_t sspi_irq(int irq, void *arg) - { - /* You only need to trigger on an edge to the active state of the - * SS signal. Once a edge is detected, the ss_cb() function should be - * called with the parameter assert set to true. It is OK - * (and even advised) to call the ss_cb() function in IRQ context in - * order not to add any delay. */ - - return IRQ_HANDLED; - } - - static void sspi_complete(void *context) - { - /* Normally the DMA or the SPI framework will call you back - * in something similar to this. The only thing you need to - * do is to call the xfer_done_cb() function, providing the pointer - * to the CAIF SPI interface. It is OK to call this function - * from IRQ context. */ - } - - static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev) - { - /* Store transfer info. For a normal implementation you should - * set up your DMA here and make sure that you are ready to - * receive the data from the master SPI. */ - - struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; - - sspi->xfer = xfer; - - return 0; - } - - void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev) - { - /* If xfer is true then you should assert the SPI_INT to indicate to - * the master that you are ready to receive the data from the master - * SPI. If xfer is false then you should de-assert SPI_INT to indicate - * that the transfer is done. - */ - - struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; - } - - static void sspi_release(struct device *dev) - { - /* - * Here you should release your SPI device resources. - */ - } - - static int __init sspi_init(void) - { - /* Here you should initialize your SPI device by providing the - * necessary functions, clock speed, name and private data. Once - * done, you can register your device with the - * platform_device_register() function. This function will return - * with the CAIF SPI interface initialized. This is probably also - * the place where you should set up your GPIOs, interrupts and SPI - * resources. */ - - int res = 0; - - /* Initialize slave device. */ - slave.sdev.init_xfer = sspi_init_xfer; - slave.sdev.sig_xfer = sspi_sig_xfer; - slave.sdev.clk_mhz = 13; - slave.sdev.priv = &slave; - slave.sdev.name = "spi_sspi"; - slave_device.dev.release = sspi_release; - - /* Initialize platform device. */ - slave_device.name = "cfspi_sspi"; - slave_device.dev.platform_data = &slave.sdev; - - /* Register platform device. */ - res = platform_device_register(&slave_device); - if (res) { - printk(KERN_WARNING "sspi_init: failed to register dev.\n"); - return -ENODEV; - } - - return res; - } - - static void __exit sspi_exit(void) - { - platform_device_del(&slave_device); - } - - module_init(sspi_init); - module_exit(sspi_exit); diff --git a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index 11af6388ea87..3561a8a29fd2 100644 --- a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst @@ -39,16 +39,6 @@ debug logs. Some of the ENA devices support a working mode called Low-latency Queue (LLQ), which saves several more microseconds. -Supported PCI vendor ID/device IDs -================================== - -========= ======================= -1d0f:0ec2 ENA PF -1d0f:1ec2 ENA PF with LLQ support -1d0f:ec20 ENA VF -1d0f:ec21 ENA VF with LLQ support -========= ======================= - ENA Source Code Directory Structure =================================== @@ -212,20 +202,11 @@ In adaptive interrupt moderation mode the interrupt delay value is updated by the driver dynamically and adjusted every NAPI cycle according to the traffic nature. -By default ENA driver applies adaptive coalescing on Rx traffic and -conventional coalescing on Tx traffic. - Adaptive coalescing can be switched on/off through ethtool(8) adaptive_rx on|off parameter. -The driver chooses interrupt delay value according to the number of -bytes and packets received between interrupt unmasking and interrupt -posting. The driver uses interrupt delay table that subdivides the -range of received bytes/packets into 5 levels and assigns interrupt -delay value to each level. - -The user can enable/disable adaptive moderation, modify the interrupt -delay table and restore its default values through sysfs. +More information about Adaptive Interrupt Moderation (DIM) can be found in +Documentation/networking/net_dim.rst RX copybreak ============ @@ -274,7 +255,7 @@ RSS inputs for hash functions. - The driver configures RSS settings using the AQ SetFeature command (ENA_ADMIN_RSS_HASH_FUNCTION, ENA_ADMIN_RSS_HASH_INPUT and - ENA_ADMIN_RSS_REDIRECTION_TABLE_CONFIG properties). + ENA_ADMIN_RSS_INDIRECTION_TABLE_CONFIG properties). - If the NETIF_F_RXHASH flag is set, the 32-bit result of the hash function delivered in the Rx CQ descriptor is set in the received SKB. diff --git a/Documentation/networking/devlink/devlink-flash.rst b/Documentation/networking/devlink/devlink-flash.rst index 40a87c0222cb..603e732f00cc 100644 --- a/Documentation/networking/devlink/devlink-flash.rst +++ b/Documentation/networking/devlink/devlink-flash.rst @@ -16,6 +16,34 @@ Note that the file name is a path relative to the firmware loading path (usually ``/lib/firmware/``). Drivers may send status updates to inform user space about the progress of the update operation. +Overwrite Mask +============== + +The ``devlink-flash`` command allows optionally specifying a mask indicating +how the device should handle subsections of flash components when updating. +This mask indicates the set of sections which are allowed to be overwritten. + +.. list-table:: List of overwrite mask bits + :widths: 5 95 + + * - Name + - Description + * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` + - Indicates that the device should overwrite settings in the components + being updated with the settings found in the provided image. + * - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` + - Indicates that the device should overwrite identifiers in the + components being updated with the identifiers found in the provided + image. This includes MAC addresses, serial IDs, and similar device + identifiers. + +Multiple overwrite bits may be combined and requested together. If no bits +are provided, it is expected that the device only update firmware binaries +in the components being updated. Settings and identifiers are expected to be +preserved across the update. A device may not support every combination and +the driver for such a device must reject any combination which cannot be +faithfully implemented. + Firmware Loading ================ diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst index d075fd090b3d..54c9f107c4b0 100644 --- a/Documentation/networking/devlink/devlink-params.rst +++ b/Documentation/networking/devlink/devlink-params.rst @@ -108,3 +108,9 @@ own name. * - ``region_snapshot_enable`` - Boolean - Enable capture of ``devlink-region`` snapshots. + * - ``enable_remote_dev_reset`` + - Boolean + - Enable device reset by remote host. When cleared, the device driver + will NACK any attempt of other host to reset the device. This parameter + is useful for setups where a device is shared by different hosts, such + as multi-host setup. diff --git a/Documentation/networking/devlink/devlink-reload.rst b/Documentation/networking/devlink/devlink-reload.rst new file mode 100644 index 000000000000..505d22da027d --- /dev/null +++ b/Documentation/networking/devlink/devlink-reload.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Devlink Reload +============== + +``devlink-reload`` provides mechanism to reinit driver entities, applying +``devlink-params`` and ``devlink-resources`` new values. It also provides +mechanism to activate firmware. + +Reload Actions +============== + +User may select a reload action. +By default ``driver_reinit`` action is selected. + +.. list-table:: Possible reload actions + :widths: 5 90 + + * - Name + - Description + * - ``driver-reinit`` + - Devlink driver entities re-initialization, including applying + new values to devlink entities which are used during driver + load such as ``devlink-params`` in configuration mode + ``driverinit`` or ``devlink-resources`` + * - ``fw_activate`` + - Firmware activate. Activates new firmware if such image is stored and + pending activation. If no limitation specified this action may involve + firmware reset. If no new image pending this action will reload current + firmware image. + +Note that even though user asks for a specific action, the driver +implementation might require to perform another action alongside with +it. For example, some driver do not support driver reinitialization +being performed without fw activation. Therefore, the devlink reload +command returns the list of actions which were actrually performed. + +Reload Limits +============= + +By default reload actions are not limited and driver implementation may +include reset or downtime as needed to perform the actions. + +However, some drivers support action limits, which limit the action +implementation to specific constraints. + +.. list-table:: Possible reload limits + :widths: 5 90 + + * - Name + - Description + * - ``no_reset`` + - No reset allowed, no down time allowed, no link flap and no + configuration is lost. + +Change Namespace +================ + +The netns option allows user to be able to move devlink instances into +namespaces during devlink reload operation. +By default all devlink instances are created in init_net and stay there. + +example usage +------------- + +.. code:: shell + + $ devlink dev reload help + $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ] + + # Run reload command for devlink driver entities re-initialization: + $ devlink dev reload pci/0000:82:00.0 action driver_reinit + reload_actions_performed: + driver_reinit + + # Run reload command to activate firmware: + # Note that mlx5 driver reloads the driver while activating firmware + $ devlink dev reload pci/0000:82:00.0 action fw_activate + reload_actions_performed: + driver_reinit fw_activate diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst index 7a798352b45d..ef719ceac299 100644 --- a/Documentation/networking/devlink/devlink-trap.rst +++ b/Documentation/networking/devlink/devlink-trap.rst @@ -409,6 +409,73 @@ be added to the following table: - ``drop`` - Traps packets dropped due to the RED (Random Early Detection) algorithm (i.e., early drops) + * - ``vxlan_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the VXLAN header parsing which + might be because of packet truncation or the I flag is not set. + * - ``llc_snap_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the LLC+SNAP header parsing + * - ``vlan_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the VLAN header parsing. Could + include unexpected packet truncation. + * - ``pppoe_ppp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the PPPoE+PPP header parsing. + This could include finding a session ID of 0xFFFF (which is reserved and + not for use), a PPPoE length which is larger than the frame received or + any common error on this type of header + * - ``mpls_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the MPLS header parsing which + could include unexpected header truncation + * - ``arp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the ARP header parsing + * - ``ip_1_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the first IP header parsing. + This packet trap could include packets which do not pass an IP checksum + check, a header length check (a minimum of 20 bytes), which might suffer + from packet truncation thus the total length field exceeds the received + packet length etc + * - ``ip_n_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the parsing of the last IP + header (the inner one in case of an IP over IP tunnel). The same common + error checking is performed here as for the ip_1_parsing trap + * - ``gre_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the GRE header parsing + * - ``udp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the UDP header parsing. + This packet trap could include checksum errorrs, an improper UDP + length detected (smaller than 8 bytes) or detection of header + truncation. + * - ``tcp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the TCP header parsing. + This could include TCP checksum errors, improper combination of SYN, FIN + and/or RESET etc. + * - ``ipsec_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the IPSEC header parsing + * - ``sctp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the SCTP header parsing. + This would mean that port number 0 was used or that the header is + truncated. + * - ``dccp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the DCCP header parsing + * - ``gtp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the GTP header parsing + * - ``esp_parsing`` + - ``drop`` + - Traps packets dropped due to an error in the ESP header parsing Driver-specific Packet Traps ============================ @@ -509,6 +576,9 @@ narrow. The description of these groups must be added to the following table: * - ``acl_trap`` - Contains packet traps for packets that were trapped (logged) by the device during ACL processing + * - ``parser_error_drops`` + - Contains packet traps for packets that were marked by the device during + parsing as erroneous Packet Trap Policers ==================== diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 237848d56f9b..a432dc419fa4 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -69,6 +69,12 @@ The ``ice`` driver reports the following versions - The version of the DDP package that is active in the device. Note 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 + the specific DDP package. * - ``fw.netlist`` - running - 1.1.2000-6.7.0 @@ -81,6 +87,37 @@ The ``ice`` driver reports the following versions - 0xee16ced7 - The first 4 bytes of the hash of the netlist module contents. +Flash Update +============ + +The ``ice`` driver implements support for flash update using the +``devlink-flash`` interface. It supports updating the device flash using a +combined flash image that contains the ``fw.mgmt``, ``fw.undi``, and +``fw.netlist`` components. + +.. list-table:: List of supported overwrite modes + :widths: 5 95 + + * - Bits + - Behavior + * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` + - Do not preserve settings stored in the flash components being + updated. This includes overwriting the port configuration that + determines the number of physical functions the device will + initialize with. + * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` and ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` + - Do not preserve either settings or identifiers. Overwrite everything + in the flash with the contents from the provided image, without + performing any preservation. This includes overwriting device + identifying fields such as the MAC address, VPD area, and device + serial number. It is expected that this combination be used with an + image customized for the specific device. + +The ice hardware does not support overwriting only identifiers while +preserving settings, and thus ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` on its +own will be rejected. If no overwrite mask is provided, the firmware will be +instructed to preserve all settings and identifying fields when updating. + Regions ======= diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index 7684ae5c4a4a..d82874760ae2 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -20,6 +20,7 @@ general. devlink-params devlink-region devlink-resource + devlink-reload devlink-trap Driver-specific documentation diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index b5a79881551f..30b98245979f 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -68,6 +68,7 @@ the flags may not apply to requests. Recognized flags are: ================================= =================================== ``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply ``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT) + ``ETHTOOL_FLAG_STATS`` include optional device statistics ================================= =================================== New request flags should follow the general idea that if the flag is not set, @@ -991,8 +992,18 @@ Kernel response contents: ``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation ``ETHTOOL_A_PAUSE_RX`` bool receive pause frames ``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames + ``ETHTOOL_A_PAUSE_STATS`` nested pause statistics ===================================== ====== ========================== +``ETHTOOL_A_PAUSE_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set +in ``ETHTOOL_A_HEADER_FLAGS``. +It will be empty if driver did not report any statistics. Drivers fill in +the statistics in the following structure: + +.. kernel-doc:: include/linux/ethtool.h + :identifiers: ethtool_pause_stats + +Each member has a corresponding attribute defined. PAUSE_SET ============ diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst index 6f4bf8447a21..f27856d77c8b 100644 --- a/Documentation/networking/ieee802154.rst +++ b/Documentation/networking/ieee802154.rst @@ -26,7 +26,9 @@ The stack is composed of three main parts: Socket API ========== -.. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); +:: + + int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); The address family, socket addresses etc. are defined in the include/net/af_ieee802154.h header or in the special header @@ -131,12 +133,12 @@ Register PHY in the system. Freeing registered PHY. -.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi): +.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi) Telling 802.15.4 module there is a new received frame in the skb with the RF Link Quality Indicator (LQI) from the hardware device. -.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling): +.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling) Telling 802.15.4 module the frame in the skb is or going to be transmitted through the hardware device @@ -155,25 +157,25 @@ operations structure at least:: ... }; -.. c:function:: int start(struct ieee802154_hw *hw): +.. c:function:: int start(struct ieee802154_hw *hw) Handler that 802.15.4 module calls for the hardware device initialization. -.. c:function:: void stop(struct ieee802154_hw *hw): +.. c:function:: void stop(struct ieee802154_hw *hw) Handler that 802.15.4 module calls for the hardware device cleanup. -.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): +.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb) Handler that 802.15.4 module calls for each frame in the skb going to be transmitted through the hardware device. -.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level): +.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level) Handler that 802.15.4 module calls for Energy Detection from the hardware device. -.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): +.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel) Set radio for listening on specific channel of the hardware device. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 611e4b130c1e..63ef386afd0a 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -93,6 +93,7 @@ Contents: sctp secid seg6-sysctl + statistics strparser switchdev sysfs-tagging diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 837d51f9e1fa..25e6673a085a 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1142,13 +1142,15 @@ icmp_ratelimit - INTEGER icmp_msgs_per_sec - INTEGER Limit maximal number of ICMP packets sent per second from this host. Only messages whose type matches icmp_ratemask (see below) are - controlled by this limit. + controlled by this limit. For security reasons, the precise count + of messages per second is randomized. Default: 1000 icmp_msgs_burst - INTEGER icmp_msgs_per_sec controls number of ICMP packets sent per second, while icmp_msgs_burst controls the burst size of these packets. + For security reasons, the precise burst size is randomized. Default: 50 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/kapi.rst b/Documentation/networking/kapi.rst index f03ae64be8bc..d198fa5eaacd 100644 --- a/Documentation/networking/kapi.rst +++ b/Documentation/networking/kapi.rst @@ -134,6 +134,15 @@ PHY Support .. kernel-doc:: drivers/net/phy/phy.c :internal: +.. kernel-doc:: drivers/net/phy/phy-core.c + :export: + +.. kernel-doc:: drivers/net/phy/phy-c45.c + :export: + +.. kernel-doc:: include/linux/phy.h + :internal: + .. kernel-doc:: drivers/net/phy/phy_device.c :export: diff --git a/Documentation/networking/l2tp.rst b/Documentation/networking/l2tp.rst index a48238a2ec09..498b382d25a0 100644 --- a/Documentation/networking/l2tp.rst +++ b/Documentation/networking/l2tp.rst @@ -4,124 +4,364 @@ L2TP ==== -This document describes how to use the kernel's L2TP drivers to -provide L2TP functionality. L2TP is a protocol that tunnels one or -more sessions over an IP tunnel. It is commonly used for VPNs -(L2TP/IPSec) and by ISPs to tunnel subscriber PPP sessions over an IP -network infrastructure. With L2TPv3, it is also useful as a Layer-2 -tunneling infrastructure. - -Features +Layer 2 Tunneling Protocol (L2TP) allows L2 frames to be tunneled over +an IP network. + +This document covers the kernel's L2TP subsystem. It documents kernel +APIs for application developers who want to use the L2TP subsystem and +it provides some technical details about the internal implementation +which may be useful to kernel developers and maintainers. + +Overview ======== -L2TPv2 (PPP over L2TP (UDP tunnels)). -L2TPv3 ethernet pseudowires. -L2TPv3 PPP pseudowires. -L2TPv3 IP encapsulation. -Netlink sockets for L2TPv3 configuration management. - -History -======= - -The original pppol2tp driver was introduced in 2.6.23 and provided -L2TPv2 functionality (rfc2661). L2TPv2 is used to tunnel one or more PPP -sessions over a UDP tunnel. - -L2TPv3 (rfc3931) changes the protocol to allow different frame types -to be passed over an L2TP tunnel by moving the PPP-specific parts of -the protocol out of the core L2TP packet headers. Each frame type is -known as a pseudowire type. Ethernet, PPP, HDLC, Frame Relay and ATM -pseudowires for L2TP are defined in separate RFC standards. Another -change for L2TPv3 is that it can be carried directly over IP with no -UDP header (UDP is optional). It is also possible to create static -unmanaged L2TPv3 tunnels manually without a control protocol -(userspace daemon) to manage them. - -To support L2TPv3, the original pppol2tp driver was split up to -separate the L2TP and PPP functionality. Existing L2TPv2 userspace -apps should be unaffected as the original pppol2tp sockets API is -retained. L2TPv3, however, uses netlink to manage L2TPv3 tunnels and -sessions. - -Design -====== - -The L2TP protocol separates control and data frames. The L2TP kernel -drivers handle only L2TP data frames; control frames are always -handled by userspace. L2TP control frames carry messages between L2TP -clients/servers and are used to setup / teardown tunnels and -sessions. An L2TP client or server is implemented in userspace. - -Each L2TP tunnel is implemented using a UDP or L2TPIP socket; L2TPIP -provides L2TPv3 IP encapsulation (no UDP) and is implemented using a -new l2tpip socket family. The tunnel socket is typically created by -userspace, though for unmanaged L2TPv3 tunnels, the socket can also be -created by the kernel. Each L2TP session (pseudowire) gets a network -interface instance. In the case of PPP, these interfaces are created -indirectly by pppd using a pppol2tp socket. In the case of ethernet, -the netdevice is created upon a netlink request to create an L2TPv3 -ethernet pseudowire. - -For PPP, the PPPoL2TP driver, net/l2tp/l2tp_ppp.c, provides a -mechanism by which PPP frames carried through an L2TP session are -passed through the kernel's PPP subsystem. The standard PPP daemon, -pppd, handles all PPP interaction with the peer. PPP network -interfaces are created for each local PPP endpoint. The kernel's PPP -subsystem arranges for PPP control frames to be delivered to pppd, -while data frames are forwarded as usual. - -For ethernet, the L2TPETH driver, net/l2tp/l2tp_eth.c, implements a -netdevice driver, managing virtual ethernet devices, one per -pseudowire. These interfaces can be managed using standard Linux tools -such as "ip" and "ifconfig". If only IP frames are passed over the -tunnel, the interface can be given an IP addresses of itself and its -peer. If non-IP frames are to be passed over the tunnel, the interface -can be added to a bridge using brctl. All L2TP datapath protocol -functions are handled by the L2TP core driver. - -Each tunnel and session within a tunnel is assigned a unique tunnel_id -and session_id. These ids are carried in the L2TP header of every -control and data packet. (Actually, in L2TPv3, the tunnel_id isn't -present in data frames - it is inferred from the IP connection on -which the packet was received.) The L2TP driver uses the ids to lookup -internal tunnel and/or session contexts to determine how to handle the -packet. Zero tunnel / session ids are treated specially - zero ids are -never assigned to tunnels or sessions in the network. In the driver, -the tunnel context keeps a reference to the tunnel UDP or L2TPIP -socket. The session context holds data that lets the driver interface -to the kernel's network frame type subsystems, i.e. PPP, ethernet. - -Userspace Programming -===================== - -For L2TPv2, there are a number of requirements on the userspace L2TP -daemon in order to use the pppol2tp driver. - -1. Use a UDP socket per tunnel. - -2. Create a single PPPoL2TP socket per tunnel bound to a special null - session id. This is used only for communicating with the driver but - must remain open while the tunnel is active. Opening this tunnel - management socket causes the driver to mark the tunnel socket as an - L2TP UDP encapsulation socket and flags it for use by the - referenced tunnel id. This hooks up the UDP receive path via - udp_encap_rcv() in net/ipv4/udp.c. PPP data frames are never passed - in this special PPPoX socket. - -3. Create a PPPoL2TP socket per L2TP session. This is typically done - by starting pppd with the pppol2tp plugin and appropriate - arguments. A PPPoL2TP tunnel management socket (Step 2) must be - created before the first PPPoL2TP session socket is created. +The kernel's L2TP subsystem implements the datapath for L2TPv2 and +L2TPv3. L2TPv2 is carried over UDP. L2TPv3 is carried over UDP or +directly over IP (protocol 115). + +The L2TP RFCs define two basic kinds of L2TP packets: control packets +(the "control plane"), and data packets (the "data plane"). The kernel +deals only with data packets. The more complex control packets are +handled by user space. + +An L2TP tunnel carries one or more L2TP sessions. Each tunnel is +associated with a socket. Each session is associated with a virtual +netdevice, e.g. ``pppN``, ``l2tpethN``, through which data frames pass +to/from L2TP. Fields in the L2TP header identify the tunnel or session +and whether it is a control or data packet. When tunnels and sessions +are set up using the Linux kernel API, we're just setting up the L2TP +data path. All aspects of the control protocol are to be handled by +user space. + +This split in responsibilities leads to a natural sequence of +operations when establishing tunnels and sessions. The procedure looks +like this: + + 1) Create a tunnel socket. Exchange L2TP control protocol messages + with the peer over that socket in order to establish a tunnel. + + 2) Create a tunnel context in the kernel, using information + obtained from the peer using the control protocol messages. + + 3) Exchange L2TP control protocol messages with the peer over the + tunnel socket in order to establish a session. + + 4) Create a session context in the kernel using information + obtained from the peer using the control protocol messages. + +L2TP APIs +========= + +This section documents each userspace API of the L2TP subsystem. + +Tunnel Sockets +-------------- + +L2TPv2 always uses UDP. L2TPv3 may use UDP or IP encapsulation. + +To create a tunnel socket for use by L2TP, the standard POSIX +socket API is used. + +For example, for a tunnel using IPv4 addresses and UDP encapsulation:: + + int sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP); + +Or for a tunnel using IPv6 addresses and IP encapsulation:: + + int sockfd = socket(AF_INET6, SOCK_DGRAM, IPPROTO_L2TP); + +UDP socket programming doesn't need to be covered here. + +IPPROTO_L2TP is an IP protocol type implemented by the kernel's L2TP +subsystem. The L2TPIP socket address is defined in struct +sockaddr_l2tpip and struct sockaddr_l2tpip6 at +`include/uapi/linux/l2tp.h`_. The address includes the L2TP tunnel +(connection) id. To use L2TP IP encapsulation, an L2TPv3 application +should bind the L2TPIP socket using the locally assigned +tunnel id. When the peer's tunnel id and IP address is known, a +connect must be done. + +If the L2TP application needs to handle L2TPv3 tunnel setup requests +from peers using L2TPIP, it must open a dedicated L2TPIP +socket to listen for those requests and bind the socket using tunnel +id 0 since tunnel setup requests are addressed to tunnel id 0. + +An L2TP tunnel and all of its sessions are automatically closed when +its tunnel socket is closed. + +Netlink API +----------- + +L2TP applications use netlink to manage L2TP tunnel and session +instances in the kernel. The L2TP netlink API is defined in +`include/uapi/linux/l2tp.h`_. + +L2TP uses `Generic Netlink`_ (GENL). Several commands are defined: +Create, Delete, Modify and Get for tunnel and session +instances, e.g. ``L2TP_CMD_TUNNEL_CREATE``. The API header lists the +netlink attribute types that can be used with each command. + +Tunnel and session instances are identified by a locally unique +32-bit id. L2TP tunnel ids are given by ``L2TP_ATTR_CONN_ID`` and +``L2TP_ATTR_PEER_CONN_ID`` attributes and L2TP session ids are given +by ``L2TP_ATTR_SESSION_ID`` and ``L2TP_ATTR_PEER_SESSION_ID`` +attributes. If netlink is used to manage L2TPv2 tunnel and session +instances, the L2TPv2 16-bit tunnel/session id is cast to a 32-bit +value in these attributes. + +In the ``L2TP_CMD_TUNNEL_CREATE`` command, ``L2TP_ATTR_FD`` tells the +kernel the tunnel socket fd being used. If not specified, the kernel +creates a kernel socket for the tunnel, using IP parameters set in +``L2TP_ATTR_IP[6]_SADDR``, ``L2TP_ATTR_IP[6]_DADDR``, +``L2TP_ATTR_UDP_SPORT``, ``L2TP_ATTR_UDP_DPORT`` attributes. Kernel +sockets are used to implement unmanaged L2TPv3 tunnels (iproute2's "ip +l2tp" commands). If ``L2TP_ATTR_FD`` is given, it must be a socket fd +that is already bound and connected. There is more information about +unmanaged tunnels later in this document. + +``L2TP_CMD_TUNNEL_CREATE`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y Sets the tunnel (connection) id. +PEER_CONN_ID Y Sets the peer tunnel (connection) id. +PROTO_VERSION Y Protocol version. 2 or 3. +ENCAP_TYPE Y Encapsulation type: UDP or IP. +FD N Tunnel socket file descriptor. +UDP_CSUM N Enable IPv4 UDP checksums. Used only if FD is + not set. +UDP_ZERO_CSUM6_TX N Zero IPv6 UDP checksum on transmit. Used only + if FD is not set. +UDP_ZERO_CSUM6_RX N Zero IPv6 UDP checksum on receive. Used only if + FD is not set. +IP_SADDR N IPv4 source address. Used only if FD is not + set. +IP_DADDR N IPv4 destination address. Used only if FD is + not set. +UDP_SPORT N UDP source port. Used only if FD is not set. +UDP_DPORT N UDP destination port. Used only if FD is not + set. +IP6_SADDR N IPv6 source address. Used only if FD is not + set. +IP6_DADDR N IPv6 destination address. Used only if FD is + not set. +DEBUG N Debug flags. +================== ======== === + +``L2TP_CMD_TUNNEL_DESTROY`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y Identifies the tunnel id to be destroyed. +================== ======== === + +``L2TP_CMD_TUNNEL_MODIFY`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y Identifies the tunnel id to be modified. +DEBUG N Debug flags. +================== ======== === + +``L2TP_CMD_TUNNEL_GET`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID N Identifies the tunnel id to be queried. + Ignored in DUMP requests. +================== ======== === + +``L2TP_CMD_SESSION_CREATE`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y The parent tunnel id. +SESSION_ID Y Sets the session id. +PEER_SESSION_ID Y Sets the parent session id. +PW_TYPE Y Sets the pseudowire type. +DEBUG N Debug flags. +RECV_SEQ N Enable rx data sequence numbers. +SEND_SEQ N Enable tx data sequence numbers. +LNS_MODE N Enable LNS mode (auto-enable data sequence + numbers). +RECV_TIMEOUT N Timeout to wait when reordering received + packets. +L2SPEC_TYPE N Sets layer2-specific-sublayer type (L2TPv3 + only). +COOKIE N Sets optional cookie (L2TPv3 only). +PEER_COOKIE N Sets optional peer cookie (L2TPv3 only). +IFNAME N Sets interface name (L2TPv3 only). +================== ======== === + +For Ethernet session types, this will create an l2tpeth virtual +interface which can then be configured as required. For PPP session +types, a PPPoL2TP socket must also be opened and connected, mapping it +onto the new session. This is covered in "PPPoL2TP Sockets" later. + +``L2TP_CMD_SESSION_DESTROY`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y Identifies the parent tunnel id of the session + to be destroyed. +SESSION_ID Y Identifies the session id to be destroyed. +IFNAME N Identifies the session by interface name. If + set, this overrides any CONN_ID and SESSION_ID + attributes. Currently supported for L2TPv3 + Ethernet sessions only. +================== ======== === + +``L2TP_CMD_SESSION_MODIFY`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID Y Identifies the parent tunnel id of the session + to be modified. +SESSION_ID Y Identifies the session id to be modified. +IFNAME N Identifies the session by interface name. If + set, this overrides any CONN_ID and SESSION_ID + attributes. Currently supported for L2TPv3 + Ethernet sessions only. +DEBUG N Debug flags. +RECV_SEQ N Enable rx data sequence numbers. +SEND_SEQ N Enable tx data sequence numbers. +LNS_MODE N Enable LNS mode (auto-enable data sequence + numbers). +RECV_TIMEOUT N Timeout to wait when reordering received + packets. +================== ======== === + +``L2TP_CMD_SESSION_GET`` attributes:- + +================== ======== === +Attribute Required Use +================== ======== === +CONN_ID N Identifies the tunnel id to be queried. + Ignored for DUMP requests. +SESSION_ID N Identifies the session id to be queried. + Ignored for DUMP requests. +IFNAME N Identifies the session by interface name. + If set, this overrides any CONN_ID and + SESSION_ID attributes. Ignored for DUMP + requests. Currently supported for L2TPv3 + Ethernet sessions only. +================== ======== === + +Application developers should refer to `include/uapi/linux/l2tp.h`_ for +netlink command and attribute definitions. + +Sample userspace code using libmnl_: + + - Open L2TP netlink socket:: + + struct nl_sock *nl_sock; + int l2tp_nl_family_id; + + nl_sock = nl_socket_alloc(); + genl_connect(nl_sock); + genl_id = genl_ctrl_resolve(nl_sock, L2TP_GENL_NAME); + + - Create a tunnel:: + + struct nlmsghdr *nlh; + struct genlmsghdr *gnlh; + + nlh = mnl_nlmsg_put_header(buf); + nlh->nlmsg_type = genl_id; /* assigned to genl socket */ + nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK; + nlh->nlmsg_seq = seq; + + gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh)); + gnlh->cmd = L2TP_CMD_TUNNEL_CREATE; + gnlh->version = L2TP_GENL_VERSION; + gnlh->reserved = 0; + + mnl_attr_put_u32(nlh, L2TP_ATTR_FD, tunl_sock_fd); + mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid); + mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid); + mnl_attr_put_u8(nlh, L2TP_ATTR_PROTO_VERSION, protocol_version); + mnl_attr_put_u16(nlh, L2TP_ATTR_ENCAP_TYPE, encap); + + - Create a session:: + + struct nlmsghdr *nlh; + struct genlmsghdr *gnlh; + + nlh = mnl_nlmsg_put_header(buf); + nlh->nlmsg_type = genl_id; /* assigned to genl socket */ + nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK; + nlh->nlmsg_seq = seq; + + gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh)); + gnlh->cmd = L2TP_CMD_SESSION_CREATE; + gnlh->version = L2TP_GENL_VERSION; + gnlh->reserved = 0; + + mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid); + mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid); + mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid); + mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_SESSION_ID, peer_sid); + mnl_attr_put_u16(nlh, L2TP_ATTR_PW_TYPE, pwtype); + /* there are other session options which can be set using netlink + * attributes during session creation -- see l2tp.h + */ + + - Delete a session:: + + struct nlmsghdr *nlh; + struct genlmsghdr *gnlh; + + nlh = mnl_nlmsg_put_header(buf); + nlh->nlmsg_type = genl_id; /* assigned to genl socket */ + nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK; + nlh->nlmsg_seq = seq; + + gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh)); + gnlh->cmd = L2TP_CMD_SESSION_DELETE; + gnlh->version = L2TP_GENL_VERSION; + gnlh->reserved = 0; + + mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid); + mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid); + + - Delete a tunnel and all of its sessions (if any):: + + struct nlmsghdr *nlh; + struct genlmsghdr *gnlh; + + nlh = mnl_nlmsg_put_header(buf); + nlh->nlmsg_type = genl_id; /* assigned to genl socket */ + nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK; + nlh->nlmsg_seq = seq; + + gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh)); + gnlh->cmd = L2TP_CMD_TUNNEL_DELETE; + gnlh->version = L2TP_GENL_VERSION; + gnlh->reserved = 0; + + mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid); + +PPPoL2TP Session Socket API +--------------------------- + +For PPP session types, a PPPoL2TP socket must be opened and connected +to the L2TP session. When creating PPPoL2TP sockets, the application provides information -to the driver about the socket in a socket connect() call. Source and -destination tunnel and session ids are provided, as well as the file -descriptor of a UDP socket. See struct pppol2tp_addr in -include/linux/if_pppol2tp.h. Note that zero tunnel / session ids are -treated specially. When creating the per-tunnel PPPoL2TP management -socket in Step 2 above, zero source and destination session ids are -specified, which tells the driver to prepare the supplied UDP file -descriptor for use as an L2TP tunnel socket. +to the kernel about the tunnel and session in a socket connect() +call. Source and destination tunnel and session ids are provided, as +well as the file descriptor of a UDP or L2TPIP socket. See struct +pppol2tp_addr in `include/linux/if_pppol2tp.h`_. For historical reasons, +there are unfortunately slightly different address structures for +L2TPv2/L2TPv3 IPv4/IPv6 tunnels and userspace must use the appropriate +structure that matches the tunnel socket type. Userspace may control behavior of the tunnel or session using setsockopt and ioctl on the PPPoX socket. The following socket @@ -130,229 +370,308 @@ options are supported:- ========= =========================================================== DEBUG bitmask of debug message categories. See below. SENDSEQ - 0 => don't send packets with sequence numbers - - 1 => send packets with sequence numbers + - 1 => send packets with sequence numbers RECVSEQ - 0 => receive packet sequence numbers are optional - - 1 => drop receive packets without sequence numbers + - 1 => drop receive packets without sequence numbers LNSMODE - 0 => act as LAC. - - 1 => act as LNS. + - 1 => act as LNS. REORDERTO reorder timeout (in millisecs). If 0, don't try to reorder. ========= =========================================================== -Only the DEBUG option is supported by the special tunnel management -PPPoX socket. - In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided to retrieve tunnel and session statistics from the kernel using the PPPoX socket of the appropriate tunnel or session. -For L2TPv3, userspace must use the netlink API defined in -include/linux/l2tp.h to manage tunnel and session contexts. The -general procedure to create a new L2TP tunnel with one session is:- - -1. Open a GENL socket using L2TP_GENL_NAME for configuring the kernel - using netlink. - -2. Create a UDP or L2TPIP socket for the tunnel. - -3. Create a new L2TP tunnel using a L2TP_CMD_TUNNEL_CREATE - request. Set attributes according to desired tunnel parameters, - referencing the UDP or L2TPIP socket created in the previous step. - -4. Create a new L2TP session in the tunnel using a - L2TP_CMD_SESSION_CREATE request. - -The tunnel and all of its sessions are closed when the tunnel socket -is closed. The netlink API may also be used to delete sessions and -tunnels. Configuration and status info may be set or read using netlink. - -The L2TP driver also supports static (unmanaged) L2TPv3 tunnels. These -are where there is no L2TP control message exchange with the peer to -setup the tunnel; the tunnel is configured manually at each end of the -tunnel. There is no need for an L2TP userspace application in this -case -- the tunnel socket is created by the kernel and configured -using parameters sent in the L2TP_CMD_TUNNEL_CREATE netlink -request. The "ip" utility of iproute2 has commands for managing static -L2TPv3 tunnels; do "ip l2tp help" for more information. +Sample userspace code: + + - Create session PPPoX data socket:: + + struct sockaddr_pppol2tp sax; + int fd; + + /* Note, the tunnel socket must be bound already, else it + * will not be ready + */ + sax.sa_family = AF_PPPOX; + sax.sa_protocol = PX_PROTO_OL2TP; + sax.pppol2tp.fd = tunnel_fd; + sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr; + sax.pppol2tp.addr.sin_port = addr->sin_port; + sax.pppol2tp.addr.sin_family = AF_INET; + sax.pppol2tp.s_tunnel = tunnel_id; + sax.pppol2tp.s_session = session_id; + sax.pppol2tp.d_tunnel = peer_tunnel_id; + sax.pppol2tp.d_session = peer_session_id; + + /* session_fd is the fd of the session's PPPoL2TP socket. + * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket. + */ + fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax)); + if (fd < 0 ) { + return -errno; + } + return 0; + +Old L2TPv2-only API +------------------- + +When L2TP was first added to the Linux kernel in 2.6.23, it +implemented only L2TPv2 and did not include a netlink API. Instead, +tunnel and session instances in the kernel were managed directly using +only PPPoL2TP sockets. The PPPoL2TP socket is used as described in +section "PPPoL2TP Session Socket API" but tunnel and session instances +are automatically created on a connect() of the socket instead of +being created by a separate netlink request: + + - Tunnels are managed using a tunnel management socket which is a + dedicated PPPoL2TP socket, connected to (invalid) session + id 0. The L2TP tunnel instance is created when the PPPoL2TP + tunnel management socket is connected and is destroyed when the + socket is closed. + + - Session instances are created in the kernel when a PPPoL2TP + socket is connected to a non-zero session id. Session parameters + are set using setsockopt. The L2TP session instance is destroyed + when the socket is closed. + +This API is still supported but its use is discouraged. Instead, new +L2TPv2 applications should use netlink to first create the tunnel and +session, then create a PPPoL2TP socket for the session. + +Unmanaged L2TPv3 tunnels +------------------------ + +The kernel L2TP subsystem also supports static (unmanaged) L2TPv3 +tunnels. Unmanaged tunnels have no userspace tunnel socket, and +exchange no control messages with the peer to set up the tunnel; the +tunnel is configured manually at each end of the tunnel. All +configuration is done using netlink. There is no need for an L2TP +userspace application in this case -- the tunnel socket is created by +the kernel and configured using parameters sent in the +``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of +``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip +l2tp help`` for more information. Debugging -========= - -The driver supports a flexible debug scheme where kernel trace -messages may be optionally enabled per tunnel and per session. Care is -needed when debugging a live system since the messages are not -rate-limited and a busy system could be swamped. Userspace uses -setsockopt on the PPPoX socket to set a debug mask. +--------- -The following debug mask bits are available: +The L2TP subsystem offers a range of debugging interfaces through the +debugfs filesystem. -================ ============================== -L2TP_MSG_DEBUG verbose debug (if compiled in) -L2TP_MSG_CONTROL userspace - kernel interface -L2TP_MSG_SEQ sequence numbers handling -L2TP_MSG_DATA data packets -================ ============================== +To access these interfaces, the debugfs filesystem must first be mounted:: -If enabled, files under a l2tp debugfs directory can be used to dump -kernel state about L2TP tunnels and sessions. To access it, the -debugfs filesystem must first be mounted:: + # mount -t debugfs debugfs /debug - # mount -t debugfs debugfs /debug +Files under the l2tp directory can then be accessed, providing a summary +of the current population of tunnel and session contexts existing in the +kernel:: -Files under the l2tp directory can then be accessed:: - - # cat /debug/l2tp/tunnels + # cat /debug/l2tp/tunnels The debugfs files should not be used by applications to obtain L2TP state information because the file format is subject to change. It is implemented to provide extra debug information to help diagnose -problems.) Users should use the netlink API. +problems. Applications should instead use the netlink API. -/proc/net/pppol2tp is also provided for backwards compatibility with -the original pppol2tp driver. It lists information about L2TPv2 -tunnels and sessions only. Its use is discouraged. +In addition the L2TP subsystem implements tracepoints using the standard +kernel event tracing API. The available L2TP events can be reviewed as +follows:: -Unmanaged L2TPv3 Tunnels -======================== - -Some commercial L2TP products support unmanaged L2TPv3 ethernet -tunnels, where there is no L2TP control protocol; tunnels are -configured at each side manually. New commands are available in -iproute2's ip utility to support this. - -To create an L2TPv3 ethernet pseudowire between local host 192.168.1.1 -and peer 192.168.1.2, using IP addresses 10.5.1.1 and 10.5.1.2 for the -tunnel endpoints:: - - # ip l2tp add tunnel tunnel_id 1 peer_tunnel_id 1 udp_sport 5000 \ - udp_dport 5000 encap udp local 192.168.1.1 remote 192.168.1.2 - # ip l2tp add session tunnel_id 1 session_id 1 peer_session_id 1 - # ip -s -d show dev l2tpeth0 - # ip addr add 10.5.1.2/32 peer 10.5.1.1/32 dev l2tpeth0 - # ip li set dev l2tpeth0 up - -Choose IP addresses to be the address of a local IP interface and that -of the remote system. The IP addresses of the l2tpeth0 interface can be -anything suitable. - -Repeat the above at the peer, with ports, tunnel/session ids and IP -addresses reversed. The tunnel and session IDs can be any non-zero -32-bit number, but the values must be reversed at the peer. - -======================== =================== -Host 1 Host2 -======================== =================== -udp_sport=5000 udp_sport=5001 -udp_dport=5001 udp_dport=5000 -tunnel_id=42 tunnel_id=45 -peer_tunnel_id=45 peer_tunnel_id=42 -session_id=128 session_id=5196755 -peer_session_id=5196755 peer_session_id=128 -======================== =================== - -When done at both ends of the tunnel, it should be possible to send -data over the network. e.g.:: - - # ping 10.5.1.1 - - -Sample Userspace Code -===================== - -1. Create tunnel management PPPoX socket:: - - kernel_fd = socket(AF_PPPOX, SOCK_DGRAM, PX_PROTO_OL2TP); - if (kernel_fd >= 0) { - struct sockaddr_pppol2tp sax; - struct sockaddr_in const *peer_addr; - - peer_addr = l2tp_tunnel_get_peer_addr(tunnel); - memset(&sax, 0, sizeof(sax)); - sax.sa_family = AF_PPPOX; - sax.sa_protocol = PX_PROTO_OL2TP; - sax.pppol2tp.fd = udp_fd; /* fd of tunnel UDP socket */ - sax.pppol2tp.addr.sin_addr.s_addr = peer_addr->sin_addr.s_addr; - sax.pppol2tp.addr.sin_port = peer_addr->sin_port; - sax.pppol2tp.addr.sin_family = AF_INET; - sax.pppol2tp.s_tunnel = tunnel_id; - sax.pppol2tp.s_session = 0; /* special case: mgmt socket */ - sax.pppol2tp.d_tunnel = 0; - sax.pppol2tp.d_session = 0; /* special case: mgmt socket */ - - if(connect(kernel_fd, (struct sockaddr *)&sax, sizeof(sax) ) < 0 ) { - perror("connect failed"); - result = -errno; - goto err; - } - } - -2. Create session PPPoX data socket:: - - struct sockaddr_pppol2tp sax; - int fd; - - /* Note, the target socket must be bound already, else it will not be ready */ - sax.sa_family = AF_PPPOX; - sax.sa_protocol = PX_PROTO_OL2TP; - sax.pppol2tp.fd = tunnel_fd; - sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr; - sax.pppol2tp.addr.sin_port = addr->sin_port; - sax.pppol2tp.addr.sin_family = AF_INET; - sax.pppol2tp.s_tunnel = tunnel_id; - sax.pppol2tp.s_session = session_id; - sax.pppol2tp.d_tunnel = peer_tunnel_id; - sax.pppol2tp.d_session = peer_session_id; - - /* session_fd is the fd of the session's PPPoL2TP socket. - * tunnel_fd is the fd of the tunnel UDP socket. - */ - fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax)); - if (fd < 0 ) { - return -errno; - } - return 0; + # find /debug/tracing/events/l2tp + +Finally, /proc/net/pppol2tp is also provided for backwards compatibility +with the original pppol2tp code. It lists information about L2TPv2 +tunnels and sessions only. Its use is discouraged. Internal Implementation ======================= -The driver keeps a struct l2tp_tunnel context per L2TP tunnel and a -struct l2tp_session context for each session. The l2tp_tunnel is -always associated with a UDP or L2TP/IP socket and keeps a list of -sessions in the tunnel. The l2tp_session context keeps kernel state -about the session. It has private data which is used for data specific -to the session type. With L2TPv2, the session always carried PPP -traffic. With L2TPv3, the session can also carry ethernet frames -(ethernet pseudowire) or other data types such as ATM, HDLC or Frame -Relay. - -When a tunnel is first opened, the reference count on the socket is -increased using sock_hold(). This ensures that the kernel socket -cannot be removed while L2TP's data structures reference it. - -Some L2TP sessions also have a socket (PPP pseudowires) while others -do not (ethernet pseudowires). We can't use the socket reference count -as the reference count for session contexts. The L2TP implementation -therefore has its own internal reference counts on the session -contexts. - -To Do -===== - -Add L2TP tunnel switching support. This would route tunneled traffic -from one L2TP tunnel into another. Specified in -http://tools.ietf.org/html/draft-ietf-l2tpext-tunnel-switching-08 - -Add L2TPv3 VLAN pseudowire support. - -Add L2TPv3 IP pseudowire support. - -Add L2TPv3 ATM pseudowire support. +This section is for kernel developers and maintainers. + +Sockets +------- + +UDP sockets are implemented by the networking core. When an L2TP +tunnel is created using a UDP socket, the socket is set up as an +encapsulated UDP socket by setting encap_rcv and encap_destroy +callbacks on the UDP socket. l2tp_udp_encap_recv is called when +packets are received on the socket. l2tp_udp_encap_destroy is called +when userspace closes the socket. + +L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and +`net/l2tp/l2tp_ip6.c`_. + +Tunnels +------- + +The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The +l2tp_tunnel is always associated with a UDP or L2TP/IP socket and +keeps a list of sessions in the tunnel. When a tunnel is first +registered with L2TP core, the reference count on the socket is +increased. This ensures that the socket cannot be removed while L2TP's +data structures reference it. + +Tunnels are identified by a unique tunnel id. The id is 16-bit for +L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit +value. + +Tunnels are kept in a per-net list, indexed by tunnel id. The tunnel +id namespace is shared by L2TPv2 and L2TPv3. The tunnel context can be +derived from the socket's sk_user_data. + +Handling tunnel socket close is perhaps the most tricky part of the +L2TP implementation. If userspace closes a tunnel socket, the L2TP +tunnel and all of its sessions must be closed and destroyed. Since the +tunnel context holds a ref on the tunnel socket, the socket's +sk_destruct won't be called until the tunnel sock_put's its +socket. For UDP sockets, when userspace closes the tunnel socket, the +socket's encap_destroy handler is invoked, which L2TP uses to initiate +its tunnel close actions. For L2TPIP sockets, the socket's close +handler initiates the same tunnel close actions. All sessions are +first closed. Each session drops its tunnel ref. When the tunnel ref +reaches zero, the tunnel puts its socket ref. When the socket is +eventually destroyed, it's sk_destruct finally frees the L2TP tunnel +context. + +Sessions +-------- + +The kernel keeps a struct l2tp_session context for each session. Each +session has private data which is used for data specific to the +session type. With L2TPv2, the session always carries PPP +traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet +pseudowire) or other data types such as PPP, ATM, HDLC or Frame +Relay. Linux currently implements only Ethernet and PPP session types. + +Some L2TP session types also have a socket (PPP pseudowires) while +others do not (Ethernet pseudowires). We can't therefore use the +socket reference count as the reference count for session +contexts. The L2TP implementation therefore has its own internal +reference counts on the session contexts. + +Like tunnels, L2TP sessions are identified by a unique +session id. Just as with tunnel ids, the session id is 16-bit for +L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit +value. + +Sessions hold a ref on their parent tunnel to ensure that the tunnel +stays extant while one or more sessions references it. + +Sessions are kept in a per-tunnel list, indexed by session id. L2TPv3 +sessions are also kept in a per-net list indexed by session id, +because L2TPv3 session ids are unique across all tunnels and L2TPv3 +data packets do not contain a tunnel id in the header. This list is +therefore needed to find the session context associated with a +received data packet when the tunnel context cannot be derived from +the tunnel socket. + +Although the L2TPv3 RFC specifies that L2TPv3 session ids are not +scoped by the tunnel, the kernel does not police this for L2TPv3 UDP +tunnels and does not add sessions of L2TPv3 UDP tunnels into the +per-net session list. In the UDP receive code, we must trust that the +tunnel can be identified using the tunnel socket's sk_user_data and +lookup the session in the tunnel's session list instead of the per-net +session list. + +PPP +--- + +`net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP +session has a PPPoL2TP socket. + +The PPPoL2TP socket's sk_user_data references the l2tp_session. + +Userspace sends and receives PPP packets over L2TP using a PPPoL2TP +socket. Only PPP control frames pass over this socket: PPP data +packets are handled entirely by the kernel, passing between the L2TP +session and its associated ``pppN`` netdev through the PPP channel +interface of the kernel PPP subsystem. + +The L2TP PPP implementation handles the closing of a PPPoL2TP socket +by closing its corresponding L2TP session. This is complicated because +it must consider racing with netlink session create/destroy requests +and pppol2tp_connect trying to reconnect with a session that is in the +process of being closed. Unlike tunnels, PPP sessions do not hold a +ref on their associated socket, so code must be careful to sock_hold +the socket where necessary. For all the details, see commit +3d609342cc04129ff7568e19316ce3d7451a27e8. + +Ethernet +-------- + +`net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It +manages a netdev for each session. + +L2TP Ethernet sessions are created and destroyed by netlink request, +or are destroyed when the tunnel is destroyed. Unlike PPP sessions, +Ethernet sessions do not have an associated socket. Miscellaneous ============= -The L2TP drivers were developed as part of the OpenL2TP project by -Katalix Systems Ltd. OpenL2TP is a full-featured L2TP client / server, -designed from the ground up to have the L2TP datapath in the -kernel. The project also implemented the pppol2tp plugin for pppd -which allows pppd to use the kernel driver. Details can be found at -http://www.openl2tp.org. +RFCs +---- + +The kernel code implements the datapath features specified in the +following RFCs: + +======= =============== =================================== +RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661 +RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931 +RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719 +======= =============== =================================== + +Implementations +--------------- + +A number of open source applications use the L2TP kernel subsystem: + +============ ============================================== +iproute2 https://github.com/shemminger/iproute2 +go-l2tp https://github.com/katalix/go-l2tp +tunneldigger https://github.com/wlanslovenija/tunneldigger +xl2tpd https://github.com/xelerance/xl2tpd +============ ============================================== + +Limitations +----------- + +The current implementation has a number of limitations: + + 1) Multiple UDP sockets with the same 5-tuple address cannot be + used. The kernel's tunnel context is identified using private + data associated with the socket so it is important that each + socket is uniquely identified by its address. + + 2) Interfacing with openvswitch is not yet implemented. It may be + useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels. + + 3) VLAN pseudowires are implemented using an ``l2tpethN`` interface + configured with a VLAN sub-interface. Since L2TPv3 VLAN + pseudowires carry one and only one VLAN, it may be better to use + a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M + pair per VLAN session. The netlink attribute + ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never + implemented. + +Testing +------- + +Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in +selftests. See `tools/testing/selftests/net/l2tp.sh`_. + +Another test suite, l2tp-ktest_, covers all +of the L2TP APIs and tunnel/session types. This may be integrated into +the kernel's built-in L2TP selftests in the future. + +.. Links +.. _Generic Netlink: generic_netlink.html +.. _libmnl: https://www.netfilter.org/projects/libmnl +.. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h +.. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h +.. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c +.. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c +.. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c +.. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c +.. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh +.. _l2tp-ktest: https://github.com/katalix/l2tp-ktest diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index d5c9320901c3..21537766be4d 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: diff --git a/Documentation/networking/nf_flowtable.rst b/Documentation/networking/nf_flowtable.rst index b6e1fa141aae..6cdf9a1724b6 100644 --- a/Documentation/networking/nf_flowtable.rst +++ b/Documentation/networking/nf_flowtable.rst @@ -109,7 +109,7 @@ More reading This documentation is based on the LWN.net articles [1]_\ [2]_. Rafal Milecki also made a very complete and comprehensive summary called "A state of network acceleration" that describes how things were before this infrastructure was -mailined [3]_ and it also makes a rough summary of this work [4]_. +mainlined [3]_ and it also makes a rough summary of this work [4]_. .. [1] https://lwn.net/Articles/738214/ .. [2] https://lwn.net/Articles/742164/ 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/scaling.rst b/Documentation/networking/scaling.rst index 8f0347b9fb3d..3d435caa3ef2 100644 --- a/Documentation/networking/scaling.rst +++ b/Documentation/networking/scaling.rst @@ -465,9 +465,9 @@ XPS Configuration ----------------- XPS is only available if the kconfig symbol CONFIG_XPS is enabled (on by -default for SMP). The functionality remains disabled until explicitly -configured. To enable XPS, the bitmap of CPUs/receive-queues that may -use a transmit queue is configured using the sysfs file entry: +default for SMP). If compiled in, it is driver dependent whether, and +how, XPS is configured at device init. The mapping of CPUs/receive-queues +to transmit queue can be inspected and configured using sysfs: For selection based on CPUs map:: diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst new file mode 100644 index 000000000000..234abedc29b2 --- /dev/null +++ b/Documentation/networking/statistics.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Interface statistics +==================== + +Overview +======== + +This document is a guide to Linux network interface statistics. + +There are three main sources of interface statistics in Linux: + + - standard interface statistics based on + :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`; + - protocol-specific statistics; and + - driver-defined statistics available via ethtool. + +Standard interface statistics +----------------------------- + +There are multiple interfaces to reach the standard statistics. +Most commonly used is the `ip` command from `iproute2`:: + + $ ip -s -s link show dev ens4u1u1 + 6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 + link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff + RX: bytes packets errors dropped overrun mcast + 74327665117 69016965 0 0 0 0 + RX errors: length crc frame fifo missed + 0 0 0 0 0 + TX: bytes packets errors dropped carrier collsns + 21405556176 44608960 0 0 0 0 + TX errors: aborted fifo window heartbeat transns + 0 0 0 0 128 + altname enp58s0u1u1 + +Note that `-s` has been specified twice to see all members of +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. +If `-s` is specified once the detailed errors won't be shown. + +`ip` supports JSON formatting via the `-j` option. + +Protocol-specific statistics +---------------------------- + +Some of the interfaces used for configuring devices are also able +to report related statistics. For example ethtool interface used +to configure pause frames can report corresponding hardware counters:: + + $ ethtool --include-statistics -a eth0 + Pause parameters for eth0: + Autonegotiate: on + RX: on + TX: on + Statistics: + tx_pause_frames: 1 + rx_pause_frames: 1 + +Driver-defined statistics +------------------------- + +Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.:: + + $ ethtool -S ens4u1u1 + NIC statistics: + tx_single_collisions: 0 + tx_multi_collisions: 0 + +uAPIs +===== + +procfs +------ + +The historical `/proc/net/dev` text interface gives access to the list +of interfaces as well as their statistics. + +Note that even though this interface is using +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` +internally it combines some of the fields. + +sysfs +----- + +Each device directory in sysfs contains a `statistics` directory (e.g. +`/sys/class/net/lo/statistics/`) with files corresponding to +members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. + +This simple interface is convenient especially in constrained/embedded +environments without access to tools. However, it's inefficient when +reading multiple stats as it internally performs a full dump of +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` +and reports only the stat corresponding to the accessed file. + +Sysfs files are documented in +`Documentation/ABI/testing/sysfs-class-net-statistics`. + + +netlink +------- + +`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats. + +Statistics are reported both in the responses to link information +requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`, +when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request). + +ethtool +------- + +Ethtool IOCTL interface allows drivers to report implementation +specific statistics. Historically it has also been used to report +statistics for which other APIs did not exist, like per-device-queue +statistics, or standard-based statistics (e.g. RFC 2863). + +Statistics and their string identifiers are retrieved separately. +Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`, +and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO` +to retrieve the number of statistics (`.n_stats`). + +ethtool-netlink +--------------- + +Ethtool netlink is a replacement for the older IOCTL interface. + +Protocol-related statistics can be requested in get commands by setting +the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently +statistics are supported in the following commands: + + - `ETHTOOL_MSG_PAUSE_GET` + +debugfs +------- + +Some drivers expose extra statistics via `debugfs`. + +struct rtnl_link_stats64 +======================== + +.. kernel-doc:: include/uapi/linux/if_link.h + :identifiers: rtnl_link_stats64 + +Notes for driver authors +======================== + +Drivers should report all statistics which have a matching member in +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively +via `.ndo_get_stats64`. Reporting such standard stats via ethtool +or debugfs will not be accepted. + +Drivers must ensure best possible compliance with +:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. +Please note for example that detailed error statistics must be +added into the general `rx_error` / `tx_error` counters. + +The `.ndo_get_stats64` callback can not sleep because of accesses +via `/proc/net/dev`. If driver may sleep when retrieving the statistics +from the device it should do so periodically asynchronously and only return +a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface +allows setting the frequency of refreshing statistics, if needed. + +Retrieving ethtool statistics is a multi-syscall process, drivers are advised +to keep the number of statistics constant to avoid race conditions with +user space trying to read them. + +Statistics must persist across routine operations like bringing the interface +down and up. + +Kernel-internal data structures +------------------------------- + +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. + +- ethtool_pause_stats() diff --git a/Documentation/networking/vxlan.rst b/Documentation/networking/vxlan.rst index ce239fa01848..2759dc1cc525 100644 --- a/Documentation/networking/vxlan.rst +++ b/Documentation/networking/vxlan.rst @@ -58,3 +58,31 @@ forwarding table using the new bridge command. 3. Show forwarding table:: # bridge fdb show dev vxlan0 + +The following NIC features may indicate support for UDP tunnel-related +offloads (most commonly VXLAN features, but support for a particular +encapsulation protocol is NIC specific): + + - `tx-udp_tnl-segmentation` + - `tx-udp_tnl-csum-segmentation` + ability to perform TCP segmentation offload of UDP encapsulated frames + + - `rx-udp_tunnel-port-offload` + receive side parsing of UDP encapsulated frames which allows NICs to + perform protocol-aware offloads, like checksum validation offload of + inner frames (only needed by NICs without protocol-agnostic offloads) + +For devices supporting `rx-udp_tunnel-port-offload` the list of currently +offloaded ports can be interrogated with `ethtool`:: + + $ ethtool --show-tunnels eth0 + Tunnel information for eth0: + UDP port table 0: + Size: 4 + Types: vxlan + No entries + UDP port table 1: + Size: 4 + Types: geneve, vxlan-gpe + Entries (1): + port 1230, vxlan-gpe diff --git a/Documentation/power/pci.rst b/Documentation/power/pci.rst index 1831e431f725..b04fb18cc4e2 100644 --- a/Documentation/power/pci.rst +++ b/Documentation/power/pci.rst @@ -320,7 +320,7 @@ that these callbacks operate on:: unsigned int d2_support:1; /* Low power state D2 is supported */ unsigned int no_d1d2:1; /* D1 and D2 are forbidden */ unsigned int wakeup_prepared:1; /* Device prepared for wake up */ - unsigned int d3_delay; /* D3->D0 transition time in ms */ + unsigned int d3hot_delay; /* D3hot->D0 transition time in ms */ ... }; diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst index a363d8c1603c..dfcb1097dce4 100644 --- a/Documentation/powerpc/isa-versions.rst +++ b/Documentation/powerpc/isa-versions.rst @@ -7,6 +7,7 @@ Mapping of some CPU versions to relevant ISA versions. ========= ==================================================================== CPU Architecture version ========= ==================================================================== +Power10 Power ISA v3.1 Power9 Power ISA v3.0B Power8 Power ISA v2.07 Power7 Power ISA v2.06 @@ -32,6 +33,7 @@ Key Features ========== ================== CPU VMX (aka. Altivec) ========== ================== +Power10 Yes Power9 Yes Power8 Yes Power7 Yes @@ -47,6 +49,7 @@ PPC970 Yes ========== ==== CPU VSX ========== ==== +Power10 Yes Power9 Yes Power8 Yes Power7 Yes @@ -62,6 +65,7 @@ PPC970 No ========== ==================================== CPU Transactional Memory ========== ==================================== +Power10 No (* see Power ISA v3.1, "Appendix A. Notes on the Removal of Transactional Memory from the Architecture") Power9 Yes (* see transactional_memory.txt) Power8 Yes Power7 No diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/powerpc/ptrace.rst index 864d4b6dddd1..77725d69eb4a 100644 --- a/Documentation/powerpc/ptrace.rst +++ b/Documentation/powerpc/ptrace.rst @@ -46,6 +46,7 @@ features will have bits indicating whether there is support for:: #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4 #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8 #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10 + #define PPC_DEBUG_FEATURE_DATA_BP_ARCH_31 0x20 2. PTRACE_SETHWDEBUG diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/powerpc/syscall64-abi.rst index 379817ca64d2..cf9b2857c72a 100644 --- a/Documentation/powerpc/syscall64-abi.rst +++ b/Documentation/powerpc/syscall64-abi.rst @@ -49,22 +49,22 @@ Register preservation rules Register preservation rules match the ELF ABI calling sequence with the following differences: ---- For the sc instruction, differences with the ELF ABI --- -=========== ============= ======================================== -r0 Volatile (System call number.) -r3 Volatile (Parameter 1, and return value.) -r4-r8 Volatile (Parameters 2-6.) -cr0 Volatile (cr0.SO is the return error condition.) -cr1, cr5-7 Nonvolatile -lr Nonvolatile -=========== ============= ======================================== - ---- For the scv 0 instruction, differences with the ELF ABI --- -=========== ============= ======================================== -r0 Volatile (System call number.) -r3 Volatile (Parameter 1, and return value.) -r4-r8 Volatile (Parameters 2-6.) -=========== ============= ======================================== ++------------------------------------------------------------------------+ +| For the sc instruction, differences with the ELF ABI | ++--------------+--------------+------------------------------------------+ +| r0 | Volatile | (System call number.) | +| rr3 | Volatile | (Parameter 1, and return value.) | +| rr4-r8 | Volatile | (Parameters 2-6.) | +| rcr0 | Volatile | (cr0.SO is the return error condition.) | +| rcr1, cr5-7 | Nonvolatile | | +| rlr | Nonvolatile | | ++--------------+--------------+------------------------------------------+ +| For the scv 0 instruction, differences with the ELF ABI | ++--------------+--------------+------------------------------------------+ +| r0 | Volatile | (System call number.) | +| r3 | Volatile | (Parameter 1, and return value.) | +| r4-r8 | Volatile | (Parameters 2-6.) | ++--------------+--------------+------------------------------------------+ All floating point and vector data registers as well as control and status registers are nonvolatile. diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index ff71d802b53d..9d83b8db8874 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -106,23 +106,29 @@ NUL or newline terminated. strcpy() -------- -strcpy() performs no bounds checking on the destination -buffer. This could result in linear overflows beyond the -end of the buffer, leading to all kinds of misbehaviors. While -`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the -risk of using this function, there is no good reason to add new uses of -this function. The safe replacement is strscpy(). +strcpy() performs no bounds checking on the destination buffer. This +could result in linear overflows beyond the end of the buffer, leading to +all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various +compiler flags help reduce the risk of using this function, there is +no good reason to add new uses of this function. The safe replacement +is strscpy(), though care must be given to any cases where the return +value of strcpy() was used, since strscpy() does not return a pointer to +the destination, but rather a count of non-NUL bytes copied (or negative +errno when it truncates). strncpy() on NUL-terminated strings ----------------------------------- -Use of strncpy() does not guarantee that the destination buffer -will be NUL terminated. This can lead to various linear read overflows -and other misbehavior due to the missing termination. It also NUL-pads the -destination buffer if the source contents are shorter than the destination -buffer size, which may be a needless performance penalty for callers using -only NUL-terminated strings. The safe replacement is strscpy(). -(Users of strscpy() still needing NUL-padding should instead -use strscpy_pad().) +Use of strncpy() does not guarantee that the destination buffer will +be NUL terminated. This can lead to various linear read overflows and +other misbehavior due to the missing termination. It also NUL-pads +the destination buffer if the source contents are shorter than the +destination buffer size, which may be a needless performance penalty +for callers using only NUL-terminated strings. The safe replacement is +strscpy(), though care must be given to any cases where the return value +of strncpy() was used, since strscpy() does not return a pointer to the +destination, but rather a count of non-NUL bytes copied (or negative +errno when it truncates). Any cases still needing NUL-padding should +instead use strscpy_pad(). If a caller is using non-NUL-terminated strings, strncpy() can still be used, but destinations should be marked with the `__nonstring @@ -131,10 +137,12 @@ attribute to avoid future compiler warnings. strlcpy() --------- -strlcpy() reads the entire source buffer first, possibly exceeding -the given limit of bytes to copy. This is inefficient and can lead to -linear read overflows if a source string is not NUL-terminated. The -safe replacement is strscpy(). +strlcpy() reads the entire source buffer first (since the return value +is meant to match that of strlen()). This read may exceed the destination +size limit. This is both inefficient and can lead to linear read overflows +if a source string is not NUL-terminated. The safe replacement is strscpy(), +though care must be given to any cases where the return value of strlcpy() +is used, since strscpy() will return negative errno values when it truncates. %p format specifier ------------------- 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/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index b681e862a335..1879f881c300 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -53,8 +53,7 @@ and elsewhere regarding submitting Linux kernel patches. 9) Check cleanly with sparse. -10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems - that they find. +10) Use ``make checkstack`` and fix any problems that it finds. .. note:: diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 58586ffe2808..83d9a82055a7 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -527,6 +527,13 @@ done on the patch. Reviewed-by: tags, when supplied by reviewers known to understand the subject area and to perform thorough reviews, will normally increase the likelihood of your patch getting into the kernel. +Both Tested-by and Reviewed-by tags, once received on mailing list from tester +or reviewer, should be added by author to the applicable patches when sending +next versions. However if the patch has changed substantially in following +version, these tags might not be applicable anymore and thus should be removed. +Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned +in the patch changelog (after the '---' separator). + A Suggested-by: tag indicates that the patch idea is suggested by the person named and ensures credit to the person for the idea. Please note that this tag should not be added without the reporter's permission, especially if the diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst index 78bc5572f829..b0a7e3010187 100644 --- a/Documentation/sound/designs/tracepoints.rst +++ b/Documentation/sound/designs/tracepoints.rst @@ -34,20 +34,20 @@ substream. In this procedure, PCM hardware parameters are decided by interaction between applications and ALSA PCM core. Once decided, runtime of the PCM substream keeps the parameters. -The parameters are described in :c:type:`struct snd_pcm_hw_params`. This +The parameters are described in struct snd_pcm_hw_params. This structure includes several types of parameters. Applications set preferable value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available set of parameters. The latter is used for an actual decision of the parameters. -The :c:type:`struct snd_pcm_hw_params` structure has below members: +The struct snd_pcm_hw_params structure has below members: ``flags`` Configurable. ALSA PCM core and some drivers handle this flag to select convenient parameters or change their behaviour. ``masks`` Configurable. This type of parameter is described in - :c:type:`struct snd_mask` and represent mask values. As of PCM protocol + struct snd_mask and represent mask values. As of PCM protocol v2.0.13, three types are defined. - SNDRV_PCM_HW_PARAM_ACCESS @@ -55,7 +55,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: - SNDRV_PCM_HW_PARAM_SUBFORMAT ``intervals`` Configurable. This type of parameter is described in - :c:type:`struct snd_interval` and represent values with a range. As of + struct snd_interval and represent values with a range. As of PCM protocol v2.0.13, twelve types are defined. - SNDRV_PCM_HW_PARAM_SAMPLE_BITS @@ -78,7 +78,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: are going to be changed. ``cmask`` Read-only. After returning from ioctl(2), buffer in user space for - :c:type:`struct snd_pcm_hw_params` includes result of each operation. + struct snd_pcm_hw_params includes result of each operation. This mask represents which mask/interval parameter is actually changed. ``info`` Read-only. This represents hardware/driver capabilities as bit flags @@ -110,10 +110,10 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: value to this parameter but some drivers intentionally set zero with a care of hardware design or data transmission protocol. -ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when +ALSA PCM core handles buffer of struct snd_pcm_hw_params when applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS. Parameters in the buffer are changed according to -:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The +struct snd_pcm_hardware and rules of constraints in the runtime. The structure describes capabilities of handled hardware. The rules describes dependencies on which a parameter is decided according to several parameters. A rule has a callback function, and drivers can register arbitrary functions @@ -121,17 +121,17 @@ to compute the target parameter. ALSA PCM core registers some rules to the runtime as a default. Each driver can join in the interaction as long as it prepared for two stuffs -in a callback of :c:type:`struct snd_pcm_ops.open`. +in a callback of struct snd_pcm_ops.open. 1. In the callback, drivers are expected to change a member of - :c:type:`struct snd_pcm_hardware` type in the runtime, according to + struct snd_pcm_hardware type in the runtime, according to capacities of corresponding hardware. 2. In the same callback, drivers are also expected to register additional rules of constraints into the runtime when several parameters have dependencies due to hardware design. The driver can refers to result of the interaction in a callback of -:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the +struct snd_pcm_ops.hw_params, however it should not change the content. Tracepoints in this category are designed to trace changes of the @@ -163,7 +163,7 @@ fields are different according to type of the parameter. For parameters of mask type, the fields represent hexadecimal dump of content of the parameter. For parameters of interval type, the fields represent values of each member of ``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in -:c:type:`struct snd_interval` in this order. +struct snd_interval in this order. Tracepoints in drivers ====================== diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index c8cc651eccf7..d24c64df7069 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -132,3 +132,4 @@ ISA DMA Helpers Other Helper Macros ------------------- .. kernel-doc:: include/sound/core.h +.. kernel-doc:: sound/sound_core.c diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index aa9d5ab183d2..73bbd59afc33 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -194,7 +194,7 @@ The minimum flow for PCI soundcards is as follows: - create ``remove`` callback. -- create a :c:type:`struct pci_driver <pci_driver>` structure +- create a struct pci_driver structure containing the three pointers above. - create an ``init`` function just calling the @@ -487,7 +487,7 @@ The destructor, remove callback, simply releases the card instance. Then the ALSA middle layer will release all the attached components automatically. -It would be typically just :c:func:`calling snd_card_free()`: +It would be typically just calling :c:func:`snd_card_free()`: :: @@ -560,16 +560,15 @@ return the card instance. The extra_size argument is used to allocate card->private_data for the chip-specific data. Note that these data are allocated by :c:func:`snd_card_new()`. -The first argument, the pointer of struct :c:type:`struct device -<device>`, specifies the parent device. For PCI devices, typically -``&pci->`` is passed there. +The first argument, the pointer of struct device, specifies the parent +device. For PCI devices, typically ``&pci->`` is passed there. Components ---------- After the card is created, you can attach the components (devices) to the card instance. In an ALSA driver, a component is represented as a -:c:type:`struct snd_device <snd_device>` object. A component +struct snd_device object. A component can be a PCM instance, a control interface, a raw MIDI interface, etc. Each such instance has one component entry. @@ -628,7 +627,7 @@ argument of :c:func:`snd_card_new()`, i.e. err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, sizeof(struct mychip), &card); -:c:type:`struct mychip <mychip>` is the type of the chip record. +struct mychip is the type of the chip record. In return, the allocated record can be accessed as @@ -890,7 +889,7 @@ functions. These resources must be released in the destructor function (see below). Now assume that the PCI device has an I/O port with 8 bytes and an -interrupt. Then :c:type:`struct mychip <mychip>` will have the +interrupt. Then struct mychip will have the following fields: :: @@ -1094,7 +1093,7 @@ PCI Entries ----------- So far, so good. Let's finish the missing PCI stuff. At first, we need a -:c:type:`struct pci_device_id <pci_device_id>` table for +struct pci_device_id table for this chipset. It's a table of PCI vendor/device ID number, and some masks. @@ -1110,19 +1109,17 @@ For example, }; MODULE_DEVICE_TABLE(pci, snd_mychip_ids); -The first and second fields of the :c:type:`struct pci_device_id -<pci_device_id>` structure are the vendor and device IDs. If you -have no reason to filter the matching devices, you can leave the -remaining fields as above. The last field of the :c:type:`struct -pci_device_id <pci_device_id>` struct contains private data -for this entry. You can specify any value here, for example, to define -specific operations for supported device IDs. Such an example is found -in the intel8x0 driver. +The first and second fields of the struct pci_device_id are the vendor +and device IDs. If you have no reason to filter the matching devices, you can +leave the remaining fields as above. The last field of the +struct pci_device_id contains private data for this entry. You can specify +any value here, for example, to define specific operations for supported +device IDs. Such an example is found in the intel8x0 driver. The last entry of this list is the terminator. You must specify this all-zero entry. -Then, prepare the :c:type:`struct pci_driver <pci_driver>` +Then, prepare the struct pci_driver record: :: @@ -1439,8 +1436,8 @@ corresponding argument. If a chip supports multiple playbacks or captures, you can specify more numbers, but they must be handled properly in open/close, etc. callbacks. When you need to know which substream you are referring to, -then it can be obtained from :c:type:`struct snd_pcm_substream -<snd_pcm_substream>` data passed to each callback as follows: +then it can be obtained from struct snd_pcm_substream data passed to each +callback as follows: :: @@ -1639,10 +1636,9 @@ In the sections below, important records are explained. Hardware Description ~~~~~~~~~~~~~~~~~~~~ -The hardware descriptor (:c:type:`struct snd_pcm_hardware -<snd_pcm_hardware>`) contains the definitions of the fundamental -hardware configuration. Above all, you'll need to define this in the -`PCM open callback`_. Note that the runtime instance holds the copy of +The hardware descriptor (struct snd_pcm_hardware) contains the definitions of +the fundamental hardware configuration. Above all, you'll need to define this +in the `PCM open callback`_. Note that the runtime instance holds the copy of the descriptor, not the pointer to the existing descriptor. That is, in the open callback, you can modify the copied descriptor (``runtime->hw``) as you need. For example, if the maximum number of @@ -1800,14 +1796,13 @@ Running Status ~~~~~~~~~~~~~~ The running status can be referred via ``runtime->status``. This is -the pointer to the :c:type:`struct snd_pcm_mmap_status -<snd_pcm_mmap_status>` record. For example, you can get the current +the pointer to the struct snd_pcm_mmap_status record. +For example, you can get the current DMA hardware pointer via ``runtime->status->hw_ptr``. The DMA application pointer can be referred via ``runtime->control``, -which points to the :c:type:`struct snd_pcm_mmap_control -<snd_pcm_mmap_control>` record. However, accessing directly to -this value is not recommended. +which points to the struct snd_pcm_mmap_control record. +However, accessing directly to this value is not recommended. Private Data ~~~~~~~~~~~~ @@ -1843,8 +1838,8 @@ error number such as ``-EINVAL``. To choose an appropriate error number, it is advised to check what value other parts of the kernel return when the same kind of request fails. -The callback function takes at least the argument with :c:type:`struct -snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip +The callback function takes at least the argument with +struct snd_pcm_substream pointer. To retrieve the chip record from the given substream instance, you can use the following macro. @@ -2313,10 +2308,10 @@ non-atomic contexts. For example, the function :c:func:`snd_pcm_period_elapsed()` is called typically from the interrupt handler. But, if you set up the driver to use a threaded interrupt handler, this call can be in non-atomic context, too. In such -a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm -<snd_pcm>` object after creating it. When this flag is set, mutex -and rwsem are used internally in the PCM core instead of spin and -rwlocks, so that you can call all PCM functions safely in a non-atomic +a case, you can set ``nonatomic`` filed of struct snd_pcm object +after creating it. When this flag is set, mutex and rwsem are used internally +in the PCM core instead of spin and rwlocks, so that you can call all PCM +functions safely in a non-atomic context. Constraints @@ -2357,8 +2352,7 @@ There are many different constraints. Look at ``sound/pcm.h`` for a complete list. You can even define your own constraint rules. For example, let's suppose my_chip can manage a substream of 1 channel if and only if the format is ``S16_LE``, otherwise it supports any format -specified in the :c:type:`struct snd_pcm_hardware -<snd_pcm_hardware>` structure (or in any other +specified in struct snd_pcm_hardware> (or in any other constraint_list). You can build a rule like this: :: @@ -2467,7 +2461,7 @@ Definition of Controls To create a new control, you need to define the following three callbacks: ``info``, ``get`` and ``put``. Then, define a -:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as: +struct snd_kcontrol_new record, such as: :: @@ -2602,8 +2596,8 @@ info callback ~~~~~~~~~~~~~ The ``info`` callback is used to get detailed information on this -control. This must store the values of the given :c:type:`struct -snd_ctl_elem_info <snd_ctl_elem_info>` object. For example, +control. This must store the values of the given +struct snd_ctl_elem_info object. For example, for a boolean control with a single element: :: @@ -2774,13 +2768,11 @@ In the simplest way, you can do like this: if (err < 0) return err; -where ``my_control`` is the :c:type:`struct snd_kcontrol_new -<snd_kcontrol_new>` object defined above, and chip is the object -pointer to be passed to kcontrol->private_data which can be referred -to in callbacks. +where ``my_control`` is the struct snd_kcontrol_new object defined above, +and chip is the object pointer to be passed to kcontrol->private_data which +can be referred to in callbacks. -:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct -snd_kcontrol <snd_kcontrol>` instance, and +:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and :c:func:`snd_ctl_add()` assigns the given control component to the card. @@ -2797,10 +2789,9 @@ can call :c:func:`snd_ctl_notify()`. For example, This function takes the card pointer, the event-mask, and the control id pointer for the notification. The event-mask specifies the types of notification, for example, in the above example, the change of control -values is notified. The id pointer is the pointer of :c:type:`struct -snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can -find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume -interrupts. +values is notified. The id pointer is the pointer of struct snd_ctl_elem_id +to be notified. You can find some examples in ``es1938.c`` or ``es1968.c`` +for hardware volume interrupts. Metadata -------- @@ -2915,9 +2906,8 @@ with an ``ac97_bus_ops_t`` record with callback functions. The bus record is shared among all belonging ac97 instances. -And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct -snd_ac97_template <snd_ac97_template>` record together with -the bus pointer created above. +And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template +record together with the bus pointer created above. :: @@ -3118,11 +3108,10 @@ devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see Usually, the port address corresponds to the command port and port + 1 corresponds to the data port. If not, you may change the ``cport`` -field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward. -However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is +field of struct snd_mpu401 manually afterward. +However, struct snd_mpu401 pointer is not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You -need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401 -<snd_mpu401>` explicitly, +need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly, :: @@ -3326,8 +3315,7 @@ data and removes them from the buffer at once: } If you know beforehand how many bytes you can accept, you can use a -buffer size greater than one with the -:c:func:`snd_rawmidi_transmit\*()` functions. +buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions. The ``trigger`` callback must not sleep. If the hardware FIFO is full before the substream buffer has been emptied, you have to continue @@ -3772,7 +3760,7 @@ For creating the SG-buffer handler, call :c:func:`snd_pcm_set_managed_buffer_all()` with ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI pre-allocator. You need to pass ``&pci->dev``, where pci is -the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as +the struct pci_dev pointer of the chip as well. :: @@ -3927,7 +3915,7 @@ the maximum size of the proc file access. The read/write callbacks of raw mode are more direct than the text mode. You need to use a low-level I/O functions such as -:c:func:`copy_from/to_user()` to transfer the data. +:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data. :: diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index a1b0f554cd82..3e81ebab26ed 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -16,19 +16,48 @@ 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'(([\w_][\w\d_]+)\(\))') -RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') +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=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=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 # an optional extension # -RE_doc = re.compile(r'Documentation(/[\w\-_/]+)(\.\w+)*') +RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*') + +# +# Reserved C words that we should skip when cross-referencing +# +Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ] + # # Many places in the docs refer to common system calls. It is @@ -48,9 +77,22 @@ def markup_refs(docname, app, node): # # Associate each regex with the function that will markup its matches # - markup_func = {RE_type: markup_c_ref, - RE_function: markup_c_ref, - RE_doc: markup_doc_ref} + markup_func_sphinx2 = {RE_doc: markup_doc_ref, + RE_function: markup_c_ref, + RE_generic_type: markup_c_ref} + + markup_func_sphinx3 = {RE_doc: markup_doc_ref, + RE_function: markup_func_ref_sphinx3, + RE_struct: markup_c_ref, + RE_union: markup_c_ref, + RE_enum: markup_c_ref, + RE_typedef: markup_c_ref} + + if sphinx.version_info[0] >= 3: + markup_func = markup_func_sphinx3 + else: + markup_func = markup_func_sphinx2 + match_iterators = [regex.finditer(t) for regex in markup_func] # # Sort all references by the starting position in text @@ -75,12 +117,63 @@ def markup_refs(docname, app, node): return repl # -# Try to replace a C reference (function() or struct/union/enum/typedef -# type_name) with an appropriate cross reference. +# In sphinx3 we can cross-reference to C macro and function, each one with its +# own C role, but both match the same regex, so we try both. # +def markup_func_ref_sphinx3(docname, app, match): + class_str = ['c-func', 'c-macro'] + reftype_str = ['function', 'macro'] + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + if not (target in Skipfuncs or target in Skipnames): + for class_s, reftype_s in zip(class_str, reftype_str): + lit_text = nodes.literal(classes=['xref', 'c', class_s]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_s, + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_s, target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + def markup_c_ref(docname, app, match): - class_str = {RE_function: 'c-func', RE_type: 'c-type'} - reftype_str = {RE_function: 'function', RE_type: 'type'} + class_str = {# Sphinx 2 only + RE_function: 'c-func', + RE_generic_type: 'c-type', + # Sphinx 3+ only + RE_struct: 'c-struct', + RE_union: 'c-union', + RE_enum: 'c-enum', + RE_typedef: 'c-type', + } + reftype_str = {# Sphinx 2 only + RE_function: 'function', + RE_generic_type: 'type', + # Sphinx 3+ only + RE_struct: 'struct', + RE_union: 'union', + RE_enum: 'enum', + RE_typedef: 'type', + } cdom = app.env.domains['c'] # @@ -89,7 +182,8 @@ def markup_c_ref(docname, app, match): target = match.group(2) target_text = nodes.Text(match.group(0)) xref = None - if not (match.re == RE_function and target in Skipfuncs): + if not ((match.re == RE_function and target in Skipfuncs) + or (target in Skipnames)): lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) lit_text += target_text pxref = addnodes.pending_xref('', refdomain = 'c', diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index cbac8e608dc4..014a5229e57a 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -40,14 +40,94 @@ from sphinx import addnodes from sphinx.domains.c import c_funcptr_sig_re, c_sig_re from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain +from itertools import chain +import re -__version__ = '1.0' +__version__ = '1.1' # Get Sphinx version major, minor, patch = sphinx.version_info[:3] +# Namespace to be prepended to the full name +namespace = None + +# +# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags +# - Store the namespace if ".. c:namespace::" tag is found +# +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') + +def markup_namespace(match): + global namespace + + namespace = match.group(1) + + return "" + +# +# Handle c:macro for function-style declaration +# +RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') +def markup_macro(match): + return ".. c:function:: " + match.group(1) + ' ' + match.group(2) + +# +# Handle newer c domain tags that are evaluated as .. c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') + +def markup_ctype(match): + return ".. c:type:: " + match.group(2) + +# +# Handle newer c domain tags that are evaluated as :c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') +def markup_ctype_refs(match): + return ":c:type:`" + match.group(2) + '`' + +# +# Simply convert :c:expr: and :c:texpr: into a literal block. +# +RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') +def markup_c_expr(match): + return '\ ``' + match.group(2) + '``\ ' + +# +# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones +# +def c_markups(app, docname, source): + result = "" + markup_func = { + RE_namespace: markup_namespace, + RE_expr: markup_c_expr, + RE_macro: markup_macro, + RE_ctype: markup_ctype, + RE_ctype_refs: markup_ctype_refs, + } + + lines = iter(source[0].splitlines(True)) + for n in lines: + match_iterators = [regex.finditer(n) for regex in markup_func] + matches = sorted(chain(*match_iterators), key=lambda m: m.start()) + for m in matches: + n = n[:m.start()] + markup_func[m.re](m) + n[m.end():] + + result = result + n + + source[0] = result + +# +# Now implements support for the cdomain namespacing logic +# + def setup(app): + # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: + app.connect('source-read', c_markups) + if (major == 1 and minor < 8): app.override_domain(CDomain) else: @@ -75,6 +155,8 @@ class CObject(Base_CObject): function-like macro, the name of the macro is returned. Otherwise ``False`` is returned. """ + global namespace + if not self.objtype == 'function': return False @@ -107,11 +189,16 @@ class CObject(Base_CObject): param += nodes.emphasis(argname, argname) paramlist += param + if namespace: + fullname = namespace + "." + fullname + return fullname def handle_signature(self, sig, signode): """Transform a C signature into RST nodes.""" + global namespace + fullname = self.handle_func_like_macro(sig, signode) if not fullname: fullname = super(CObject, self).handle_signature(sig, signode) @@ -122,6 +209,10 @@ class CObject(Base_CObject): else: # FIXME: handle :name: value of other declaration types? pass + else: + if namespace: + fullname = namespace + "." + fullname + return fullname def add_target_and_index(self, name, sig, signode): 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/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 4bcbd6ae01cd..e9857ab904f1 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -62,6 +62,7 @@ class KernelDocDirective(Directive): 'export': directives.unchanged, 'internal': directives.unchanged, 'identifiers': directives.unchanged, + 'no-identifiers': directives.unchanged, 'functions': directives.unchanged, } has_content = False @@ -70,6 +71,11 @@ class KernelDocDirective(Directive): env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions + cmd += ['-sphinx-version', sphinx.__version__] + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] @@ -99,6 +105,12 @@ class KernelDocDirective(Directive): else: cmd += ['-no-doc-sections'] + if 'no-identifiers' in self.options: + no_identifiers = self.options.get('no-identifiers').split() + if no_identifiers: + for i in no_identifiers: + cmd += ['-nosymbol', i] + for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): env.note_dependency(os.path.abspath(f)) @@ -136,7 +148,8 @@ class KernelDocDirective(Directive): lineoffset = int(match.group(1)) - 1 # we must eat our comments since the upset the markup else: - result.append(line, filename, lineoffset) + doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 node = nodes.section() 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/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 00a69aceff44..1910079f984f 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -110,7 +110,7 @@ while (<IN>) { ) { my $s = $1; - $structs{$s} = "struct :c:type:`$s`\\ "; + $structs{$s} = "struct $s\\ "; next; } } diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index dcb390075ca1..89b64334929b 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -61,6 +61,10 @@ These options can be used for each instance including global ftrace node. ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]] Enable given ftrace options. +ftrace.[instance.INSTANCE.]tracing_on = 0|1 + Enable/Disable tracing on this instance when starting boot-time tracing. + (you can enable it by the "traceon" event trigger action) + ftrace.[instance.INSTANCE.]trace_clock = CLOCK Set given CLOCK to ftrace's trace_clock. @@ -116,6 +120,20 @@ instance node, but those are also visible from other instances. So please take care for event name conflict. +When to Start +============= + +All boot-time tracing options starting with ``ftrace`` will be enabled at the +end of core_initcall. This means you can trace the events from postcore_initcall. +Most of the subsystems and architecture dependent drivers will be initialized +after that (arch_initcall or subsys_initcall). Thus, you can trace those with +boot-time tracing. +If you want to trace events before core_initcall, you can use the options +starting with ``kernel``. Some of them will be enabled eariler than the initcall +processing (for example,. ``kernel.ftrace=function`` and ``kernel.trace_event`` +will start before the initcall.) + + Examples ======== @@ -164,6 +182,26 @@ is for tracing functions starting with "user\_", and others tracing The instance node also accepts event nodes so that each instance can customize its event tracing. +With the trigger action and kprobes, you can trace function-graph while +a function is called. For example, this will trace all function calls in +the pci_proc_init():: + + ftrace { + tracing_on = 0 + tracer = function_graph + event.kprobes { + start_event { + probes = "pci_proc_init" + actions = "traceon" + } + end_event { + probes = "pci_proc_init%return" + actions = "traceoff" + } + } + } + + This boot-time tracing also supports ftrace kernel parameters via boot config. For example, following kernel parameters:: diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index f792b1959a33..2a5aa48eff6c 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -589,8 +589,19 @@ name:: { .type = "int", .name = "my_int_field" }, }; -See synth_field_size() for available types. If field_name contains [n] -the field is considered to be an array. +See synth_field_size() for available types. + +If field_name contains [n], the field is considered to be a static array. + +If field_names contains[] (no subscript), the field is considered to +be a dynamic array, which will only take as much space in the event as +is required to hold the array. + +Because space for an event is reserved before assigning field values +to the event, using dynamic arrays implies that the piecewise +in-kernel API described below can't be used with dynamic arrays. The +other non-piecewise in-kernel APIs can, however, be used with dynamic +arrays. If the event is created from within a module, a pointer to the module must be passed to synth_event_create(). This will ensure that the diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index 2a05e770618a..a4955f7e3d19 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -55,17 +55,17 @@ an ftrace_ops with ftrace: Both .flags and .private are optional. Only .func is required. -To enable tracing call: +To enable tracing call:: -.. c:function:: register_ftrace_function(&ops); + register_ftrace_function(&ops); -To disable tracing call: +To disable tracing call:: -.. c:function:: unregister_ftrace_function(&ops); + unregister_ftrace_function(&ops); -The above is defined by including the header: +The above is defined by including the header:: -.. c:function:: #include <linux/ftrace.h> + #include <linux/ftrace.h> The registered callback will start being called some time after the register_ftrace_function() is called and before it returns. The exact time diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index f93333524a44..b71e09f745c3 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -1776,6 +1776,24 @@ consisting of the name of the new event along with one or more variables and their types, which can be any valid field type, separated by semicolons, to the tracing/synthetic_events file. +See synth_field_size() for available types. + +If field_name contains [n], the field is considered to be a static array. + +If field_names contains[] (no subscript), the field is considered to +be a dynamic array, which will only take as much space in the event as +is required to hold the array. + +A string field can be specified using either the static notation: + + char name[32]; + +Or the dynamic: + + char name[]; + +The size limit for either is 256. + For instance, the following creates a new event named 'wakeup_latency' with 3 fields: lat, pid, and prio. Each of those fields is simply a variable reference to a variable on another event:: diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 10850a9e9af3..b175d88f31eb 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -30,6 +30,7 @@ Synopsis of kprobe_events p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe + p:[GRP/]EVENT] [MOD:]SYM[+0]%return [FETCHARGS] : Set a return probe -:[GRP/]EVENT : Clear a probe GRP : Group name. If omitted, use "kprobes" for it. @@ -37,6 +38,7 @@ Synopsis of kprobe_events based on SYM+offs or MEMADDR. MOD : Module name which has given SYM. SYM[+offs] : Symbol+offset where the probe is inserted. + SYM%return : Return address of the symbol MEMADDR : Address where the probe is inserted. MAXACTIVE : Maximum number of instances of the specified function that can be probed simultaneously, or 0 for the default value diff --git a/Documentation/trace/tracepoints.rst b/Documentation/trace/tracepoints.rst index 6e3ce3bf3593..0cb8d9ca3d60 100644 --- a/Documentation/trace/tracepoints.rst +++ b/Documentation/trace/tracepoints.rst @@ -146,3 +146,30 @@ with jump labels and avoid conditional branches. define tracepoints. Check http://lwn.net/Articles/379903, http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362 for a series of articles with more details. + +If you require calling a tracepoint from a header file, it is not +recommended to call one directly or to use the trace_<tracepoint>_enabled() +function call, as tracepoints in header files can have side effects if a +header is included from a file that has CREATE_TRACE_POINTS set, as +well as the trace_<tracepoint>() is not that small of an inline +and can bloat the kernel if used by other inlined functions. Instead, +include tracepoint-defs.h and use tracepoint_enabled(). + +In a C file:: + + void do_trace_foo_bar_wrapper(args) + { + trace_foo_bar(args); + } + +In the header file:: + + DECLARE_TRACEPOINT(foo_bar); + + static inline void some_inline_function() + { + [..] + if (tracepoint_enabled(foo_bar)) + do_trace_foo_bar_wrapper(args); + [..] + } diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index 98cde99939d7..a8e5938f609e 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -28,6 +28,7 @@ Synopsis of uprobe_tracer p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe) + p[:[GRP/]EVENT] PATH:OFFSET%return [FETCHARGS] : Set a return uprobe (uretprobe) -:[GRP/]EVENT : Clear uprobe or uretprobe event GRP : Group name. If omitted, "uprobes" is the default value. @@ -35,6 +36,7 @@ Synopsis of uprobe_tracer on PATH+OFFSET. PATH : Path to an executable or a library. OFFSET : Offset where the probe is inserted. + OFFSET%return : Offset where the return probe is inserted. FETCHARGS : Arguments. Each probe can have up to 128 args. %REG : Fetch register REG diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 6aab27a8d323..3d30b69f1ec1 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -402,7 +402,7 @@ il valore convertito. Tutte le varianti supportano anche il processo inverso: :c:func:`be32_to_cpu()`, eccetera. Queste funzioni hanno principalmente due varianti: la variante per -puntatori, come :c:func:`cpu_to_be32p(), che prende un puntatore +puntatori, come :c:func:`cpu_to_be32p()`, che prende un puntatore ad un tipo, e ritorna il valore convertito. L'altra variante per la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`, che convertono il valore puntato da un puntatore, e ritornano void. diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 4615df5723fb..bf1acd6204ef 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1,5 +1,7 @@ .. include:: ../disclaimer-ita.rst +.. c:namespace:: it_IT + :Original: :ref:`Documentation/kernel-hacking/locking.rst <kernel_hacking_lock>` :Translator: Federico Vaga <federico.vaga@vaga.pv.it> 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/translations/zh_CN/arm64/amu.rst b/Documentation/translations/zh_CN/arm64/amu.rst index bd875f221330..ab7180f91394 100644 --- a/Documentation/translations/zh_CN/arm64/amu.rst +++ b/Documentation/translations/zh_CN/arm64/amu.rst @@ -4,9 +4,9 @@ Translator: Bailu Lin <bailu.lin@vivo.com> -================================= +================================== AArch64 Linux 中扩展的活动监控单元 -================================= +================================== 作者: Ionela Voinescu <ionela.voinescu@arm.com> diff --git a/Documentation/translations/zh_CN/arm64/hugetlbpage.rst b/Documentation/translations/zh_CN/arm64/hugetlbpage.rst new file mode 100644 index 000000000000..13304d269d0b --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/hugetlbpage.rst @@ -0,0 +1,45 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/arm64/hugetlbpage.rst <hugetlbpage_index>` + +Translator: Bailu Lin <bailu.lin@vivo.com> + +===================== +ARM64中的 HugeTLBpage +===================== + +大页依靠有效利用 TLBs 来提高地址翻译的性能。这取决于以下 +两点 - + + - 大页的大小 + - TLBs 支持的条目大小 + +ARM64 接口支持2种大页方式。 + +1) pud/pmd 级别的块映射 +----------------------- + +这是常规大页，他们的 pmd 或 pud 页面表条目指向一个内存块。 +不管 TLB 中支持的条目大小如何，块映射可以减少翻译大页地址 +所需遍历的页表深度。 + +2) 使用连续位 +------------- + +架构中转换页表条目(D4.5.3, ARM DDI 0487C.a)中提供一个连续 +位告诉 MMU 这个条目是一个连续条目集的一员，它可以被缓存在单 +个 TLB 条目中。 + +在 Linux 中连续位用来增加 pmd 和 pte(最后一级)级别映射的大 +小。受支持的连续页表条目数量因页面大小和页表级别而异。 + + +支持以下大页尺寸配置 - + + ====== ======== ==== ======== === + - CONT PTE PMD CONT PMD PUD + ====== ======== ==== ======== === + 4K: 64K 2M 32M 1G + 16K: 2M 32M 1G + 64K: 2M 512M 16G + ====== ======== ==== ======== === diff --git a/Documentation/translations/zh_CN/arm64/index.rst b/Documentation/translations/zh_CN/arm64/index.rst index 646ed1f7aea3..e31a6090384d 100644 --- a/Documentation/translations/zh_CN/arm64/index.rst +++ b/Documentation/translations/zh_CN/arm64/index.rst @@ -14,3 +14,4 @@ ARM64 架构 :maxdepth: 2 amu + hugetlbpage 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/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst index 33c563f414a8..409e70a5f80f 100644 --- a/Documentation/userspace-api/media/cec/cec-func-close.rst +++ b/Documentation/userspace-api/media/cec/cec-func-close.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-close: @@ -11,7 +12,6 @@ Name cec-close - Close a cec device - Synopsis ======== @@ -19,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: cec-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -36,11 +33,10 @@ Description Closes the cec device. Resources associated with the file descriptor are freed. The device configuration remain unchanged. - Return Value ============ -:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: ``EBADF`` diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst index 3b88230fad80..7c93f86de6cc 100644 --- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst +++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-ioctl: @@ -18,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: cec-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``request`` CEC ioctl request code as defined in the cec.h header file, for @@ -35,11 +34,10 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== -The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The +The :c:func:`ioctl()` function manipulates cec device parameters. The argument ``fd`` must be an open file descriptor. The ioctl ``request`` code specifies the cec function to be called. It @@ -51,7 +49,6 @@ their parameters are located in the cec.h header file. All cec ioctl requests, their respective function and parameters are specified in :ref:`cec-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst index 887bfd2a755e..d86563a34b9e 100644 --- a/Documentation/userspace-api/media/cec/cec-func-open.rst +++ b/Documentation/userspace-api/media/cec/cec-func-open.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-open: @@ -18,10 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: cec-open - Arguments ========= @@ -42,11 +40,10 @@ Arguments Other flags have no effect. - Description =========== -To open a cec device applications call :c:func:`open() <cec-open>` with the +To open a cec device applications call :c:func:`open()` with the desired device name. The function has no side effects; the device configuration remain unchanged. @@ -54,11 +51,10 @@ When the device is opened in read-only mode, attempts to modify its configuration will result in an error, and ``errno`` will be set to EBADF. - Return Value ============ -:c:func:`open() <cec-open>` returns the new file descriptor on success. On error, +:c:func:`open()` returns the new file descriptor on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes include: diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst index 2d87136e9a3f..980bbfc0bcce 100644 --- a/Documentation/userspace-api/media/cec/cec-func-poll.rst +++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-poll: @@ -11,7 +12,6 @@ Name cec-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: cec-poll Arguments ========= @@ -35,14 +33,13 @@ Arguments ``timeout`` Timeout to wait for events - Description =========== -With the :c:func:`poll() <cec-poll>` function applications can wait for CEC +With the :c:func:`poll()` function applications can wait for CEC events. -On success :c:func:`poll() <cec-poll>` returns the number of file descriptors +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the ``revents`` field of the respective struct :c:type:`pollfd` is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in @@ -53,13 +50,12 @@ then the ``POLLPRI`` flag is set. When the function times out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. -For more details see the :c:func:`poll() <cec-poll>` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :c:func:`poll() <cec-poll>` returns the number structures which have +On success, :c:func:`poll()` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst index 7f25365ce0fb..c7309a2fcbce 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_G_CAPS: @@ -14,18 +15,18 @@ CEC_ADAP_G_CAPS - Query device capabilities Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp ) - :name: CEC_ADAP_G_CAPS +.. c:macro:: CEC_ADAP_G_CAPS + +``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -62,7 +63,6 @@ returns the information to the application. The ioctl never fails. - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` macro. - .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| .. _cec-capabilities: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst index 6818ddf1495c..13116b0b5c17 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst @@ -2,6 +2,8 @@ .. .. Copyright 2019 Google LLC .. +.. c:namespace:: CEC + .. _CEC_ADAP_G_CONNECTOR_INFO: ******************************* @@ -16,18 +18,18 @@ CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp ) - :name: CEC_ADAP_G_CONNECTOR_INFO +.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO + +``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -57,7 +59,6 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. * - } - - .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| .. _connector-type: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst index 1ca893270ae9..c760c07b6b3f 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_LOG_ADDRS: .. _CEC_ADAP_G_LOG_ADDRS: @@ -13,21 +14,22 @@ Name CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_G_LOG_ADDRS +.. c:macro:: CEC_ADAP_G_LOG_ADDRS + +``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)`` + +.. c:macro:: CEC_ADAP_S_LOG_ADDRS -.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_S_LOG_ADDRS +``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`cec_log_addrs`. @@ -148,7 +150,6 @@ logical address types are already defined will return with error ``EBUSY``. give the CEC framework more information about the device type, even though the framework won't use it directly in the CEC message. - .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| .. _cec-log-addrs-flags: @@ -185,7 +186,6 @@ logical address types are already defined will return with error ``EBUSY``. All other messages are ignored. - .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| .. _cec-versions: @@ -211,7 +211,6 @@ logical address types are already defined will return with error ``EBUSY``. - 6 - CEC version according to the HDMI 2.0 standard. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _cec-prim-dev-types: @@ -257,7 +256,6 @@ logical address types are already defined will return with error ``EBUSY``. - 7 - Use for a video processor device. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _cec-log-addr-types: @@ -306,7 +304,6 @@ logical address types are already defined will return with error ``EBUSY``. Control). - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _cec-all-dev-types-flags: @@ -348,7 +345,6 @@ logical address types are already defined will return with error ``EBUSY``. - This supports the CEC Switch or Video Processing type. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst index a10443be1b26..fb22f6894f26 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_PHYS_ADDR: .. _CEC_ADAP_G_PHYS_ADDR: @@ -13,21 +14,22 @@ Name CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_G_PHYS_ADDR +.. c:macro:: CEC_ADAP_G_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`` -.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_S_PHYS_ADDR +.. c:macro:: CEC_ADAP_S_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to the CEC address. @@ -71,7 +73,6 @@ For example, the EDID for each HDMI input of the TV will have a different physical address of the form a.0.0.0 that the sources will read out and use as their physical address. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst index 3bc81fc5a73f..736fda5ad73d 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_DQEVENT: @@ -11,22 +12,21 @@ Name CEC_DQEVENT - Dequeue a CEC event - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) - :name: CEC_DQEVENT +.. c:macro:: CEC_DQEVENT + +``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -72,7 +72,6 @@ it is guaranteed that the state did change in between the two events. the HDMI driver is still configuring the device or because the HDMI device was unbound. - .. c:type:: cec_event_lost_msgs .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| @@ -94,7 +93,6 @@ it is guaranteed that the state did change in between the two events. replied to within a second according to the CEC specification, this is more than enough. - .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| .. c:type:: cec_event @@ -130,7 +128,6 @@ it is guaranteed that the state did change in between the two events. * - } - - .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| .. _cec-events: @@ -204,7 +201,6 @@ it is guaranteed that the state did change in between the two events. if the 5V is high, then an initial event will be generated for that filehandle. - .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| .. _cec-event-flags: @@ -230,7 +226,6 @@ it is guaranteed that the state did change in between the two events. This is an indication that the application cannot keep up. - Return Value ============ 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 2093e373c93c..d3387b1fa7c5 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_MODE: .. _CEC_G_MODE: @@ -13,17 +14,19 @@ CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp ) - :name: CEC_G_MODE +.. c:macro:: CEC_G_MODE -.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp ) - :name: CEC_S_MODE +``int ioctl(int fd, CEC_G_MODE, __u32 *argp)`` + +.. c:macro:: CEC_S_MODE + +``int ioctl(int fd, CEC_S_MODE, __u32 *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to CEC mode. @@ -101,7 +104,6 @@ Available initiator modes are: then an attempt to become one will return the ``EBUSY`` error code error. - Available follower modes are: .. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| @@ -193,7 +195,6 @@ Available follower modes are: the process has the ``CAP_NET_ADMIN`` capability. If that is not set, then the ``EPERM`` error code is returned. - Core message processing details: .. tabularcolumns:: |p{6.6cm}|p{10.9cm}| @@ -272,7 +273,6 @@ Core message processing details: and then just pass the message on to the follower(s). - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index 9d629d46973c..b2fc051e99f4 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_TRANSMIT: .. _CEC_RECEIVE: @@ -12,21 +13,22 @@ Name CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp ) - :name: CEC_RECEIVE +.. c:macro:: CEC_RECEIVE + +``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)`` -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) - :name: CEC_TRANSMIT +.. c:macro:: CEC_TRANSMIT + +``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct cec_msg. @@ -194,7 +196,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). supports this, otherwise it is always 0. This counter is only valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. - .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| .. _cec-msg-flags: @@ -228,7 +229,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). capability. If that is not set, then the ``EPERM`` error code is returned. - .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| .. _cec-tx-status: @@ -298,7 +298,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The transmit timed out. This should not normally happen and this indicates a driver problem. - .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| .. _cec-rx-status: @@ -335,7 +334,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). reply was interrupted. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst index ba4f48b30d29..33b5363317f1 100644 --- a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst +++ b/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_BILINGUAL_CHANNEL_SELECT: @@ -16,9 +17,9 @@ AUDIO_BILINGUAL_CHANNEL_SELECT Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_BILINGUAL_CHANNEL_SELECT +.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT +``int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct audio_channel_select *select)`` Arguments --------- @@ -39,7 +40,6 @@ Arguments - Select the output format of the audio (mono left/right, stereo). - Description ----------- @@ -50,7 +50,6 @@ for MPEG decoders controlled through V4L2. This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-channel-select.rst index ba83b639d955..74093df92a68 100644 --- a/Documentation/userspace-api/media/dvb/audio-channel-select.rst +++ b/Documentation/userspace-api/media/dvb/audio-channel-select.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_CHANNEL_SELECT: @@ -16,9 +17,9 @@ AUDIO_CHANNEL_SELECT Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_CHANNEL_SELECT +.. c:macro:: AUDIO_CHANNEL_SELECT +``int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct audio_channel_select *select)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -40,7 +40,6 @@ Arguments - Select the output format of the audio (mono left/right, stereo). - Description ----------- @@ -50,7 +49,6 @@ V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. This ioctl call asks the Audio Device to select the requested channel if possible. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst b/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst index 7035a40c0e3a..a0ebb0278260 100644 --- a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst +++ b/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_CLEAR_BUFFER: @@ -16,8 +17,9 @@ AUDIO_CLEAR_BUFFER Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER) - :name: AUDIO_CLEAR_BUFFER +.. c:macro:: AUDIO_CLEAR_BUFFER + +``int ioctl(int fd, AUDIO_CLEAR_BUFFER)`` Arguments --------- @@ -26,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -39,7 +40,6 @@ Description This ioctl call asks the Audio Device to clear all software and hardware buffers of the audio decoder device. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-continue.rst b/Documentation/userspace-api/media/dvb/audio-continue.rst index c8d514a4eeb0..a2e9850f37f2 100644 --- a/Documentation/userspace-api/media/dvb/audio-continue.rst +++ b/Documentation/userspace-api/media/dvb/audio-continue.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_CONTINUE: @@ -16,9 +17,9 @@ AUDIO_CONTINUE Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_CONTINUE) - :name: AUDIO_CONTINUE +.. c:macro:: AUDIO_CONTINUE +``int ioctl(int fd, AUDIO_CONTINUE)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,7 +40,6 @@ Description This ioctl restarts the decoding and playing process previously paused with AUDIO_PAUSE command. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-fclose.rst b/Documentation/userspace-api/media/dvb/audio-fclose.rst index c968177b1e3f..77857d578e83 100644 --- a/Documentation/userspace-api/media/dvb/audio-fclose.rst +++ b/Documentation/userspace-api/media/dvb/audio-fclose.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _audio_fclose: @@ -17,8 +18,6 @@ Synopsis -------- .. c:function:: int close(int fd) - :name: dvb-audio-close - Arguments --------- @@ -27,20 +26,17 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd - File descriptor returned by a previous call to open(). - Description ----------- This system call closes a previously opened audio device. - Return Value ------------ @@ -48,7 +44,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EBADF`` diff --git a/Documentation/userspace-api/media/dvb/audio-fopen.rst b/Documentation/userspace-api/media/dvb/audio-fopen.rst index d34001e038dc..774daaab3bad 100644 --- a/Documentation/userspace-api/media/dvb/audio-fopen.rst +++ b/Documentation/userspace-api/media/dvb/audio-fopen.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _audio_fopen: @@ -17,8 +18,6 @@ Synopsis -------- .. c:function:: int open(const char *deviceName, int flags) - :name: dvb-audio-open - Arguments --------- @@ -27,7 +26,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - const char \*deviceName @@ -60,7 +58,6 @@ Arguments - - (blocking mode is the default) - Description ----------- @@ -78,7 +75,6 @@ fail, and an error code will be returned. If the Audio Device is opened in O_RDONLY mode, the only ioctl call that can be used is AUDIO_GET_STATUS. All other call will return with an error code. - Return Value ------------ @@ -88,7 +84,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` diff --git a/Documentation/userspace-api/media/dvb/audio-fwrite.rst b/Documentation/userspace-api/media/dvb/audio-fwrite.rst index d17ec719e231..7b096ac2b6c4 100644 --- a/Documentation/userspace-api/media/dvb/audio-fwrite.rst +++ b/Documentation/userspace-api/media/dvb/audio-fwrite.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _audio_fwrite: @@ -17,8 +18,6 @@ Synopsis -------- .. c:function:: size_t write(int fd, const void *buf, size_t count) - :name: dvb-audio-write - Arguments --------- @@ -27,7 +26,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +44,6 @@ Arguments - Size of buf. - Description ----------- @@ -56,7 +53,6 @@ PES format. If O_NONBLOCK is not specified the function will block until buffer space is available. The amount of data to be transferred is implied by count. - Return Value ------------ @@ -64,7 +60,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EPERM`` diff --git a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst b/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst index 33907e40e48c..6d9eb71dad17 100644 --- a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst +++ b/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_GET_CAPABILITIES: @@ -16,9 +17,9 @@ AUDIO_GET_CAPABILITIES Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap) - :name: AUDIO_GET_CAPABILITIES +.. c:macro:: AUDIO_GET_CAPABILITIES +``int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -40,14 +40,12 @@ Arguments - Returns a bit array of supported sound formats. - Description ----------- This ioctl call asks the Audio Device to tell us about the decoding capabilities of the audio hardware. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-get-status.rst b/Documentation/userspace-api/media/dvb/audio-get-status.rst index 4213d076c6ed..7ae8db2e65e9 100644 --- a/Documentation/userspace-api/media/dvb/audio-get-status.rst +++ b/Documentation/userspace-api/media/dvb/audio-get-status.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_GET_STATUS: @@ -16,9 +17,9 @@ AUDIO_GET_STATUS Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status) - :name: AUDIO_GET_STATUS +.. c:macro:: AUDIO_GET_STATUS +``int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -40,14 +40,12 @@ Arguments - Returns the current state of Audio Device. - Description ----------- This ioctl call asks the Audio Device to return the current state of the Audio Device. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-pause.rst b/Documentation/userspace-api/media/dvb/audio-pause.rst index 2de74f1662cf..d37d1ddce4df 100644 --- a/Documentation/userspace-api/media/dvb/audio-pause.rst +++ b/Documentation/userspace-api/media/dvb/audio-pause.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_PAUSE: @@ -16,8 +17,9 @@ AUDIO_PAUSE Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_PAUSE) - :name: AUDIO_PAUSE +.. c:macro:: AUDIO_PAUSE + +``int ioctl(int fd, AUDIO_PAUSE)`` Arguments --------- @@ -26,14 +28,12 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd - File descriptor returned by a previous call to open(). - Description ----------- @@ -41,7 +41,6 @@ This ioctl call suspends the audio stream being played. Decoding and playing are paused. It is then possible to restart again decoding and playing process of the audio stream using AUDIO_CONTINUE command. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-play.rst b/Documentation/userspace-api/media/dvb/audio-play.rst index d4e4eacb8686..e591930b6ca7 100644 --- a/Documentation/userspace-api/media/dvb/audio-play.rst +++ b/Documentation/userspace-api/media/dvb/audio-play.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_PLAY: @@ -16,9 +17,9 @@ AUDIO_PLAY Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_PLAY) - :name: AUDIO_PLAY +.. c:macro:: AUDIO_PLAY +``int ioctl(int fd, AUDIO_PLAY)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,7 +40,6 @@ Description This ioctl call asks the Audio Device to start playing an audio stream from the selected source. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-select-source.rst b/Documentation/userspace-api/media/dvb/audio-select-source.rst index fb09f914cb8f..6a0c0f365eb1 100644 --- a/Documentation/userspace-api/media/dvb/audio-select-source.rst +++ b/Documentation/userspace-api/media/dvb/audio-select-source.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SELECT_SOURCE: @@ -16,9 +17,9 @@ AUDIO_SELECT_SOURCE Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source) - :name: AUDIO_SELECT_SOURCE +.. c:macro:: AUDIO_SELECT_SOURCE +``int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -40,7 +40,6 @@ Arguments - Indicates the source that shall be used for the Audio stream. - Description ----------- @@ -49,7 +48,6 @@ the input data. The possible sources are demux or memory. If AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device through the write command. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst b/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst index 5bcb9b1ed19d..85a8016bf025 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_AV_SYNC: @@ -16,9 +17,9 @@ AUDIO_SET_AV_SYNC Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state) - :name: AUDIO_SET_AV_SYNC +.. c:macro:: AUDIO_SET_AV_SYNC +``int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -44,14 +44,12 @@ Arguments FALSE: AV-sync OFF - Description ----------- This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst b/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst index f24a18bbb567..ecac02f1b2fc 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_BYPASS_MODE: @@ -16,8 +17,9 @@ AUDIO_SET_BYPASS_MODE Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode) - :name: AUDIO_SET_BYPASS_MODE +.. c:macro:: AUDIO_SET_BYPASS_MODE + +``int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode)`` Arguments --------- @@ -26,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -44,7 +45,6 @@ Arguments FALSE: Bypass is enabled - Description ----------- @@ -54,7 +54,6 @@ that can’t be handled by the Digital TV system shall be decoded. Dolby DigitalTM streams are automatically forwarded by the Digital TV subsystem if the hardware can handle it. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-id.rst b/Documentation/userspace-api/media/dvb/audio-set-id.rst index 0227e1071d0c..39ad846d412d 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-id.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-id.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_ID: @@ -16,8 +17,9 @@ AUDIO_SET_ID Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id) - :name: AUDIO_SET_ID +.. c:macro:: AUDIO_SET_ID + +``int ioctl(int fd, AUDIO_SET_ID, int id)`` Arguments --------- @@ -26,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -39,7 +40,6 @@ Arguments - audio sub-stream id - Description ----------- @@ -51,7 +51,6 @@ other stream types. If the stream type is set the id just specifies the substream id of the audio stream and only the first 5 bits are recognized. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst b/Documentation/userspace-api/media/dvb/audio-set-mixer.rst index 58f18cf8240d..45dbdf4801e0 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-mixer.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_MIXER: @@ -16,8 +17,9 @@ AUDIO_SET_MIXER Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix) - :name: AUDIO_SET_MIXER +.. c:macro:: AUDIO_SET_MIXER + +``int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix)`` Arguments --------- @@ -26,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -39,13 +40,11 @@ Arguments - mixer settings. - Description ----------- This ioctl lets you adjust the mixer settings of the audio decoder. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-mute.rst b/Documentation/userspace-api/media/dvb/audio-set-mute.rst index 7ea7d8663e6b..987751f92967 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-mute.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-mute.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_MUTE: @@ -16,9 +17,9 @@ AUDIO_SET_MUTE Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state) - :name: AUDIO_SET_MUTE +.. c:macro:: AUDIO_SET_MUTE +``int ioctl(int fd, AUDIO_SET_MUTE, boolean state)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -44,7 +44,6 @@ Arguments FALSE: Audio Un-mute - Description ----------- @@ -55,7 +54,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` with the This ioctl call asks the audio device to mute the stream that is currently being played. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst b/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst index d9f4924afdbe..77d73c74882f 100644 --- a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst +++ b/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_SET_STREAMTYPE: @@ -16,9 +17,9 @@ AUDIO_SET_STREAMTYPE Synopsis -------- -.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type) - :name: AUDIO_SET_STREAMTYPE +.. c:macro:: AUDIO_SET_STREAMTYPE +``int ioctl(fd, AUDIO_SET_STREAMTYPE, int type)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - - int fd @@ -40,7 +40,6 @@ Arguments - stream type - Description ----------- @@ -48,7 +47,6 @@ This ioctl tells the driver which kind of audio stream to expect. This is useful if the stream offers several audio sub-streams like LPCM and AC3. - Return Value ------------ @@ -57,12 +55,10 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` diff --git a/Documentation/userspace-api/media/dvb/audio-stop.rst b/Documentation/userspace-api/media/dvb/audio-stop.rst index 3a2bc328626d..d77f786fd797 100644 --- a/Documentation/userspace-api/media/dvb/audio-stop.rst +++ b/Documentation/userspace-api/media/dvb/audio-stop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.audio .. _AUDIO_STOP: @@ -16,8 +17,9 @@ AUDIO_STOP Synopsis -------- -.. c:function:: int ioctl(int fd, AUDIO_STOP) - :name: AUDIO_STOP +.. c:macro:: AUDIO_STOP + +``int ioctl(int fd, AUDIO_STOP)`` Arguments --------- @@ -26,21 +28,18 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd - File descriptor returned by a previous call to open(). - Description ----------- This ioctl call asks the Audio Device to stop playing the current stream. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-fclose.rst b/Documentation/userspace-api/media/dvb/ca-fclose.rst index 00379ee7e9ed..27f217a350e7 100644 --- a/Documentation/userspace-api/media/dvb/ca-fclose.rst +++ b/Documentation/userspace-api/media/dvb/ca-fclose.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _ca_fclose: @@ -11,26 +12,22 @@ Name Digital TV CA close() - Synopsis -------- .. c:function:: int close(int fd) - :name: dvb-ca-close - Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. Description ----------- This system call closes a previously opened CA device. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-fopen.rst b/Documentation/userspace-api/media/dvb/ca-fopen.rst index 9ca4bd1d8d5f..7f99908fff2c 100644 --- a/Documentation/userspace-api/media/dvb/ca-fopen.rst +++ b/Documentation/userspace-api/media/dvb/ca-fopen.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _ca_fopen: @@ -11,13 +12,10 @@ Name Digital TV CA open() - Synopsis -------- .. c:function:: int open(const char *name, int flags) - :name: dvb-ca-open - Arguments --------- @@ -45,7 +43,6 @@ Arguments - open in non-blocking mode (blocking mode is the default) - Description ----------- @@ -63,11 +60,9 @@ Only one user can open the CA Device in ``O_RDWR`` mode. All other attempts to open the device in this mode will fail, and an error code will be returned. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/ca-get-cap.rst b/Documentation/userspace-api/media/dvb/ca-get-cap.rst index 93742a5d941d..9b29513eeda8 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-cap.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-cap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_CAP: @@ -11,19 +12,18 @@ Name CA_GET_CAP - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps) - :name: CA_GET_CAP +.. c:macro:: CA_GET_CAP +``int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``caps`` Pointer to struct :c:type:`ca_caps`. diff --git a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst index be7dec053685..0cfdcdab33a8 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_DESCR_INFO: @@ -11,18 +12,18 @@ Name CA_GET_DESCR_INFO - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc) - :name: CA_GET_DESCR_INFO +.. c:macro:: CA_GET_DESCR_INFO + +``int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``desc`` Pointer to struct :c:type:`ca_descr_info`. diff --git a/Documentation/userspace-api/media/dvb/ca-get-msg.rst b/Documentation/userspace-api/media/dvb/ca-get-msg.rst index e8802b4c5fa1..7c9a8d197343 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-msg.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-msg.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_MSG: @@ -11,19 +12,18 @@ Name CA_GET_MSG - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg) - :name: CA_GET_MSG +.. c:macro:: CA_GET_MSG +``int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_msg`. @@ -38,11 +38,9 @@ Receives a message via a CI CA module. Please notice that, on most drivers, this is done by reading from the /dev/adapter?/ca? device node. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst index d283df335914..582444af7003 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_SLOT_INFO: @@ -11,19 +12,18 @@ Name CA_GET_SLOT_INFO - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info) - :name: CA_GET_SLOT_INFO +.. c:macro:: CA_GET_SLOT_INFO +``int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``info`` Pointer to struct :c:type:`ca_slot_info`. @@ -34,7 +34,6 @@ Description Returns information about a CA slot identified by :c:type:`ca_slot_info`.slot_num. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-reset.rst b/Documentation/userspace-api/media/dvb/ca-reset.rst index fc49ef2ffcdb..b01ca48f0b50 100644 --- a/Documentation/userspace-api/media/dvb/ca-reset.rst +++ b/Documentation/userspace-api/media/dvb/ca-reset.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_RESET: @@ -11,19 +12,18 @@ Name CA_RESET - Synopsis -------- -.. c:function:: int ioctl(fd, CA_RESET) - :name: CA_RESET +.. c:macro:: CA_RESET +``int ioctl(fd, CA_RESET)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. Description ----------- @@ -31,7 +31,6 @@ Description Puts the Conditional Access hardware on its initial state. It should be called before start using the CA hardware. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-send-msg.rst b/Documentation/userspace-api/media/dvb/ca-send-msg.rst index cf423fe881b8..7dd2ab4ef675 100644 --- a/Documentation/userspace-api/media/dvb/ca-send-msg.rst +++ b/Documentation/userspace-api/media/dvb/ca-send-msg.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_SEND_MSG: @@ -11,24 +12,22 @@ Name CA_SEND_MSG - Synopsis -------- -.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg) - :name: CA_SEND_MSG +.. c:macro:: CA_SEND_MSG +``int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_msg`. - Description ----------- diff --git a/Documentation/userspace-api/media/dvb/ca-set-descr.rst b/Documentation/userspace-api/media/dvb/ca-set-descr.rst index a5c628a4d3cd..a740af34c872 100644 --- a/Documentation/userspace-api/media/dvb/ca-set-descr.rst +++ b/Documentation/userspace-api/media/dvb/ca-set-descr.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_SET_DESCR: @@ -11,19 +12,18 @@ Name CA_SET_DESCR - Synopsis -------- -.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc) - :name: CA_SET_DESCR +.. c:macro:: CA_SET_DESCR +``int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_descr`. diff --git a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst index 3f08ecd88b0c..ea0c7dd91e05 100644 --- a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst +++ b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_ADD_PID: @@ -11,24 +12,22 @@ Name DMX_ADD_PID - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid) - :name: DMX_ADD_PID +.. c:macro:: DMX_ADD_PID +``int ioctl(fd, DMX_ADD_PID, __u16 *pid)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pid`` PID number to be filtered. - Description ----------- @@ -36,7 +35,6 @@ This ioctl call allows to add multiple PIDs to a transport stream filter previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst index cde2b78a35fa..5cdc2035e3b7 100644 --- a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_EXPBUF: @@ -13,24 +14,22 @@ DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) - :name: DMX_EXPBUF +.. c:macro:: DMX_EXPBUF +``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_exportbuffer`. - Description =========== @@ -54,11 +53,9 @@ driver, on success. This is a DMABUF file descriptor. The application may pass it to other DMABUF-aware devices. It is recommended to close a DMABUF file when it is no longer used to allow the associated memory to be reclaimed. - Examples ======== - .. code-block:: c int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) diff --git a/Documentation/userspace-api/media/dvb/dmx-fclose.rst b/Documentation/userspace-api/media/dvb/dmx-fclose.rst index af036792f13d..719ac1d4f686 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fclose.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fclose.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fclose: @@ -11,27 +12,23 @@ Name Digital TV demux close() - Synopsis -------- .. c:function:: int close(int fd) - :name: dvb-dmx-close - Arguments --------- ``fd`` File descriptor returned by a previous call to - :c:func:`open() <dvb-dmx-open>`. + :c:func:`open()`. Description ----------- This system call deactivates and deallocates a filter that was -previously allocated via the :c:func:`open() <dvb-dmx-open>` call. - +previously allocated via the :c:func:`open()` call. Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-fopen.rst b/Documentation/userspace-api/media/dvb/dmx-fopen.rst index 7117c9bc4325..8f0a2b831d4a 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fopen.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fopen.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fopen: @@ -11,12 +12,10 @@ Name Digital TV demux open() - Synopsis -------- .. c:function:: int open(const char *deviceName, int flags) - :name: dvb-dmx-open Arguments --------- @@ -47,7 +46,6 @@ Arguments - open in non-blocking mode (blocking mode is the default) - Description ----------- @@ -68,7 +66,6 @@ affect the semantics of the ``open()`` call itself. A device opened in blocking mode can later be put into non-blocking mode (and vice versa) using the ``F_SETFL`` command of the fcntl system call. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-fread.rst b/Documentation/userspace-api/media/dvb/dmx-fread.rst index c708a240abae..78e9daef595a 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fread.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fread.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fread: @@ -11,18 +12,16 @@ Name Digital TV demux read() - Synopsis -------- .. c:function:: size_t read(int fd, void *buf, size_t count) - :name: dvb-dmx-read Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``buf`` Buffer to be filled @@ -44,7 +43,6 @@ to be transferred is implied by count. :c:type:`DMX_CHECK_CRC <dmx_sct_filter_params>` flag set, data that fails on CRC check will be silently ignored. - Return Value ------------ @@ -75,6 +73,5 @@ appropriately. - The driver failed to write to the callers buffer due to an invalid \*buf pointer. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst index bef565a35c59..e11ee0ba84a5 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fwrite: @@ -11,18 +12,16 @@ Name Digital TV demux write() - Synopsis -------- .. c:function:: ssize_t write(int fd, const void *buf, size_t count) - :name: dvb-dmx-write Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``buf`` Buffer with data to be written @@ -40,7 +39,6 @@ digitally recorded Transport Stream. Matching filters have to be defined in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. The amount of data to be transferred is implied by count. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst index e92d94d93b18..4f5f0505c0d5 100644 --- a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst +++ b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_GET_PES_PIDS: @@ -11,23 +12,22 @@ Name DMX_GET_PES_PIDS - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5]) - :name: DMX_GET_PES_PIDS +.. c:macro:: DMX_GET_PES_PIDS + +``int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pids`` Array used to store 5 Program IDs. - Description ----------- @@ -45,13 +45,11 @@ pids[DMX_PES_SUBTITLE] 3 first subtitle PID pids[DMX_PES_PCR] 4 first Program Clock Reference PID ======================= ======== ======================================= - .. note:: A value equal to 0xffff means that the PID was not filled by the Kernel. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst index 3762efcf1355..6ada74f6eb18 100644 --- a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst +++ b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_GET_STC: @@ -11,23 +12,22 @@ Name DMX_GET_STC - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc) - :name: DMX_GET_STC +.. c:macro:: DMX_GET_STC + +``int ioctl(int fd, DMX_GET_STC, struct dmx_stc *stc)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``stc`` Pointer to :c:type:`dmx_stc` where the stc data is to be stored. - Description ----------- @@ -39,7 +39,6 @@ The result is returned in form of a ratio with a 64 bit numerator and a 32 bit denominator, so the real 90kHz STC value is ``stc->stc / stc->base``. - Return Value ------------ @@ -61,6 +60,5 @@ appropriately. - Invalid stc number. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-mmap.rst b/Documentation/userspace-api/media/dvb/dmx-mmap.rst index efa9b04be700..8826c6226fb0 100644 --- a/Documentation/userspace-api/media/dvb/dmx-mmap.rst +++ b/Documentation/userspace-api/media/dvb/dmx-mmap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx-mmap: @@ -21,9 +22,7 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: dmx-mmap Arguments ========= @@ -54,7 +53,7 @@ Arguments ``MAP_FIXED`` requests that the driver selects no other address than the one specified. If the specified address cannot be used, - :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, ``start`` must be a multiple of the pagesize. Use of this option is discouraged. @@ -69,17 +68,16 @@ Arguments flags. ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``offset`` Offset of the buffer in device memory, as returned by :ref:`DMX_QUERYBUF` ioctl. - Description =========== -The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at +The :c:func:`mmap()` function asks to map ``length`` bytes starting at ``offset`` in the memory of the device specified by ``fd`` into the application address space, preferably at address ``start``. This latter address is a hint only, and is usually specified as 0. @@ -88,13 +86,12 @@ Suitable length and offset parameters are queried with the :ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the :ref:`DMX_REQBUFS` ioctl before they can be queried. -To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used. - +To unmap buffers the :c:func:`munmap()` function is used. Return Value ============ -On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/dvb/dmx-munmap.rst b/Documentation/userspace-api/media/dvb/dmx-munmap.rst index 308a9593919c..66bbc11e5c40 100644 --- a/Documentation/userspace-api/media/dvb/dmx-munmap.rst +++ b/Documentation/userspace-api/media/dvb/dmx-munmap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx-munmap: @@ -13,7 +14,6 @@ dmx-munmap - Unmap device memory .. warning:: This API is still experimental. - Synopsis ======== @@ -22,33 +22,29 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: int munmap( void *start, size_t length ) - :name: dmx-munmap Arguments ========= ``start`` Address of the mapped buffer as returned by the - :ref:`mmap() <dmx-mmap>` function. + :c:func:`mmap()` function. ``length`` Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() <dmx-mmap>`. - + :c:func:`mmap()`. Description =========== -Unmaps a previously with the :ref:`mmap() <dmx-mmap>` function mapped +Unmaps a previously with the :c:func:`mmap()` function mapped buffer and frees it, if possible. - Return Value ============ -On success :ref:`munmap() <dmx-munmap>` returns 0, on failure -1 and the +On success :c:func:`munmap()` returns 0, on failure -1 and the ``errno`` variable is set appropriately: EINVAL diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst index fcb1c55dd49a..17e70143c1b0 100644 --- a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_QBUF: @@ -13,27 +14,26 @@ DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) - :name: DMX_QBUF +.. c:macro:: DMX_QBUF + +``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` -.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) - :name: DMX_DQBUF +.. c:macro:: DMX_DQBUF +``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_buffer`. - Description =========== @@ -60,13 +60,12 @@ the driver fills the remaining fields or returns an error code. By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns +:c:func:`open()` function, ``DMX_DQBUF`` returns immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`dmx_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst index df13e2b053c9..08ee9853d6b4 100644 --- a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_QUERYBUF: @@ -13,24 +14,22 @@ DMX_QUERYBUF - Query the status of a buffer .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) - :name: DMX_QUERYBUF +.. c:macro:: DMX_QUERYBUF +``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dvb_buffer`. - Description =========== diff --git a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst index ce408d0d7c77..f75b33e5e49a 100644 --- a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst +++ b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_REMOVE_PID: @@ -11,24 +12,22 @@ Name DMX_REMOVE_PID - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid) - :name: DMX_REMOVE_PID +.. c:macro:: DMX_REMOVE_PID +``int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pid`` PID of the PES filter to be removed. - Description ----------- @@ -37,7 +36,6 @@ transport stream filter, e. g. a filter previously set up with output equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`, created via either :ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst index 433aed632f92..d2bb1909ec98 100644 --- a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst +++ b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_REQBUFS: @@ -13,19 +14,18 @@ DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) - :name: DMX_REQBUFS +.. c:macro:: DMX_REQBUFS +``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_requestbuffers`. @@ -64,7 +64,6 @@ buffers, however this cannot succeed when any buffers are still mapped. A ``count`` value of zero frees all buffers, after aborting or finishing any DMA in progress. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst index e803cbab220b..13ce4092c2d2 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_BUFFER_SIZE: @@ -11,19 +12,18 @@ Name DMX_SET_BUFFER_SIZE - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size) - :name: DMX_SET_BUFFER_SIZE +.. c:macro:: DMX_SET_BUFFER_SIZE +``int ioctl(int fd, DMX_SET_BUFFER_SIZE, unsigned long size)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``size`` Unsigned long size @@ -36,11 +36,9 @@ filtered data. The default size is two maximum sized sections, i.e. if this function is not called a buffer size of ``2 * 4096`` bytes will be used. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst index 4cd3db512b4e..f43455b7adae 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_FILTER: @@ -11,24 +12,23 @@ Name DMX_SET_FILTER - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params) - :name: DMX_SET_FILTER +.. c:macro:: DMX_SET_FILTER + +``int ioctl(int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``params`` Pointer to structure containing filter parameters. - Description ----------- @@ -43,11 +43,9 @@ operation should be started immediately (without waiting for a :ref:`DMX_START` ioctl call). If a filter was previously set-up, this filter will be canceled, and the receive buffer will be flushed. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst index 8e54fd2636ed..5bb682e4a88f 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_PES_FILTER: @@ -11,25 +12,22 @@ Name DMX_SET_PES_FILTER - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params) - :name: DMX_SET_PES_FILTER +.. c:macro:: DMX_SET_PES_FILTER +``int ioctl(int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)`` Arguments --------- - ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``params`` Pointer to structure containing filter parameters. - Description ----------- @@ -38,7 +36,6 @@ provided. By a PES filter is meant a filter that is based just on the packet identifier (PID), i.e. no PES header or payload filtering capability is supported. - Return Value ------------ @@ -54,7 +51,6 @@ appropriately. :stub-columns: 0 :widths: 1 16 - - .. row 1 - ``EBUSY`` @@ -64,6 +60,5 @@ appropriately. Make sure that these filters are stopped before starting this filter. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-start.rst b/Documentation/userspace-api/media/dvb/dmx-start.rst index 6f1413e13936..aedccf952a14 100644 --- a/Documentation/userspace-api/media/dvb/dmx-start.rst +++ b/Documentation/userspace-api/media/dvb/dmx-start.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_START: @@ -11,19 +12,18 @@ Name DMX_START - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_START) - :name: DMX_START +.. c:macro:: DMX_START +``int ioctl(int fd, DMX_START)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. Description ----------- @@ -31,7 +31,6 @@ Description This ioctl call is used to start the actual filtering operation defined via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. - Return Value ------------ @@ -46,7 +45,6 @@ appropriately. :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` @@ -63,6 +61,5 @@ appropriately. Make sure that these filters are stopped before starting this filter. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-stop.rst b/Documentation/userspace-api/media/dvb/dmx-stop.rst index cbc3956fd71d..8661e6772104 100644 --- a/Documentation/userspace-api/media/dvb/dmx-stop.rst +++ b/Documentation/userspace-api/media/dvb/dmx-stop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_STOP: @@ -11,19 +12,18 @@ Name DMX_STOP - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_STOP) - :name: DMX_STOP +.. c:macro:: DMX_STOP +``int ioctl(int fd, DMX_STOP)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. Description ----------- @@ -32,7 +32,6 @@ This ioctl call is used to stop the actual filtering operation defined via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and started via the :ref:`DMX_START` command. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst index 115cced97e66..d9be817f0390 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_RECV_SLAVE_REPLY: @@ -11,24 +12,22 @@ Name FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp ) - :name: FE_DISEQC_RECV_SLAVE_REPLY +.. c:macro:: FE_DISEQC_RECV_SLAVE_REPLY +``int ioctl(int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`dvb_diseqc_slave_reply`. - Description =========== diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst index 5ffc34a6496e..d36f7d1157c6 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_RESET_OVERLOAD: @@ -11,19 +12,18 @@ Name FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL ) - :name: FE_DISEQC_RESET_OVERLOAD +.. c:macro:: FE_DISEQC_RESET_OVERLOAD +``int ioctl(int fd, FE_DISEQC_RESET_OVERLOAD, NULL)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. Description =========== @@ -33,7 +33,6 @@ this ioctl call restores the power to the bus. The call requires read/write access to the device. This call has no effect if the device is manually powered off. Not all Digital TV adapters support this ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst index fd59afe814f3..8fb73ee29951 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_SEND_BURST: @@ -11,24 +12,22 @@ Name FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone ) - :name: FE_DISEQC_SEND_BURST +.. c:macro:: FE_DISEQC_SEND_BURST +``int ioctl(int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``tone`` An integer enumered value described at :c:type:`fe_sec_mini_cmd`. - Description =========== @@ -39,7 +38,6 @@ read/write permissions. It provides support for what's specified at `Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__ - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst index faa2a8364e10..c97029def2ee 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_SEND_MASTER_CMD: @@ -11,25 +12,23 @@ Name FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp ) - :name: FE_DISEQC_SEND_MASTER_CMD +.. c:macro:: FE_DISEQC_SEND_MASTER_CMD +``int ioctl(int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`dvb_diseqc_master_cmd` - Description =========== diff --git a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst index 60d69bb6da71..d1dba74c55a9 100644 --- a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISHNETWORK_SEND_LEGACY_CMD: @@ -11,24 +12,22 @@ Name FE_DISHNETWORK_SEND_LEGACY_CMD - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd) - :name: FE_DISHNETWORK_SEND_LEGACY_CMD +.. c:macro:: FE_DISHNETWORK_SEND_LEGACY_CMD +``int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``cmd`` Sends the specified raw cmd to the dish via DISEqC. - Description =========== @@ -42,7 +41,6 @@ frontend, for Dish Network legacy switches. As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst index df0cc91384d9..40d7320f82f7 100644 --- a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst +++ b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_ENABLE_HIGH_LNB_VOLTAGE: @@ -11,19 +12,18 @@ Name FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high ) - :name: FE_ENABLE_HIGH_LNB_VOLTAGE +.. c:macro:: FE_ENABLE_HIGH_LNB_VOLTAGE +``int ioctl(int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``high`` Valid flags: @@ -33,7 +33,6 @@ Arguments - >0 - enables slightly higher voltages instead of 13/18V, in order to compensate for long antenna cables. - Description =========== @@ -41,7 +40,6 @@ Select output DC level between normal LNBf voltages or higher LNBf voltages between 0 (normal) or a value grater than 0 for higher voltages. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-get-event.rst b/Documentation/userspace-api/media/dvb/fe-get-event.rst index 723bb3a4a630..f63029eca90e 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-event.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-event.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_EVENT: @@ -13,24 +14,22 @@ FE_GET_EVENT .. attention:: This ioctl is deprecated. - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev) - :name: FE_GET_EVENT +.. c:macro:: FE_GET_EVENT +``int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ev`` Points to the location where the event, if any, is to be stored. - Description =========== @@ -40,7 +39,6 @@ or non-blocking mode. In the latter case, the call fails immediately with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until an event becomes available. - Return Value ============ @@ -49,12 +47,10 @@ On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set appropriately. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EWOULDBLOCK`` diff --git a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst index 2bfc1f1a3dc5..40700533e7e7 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_FRONTEND: @@ -13,32 +14,28 @@ FE_GET_FRONTEND .. attention:: This ioctl is deprecated. - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_GET_FRONTEND +.. c:macro:: FE_GET_FRONTEND +``int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. - + File descriptor returned by :c:func:`open()`. ``p`` Points to parameters for tuning operation. - Description =========== This ioctl call queries the currently effective frontend parameters. For this command, read-only access to the device is sufficient. - Return Value ============ @@ -51,7 +48,6 @@ appropriately. :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst index eba115c03471..2e5f0209846f 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-info.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_INFO: @@ -12,24 +13,22 @@ Name FE_GET_INFO - Query Digital TV frontend capabilities and returns information about the - front-end. This call only requires read-only access to the device. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp ) - :name: FE_GET_INFO +.. c:macro:: FE_GET_INFO +``int ioctl(int fd, FE_GET_INFO, struct dvb_frontend_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`dvb_frontend_info` - Description =========== @@ -40,7 +39,6 @@ takes a pointer to dvb_frontend_info which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an error. - frontend capabilities ===================== @@ -49,7 +47,6 @@ supported only on some specific frontend types. The frontend capabilities are described at :c:type:`fe_caps`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-get-property.rst b/Documentation/userspace-api/media/dvb/fe-get-property.rst index 10e1db172d8a..29363dc4a0c3 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-property.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-property.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_PROPERTY: @@ -11,27 +12,26 @@ Name FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp ) - :name: FE_GET_PROPERTY +.. c:macro:: FE_GET_PROPERTY + +``int ioctl(int fd, FE_GET_PROPERTY, struct dtv_properties *argp)`` -.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp ) - :name: FE_SET_PROPERTY +.. c:macro:: FE_SET_PROPERTY +``int ioctl(int fd, FE_SET_PROPERTY, struct dtv_properties *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dtv_properties`. - Description =========== @@ -63,7 +63,6 @@ depends on the delivery system and on the device: - This call only requires read-only access to the device. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-ber.rst b/Documentation/userspace-api/media/dvb/fe-read-ber.rst index 2200eb1d06f9..f33f1dd20501 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-ber.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-ber.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_BER: @@ -16,20 +17,19 @@ FE_READ_BER Synopsis ======== -.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber) - :name: FE_READ_BER +.. c:macro:: FE_READ_BER +``int ioctl(int fd, FE_READ_BER, uint32_t *ber)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ber`` The bit error rate is stored into \*ber. - Description =========== @@ -37,7 +37,6 @@ This ioctl call returns the bit error rate for the signal currently received/demodulated by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst index 4832efad2a2e..2b7d06145cb1 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_SIGNAL_STRENGTH: @@ -16,20 +17,19 @@ FE_READ_SIGNAL_STRENGTH Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength) - :name: FE_READ_SIGNAL_STRENGTH +.. c:macro:: FE_READ_SIGNAL_STRENGTH +``int ioctl(int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``strength`` The signal strength value is stored into \*strength. - Description =========== @@ -37,7 +37,6 @@ This ioctl call returns the signal strength value for the signal currently received by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-snr.rst b/Documentation/userspace-api/media/dvb/fe-read-snr.rst index 141e4fc661c2..e44e559ab7e8 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-snr.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-snr.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_SNR: @@ -16,20 +17,19 @@ FE_READ_SNR Synopsis ======== -.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr) - :name: FE_READ_SNR +.. c:macro:: FE_READ_SNR +``int ioctl(int fd, FE_READ_SNR, int16_t *snr)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``snr`` The signal-to-noise ratio is stored into \*snr. - Description =========== @@ -37,7 +37,6 @@ This ioctl call returns the signal-to-noise ratio for the signal currently received by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-status.rst b/Documentation/userspace-api/media/dvb/fe-read-status.rst index ba61feb5e535..75c6ee60ac9c 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-status.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-status.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_STATUS: @@ -11,25 +12,23 @@ Name FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_STATUS, unsigned int *status ) - :name: FE_READ_STATUS +.. c:macro:: FE_READ_STATUS +``int ioctl(int fd, FE_READ_STATUS, unsigned int *status)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``status`` pointer to a bitmask integer filled with the values defined by enum :c:type:`fe_status`. - Description =========== @@ -44,7 +43,6 @@ written. varies according with the architecture. This needs to be fixed in the future. - int fe_status ============= @@ -52,7 +50,6 @@ The fe_status parameter is used to indicate the current state and/or state changes of the frontend hardware. It is produced using the enum :c:type:`fe_status` values on a bitmask - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst index bf9746f8a671..653cd99a66f5 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_UNCORRECTED_BLOCKS: @@ -16,20 +17,19 @@ FE_READ_UNCORRECTED_BLOCKS Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks) - :name: FE_READ_UNCORRECTED_BLOCKS +.. c:macro:: FE_READ_UNCORRECTED_BLOCKS +``int ioctl(int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ublocks`` The total number of uncorrected blocks seen by the driver so far. - Description =========== @@ -39,7 +39,6 @@ increment in block count during a specific time interval should be calculated. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst index f0e178e3a180..56923c1a66b0 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_FRONTEND_TUNE_MODE: @@ -11,19 +12,18 @@ Name FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags ) - :name: FE_SET_FRONTEND_TUNE_MODE +.. c:macro:: FE_SET_FRONTEND_TUNE_MODE +``int ioctl(int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``flags`` Valid flags: @@ -37,14 +37,12 @@ Arguments is closed, this flag will be automatically turned off when the device is reopened read-write. - Description =========== Allow setting tuner mode flags to the frontend, between 0 (normal) or ``FE_TUNE_MODE_ONESHOT`` mode - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst index 2b169778e0d6..d1b857632059 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_FRONTEND: @@ -13,24 +14,22 @@ Name FE_SET_FRONTEND - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_SET_FRONTEND +.. c:macro:: FE_SET_FRONTEND +``int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``p`` Points to parameters for tuning operation. - Description =========== @@ -44,7 +43,6 @@ operation is initiated before the previous one was completed, the previous operation will be aborted in favor of the new one. This command requires read/write access to the device. - Return Value ============ @@ -66,6 +64,5 @@ appropriately. - Maximum supported symbol rate reached. - Generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-tone.rst b/Documentation/userspace-api/media/dvb/fe-set-tone.rst index 944d54488e71..9f44bf946183 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-tone.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-tone.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_TONE: @@ -11,24 +12,22 @@ Name FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone ) - :name: FE_SET_TONE +.. c:macro:: FE_SET_TONE +``int ioctl(int fd, FE_SET_TONE, enum fe_sec_tone_mode tone)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``tone`` an integer enumered value described at :c:type:`fe_sec_tone_mode` - Description =========== @@ -45,7 +44,6 @@ this is done using the DiSEqC ioctls. capability of selecting the band. So, it is recommended that applications would change to SEC_TONE_OFF when the device is not used. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst index 73740be0e7dc..c66771830be1 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_VOLTAGE: @@ -11,24 +12,22 @@ Name FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage ) - :name: FE_SET_VOLTAGE +.. c:macro:: FE_SET_VOLTAGE +``int ioctl(int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``voltage`` an integer enumered value described at :c:type:`fe_sec_voltage` - Description =========== @@ -49,7 +48,6 @@ power up the LNBf. the voltage to SEC_VOLTAGE_OFF while the device is not is used is recommended. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/frontend_f_close.rst b/Documentation/userspace-api/media/dvb/frontend_f_close.rst index 96e15b4ee76d..52c323a85014 100644 --- a/Documentation/userspace-api/media/dvb/frontend_f_close.rst +++ b/Documentation/userspace-api/media/dvb/frontend_f_close.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _frontend_f_close: @@ -11,7 +12,6 @@ Name fe-close - Close a frontend device - Synopsis ======== @@ -19,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: dvb-fe-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -37,7 +34,6 @@ This system call closes a previously opened front-end device. After closing a front-end device, its corresponding hardware might be powered down automatically. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/frontend_f_open.rst b/Documentation/userspace-api/media/dvb/frontend_f_open.rst index 49a01dd58d03..bb37eded0870 100644 --- a/Documentation/userspace-api/media/dvb/frontend_f_open.rst +++ b/Documentation/userspace-api/media/dvb/frontend_f_open.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _frontend_f_open: @@ -11,7 +12,6 @@ Name fe-open - Open a frontend device - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: dvb-fe-open Arguments ========= @@ -44,7 +42,6 @@ Arguments Other flags have no effect. - Description =========== @@ -70,16 +67,14 @@ the specified mode. This implies that the corresponding hardware is powered up, and that other front-ends may have been powered down to make that possible. - Return Value ============ -On success :ref:`open() <frontend_f_open>` returns the new file descriptor. +On success :c:func:`open()` returns the new file descriptor. On error, -1 is returned, and the ``errno`` variable is set appropriately. Possible error codes are: - On success 0 is returned, and :c:type:`ca_slot_info` is filled. On error -1 is returned, and the ``errno`` variable is set @@ -105,6 +100,5 @@ appropriately. - The limit on the total number of files open on the system has been reached. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-add-if.rst b/Documentation/userspace-api/media/dvb/net-add-if.rst index 0859830b645e..022b4c626249 100644 --- a/Documentation/userspace-api/media/dvb/net-add-if.rst +++ b/Documentation/userspace-api/media/dvb/net-add-if.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_ADD_IF: @@ -11,24 +12,22 @@ Name NET_ADD_IF - Creates a new network interface for a given Packet ID. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_ADD_IF, struct dvb_net_if *net_if ) - :name: NET_ADD_IF +.. c:macro:: NET_ADD_IF +``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` pointer to struct :c:type:`dvb_net_if` - Description =========== diff --git a/Documentation/userspace-api/media/dvb/net-get-if.rst b/Documentation/userspace-api/media/dvb/net-get-if.rst index d8c9f939d62c..e99696c9db74 100644 --- a/Documentation/userspace-api/media/dvb/net-get-if.rst +++ b/Documentation/userspace-api/media/dvb/net-get-if.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_GET_IF: @@ -11,24 +12,22 @@ Name NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_GET_IF, struct dvb_net_if *net_if ) - :name: NET_GET_IF +.. c:macro:: NET_GET_IF +``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` pointer to struct :c:type:`dvb_net_if` - Description =========== @@ -39,7 +38,6 @@ encapsulation type used on such interface. If the interface was not created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill the ``errno`` with ``EINVAL`` error code. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/net-remove-if.rst b/Documentation/userspace-api/media/dvb/net-remove-if.rst index ecbcacbaf9f7..ac88691c0423 100644 --- a/Documentation/userspace-api/media/dvb/net-remove-if.rst +++ b/Documentation/userspace-api/media/dvb/net-remove-if.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_REMOVE_IF: @@ -11,31 +12,28 @@ Name NET_REMOVE_IF - Removes a network interface. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_REMOVE_IF, int ifnum ) - :name: NET_REMOVE_IF +.. c:macro:: NET_REMOVE_IF +``int ioctl(int fd, NET_REMOVE_IF, int ifnum)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` number of the interface to be removed - Description =========== The NET_REMOVE_IF ioctl deletes an interface previously created via :ref:`NET_ADD_IF <net>`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst b/Documentation/userspace-api/media/dvb/video-clear-buffer.rst index fa1f2f49bdac..a7730559bbb2 100644 --- a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst +++ b/Documentation/userspace-api/media/dvb/video-clear-buffer.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_CLEAR_BUFFER: @@ -16,9 +17,9 @@ VIDEO_CLEAR_BUFFER Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_CLEAR_BUFFER) - :name: VIDEO_CLEAR_BUFFER +.. c:macro:: VIDEO_CLEAR_BUFFER +``int ioctl(fd, VIDEO_CLEAR_BUFFER)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,14 +40,12 @@ Arguments - Equals VIDEO_CLEAR_BUFFER for this command. - Description ----------- This ioctl call clears all video buffers in the driver and in the decoder hardware. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-command.rst b/Documentation/userspace-api/media/dvb/video-command.rst index ef0da85d5f92..cae9445eb3af 100644 --- a/Documentation/userspace-api/media/dvb/video-command.rst +++ b/Documentation/userspace-api/media/dvb/video-command.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_COMMAND: @@ -16,9 +17,9 @@ VIDEO_COMMAND Synopsis -------- -.. c:function:: int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd) - :name: VIDEO_COMMAND +.. c:macro:: VIDEO_COMMAND +``int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Commands the decoder. - Description ----------- @@ -59,7 +58,7 @@ subset of the ``v4l2_decoder_cmd`` struct, so refer to the :ref:`VIDIOC_DECODER_CMD` documentation for more information. -.. c:type:: struct video_command +.. c:type:: video_command .. code-block:: c @@ -89,7 +88,6 @@ more information. }; }; - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-continue.rst b/Documentation/userspace-api/media/dvb/video-continue.rst index 9a767b50b23b..bc34bf3989e4 100644 --- a/Documentation/userspace-api/media/dvb/video-continue.rst +++ b/Documentation/userspace-api/media/dvb/video-continue.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_CONTINUE: @@ -16,9 +17,9 @@ VIDEO_CONTINUE Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_CONTINUE) - :name: VIDEO_CONTINUE +.. c:macro:: VIDEO_CONTINUE +``int ioctl(fd, VIDEO_CONTINUE)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,7 +40,6 @@ Arguments - Equals VIDEO_CONTINUE for this command. - Description ----------- @@ -50,7 +49,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` instead. This ioctl call restarts decoding and playing processes of the video stream which was played before a call to VIDEO_FREEZE was made. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-fast-forward.rst b/Documentation/userspace-api/media/dvb/video-fast-forward.rst index c43a13c7ae75..e71fa8d6965b 100644 --- a/Documentation/userspace-api/media/dvb/video-fast-forward.rst +++ b/Documentation/userspace-api/media/dvb/video-fast-forward.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_FAST_FORWARD: @@ -16,9 +17,9 @@ VIDEO_FAST_FORWARD Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames) - :name: VIDEO_FAST_FORWARD +.. c:macro:: VIDEO_FAST_FORWARD +``int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - The number of frames to skip. - Description ----------- @@ -54,7 +53,6 @@ This ioctl call asks the Video Device to skip decoding of N number of I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is selected. - Return Value ------------ @@ -63,12 +61,10 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EPERM`` diff --git a/Documentation/userspace-api/media/dvb/video-fclose.rst b/Documentation/userspace-api/media/dvb/video-fclose.rst index 27ccb2d6f961..01d24d548439 100644 --- a/Documentation/userspace-api/media/dvb/video-fclose.rst +++ b/Documentation/userspace-api/media/dvb/video-fclose.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _video_fclose: @@ -18,7 +19,6 @@ Synopsis .. c:function:: int close(int fd) - Arguments --------- @@ -26,20 +26,17 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd - File descriptor returned by a previous call to open(). - Description ----------- This system call closes a previously opened video device. - Return Value ------------ @@ -47,7 +44,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EBADF`` diff --git a/Documentation/userspace-api/media/dvb/video-fopen.rst b/Documentation/userspace-api/media/dvb/video-fopen.rst index aa1dc6020fa7..1371b083e4e8 100644 --- a/Documentation/userspace-api/media/dvb/video-fopen.rst +++ b/Documentation/userspace-api/media/dvb/video-fopen.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _video_fopen: @@ -18,7 +19,6 @@ Synopsis .. c:function:: int open(const char *deviceName, int flags) - Arguments --------- @@ -26,7 +26,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - const char \*deviceName @@ -59,7 +58,6 @@ Arguments - - (blocking mode is the default) - Description ----------- @@ -79,7 +77,6 @@ returned. If the Video Device is opened in O_RDONLY mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other call will return an error code. - Return Value ------------ @@ -89,7 +86,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` diff --git a/Documentation/userspace-api/media/dvb/video-freeze.rst b/Documentation/userspace-api/media/dvb/video-freeze.rst index 93e0ae8e79d8..4321f257cb70 100644 --- a/Documentation/userspace-api/media/dvb/video-freeze.rst +++ b/Documentation/userspace-api/media/dvb/video-freeze.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_FREEZE: @@ -16,9 +17,9 @@ VIDEO_FREEZE Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_FREEZE) - :name: VIDEO_FREEZE +.. c:macro:: VIDEO_FREEZE +``int ioctl(fd, VIDEO_FREEZE)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,7 +40,6 @@ Arguments - Equals VIDEO_FREEZE for this command. - Description ----------- @@ -54,7 +53,6 @@ If VIDEO_SOURCE_MEMORY is selected in the ioctl call VIDEO_SELECT_SOURCE, the Digital TV subsystem will not decode any more data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-fwrite.rst b/Documentation/userspace-api/media/dvb/video-fwrite.rst index 5ccdf78f11e1..a07fd7d7a40e 100644 --- a/Documentation/userspace-api/media/dvb/video-fwrite.rst +++ b/Documentation/userspace-api/media/dvb/video-fwrite.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _video_fwrite: @@ -18,7 +19,6 @@ Synopsis .. c:function:: size_t write(int fd, const void *buf, size_t count) - Arguments --------- @@ -26,7 +26,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -45,7 +44,6 @@ Arguments - Size of buf. - Description ----------- @@ -55,7 +53,6 @@ PES format, unless the capability allows other formats. If O_NONBLOCK is not specified the function will block until buffer space is available. The amount of data to be transferred is implied by count. - Return Value ------------ @@ -63,7 +60,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EPERM`` diff --git a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst b/Documentation/userspace-api/media/dvb/video-get-capabilities.rst index 619f78a66b6c..01e09f56656c 100644 --- a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst +++ b/Documentation/userspace-api/media/dvb/video-get-capabilities.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_CAPABILITIES: @@ -16,9 +17,9 @@ VIDEO_GET_CAPABILITIES Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap) - :name: VIDEO_GET_CAPABILITIES +.. c:macro:: VIDEO_GET_CAPABILITIES +``int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Pointer to a location where to store the capability information. - Description ----------- @@ -54,7 +53,6 @@ This ioctl call asks the video device about its decoding capabilities. On success it returns and integer which has bits set according to the defines in section ??. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-get-event.rst b/Documentation/userspace-api/media/dvb/video-get-event.rst index 29566a245fcd..90382bc36cfe 100644 --- a/Documentation/userspace-api/media/dvb/video-get-event.rst +++ b/Documentation/userspace-api/media/dvb/video-get-event.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_EVENT: @@ -16,9 +17,9 @@ VIDEO_GET_EVENT Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev) - :name: VIDEO_GET_EVENT +.. c:macro:: VIDEO_GET_EVENT +``int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Points to the location where the event, if any, is to be stored. - Description ----------- @@ -93,7 +92,6 @@ appropriately. The generic error codes are described at the :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EWOULDBLOCK`` diff --git a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst b/Documentation/userspace-api/media/dvb/video-get-frame-count.rst index 5f65f8dba184..b48ac8c58a41 100644 --- a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst +++ b/Documentation/userspace-api/media/dvb/video-get-frame-count.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_FRAME_COUNT: @@ -16,9 +17,9 @@ VIDEO_GET_FRAME_COUNT Synopsis -------- -.. c:function:: int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) - :name: VIDEO_GET_FRAME_COUNT +.. c:macro:: VIDEO_GET_FRAME_COUNT +``int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -47,7 +47,6 @@ Arguments - Returns the number of frames displayed since the decoder was started. - Description ----------- @@ -58,7 +57,6 @@ control. This ioctl call asks the Video Device to return the number of displayed frames since the decoder was started. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-get-pts.rst b/Documentation/userspace-api/media/dvb/video-get-pts.rst index 28655a1a9249..fedaff41be0b 100644 --- a/Documentation/userspace-api/media/dvb/video-get-pts.rst +++ b/Documentation/userspace-api/media/dvb/video-get-pts.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_PTS: @@ -16,9 +17,9 @@ VIDEO_GET_PTS Synopsis -------- -.. c:function:: int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts) - :name: VIDEO_GET_PTS +.. c:macro:: VIDEO_GET_PTS +``int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -51,7 +51,6 @@ Arguments but may also be a value close to it like the PTS of the last decoded frame or the last PTS extracted by the PES parser. - Description ----------- @@ -62,7 +61,6 @@ control. This ioctl call asks the Video Device to return the current PTS timestamp. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-get-size.rst b/Documentation/userspace-api/media/dvb/video-get-size.rst index a199afbfc1b1..de34331c5bd1 100644 --- a/Documentation/userspace-api/media/dvb/video-get-size.rst +++ b/Documentation/userspace-api/media/dvb/video-get-size.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_SIZE: @@ -16,9 +17,9 @@ VIDEO_GET_SIZE Synopsis -------- -.. c:function:: int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size) - :name: VIDEO_GET_SIZE +.. c:macro:: VIDEO_GET_SIZE +``int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Returns the size and aspect ratio. - Description ----------- @@ -62,7 +61,6 @@ This ioctl returns the size and aspect ratio. video_format_t aspect_ratio; } video_size_t; - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-get-status.rst b/Documentation/userspace-api/media/dvb/video-get-status.rst index 3f29dac18a21..9b86fbf411d4 100644 --- a/Documentation/userspace-api/media/dvb/video-get-status.rst +++ b/Documentation/userspace-api/media/dvb/video-get-status.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_GET_STATUS: @@ -16,9 +17,9 @@ VIDEO_GET_STATUS Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status) - :name: VIDEO_GET_STATUS +.. c:macro:: VIDEO_GET_STATUS +``int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Returns the current status of the Video Device. - Description ----------- diff --git a/Documentation/userspace-api/media/dvb/video-play.rst b/Documentation/userspace-api/media/dvb/video-play.rst index 71db54d840cb..35ac8b98fdbf 100644 --- a/Documentation/userspace-api/media/dvb/video-play.rst +++ b/Documentation/userspace-api/media/dvb/video-play.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_PLAY: @@ -16,9 +17,9 @@ VIDEO_PLAY Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_PLAY) - :name: VIDEO_PLAY +.. c:macro:: VIDEO_PLAY +``int ioctl(fd, VIDEO_PLAY)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -40,7 +40,6 @@ Arguments - Equals VIDEO_PLAY for this command. - Description ----------- @@ -50,7 +49,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` instead. This ioctl call asks the Video Device to start playing a video stream from the selected source. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-select-source.rst b/Documentation/userspace-api/media/dvb/video-select-source.rst index 2e4ee53fa155..929a20985d53 100644 --- a/Documentation/userspace-api/media/dvb/video-select-source.rst +++ b/Documentation/userspace-api/media/dvb/video-select-source.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SELECT_SOURCE: @@ -16,9 +17,9 @@ VIDEO_SELECT_SOURCE Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) - :name: VIDEO_SELECT_SOURCE +.. c:macro:: VIDEO_SELECT_SOURCE +``int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Indicates which source shall be used for the Video stream. - Description ----------- diff --git a/Documentation/userspace-api/media/dvb/video-set-blank.rst b/Documentation/userspace-api/media/dvb/video-set-blank.rst index 5454fe7905bd..70249a6ba125 100644 --- a/Documentation/userspace-api/media/dvb/video-set-blank.rst +++ b/Documentation/userspace-api/media/dvb/video-set-blank.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SET_BLANK: @@ -16,9 +17,9 @@ VIDEO_SET_BLANK Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode) - :name: VIDEO_SET_BLANK +.. c:macro:: VIDEO_SET_BLANK +``int ioctl(fd, VIDEO_SET_BLANK, boolean mode)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -51,13 +51,11 @@ Arguments - - FALSE: Show last decoded frame. - Description ----------- This ioctl call asks the Video Device to blank out the picture. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-set-display-format.rst b/Documentation/userspace-api/media/dvb/video-set-display-format.rst index ada6113e2f2d..1de4f40ae732 100644 --- a/Documentation/userspace-api/media/dvb/video-set-display-format.rst +++ b/Documentation/userspace-api/media/dvb/video-set-display-format.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SET_DISPLAY_FORMAT: @@ -16,9 +17,9 @@ VIDEO_SET_DISPLAY_FORMAT Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT) - :name: VIDEO_SET_DISPLAY_FORMAT +.. c:macro:: VIDEO_SET_DISPLAY_FORMAT +``int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,14 +46,12 @@ Arguments - Selects the video format to be used. - Description ----------- This ioctl call asks the Video Device to select the video format to be applied by the MPEG chip on the video. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-set-format.rst b/Documentation/userspace-api/media/dvb/video-set-format.rst index 758a5d1642ab..bb64e37ae081 100644 --- a/Documentation/userspace-api/media/dvb/video-set-format.rst +++ b/Documentation/userspace-api/media/dvb/video-set-format.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SET_FORMAT: @@ -16,9 +17,9 @@ VIDEO_SET_FORMAT Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format) - :name: VIDEO_SET_FORMAT +.. c:macro:: VIDEO_SET_FORMAT +``int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - video format of TV as defined in section ??. - Description ----------- @@ -72,12 +71,10 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` diff --git a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst b/Documentation/userspace-api/media/dvb/video-set-streamtype.rst index f3a99858b1db..1f31c048bdbc 100644 --- a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst +++ b/Documentation/userspace-api/media/dvb/video-set-streamtype.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SET_STREAMTYPE: @@ -16,9 +17,9 @@ VIDEO_SET_STREAMTYPE Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SET_STREAMTYPE, int type) - :name: VIDEO_SET_STREAMTYPE +.. c:macro:: VIDEO_SET_STREAMTYPE +``int ioctl(fd, VIDEO_SET_STREAMTYPE, int type)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - stream type - Description ----------- @@ -54,7 +53,6 @@ This ioctl tells the driver which kind of stream to expect being written to it. If this call is not used the default of video PES is used. Some drivers might not support this call and always expect PES. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-slowmotion.rst b/Documentation/userspace-api/media/dvb/video-slowmotion.rst index 2ccb84d6a68b..1478fcc30cb8 100644 --- a/Documentation/userspace-api/media/dvb/video-slowmotion.rst +++ b/Documentation/userspace-api/media/dvb/video-slowmotion.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_SLOWMOTION: @@ -16,9 +17,9 @@ VIDEO_SLOWMOTION Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_SLOWMOTION, int nFrames) - :name: VIDEO_SLOWMOTION +.. c:macro:: VIDEO_SLOWMOTION +``int ioctl(fd, VIDEO_SLOWMOTION, int nFrames)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - The number of times to repeat each frame. - Description ----------- @@ -54,7 +53,6 @@ This ioctl call asks the video device to repeat decoding frames N number of times. This call can only be used if VIDEO_SOURCE_MEMORY is selected. - Return Value ------------ @@ -63,12 +61,10 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EPERM`` diff --git a/Documentation/userspace-api/media/dvb/video-stillpicture.rst b/Documentation/userspace-api/media/dvb/video-stillpicture.rst index a04f9f3ed162..d25384222a20 100644 --- a/Documentation/userspace-api/media/dvb/video-stillpicture.rst +++ b/Documentation/userspace-api/media/dvb/video-stillpicture.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_STILLPICTURE: @@ -16,9 +17,9 @@ VIDEO_STILLPICTURE Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp) - :name: VIDEO_STILLPICTURE +.. c:macro:: VIDEO_STILLPICTURE +``int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Pointer to a location where an I-frame and size is stored. - Description ----------- @@ -54,7 +53,6 @@ This ioctl call asks the Video Device to display a still picture (I-frame). The input data shall contain an I-frame. If the pointer is NULL, then the current displayed still picture is blanked. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-stop.rst b/Documentation/userspace-api/media/dvb/video-stop.rst index 9318655dce23..96f61c5b48a2 100644 --- a/Documentation/userspace-api/media/dvb/video-stop.rst +++ b/Documentation/userspace-api/media/dvb/video-stop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_STOP: @@ -16,9 +17,9 @@ VIDEO_STOP Synopsis -------- -.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode) - :name: VIDEO_STOP +.. c:macro:: VIDEO_STOP +``int ioctl(fd, VIDEO_STOP, boolean mode)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -56,7 +56,6 @@ Arguments - - FALSE: Show last decoded frame. - Description ----------- @@ -67,7 +66,6 @@ This ioctl call asks the Video Device to stop playing the current stream. Depending on the input parameter, the screen can be blanked out or displaying the last decoded frame. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/video-try-command.rst b/Documentation/userspace-api/media/dvb/video-try-command.rst index 430c36035329..79bf3dfb8a32 100644 --- a/Documentation/userspace-api/media/dvb/video-try-command.rst +++ b/Documentation/userspace-api/media/dvb/video-try-command.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.video .. _VIDEO_TRY_COMMAND: @@ -16,9 +17,9 @@ VIDEO_TRY_COMMAND Synopsis -------- -.. c:function:: int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd) - :name: VIDEO_TRY_COMMAND +.. c:macro:: VIDEO_TRY_COMMAND +``int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd)`` Arguments --------- @@ -27,7 +28,6 @@ Arguments :header-rows: 0 :stub-columns: 0 - - .. row 1 - int fd @@ -46,7 +46,6 @@ Arguments - Try a decoder command. - Description ----------- @@ -59,7 +58,6 @@ subset of the ``v4l2_decoder_cmd`` struct, so refer to the :ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation for more information. - Return Value ------------ diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst index ec571b34ce69..8ac2443e76c1 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-close.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-close: @@ -11,7 +12,6 @@ Name media-close - Close a media device - Synopsis ======== @@ -19,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: mc-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <mc-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -36,11 +33,10 @@ Description Closes the media device. Resources associated with the file descriptor are freed. The device configuration remain unchanged. - Return Value ============ -:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: EBADF diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst index 35ed549bec0e..9e9a838f4795 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-ioctl: @@ -11,7 +12,6 @@ Name media-ioctl - Control a media device - Synopsis ======== @@ -19,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: mc-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <mc-open>`. + File descriptor returned by :c:func:`open()`. ``request`` Media ioctl request code as defined in the media.h header file, for @@ -36,7 +34,6 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== @@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl requests, their respective function and parameters are specified in :ref:`media-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst index 2c2595157ea3..24487cb0a308 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-open.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-open: @@ -11,7 +12,6 @@ Name media-open - Open a media device - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: mc-open Arguments ========= @@ -33,11 +31,10 @@ Arguments Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. Other flags have no effect. - Description =========== -To open a media device applications call :ref:`open() <media-func-open>` with the +To open a media device applications call :c:func:`open()` with the desired device name. The function has no side effects; the device configuration remain unchanged. @@ -45,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its configuration will result in an error, and ``errno`` will be set to EBADF. - Return Value ============ -:ref:`open() <func-open>` returns the new file descriptor on success. On error, +:c:func:`open()` returns the new file descriptor on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst index cde1ddfc0bfb..0c4c5d2cfcb2 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_device_info: @@ -11,24 +12,22 @@ Name MEDIA_IOC_DEVICE_INFO - Query device information - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) - :name: MEDIA_IOC_DEVICE_INFO +.. c:macro:: MEDIA_IOC_DEVICE_INFO +``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_device_info`. - Description =========== @@ -38,7 +37,6 @@ a struct :c:type:`media_device_info`. The driver fills the structure and returns the information to the application. The ioctl never fails. - .. c:type:: media_device_info .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -48,7 +46,6 @@ ioctl never fails. :stub-columns: 0 :widths: 1 1 2 - * - char - ``driver``\ [16] - Name of the driver implementing the media API as a NUL-terminated @@ -94,7 +91,6 @@ ioctl never fails. - Reserved for future extensions. Drivers and applications must set this array to zero. - The ``serial`` and ``bus_info`` fields can be used to distinguish between multiple instances of otherwise identical hardware. The serial number takes precedence when provided and can be assumed to be unique. @@ -102,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be used instead. The ``bus_info`` field is guaranteed to be unique, but can vary across reboots or device unplug/replug. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst index 93e35f198f47..92dd8ecd538c 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_enum_entities: @@ -11,24 +12,22 @@ Name MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) - :name: MEDIA_IOC_ENUM_ENTITIES +.. c:macro:: MEDIA_IOC_ENUM_ENTITIES +``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_entity_desc`. - Description =========== @@ -49,7 +48,6 @@ Entity IDs can be non-contiguous. Applications must *not* try to enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error. - .. c:type:: media_entity_desc .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| @@ -136,7 +134,6 @@ id's until they get an error. * - } - - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst index f3e94c7b5dc3..3bc98a6a2ec5 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_enum_links: @@ -11,24 +12,22 @@ Name MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) - :name: MEDIA_IOC_ENUM_LINKS +.. c:macro:: MEDIA_IOC_ENUM_LINKS +``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_links_enum`. - Description =========== @@ -53,7 +52,6 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`. Only forward links that originate at one of the entity's source pads are returned during the enumeration process. - .. c:type:: media_links_enum .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -82,7 +80,6 @@ returned during the enumeration process. - Reserved for future extensions. Drivers and applications must set the array to zero. - .. c:type:: media_pad_desc .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -110,7 +107,6 @@ returned during the enumeration process. the array to zero. - .. c:type:: media_link_desc .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -137,7 +133,6 @@ returned during the enumeration process. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst index 9b7d2296b7fd..8f8b3b586edd 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_g_topology: @@ -11,24 +12,22 @@ Name MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) - :name: MEDIA_IOC_G_TOPOLOGY +.. c:macro:: MEDIA_IOC_G_TOPOLOGY +``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_v2_topology`. - Description =========== @@ -120,7 +119,6 @@ desired arrays with the media graph elements. converted to a 64-bits integer. It can be zero. if zero, the ioctl won't store the links. It will just update ``num_links`` - .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| .. c:type:: media_v2_entity @@ -158,7 +156,6 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| .. c:type:: media_v2_interface @@ -192,7 +189,6 @@ desired arrays with the media graph elements. - Used only for device node interfaces. See :c:type:`media_v2_intf_devnode` for details. - .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| .. c:type:: media_v2_intf_devnode @@ -245,7 +241,6 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| .. c:type:: media_v2_link @@ -282,7 +277,6 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst index ea05ff0c5382..9195b4b8bf20 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_request_alloc: @@ -11,24 +12,22 @@ Name MEDIA_IOC_REQUEST_ALLOC - Allocate a request - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) - :name: MEDIA_IOC_REQUEST_ALLOC +.. c:macro:: MEDIA_IOC_REQUEST_ALLOC +``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. - Description =========== @@ -51,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait for the request to complete. The request will remain allocated until all the file descriptors associated -with it are closed by :ref:`close() <request-func-close>` and the driver no +with it are closed by :c:func:`close()` and the driver no longer uses the request internally. See also :ref:`here <media-request-life-time>` for more information. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst index e2aa51015783..23208300cb61 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_setup_link: @@ -11,24 +12,22 @@ Name MEDIA_IOC_SETUP_LINK - Modify the properties of a link - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) - :name: MEDIA_IOC_SETUP_LINK +.. c:macro:: MEDIA_IOC_SETUP_LINK +``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_link_desc`. - Description =========== @@ -53,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code. If the specified link can't be found the driver returns with an ``EINVAL`` error code. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst index ca1b33196242..04b33db2bb45 100644 --- a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_request_ioc_queue: @@ -11,13 +12,12 @@ Name MEDIA_REQUEST_IOC_QUEUE - Queue a request - Synopsis ======== -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) - :name: MEDIA_REQUEST_IOC_QUEUE +.. c:macro:: MEDIA_REQUEST_IOC_QUEUE +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` Arguments ========= @@ -25,7 +25,6 @@ Arguments ``request_fd`` File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - Description =========== diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst index cfd503bdef70..57567b87b985 100644 --- a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_request_ioc_reinit: @@ -11,13 +12,12 @@ Name MEDIA_REQUEST_IOC_REINIT - Re-initialize a request - Synopsis ======== -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) - :name: MEDIA_REQUEST_IOC_REINIT +.. c:macro:: MEDIA_REQUEST_IOC_REINIT +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)`` Arguments ========= @@ -33,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated request. Re-initializing a request will clear any existing data from the request. -This avoids having to :ref:`close() <request-func-close>` a completed +This avoids having to :c:func:`close()` a completed request and allocate a new request. Instead the completed request can just be re-initialized and it is ready to be used again. diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst index c0fa4dbb2b28..6c4cbd9f08a5 100644 --- a/Documentation/userspace-api/media/mediactl/request-api.rst +++ b/Documentation/userspace-api/media/mediactl/request-api.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-request-api: @@ -93,7 +94,7 @@ regardless of whether a request is in use or not. Setting the same control through a request and also directly can lead to undefined behavior! -User-space can :ref:`poll() <request-func-poll>` a request file descriptor in +User-space can :c:func:`poll()` a request file descriptor in order to wait until the request completes. A request is considered complete once all its associated buffers are available for dequeuing and all the associated controls have been updated with the values at the time of completion. @@ -115,7 +116,7 @@ Recycling and Destruction ------------------------- Finally, a completed request can either be discarded or be reused. Calling -:ref:`close() <request-func-close>` on a request file descriptor will make +:c:func:`close()` on a request file descriptor will make that file descriptor unusable and the request will be freed once it is no longer in use by the kernel. That is, if the request is queued and then the file descriptor is closed, then it won't be freed until the driver completed diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst index 04e00bb9defd..f4b8eb385ad7 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-close.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC.request .. _request-func-close: @@ -11,7 +12,6 @@ Name request-close - Close a request file descriptor - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: req-close Arguments ========= @@ -29,7 +27,6 @@ Arguments ``fd`` File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - Description =========== @@ -38,11 +35,10 @@ are freed once all file descriptors associated with the request are closed and the driver has completed the request. See :ref:`here <media-request-life-time>` for more information. - Return Value ============ -:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: EBADF diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst index 1e1c5edb860c..4fb3d2ef32d1 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _request-func-ioctl: @@ -11,7 +12,6 @@ Name request-ioctl - Control a request file descriptor - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int cmd, void *argp ) - :name: req-ioctl +``int ioctl(int fd, int cmd, void *argp)`` Arguments ========= @@ -36,7 +34,6 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== @@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl commands, their respective function and parameters are specified in :ref:`media-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst index 92947213d3d5..ce0043dbe7da 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-poll.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _request-func-poll: @@ -11,7 +12,6 @@ Name request-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: request-poll Arguments ========= @@ -35,14 +33,13 @@ Arguments ``timeout`` Timeout to wait for events - Description =========== -With the :c:func:`poll() <request-func-poll>` function applications can wait +With the :c:func:`poll()` function applications can wait for a request to complete. -On success :c:func:`poll() <request-func-poll>` returns the number of file +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the ``revents`` field of the respective struct :c:type:`pollfd` is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` @@ -53,11 +50,10 @@ set appropriately. Attempting to poll for a request that is not yet queued will set the ``POLLERR`` flag in ``revents``. - Return Value ============ -On success, :c:func:`poll() <request-func-poll>` returns the number of +On success, :c:func:`poll()` returns the number of structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst index 6846ae99848c..66a243dbd437 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-features.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_features: @@ -14,8 +15,9 @@ LIRC_GET_FEATURES - Get the underlying hardware device's features Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features) - :name: LIRC_GET_FEATURES +.. c:macro:: LIRC_GET_FEATURES + +``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)`` Arguments ========= @@ -26,11 +28,9 @@ Arguments ``features`` Bitmask with the LIRC features. - Description =========== - Get the underlying hardware device's features. If a driver does not announce support of certain features, calling of the corresponding ioctls is undefined. @@ -184,7 +184,6 @@ LIRC features Unused. Kept just to avoid breaking uAPI. - Return Value ============ 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 e8f397a87331..188478ed1233 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_rec_mode: .. _lirc_set_rec_mode: @@ -15,11 +16,13 @@ LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) - :name: LIRC_GET_REC_MODE +.. c:macro:: LIRC_GET_REC_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) - :name: LIRC_SET_REC_MODE +``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_REC_MODE + +``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)`` Arguments ========= @@ -47,7 +50,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` 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 3f08aa7c24a9..e29445c5ce16 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_rec_resolution: @@ -14,8 +15,9 @@ LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microsecond Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds) - :name: LIRC_GET_REC_RESOLUTION +.. c:macro:: LIRC_GET_REC_RESOLUTION + +``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)`` Arguments ========= @@ -26,7 +28,6 @@ Arguments ``microseconds`` Resolution, in microseconds. - Description =========== @@ -38,7 +39,6 @@ This ioctl returns the integer value with such resolution, with can be used by userspace applications like lircd to automatically adjust the tolerance value. - Return Value ============ 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 f93b30c92193..77472fb5608a 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_send_mode: .. _lirc_set_send_mode: @@ -15,11 +16,13 @@ LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) - :name: LIRC_GET_SEND_MODE +.. c:macro:: LIRC_GET_SEND_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) - :name: LIRC_SET_SEND_MODE +``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_SEND_MODE + +``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)`` Arguments ========= @@ -30,7 +33,6 @@ Arguments ``mode`` The mode used for transmitting. - Description =========== @@ -44,14 +46,12 @@ modes the driver supports. Return Value ============ - .. tabularcolumns:: |p{2.5cm}|p{15.0cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst index ec191a383d75..f5f3e06d6206 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_min_timeout: .. _lirc_get_max_timeout: @@ -16,11 +17,13 @@ range for IR receive. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MIN_TIMEOUT +.. c:macro:: LIRC_GET_MIN_TIMEOUT -.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MAX_TIMEOUT +``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_GET_MAX_TIMEOUT + +``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)`` Arguments ========= @@ -31,7 +34,6 @@ Arguments ``timeout`` Timeout, in microseconds. - Description =========== @@ -47,7 +49,6 @@ that can be set. both ioctls will return the same value even though the timeout cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst index b94a349bd99e..d589560214f4 100644 --- a/Documentation/userspace-api/media/rc/lirc-read.rst +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc-read: @@ -11,7 +12,6 @@ Name lirc-read - Read from a LIRC device - Synopsis ======== @@ -19,10 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: lirc-read - Arguments ========= @@ -39,9 +36,9 @@ Arguments Description =========== -:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file +:c:func:`read()` attempts to read up to ``count`` bytes from file descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, -:ref:`read() <lirc-read>` returns zero and has no other results. If ``count`` +:c:func:`read()` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. The exact format of the data depends on what :ref:`lirc_modes` a driver @@ -59,7 +56,6 @@ by hardware decoders. The :c:type:`rc_proto` member is set to the used for transmission, and ``scancode`` to the decoded scancode, and the ``keycode`` set to the keycode or ``KEY_RESERVED``. - Return Value ============ 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 820d6bf28c1c..9bf9811a905a 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_measure_carrier_mode: @@ -14,8 +15,9 @@ LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable ) - :name: LIRC_SET_MEASURE_CARRIER_MODE +.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE + +``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)`` Arguments ========= @@ -27,7 +29,6 @@ Arguments enable = 1 means enable measure mode, enable = 0 means disable measure mode. - Description =========== @@ -37,7 +38,6 @@ Enable or disable measure mode. If enabled, from the next key press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By default this should be turned off. - Return Value ============ 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 e33e6a320b7a..530bc223930a 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_carrier_range: @@ -15,8 +16,9 @@ IR receive. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER_RANGE +.. c:macro:: LIRC_SET_REC_CARRIER_RANGE + +``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)`` Arguments ========= 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 a6784d5e59c8..28c928f1cc14 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_carrier: @@ -11,12 +12,12 @@ Name LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. - Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER +.. c:macro:: LIRC_SET_REC_CARRIER + +``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)`` Arguments ========= @@ -37,7 +38,6 @@ Set receive carrier used to modulate IR PWM pulses and spaces. If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl sets the upper bound frequency that will be recognized by the device. - Return Value ============ 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 55be65df7d5a..83e7155c5796 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_timeout_reports: @@ -14,8 +15,9 @@ LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable ) - :name: LIRC_SET_REC_TIMEOUT_REPORTS +.. c:macro:: LIRC_SET_REC_TIMEOUT_REPORTS + +``int ioctl(int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable)`` Arguments ========= @@ -27,7 +29,6 @@ Arguments enable = 1 means enable timeout report, enable = 0 means disable timeout reports. - Description =========== @@ -40,7 +41,6 @@ should be turned off. This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`. - Return Value ============ 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 e91a0daecde6..8f3f9adf54ab 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_timeout: .. _lirc_get_rec_timeout: @@ -15,11 +16,13 @@ LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR ina Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_GET_REC_TIMEOUT +.. c:macro:: LIRC_GET_REC_TIMEOUT -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_SET_REC_TIMEOUT +``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_SET_REC_TIMEOUT + +``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)`` Arguments ========= @@ -30,7 +33,6 @@ Arguments ``timeout`` Timeout, in microseconds. - Description =========== @@ -45,7 +47,6 @@ given value should be set. The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`. - Return Value ============ 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 e199aac7d8e0..e3810ba58746 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_send_carrier: @@ -11,12 +12,12 @@ Name LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. - Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency ) - :name: LIRC_SET_SEND_CARRIER +.. c:macro:: LIRC_SET_SEND_CARRIER + +``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)`` Arguments ========= @@ -32,7 +33,6 @@ Description Set send carrier used to modulate IR PWM pulses and spaces. - Return Value ============ 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 a9074f4fb058..52a072529af9 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_send_duty_cycle: @@ -15,8 +16,9 @@ IR transmit. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle) - :name: LIRC_SET_SEND_DUTY_CYCLE +.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE + +``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)`` Arguments ========= @@ -28,7 +30,6 @@ Arguments Duty cicle, describing the pulse width in percent (from 1 to 99) of the total cycle. Values 0 and 100 are reserved. - Description =========== @@ -38,7 +39,6 @@ Currently, no special meaning is defined for 0 or 100, but this could be used to switch off carrier generation in the future, so these values should be reserved. - Return Value ============ 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 1f5527427281..68f4cc2e3ae3 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_transmitter_mask: @@ -14,8 +15,9 @@ LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask ) - :name: LIRC_SET_TRANSMITTER_MASK +.. c:macro:: LIRC_SET_TRANSMITTER_MASK + +``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)`` Arguments ========= @@ -26,7 +28,6 @@ Arguments ``mask`` Mask with channels to enable tx. Channel 0 is the least significant bit. - Description =========== @@ -42,7 +43,6 @@ When an invalid bit mask is given, i.e. a bit is set, even though the device does not have so many transitters, then this ioctl returns the number of available transitters and does nothing otherwise. - Return Value ============ 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 2c43b620b3f3..be5321c4a91f 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,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_wideband_receiver: @@ -14,8 +15,9 @@ LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable ) - :name: LIRC_SET_WIDEBAND_RECEIVER +.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER + +``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)`` Arguments ========= @@ -27,7 +29,6 @@ Arguments enable = 1 means enable wideband receiver, enable = 0 means disable wideband receiver. - Description =========== @@ -47,7 +48,6 @@ reduced range of reception. carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst index 421de2cfa4ca..c1c3230d4fd6 100644 --- a/Documentation/userspace-api/media/rc/lirc-write.rst +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc-write: @@ -11,7 +12,6 @@ Name lirc-write - Write to a LIRC device - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: lirc-write Arguments ========= @@ -38,7 +36,7 @@ Arguments Description =========== -:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device +:c:func:`write()` writes up to ``count`` bytes to the device referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. @@ -64,7 +62,6 @@ for the protocol or the scancode is not valid for the specified protocol, ``EINVAL`` is returned. The write function blocks until the scancode is transmitted by the hardware. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 4f95496adc5b..7dbdfbb4a0a9 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _buffer: @@ -33,7 +34,6 @@ mem-to-mem devices is an exception to the rule: the timestamp source flags are copied from the OUTPUT video buffer to the CAPTURE video buffer. - Interactions between formats, controls and buffers ================================================== @@ -152,7 +152,6 @@ based on the queried sizes (for instance by allocating a set of buffers large enough for all the desired formats and controls, or by allocating separate set of appropriately sized buffers for each use case). - .. c:type:: v4l2_buffer struct v4l2_buffer @@ -257,7 +256,7 @@ struct v4l2_buffer ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the start of the device memory. The value is returned by the driver and apart of serving as parameter to the - :ref:`mmap() <func-mmap>` function not useful for applications. + :c:func:`mmap()` function not useful for applications. See :ref:`mmap` for details * - unsigned long - ``userptr`` @@ -310,7 +309,6 @@ struct v4l2_buffer given, then ``EINVAL`` will be returned. - .. c:type:: v4l2_plane struct v4l2_plane @@ -350,7 +348,7 @@ struct v4l2_plane - ``mem_offset`` - When the memory type in the containing struct :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this - is the value that should be passed to :ref:`mmap() <func-mmap>`, + is the value that should be passed to :c:func:`mmap()`, similar to the ``offset`` field in struct :c:type:`v4l2_buffer`. * - unsigned long @@ -384,7 +382,6 @@ struct v4l2_plane applications. - .. c:type:: v4l2_buf_type enum v4l2_buf_type @@ -448,7 +445,6 @@ enum v4l2_buf_type - Buffer for metadata output, see :ref:`metadata`. - .. _buffer-flags: Buffer Flags @@ -682,20 +678,6 @@ Buffer Flags .. _memory-flags: -Memory Consistency Flags -======================== - -.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - -.. c:type:: v4l2_memory - enum v4l2_memory ================ @@ -720,7 +702,6 @@ enum v4l2_memory - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. - Timecodes ========= @@ -729,7 +710,6 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a (struct :c:type:`timeval` timestamps are stored in the struct :c:type:`v4l2_buffer` ``timestamp`` field.) - .. c:type:: v4l2_timecode struct v4l2_timecode @@ -766,7 +746,6 @@ struct v4l2_timecode - The "user group" bits from the timecode. - .. _timecode-type: Timecode Types @@ -796,7 +775,6 @@ Timecode Types - - .. _timecode-flags: Timecode Flags diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst index 5ea1ffe71fa6..fe58fd450e2f 100644 --- a/Documentation/userspace-api/media/v4l/dev-capture.rst +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _capture: @@ -19,7 +20,6 @@ device. .. note:: The same device file names are used for video output devices. - Querying Capabilities ===================== @@ -34,7 +34,6 @@ functions they may also support the :ref:`video overlay <overlay>` streaming I/O methods must be supported. Tuners and audio inputs are optional. - Supplemental Functions ====================== @@ -45,7 +44,6 @@ Video capture devices shall support :ref:`audio input <audio>`, :ref:`video input <video>` ioctls must be supported by all video capture devices. - Image Format Negotiation ======================== @@ -55,7 +53,7 @@ capture, the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -95,7 +93,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Reading Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst index 2315faf61aaf..eadcb4aa813b 100644 --- a/Documentation/userspace-api/media/v4l/dev-output.rst +++ b/Documentation/userspace-api/media/v4l/dev-output.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _output: @@ -18,7 +19,6 @@ device. .. note:: The same device file names are used also for video capture devices. - Querying Capabilities ===================== @@ -32,7 +32,6 @@ functions they may also support the :ref:`raw VBI output <raw-vbi>` streaming I/O methods must be supported. Modulators and audio outputs are optional. - Supplemental Functions ====================== @@ -43,7 +42,6 @@ Video output devices shall support :ref:`audio output <audio>`, :ref:`video output <video>` ioctls must be supported by all video output devices. - Image Format Negotiation ======================== @@ -53,7 +51,7 @@ the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then writing to it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -92,7 +90,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Writing Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index bb52f85a619c..3f43a01ba938 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _raw-vbi: @@ -32,7 +33,6 @@ applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Accessed as ``/dev/vbi``, raw VBI capturing or output is the default device function. - Querying Capabilities ===================== @@ -44,7 +44,6 @@ in the ``capabilities`` field of struct read/write, streaming or asynchronous I/O methods must be supported. VBI devices may or may not have a tuner or modulator. - Supplemental Functions ====================== @@ -53,7 +52,6 @@ VBI devices shall support :ref:`video input or output <video>`, ioctls as needed. The :ref:`video standard <standard>` ioctls provide information vital to program a VBI device, therefore must be supported. - Raw VBI Format Negotiation ========================== @@ -62,7 +60,7 @@ frequency. To properly interpret the data V4L2 specifies an ioctl to query the sampling parameters. Moreover, to allow for some flexibility applications can also suggest different parameters. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications should always ensure they really get what they want, requesting reasonable @@ -91,8 +89,8 @@ happen for instance when the video and VBI areas to capture would overlap, or when the driver supports multiple opens and another process already requested VBI capturing or output. Anyway, applications must expect other resource allocation points which may return ``EBUSY``, at the -:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>` -, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls. +:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()` +, :c:func:`write()` and :c:func:`select()` calls. VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests @@ -182,7 +180,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does - This array is reserved for future extensions. Drivers and applications must set it to zero. - .. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| .. _vbifmt-flags: @@ -218,7 +215,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does non-zero. - .. _vbi-hsync: .. kernel-figure:: vbi_hsync.svg @@ -227,7 +223,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does **Figure 4.1. Line synchronization** - .. _vbi-525: .. kernel-figure:: vbi_525.svg @@ -251,7 +246,6 @@ negotiation, or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. A format change during active I/O is not permitted. - Reading and writing VBI images ============================== @@ -261,7 +255,6 @@ consisting of two fields of VBI images immediately following in memory. The total size of a frame computes as follows: - .. code-block:: c (count[0] + count[1]) * samples_per_line * sample size in bytes @@ -276,8 +269,8 @@ The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the -first :ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call can be resource allocation +first :c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call can be resource allocation points returning an ``EBUSY`` error code if the required hardware resources are temporarily unavailable, for example the device is already in use by another process. diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst index 463726ba46d7..207216d5e6a5 100644 --- a/Documentation/userspace-api/media/v4l/dev-rds.rst +++ b/Documentation/userspace-api/media/v4l/dev-rds.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rds: @@ -28,7 +29,6 @@ The RDS interface does not support this format. Should support for MMBS the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Querying Capabilities ===================== @@ -68,31 +68,27 @@ like program identification codes and radio text, the flag :ref:`Writing RDS data <writing-rds-data>` and :ref:`FM Transmitter Control Reference <fm-tx-controls>`. - .. _reading-rds-data: Reading RDS data ================ RDS data can be read from the radio device with the -:ref:`read() <func-read>` function. The data is packed in groups of +:c:func:`read()` function. The data is packed in groups of three bytes. - .. _writing-rds-data: Writing RDS data ================ RDS data can be written to the radio device with the -:ref:`write() <func-write>` function. The data is packed in groups of +:c:func:`write()` function. The data is packed in groups of three bytes, as follows: - RDS datastructures ================== - .. c:type:: v4l2_rds_data .. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| @@ -113,7 +109,6 @@ RDS datastructures - Block description - .. _v4l2-rds-block: .. tabularcolumns:: |p{2.9cm}|p{14.6cm}| @@ -136,7 +131,6 @@ RDS datastructures reception of this block. - .. _v4l2-rds-block-codes: .. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 807751f305fb..f0df144c9f63 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _sliced: @@ -27,7 +28,6 @@ however the default function here is video capturing or output. Different file descriptors must be used to pass raw and sliced VBI data simultaneously, if this is supported by the driver. - Querying Capabilities ===================== @@ -39,7 +39,6 @@ respectively, in the ``capabilities`` field of struct read/write, streaming or asynchronous :ref:`I/O methods <io>` must be supported. Sliced VBI devices may have a tuner or modulator. - Supplemental Functions ====================== @@ -49,7 +48,6 @@ capabilities, and they may support :ref:`control` ioctls. The :ref:`video standard <standard>` ioctls provide information vital to program a sliced VBI device, therefore must be supported. - .. _sliced-vbi-format-negotitation: Sliced VBI Format Negotiation @@ -96,9 +94,8 @@ at this point, it may return an ``EBUSY`` error code if the required resources are temporarily unavailable. Other resource allocation points which may return ``EBUSY`` can be the :ref:`VIDIOC_STREAMON` ioctl and the first -:ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call. - +:c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call. .. c:type:: v4l2_sliced_vbi_format @@ -191,7 +188,7 @@ struct v4l2_sliced_vbi_format * - __u32 - ``io_size`` - :cspan:`2` Maximum number of bytes passed by one - :ref:`read() <func-read>` or :ref:`write() <func-write>` call, + :c:func:`read()` or :c:func:`write()` call, and the buffer size in bytes for the :ref:`VIDIOC_QBUF` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field @@ -274,7 +271,6 @@ Sliced VBI services \normalsize - Drivers may return an ``EINVAL`` error code when applications attempt to read or write data without prior format negotiation, after switching the video standard (which may invalidate the negotiated VBI parameters) and @@ -284,13 +280,12 @@ return an ``EBUSY`` error code when applications attempt to change the format while i/o is in progress (between a :ref:`VIDIOC_STREAMON` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first -:ref:`read() <func-read>` or :ref:`write() <func-write>` call). - +:c:func:`read()` or :c:func:`write()` call). Reading and writing sliced VBI data =================================== -A single :ref:`read() <func-read>` or :ref:`write() <func-write>` +A single :c:func:`read()` or :c:func:`write()` call must pass all data belonging to one video frame. That is an array of struct :c:type:`v4l2_sliced_vbi_data` structures with one or more elements and a total size not exceeding ``io_size`` bytes. Likewise @@ -298,7 +293,6 @@ in streaming I/O mode one buffer of ``io_size`` bytes must contain data of one video frame. The ``id`` of unused struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. - .. c:type:: v4l2_sliced_vbi_data struct v4l2_sliced_vbi_data @@ -344,9 +338,8 @@ struct v4l2_sliced_vbi_data bytes at the end of this array are undefined, drivers and applications shall ignore them. - Packets are always passed in ascending line number order, without -duplicate line numbers. The :ref:`write() <func-write>` function and +duplicate line numbers. The :c:func:`write()` function and the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL`` error code when applications violate this rule. They must also return an EINVAL error code when applications pass an incorrect field or line @@ -370,7 +363,6 @@ streaming (:ref:`memory mapping <mmap>` and/or :ref:`user pointer <userp>`) I/O. The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. - Sliced VBI Data in MPEG Streams =============================== @@ -405,7 +397,6 @@ data insertion is not supported by the device. The following subsections specify the format of the embedded sliced VBI data. - MPEG Stream Embedded, Sliced VBI Data Format: NONE -------------------------------------------------- @@ -417,7 +408,6 @@ nor driver shall insert "empty" embedded sliced VBI data packets in the MPEG stream when this format is set. No MPEG stream data structures are specified for this format. - MPEG Stream Embedded, Sliced VBI Data Format: IVTV -------------------------------------------------- @@ -460,7 +450,6 @@ the end with unspecified fill bytes to align the end of the payload to a with 18 lines/field with 43 bytes of data/line and a 4 byte magic number). - .. c:type:: v4l2_mpeg_vbi_fmt_ivtv struct v4l2_mpeg_vbi_fmt_ivtv @@ -523,7 +512,6 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field valid and that 36 lines of sliced VBI data are present. - .. c:type:: v4l2_mpeg_vbi_itv0 .. c:type:: v4l2_mpeg_vbi_ITV0 @@ -548,7 +536,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 value: - :: linemask[0] b0: line 6 first field @@ -574,7 +561,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 applications. - .. _v4l2-mpeg-vbi-itv0-1: struct v4l2_mpeg_vbi_ITV0 @@ -596,7 +582,6 @@ struct v4l2_mpeg_vbi_ITV0 lines 6 through 23 of the second field. - .. c:type:: v4l2_mpeg_vbi_itv0_line struct v4l2_mpeg_vbi_itv0_line @@ -619,7 +604,6 @@ struct v4l2_mpeg_vbi_itv0_line - The sliced VBI data for the line. - .. _ITV0-Line-Identifier-Constants: Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field @@ -653,7 +637,6 @@ Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field description of the line payload. - .. [#f1] According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index 3f7bac44377c..caa05fbbd396 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _diff-v4l: @@ -13,7 +14,6 @@ the much improved V4L2 API replaces the V4L API. The support for the old V4L calls were removed from Kernel, but the library :ref:`libv4l` supports the conversion of a V4L API system call into a V4L2 one. - Opening and Closing Devices =========================== @@ -32,7 +32,6 @@ recommend that V4L2 drivers by default register devices with the same numbers, but the system administrator can assign arbitrary minor numbers using driver module options. The major device number remains 81. - .. _v4l-dev: .. flat-table:: V4L Device Types, Names and Numbers @@ -53,14 +52,12 @@ using driver module options. The major device number remains 81. - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31`` - 224-255 - V4L prohibits (or used to prohibit) multiple opens of a device file. V4L2 drivers *may* support multiple opens, see :ref:`open` for details and consequences. V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. - Querying Capabilities ===================== @@ -151,7 +148,6 @@ introduction. - ``-`` - See above. - The ``audios`` field was replaced by ``capabilities`` flag ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or outputs. To determine their number applications can enumerate audio @@ -164,7 +160,6 @@ were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or dimensions returns the closest size possible, taking into account the current video standard, cropping and scaling limitations. - Video Sources ============= @@ -180,7 +175,6 @@ The ``channel`` field counting inputs was renamed to ``index``, the video input types were renamed as follows: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -192,7 +186,6 @@ video input types were renamed as follows: * - ``VIDEO_TYPE_CAMERA`` - ``V4L2_INPUT_TYPE_CAMERA`` - Unlike the ``tuners`` field expressing the number of tuners of this input, V4L2 assumes each video input is connected to at most one tuner. However a tuner can have more than one input, i. e. RF connectors, and a @@ -216,7 +209,6 @@ addition together with the ``norm`` field and has been removed in the meantime. V4L2 has a similar, albeit more comprehensive approach to video standards, see :ref:`standard` for more information. - Tuning ====== @@ -260,7 +252,6 @@ frequency where renamed to to a struct :c:type:`v4l2_frequency` instead of an unsigned long integer. - .. _v4l-image-properties: Image Properties @@ -274,7 +265,6 @@ replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -292,7 +282,6 @@ replaced by V4L2 controls accessible with the * - ``whiteness`` - ``V4L2_CID_WHITENESS`` - The V4L picture controls are assumed to range from 0 to 65535 with no particular reset value. The V4L2 API permits arbitrary limits and defaults which can be queried with the @@ -306,7 +295,6 @@ of the image depth and others need not know. The ``palette`` field moved into the struct :c:type:`v4l2_pix_format`: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -346,11 +334,9 @@ into the struct :c:type:`v4l2_pix_format`: * - ``VIDEO_PALETTE_YUV410P`` - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>` - V4L2 image formats are defined in :ref:`pixfmt`. The image format can be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Audio ===== @@ -384,7 +370,6 @@ The following fields where replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -400,7 +385,6 @@ The following fields where replaced by V4L2 controls accessible with the * - ``balance`` - ``V4L2_CID_AUDIO_BALANCE`` - To determine which of these controls are supported by a driver V4L provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``, ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the @@ -416,7 +400,6 @@ V4L2 API permits arbitrary limits and defaults which can be queried with the :ref:`VIDIOC_QUERYCTRL` ioctl. For general information about controls see :ref:`control`. - Frame Buffer Overlay ==================== @@ -463,7 +446,6 @@ size is determined by ``w.width`` and ``w.height``. The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to :ref:`VIDIOC_OVERLAY`. - Cropping ======== @@ -490,21 +472,19 @@ struct :c:type:`v4l2_window`. These structures are used to select a capture or overlay format with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Reading Images, Memory Mapping ============================== - Capturing using the read method ------------------------------- There is no essential difference between reading images from a V4L or -V4L2 device using the :ref:`read() <func-read>` function, however V4L2 +V4L2 device using the :c:func:`read()` function, however V4L2 drivers are not required to support this I/O method. Applications can determine if the function is available with the :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices exchanging data with applications must support the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions. To select an image format and size, V4L provides the ``VIDIOCSPICT`` and @@ -517,7 +497,6 @@ negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and For more information about the V4L2 read interface see :ref:`rw`. - Capturing using memory mapping ------------------------------ @@ -528,7 +507,6 @@ read method. V4L2 supports memory mapping as well, with a few differences. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -550,7 +528,7 @@ differences. ``VIDIOCGMBUF`` ioctl is available to query the number of buffers, the offset of each buffer from the start of the virtual file, and the overall amount of memory used, which can be used as arguments - for the :ref:`mmap() <func-mmap>` function. + for the :c:func:`mmap()` function. - Buffers are individually mapped. The offset and size of each buffer can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. @@ -568,7 +546,7 @@ differences. the incoming queue. Filled buffers are dequeued from the outgoing queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait until filled buffers become available this function, - :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can + :c:func:`select()` or :c:func:`poll()` can be used. The :ref:`VIDIOC_STREAMON` ioctl must be called once after enqueuing one or more buffers to start capturing. Its counterpart @@ -577,11 +555,9 @@ differences. signal status, if known, with the :ref:`VIDIOC_ENUMINPUT` ioctl. - For a more in-depth discussion of memory mapping and examples, see :ref:`mmap`. - Reading Raw VBI Data ==================== @@ -592,7 +568,6 @@ the V4L VBI interface. Reading from the device yields a raw VBI image with the following parameters: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -616,7 +591,6 @@ with the following parameters: * - flags - 0 - Undocumented in the V4L specification, in Linux 2.3 the ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct ``vbi_format`` were added to determine the VBI image @@ -630,11 +604,10 @@ remaining fields are probably equivalent to struct Apparently only the Zoran (ZR 36120) driver implements these ioctls. The semantics differ from those specified for V4L2 in two ways. The -parameters are reset on :ref:`open() <func-open>` and +parameters are reset on :c:func:`open()` and ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters are invalid. - Miscellaneous ============= diff --git a/Documentation/userspace-api/media/v4l/dmabuf.rst b/Documentation/userspace-api/media/v4l/dmabuf.rst index f43d400dafaa..50fba11c2477 100644 --- a/Documentation/userspace-api/media/v4l/dmabuf.rst +++ b/Documentation/userspace-api/media/v4l/dmabuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _dmabuf: @@ -36,7 +37,6 @@ are passed in struct :c:type:`v4l2_buffer` (or in struct driver must be switched into DMABUF I/O mode by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type. - Example: Initiating streaming I/O with DMABUF file descriptors ============================================================== @@ -135,10 +135,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions are always available. To start and stop capturing or displaying applications call the @@ -158,5 +158,5 @@ Drivers implementing DMABUF importing I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, -and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>` +and the :c:func:`select()` and :c:func:`poll()` functions. diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst index eaa6445f6160..35bbb2fea46e 100644 --- a/Documentation/userspace-api/media/v4l/format.rst +++ b/Documentation/userspace-api/media/v4l/format.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _format: @@ -6,7 +7,6 @@ Data Formats ************ - Data Format Negotiation ======================= @@ -53,8 +53,8 @@ image size. When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side effects are implied by the next step, the selection of an I/O method with the :ref:`VIDIOC_REQBUFS` ioctl or implicit -with the first :ref:`read() <func-read>` or -:ref:`write() <func-write>` call. +with the first :c:func:`read()` or +:c:func:`write()` call. Generally only one logical stream can be assigned to a file descriptor, the exception being drivers permitting simultaneous video capturing and @@ -67,7 +67,6 @@ All drivers exchanging data with applications must support the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. - Image Format Enumeration ======================== diff --git a/Documentation/userspace-api/media/v4l/func-close.rst b/Documentation/userspace-api/media/v4l/func-close.rst index c03ff3e62738..dba3263fd1b9 100644 --- a/Documentation/userspace-api/media/v4l/func-close.rst +++ b/Documentation/userspace-api/media/v4l/func-close.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-close: @@ -11,7 +12,6 @@ Name v4l2-close - Close a V4L2 device - Synopsis ======== @@ -19,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: v4l2-close Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -38,7 +35,6 @@ associated with the file descriptor are freed. However data format parameters, current input or output, control values or other properties remain unchanged. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-ioctl.rst b/Documentation/userspace-api/media/v4l/func-ioctl.rst index 8bde6b4f1cb5..f3b005094334 100644 --- a/Documentation/userspace-api/media/v4l/func-ioctl.rst +++ b/Documentation/userspace-api/media/v4l/func-ioctl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-ioctl: @@ -11,7 +12,6 @@ Name v4l2-ioctl - Program a V4L2 device - Synopsis ======== @@ -19,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: v4l2-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``request`` V4L2 ioctl request code as defined in the ``videodev2.h`` header @@ -36,7 +34,6 @@ Arguments ``argp`` Pointer to a function parameter, usually a structure. - Description =========== @@ -50,7 +47,6 @@ include the version in the kernel sources on the system they compile on. All V4L2 ioctl requests, their respective function and parameters are specified in :ref:`user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-mmap.rst b/Documentation/userspace-api/media/v4l/func-mmap.rst index b3a9cd862a7f..e3e5e64ebe7e 100644 --- a/Documentation/userspace-api/media/v4l/func-mmap.rst +++ b/Documentation/userspace-api/media/v4l/func-mmap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-mmap: @@ -11,7 +12,6 @@ Name v4l2-mmap - Map device memory into application address space - Synopsis ======== @@ -20,9 +20,7 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: v4l2-mmap Arguments ========= @@ -54,7 +52,7 @@ Arguments #. The Linux ``videobuf`` kernel module, which is used by some drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the driver does not support the desired protection, the - :ref:`mmap() <func-mmap>` function fails. + :c:func:`mmap()` function fails. #. Device memory accesses (e. g. the memory on a graphics card with video capturing hardware) may incur a performance penalty @@ -70,7 +68,7 @@ Arguments ``MAP_FIXED`` requests that the driver selects no other address than the one specified. If the specified address cannot be used, - :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, ``start`` must be a multiple of the pagesize. Use of this option is discouraged. @@ -87,7 +85,7 @@ Arguments flags. ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``offset`` Offset of the buffer in device memory. This must be the same value @@ -97,11 +95,10 @@ Arguments in the struct :c:type:`v4l2_plane` ``m`` union ``mem_offset`` field for the multi-planar API. - Description =========== -The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at +The :c:func:`mmap()` function asks to map ``length`` bytes starting at ``offset`` in the memory of the device specified by ``fd`` into the application address space, preferably at address ``start``. This latter address is a hint only, and is usually specified as 0. @@ -111,13 +108,12 @@ Suitable length and offset parameters are queried with the allocated with the :ref:`VIDIOC_REQBUFS` ioctl before they can be queried. -To unmap buffers the :ref:`munmap() <func-munmap>` function is used. - +To unmap buffers the :c:func:`munmap()` function is used. Return Value ============ -On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/v4l/func-munmap.rst b/Documentation/userspace-api/media/v4l/func-munmap.rst index e8a27e43373a..077d58333904 100644 --- a/Documentation/userspace-api/media/v4l/func-munmap.rst +++ b/Documentation/userspace-api/media/v4l/func-munmap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-munmap: @@ -11,7 +12,6 @@ Name v4l2-munmap - Unmap device memory - Synopsis ======== @@ -20,37 +20,33 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: int munmap( void *start, size_t length ) - :name: v4l2-munmap Arguments ========= ``start`` Address of the mapped buffer as returned by the - :ref:`mmap() <func-mmap>` function. + :c:func:`mmap()` function. ``length`` Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() <func-mmap>` and returned by the driver in the struct + :c:func:`mmap()` and returned by the driver in the struct :c:type:`v4l2_buffer` ``length`` field for the single-planar API and in the struct :c:type:`v4l2_plane` ``length`` field for the multi-planar API. - Description =========== -Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped +Unmaps a previously with the :c:func:`mmap()` function mapped buffer and frees it, if possible. - Return Value ============ -On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the +On success :c:func:`munmap()` returns 0, on failure -1 and the ``errno`` variable is set appropriately: EINVAL diff --git a/Documentation/userspace-api/media/v4l/func-open.rst b/Documentation/userspace-api/media/v4l/func-open.rst index f3890d284918..ba23ff1e45dd 100644 --- a/Documentation/userspace-api/media/v4l/func-open.rst +++ b/Documentation/userspace-api/media/v4l/func-open.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-open: @@ -11,7 +12,6 @@ Name v4l2-open - Open a V4L2 device - Synopsis ======== @@ -19,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: v4l2-open Arguments ========= @@ -34,7 +32,7 @@ Arguments technicality, input devices still support only reading and output devices only writing. - When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>` + When the ``O_NONBLOCK`` flag is given, the :c:func:`read()` function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will return the ``EAGAIN`` error code when no data is available or no buffer is in the driver outgoing queue, otherwise these functions @@ -43,22 +41,20 @@ Arguments Other flags have no effect. - Description =========== -To open a V4L2 device applications call :ref:`open() <func-open>` with the +To open a V4L2 device applications call :c:func:`open()` with the desired device name. This function has no side effects; all data format parameters, current input or output, control values or other properties -remain unchanged. At the first :ref:`open() <func-open>` call after loading the +remain unchanged. At the first :c:func:`open()` call after loading the driver they will be reset to default values, drivers are never in an undefined state. - Return Value ============ -On success :ref:`open() <func-open>` returns the new file descriptor. On error +On success :c:func:`open()` returns the new file descriptor. On error -1 is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/v4l/func-poll.rst b/Documentation/userspace-api/media/v4l/func-poll.rst index 95cf9c6fedcd..cbf4a0a10ae2 100644 --- a/Documentation/userspace-api/media/v4l/func-poll.rst +++ b/Documentation/userspace-api/media/v4l/func-poll.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-poll: @@ -11,7 +12,6 @@ Name v4l2-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -19,19 +19,16 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: v4l2-poll Arguments ========= - Description =========== -With the :ref:`poll() <func-poll>` function applications can suspend execution +With the :c:func:`poll()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -44,57 +41,56 @@ display. When buffers are already in the outgoing queue of the driver (capture) or the incoming queue isn't full (display) the function returns immediately. -On success :ref:`poll() <func-poll>` returns the number of file descriptors +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the -``revents`` field of the respective :c:func:`struct pollfd` structure +``revents`` field of the respective ``struct pollfd`` structure is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` flags in the ``revents`` field, output devices the ``POLLOUT`` and ``POLLWRNORM`` flags. When the function timed out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call -:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>` +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()` function succeeds, but sets the ``POLLERR`` flag in the ``revents`` field. When the application has called :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the -:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in +:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in the ``revents`` field. For output devices this same situation will cause -:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and +:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and ``POLLWRNORM`` flags in the ``revents`` field. If an event occurred (see :ref:`VIDIOC_DQEVENT`) then ``POLLPRI`` will be set in the ``revents`` field and -:ref:`poll() <func-poll>` will return. +:c:func:`poll()` will return. -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`poll()` function starts capturing. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until data has been captured and can be read. When the driver captures continuously (as opposed to, for example, still images) the function may return immediately. -When use of the :ref:`write() <func-write>` function has been negotiated and the -driver does not stream yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`write()` function has been negotiated and the +driver does not stream yet, the :c:func:`poll()` function starts streaming. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until the driver is ready for a non-blocking -:ref:`write() <func-write>` call. +:c:func:`write()` call. If the caller is only interested in events (just ``POLLPRI`` is set in -the ``events`` field), then :ref:`poll() <func-poll>` will *not* start +the ``events`` field), then :c:func:`poll()` will *not* start streaming if the driver does not stream yet. This makes it possible to just poll for events and not for buffers. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`poll() <func-poll>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`poll()` function. -For more details see the :ref:`poll() <func-poll>` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :ref:`poll() <func-poll>` returns the number structures which have +On success, :c:func:`poll()` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/v4l/func-read.rst b/Documentation/userspace-api/media/v4l/func-read.rst index 56b255c595e1..e6f6ac4bed77 100644 --- a/Documentation/userspace-api/media/v4l/func-read.rst +++ b/Documentation/userspace-api/media/v4l/func-read.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-read: @@ -11,7 +12,6 @@ Name v4l2-read - Read from a V4L2 device - Synopsis ======== @@ -19,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: v4l2-read Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer to be filled @@ -38,48 +36,48 @@ Arguments Description =========== -:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file +:c:func:`read()` attempts to read up to ``count`` bytes from file descriptor ``fd`` into the buffer starting at ``buf``. The layout of the data in the buffer is discussed in the respective device interface -section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero +section, see ##. If ``count`` is zero, :c:func:`read()` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. Regardless of the ``count`` value each -:ref:`read() <func-read>` call will provide at most one frame (two fields) +:c:func:`read()` call will provide at most one frame (two fields) worth of data. -By default :ref:`read() <func-read>` blocks until data becomes available. When -the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` +By default :c:func:`read()` blocks until data becomes available. When +the ``O_NONBLOCK`` flag was given to the :c:func:`open()` function it returns immediately with an ``EAGAIN`` error code when no data -is available. The :ref:`select() <func-select>` or -:ref:`poll() <func-poll>` functions can always be used to suspend +is available. The :c:func:`select()` or +:c:func:`poll()` functions can always be used to suspend execution until data becomes available. All drivers supporting the -:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and -:ref:`poll() <func-poll>`. +:c:func:`read()` function must also support :c:func:`select()` and +:c:func:`poll()`. Drivers can implement read functionality in different ways, using a single or multiple buffers and discarding the oldest or newest frames once the internal buffers are filled. -:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled. +:c:func:`read()` never returns a "snapshot" of a buffer being filled. Using a single buffer the driver will stop capturing when the application starts reading the buffer until the read is finished. Thus only the period of the vertical blanking interval is available for reading, or the capture rate must fall below the nominal frame rate of the video standard. -The behavior of :ref:`read() <func-read>` when called during the active picture +The behavior of :c:func:`read()` when called during the active picture period or the vertical blanking separating the top and bottom field depends on the discarding policy. A driver discarding the oldest frames keeps capturing into an internal buffer, continuously overwriting the previously, not read frame, and returns the frame being received at the -time of the :ref:`read() <func-read>` call as soon as it is complete. +time of the :c:func:`read()` call as soon as it is complete. A driver discarding the newest frames stops capturing until the next -:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>` +:c:func:`read()` call. The frame being received at :c:func:`read()` time is discarded, returning the following frame instead. Again this implies a reduction of the capture rate to one half or less of the nominal frame rate. An example of this model is the video read mode of -the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>` +the bttv driver, initiating a DMA to user memory when :c:func:`read()` is called and returning when the DMA finished. In the multiple buffer model drivers maintain a ring of internal @@ -94,14 +92,13 @@ the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and however. The discarding policy is not reported and cannot be changed. For minimum requirements see :ref:`devices`. - Return Value ============ On success, the number of bytes read is returned. It is not an error if this number is smaller than the number of bytes requested, or the amount of data required for one frame. This may happen for example because -:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is +:c:func:`read()` was interrupted by a signal. On error, -1 is returned, and the ``errno`` variable is set appropriately. In this case the next read will start at the beginning of a new frame. Possible error codes are: @@ -129,5 +126,5 @@ EIO communicate with a remote device (USB camera etc.). EINVAL - The :ref:`read() <func-read>` function is not supported by this driver, not + The :c:func:`read()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/func-select.rst b/Documentation/userspace-api/media/v4l/func-select.rst index 6715d5efcc27..ba1879c728f0 100644 --- a/Documentation/userspace-api/media/v4l/func-select.rst +++ b/Documentation/userspace-api/media/v4l/func-select.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-select: @@ -11,7 +12,6 @@ Name v4l2-select - Synchronous I/O multiplexing - Synopsis ======== @@ -21,9 +21,7 @@ Synopsis #include <sys/types.h> #include <unistd.h> - .. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) - :name: v4l2-select Arguments ========= @@ -43,11 +41,10 @@ Arguments ``timeout`` Maximum time to wait. - Description =========== -With the :ref:`select() <func-select>` function applications can suspend +With the :c:func:`select()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -56,40 +53,39 @@ buffer has been filled or displayed and can be dequeued with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in the outgoing queue of the driver the function returns immediately. -On success :ref:`select() <func-select>` returns the total number of bits set in -:c:func:`struct fd_set`. When the function timed out it returns +On success :c:func:`select()` returns the total number of bits set in +``fd_set``. When the function timed out it returns a value of zero. On failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call :ref:`VIDIOC_QBUF` or -:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>` +:ref:`VIDIOC_STREAMON` yet the :c:func:`select()` function succeeds, setting the bit of the file descriptor in ``readfds`` or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` calls will fail. [#f1]_ -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`select() <func-select>` function starts -capturing. When that fails, :ref:`select() <func-select>` returns successful and -a subsequent :ref:`read() <func-read>` call, which also attempts to start +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`select()` function starts +capturing. When that fails, :c:func:`select()` returns successful and +a subsequent :c:func:`read()` call, which also attempts to start capturing, will return an appropriate error code. When the driver captures continuously (as opposed to, for example, still images) and -data is already available the :ref:`select() <func-select>` function returns +data is already available the :c:func:`select()` function returns immediately. -When use of the :ref:`write() <func-write>` function has been negotiated the -:ref:`select() <func-select>` function just waits until the driver is ready for a -non-blocking :ref:`write() <func-write>` call. +When use of the :c:func:`write()` function has been negotiated the +:c:func:`select()` function just waits until the driver is ready for a +non-blocking :c:func:`write()` call. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`select() <func-select>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`select()` function. -For more details see the :ref:`select() <func-select>` manual page. - +For more details see the :c:func:`select()` manual page. Return Value ============ -On success, :ref:`select() <func-select>` returns the number of descriptors +On success, :c:func:`select()` returns the number of descriptors contained in the three returned descriptor sets, which will be zero if the timeout expired. On error -1 is returned, and the ``errno`` variable is set appropriately; the sets and ``timeout`` are undefined. Possible @@ -115,6 +111,6 @@ EINVAL ``FD_SETSIZE``. .. [#f1] - The Linux kernel implements :ref:`select() <func-select>` like the - :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot + The Linux kernel implements :c:func:`select()` like the + :c:func:`poll()` function, but :c:func:`select()` cannot return a ``POLLERR``. diff --git a/Documentation/userspace-api/media/v4l/func-write.rst b/Documentation/userspace-api/media/v4l/func-write.rst index 37683611df04..49f5a0f4275f 100644 --- a/Documentation/userspace-api/media/v4l/func-write.rst +++ b/Documentation/userspace-api/media/v4l/func-write.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-write: @@ -11,7 +12,6 @@ Name v4l2-write - Write to a V4L2 device - Synopsis ======== @@ -19,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: v4l2-write Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer with data to be written @@ -38,10 +36,10 @@ Arguments Description =========== -:ref:`write() <func-write>` writes up to ``count`` bytes to the device +:c:func:`write()` writes up to ``count`` bytes to the device referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. When the hardware outputs are not active yet, this function -enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0 +enables them. When ``count`` is zero, :c:func:`write()` returns 0 without any other effect. When the application does not provide more data in time, the previous @@ -49,7 +47,6 @@ video frame, raw VBI image, sliced VPS or WSS data is displayed again. Sliced Teletext or Closed Caption data is not repeated, the driver inserts a blank line instead. - Return Value ============ @@ -80,5 +77,5 @@ EIO I/O error. This indicates some hardware problem. EINVAL - The :ref:`write() <func-write>` function is not supported by this driver, + The :c:func:`write()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index 1a4fd941f163..28a2750d5c8c 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _hist-v4l2: @@ -14,18 +15,17 @@ not just an extension but a replacement for the V4L API. However it took another four years and two stable kernel releases until the new API was finally accepted for inclusion into the kernel in its present form. - Early Versions ============== 1998-08-20: First version. -1998-08-27: The :ref:`select() <func-select>` function was introduced. +1998-08-27: The :c:func:`select()` function was introduced. 1998-09-10: New video standard interface. 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise -meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the +meaningless ``O_TRUNC`` :c:func:`open()` flag, and the aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set this flag if they intend to access controls only, as opposed to capture applications which need exclusive access. The ``VIDEO_STD_XXX`` @@ -65,7 +65,6 @@ output devices were added. 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. - V4L2 Version 0.16 1999-01-31 ============================ @@ -73,7 +72,6 @@ V4L2 Version 0.16 1999-01-31 are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added digital zoom (cropping) controls. - V4L2 Version 0.18 1999-03-16 ============================ @@ -81,7 +79,6 @@ Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver writers, this changes how you implement your ioctl handler. See the Driver Writer's Guide. Added some more control id codes. - V4L2 Version 0.19 1999-06-05 ============================ @@ -107,7 +104,6 @@ malfunction of this ioctl. 1999-06-05: Changed the value of V4L2_CID_WHITENESS. - V4L2 Version 0.20 (1999-09-10) ============================== @@ -128,14 +124,12 @@ common Linux driver API conventions. VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example - .. code-block:: c err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); becomes - .. code-block:: c int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); @@ -202,7 +196,6 @@ common Linux driver API conventions. field counts captured frames, it is ignored by output devices. When a capture driver drops a frame, the sequence number of that frame is skipped. - V4L2 Version 0.20 incremental changes ===================================== @@ -290,13 +283,11 @@ A number of changes were made to the raw VBI interface. were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the latter was missing in the ``videodev.h`` file. - V4L2 Version 0.20 2002-07-25 ============================ Added sliced VBI interface proposal. - V4L2 in Linux 2.5.46, 2002-10 ============================= @@ -307,7 +298,7 @@ This unnamed version was finally merged into Linux 2.5.46. 1. As specified in :ref:`related`, drivers must make related device functions available under all minor device numbers. -2. The :ref:`open() <func-open>` function requires access mode +2. The :c:func:`open()` function requires access mode ``O_RDWR`` regardless of the device type. All V4L2 drivers exchanging data with applications must support the ``O_NONBLOCK`` flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the @@ -435,7 +426,6 @@ This unnamed version was finally merged into Linux 2.5.46. the buffer type names changed as follows. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -597,7 +587,6 @@ This unnamed version was finally merged into Linux 2.5.46. V4L2 documentation was inaccurate, this has been corrected in :ref:`pixfmt`. - V4L2 2003-06-19 =============== @@ -648,7 +637,6 @@ V4L2 2003-06-19 Kernel 2.6.39. Drivers and applications assuming a constant parameter need an update. - V4L2 2003-11-05 =============== @@ -657,7 +645,6 @@ V4L2 2003-11-05 refer to bytes in memory, in ascending address order. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -678,7 +665,6 @@ V4L2 2003-11-05 - R, G, B, X - B, G, R, X - The ``V4L2_PIX_FMT_BGR24`` example was always correct. In :ref:`v4l-image-properties` the mapping of the V4L @@ -689,7 +675,6 @@ V4L2 2003-11-05 RGB pixel formats differently. These issues have yet to be addressed, for details see :ref:`pixfmt-rgb`. - V4L2 in Linux 2.6.6, 2004-05-09 =============================== @@ -698,7 +683,6 @@ V4L2 in Linux 2.6.6, 2004-05-09 ioctl, while the read-only version was renamed to ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. - V4L2 in Linux 2.6.8 =================== @@ -709,7 +693,6 @@ V4L2 in Linux 2.6.8 the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no longer read-only. - V4L2 spec erratum 2004-08-01 ============================ @@ -727,7 +710,6 @@ V4L2 spec erratum 2004-08-01 also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` error code was not documented. - V4L2 in Linux 2.6.14 ==================== @@ -735,7 +717,6 @@ V4L2 in Linux 2.6.14 :ref:`sliced` and replaces the interface first proposed in V4L2 specification 0.8. - V4L2 in Linux 2.6.15 ==================== @@ -755,7 +736,6 @@ V4L2 in Linux 2.6.15 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed in Linux 2.6.25.) - V4L2 spec erratum 2005-11-27 ============================ @@ -765,7 +745,6 @@ cropping is supported. In the video standard selection example in :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used the wrong argument type. - V4L2 spec erratum 2006-01-10 ============================ @@ -778,14 +757,12 @@ V4L2 spec erratum 2006-01-10 write-only as stated on its reference page. The ioctl changed in 2003 as noted above. - V4L2 spec erratum 2006-02-03 ============================ 1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe`` field gives the time in seconds, not microseconds. - V4L2 spec erratum 2006-02-04 ============================ @@ -808,7 +785,6 @@ V4L2 in Linux 2.6.17 ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. - V4L2 spec erratum 2006-09-23 (Draft 0.15) ========================================= @@ -837,7 +813,6 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15) extended from 224-239 to 224-255. Accordingly device file names ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. - V4L2 in Linux 2.6.18 ==================== @@ -852,7 +827,6 @@ V4L2 in Linux 2.6.18 ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` (:ref:`control-flags`). See :ref:`extended-controls` for details. - V4L2 in Linux 2.6.19 ==================== @@ -874,14 +848,12 @@ V4L2 in Linux 2.6.19 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was added. - V4L2 spec erratum 2006-10-12 (Draft 0.17) ========================================= 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not 4:2:2 format. - V4L2 in Linux 2.6.21 ==================== @@ -889,7 +861,6 @@ V4L2 in Linux 2.6.21 General Public License version two or later, and under a 3-clause BSD-style license. - V4L2 in Linux 2.6.22 ==================== @@ -914,7 +885,6 @@ V4L2 in Linux 2.6.22 This may **break compatibility** with existing applications. Drivers supporting the "host order RGB32" format are not known. - V4L2 in Linux 2.6.24 ==================== @@ -922,7 +892,6 @@ V4L2 in Linux 2.6.24 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and ``V4L2_PIX_FMT_YUV32`` were added. - V4L2 in Linux 2.6.25 ==================== @@ -949,7 +918,6 @@ V4L2 in Linux 2.6.25 interface in Linux 2.6.18, where finally removed from the ``videodev2.h`` header file. - V4L2 in Linux 2.6.26 ==================== @@ -959,7 +927,6 @@ V4L2 in Linux 2.6.26 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and ``V4L2_CID_COLOR_KILLER``. - V4L2 in Linux 2.6.27 ==================== @@ -971,7 +938,6 @@ V4L2 in Linux 2.6.27 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. - V4L2 in Linux 2.6.28 ==================== @@ -983,7 +949,6 @@ V4L2 in Linux 2.6.28 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. - V4L2 in Linux 2.6.29 ==================== @@ -999,7 +964,6 @@ V4L2 in Linux 2.6.29 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and ``V4L2_CID_PRIVACY``. - V4L2 in Linux 2.6.30 ==================== @@ -1007,7 +971,6 @@ V4L2 in Linux 2.6.30 2. New control ``V4L2_CID_COLORFX`` was added. - V4L2 in Linux 2.6.32 ==================== @@ -1034,21 +997,18 @@ V4L2 in Linux 2.6.32 9. Added Remote Controller chapter, describing the default Remote Controller mapping for media devices. - V4L2 in Linux 2.6.33 ==================== 1. Added support for Digital Video timings in order to support HDTV receivers and transmitters. - V4L2 in Linux 2.6.34 ==================== 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` controls to the :ref:`Camera controls class <camera-controls>`. - V4L2 in Linux 2.6.37 ==================== @@ -1057,7 +1017,6 @@ V4L2 in Linux 2.6.37 applications found that used it. It was originally scheduled for removal in 2.6.35. - V4L2 in Linux 2.6.39 ==================== @@ -1067,7 +1026,6 @@ V4L2 in Linux 2.6.39 drivers and applications. See :ref:`multi-planar API <planar-apis>` for details. - V4L2 in Linux 3.1 ================= @@ -1078,7 +1036,6 @@ V4L2 in Linux 3.1 Added V4L2_CTRL_TYPE_BITMASK. - V4L2 in Linux 3.2 ================= @@ -1089,7 +1046,6 @@ V4L2 in Linux 3.2 Does not affect the compatibility of current drivers and applications. See :ref:`selection API <selection-api>` for details. - V4L2 in Linux 3.3 ================= @@ -1099,7 +1055,6 @@ V4L2 in Linux 3.3 2. Added the device_caps field to struct v4l2_capabilities and added the new V4L2_CAP_DEVICE_CAPS capability. - V4L2 in Linux 3.4 ================= @@ -1110,7 +1065,6 @@ V4L2 in Linux 3.4 :ref:`VIDIOC_QUERY_DV_TIMINGS` and :ref:`VIDIOC_DV_TIMINGS_CAP`. - V4L2 in Linux 3.5 ================= @@ -1137,7 +1091,6 @@ V4L2 in Linux 3.5 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. - V4L2 in Linux 3.6 ================= @@ -1150,7 +1103,6 @@ V4L2 in Linux 3.6 3. Added support for frequency band enumerations: :ref:`VIDIOC_ENUM_FREQ_BANDS`. - V4L2 in Linux 3.9 ================= @@ -1160,7 +1112,6 @@ V4L2 in Linux 3.9 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See :ref:`ctrl-changes-flags`. - V4L2 in Linux 3.10 ================== @@ -1172,32 +1123,27 @@ V4L2 in Linux 3.10 2. Added new debugging ioctl :ref:`VIDIOC_DBG_G_CHIP_INFO`. - V4L2 in Linux 3.11 ================== 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. - V4L2 in Linux 3.14 ================== 1. In struct v4l2_rect, the type of ``width`` and ``height`` fields changed from _s32 to _u32. - V4L2 in Linux 3.15 ================== 1. Added Software Defined Radio (SDR) Interface. - V4L2 in Linux 3.16 ================== 1. Added event V4L2_EVENT_SOURCE_CHANGE. - V4L2 in Linux 3.17 ================== @@ -1207,14 +1153,12 @@ V4L2 in Linux 3.17 2. Added compound control types and :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. - V4L2 in Linux 3.18 ================== 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera controls. - V4L2 in Linux 3.19 ================== @@ -1232,13 +1176,11 @@ V4L2 in Linux 4.4 3. Added transmitter support for Software Defined Radio (SDR) Interface. - .. _other: Relation of V4L2 to other Linux multimedia APIs =============================================== - .. _xvideo: X Video Extension @@ -1284,7 +1226,6 @@ YUV to RGB conversion and scaling for faster video playback, and added an interface to MPEG-2 decoding hardware. This API is useful to display images captured with V4L2 devices. - Digital Video ------------- @@ -1294,13 +1235,11 @@ homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both. - Audio Interfaces ---------------- [to do - OSS/ALSA] - .. _experimental: Experimental API Elements @@ -1314,7 +1253,6 @@ change in the future. - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. - .. _obsolete: Obsolete API Elements diff --git a/Documentation/userspace-api/media/v4l/io.rst b/Documentation/userspace-api/media/v4l/io.rst index 9dc36b41dbf6..ce0cece6f35f 100644 --- a/Documentation/userspace-api/media/v4l/io.rst +++ b/Documentation/userspace-api/media/v4l/io.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _io: @@ -9,8 +10,8 @@ The V4L2 API defines several different methods to read from or write to a device. All drivers exchanging data with applications must support at least one of them. -The classic I/O method using the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function is automatically selected after opening a +The classic I/O method using the :c:func:`read()` and +:c:func:`write()` function is automatically selected after opening a V4L2 device. When the driver does not support this method attempts to read or write will fail at any time. @@ -38,7 +39,6 @@ closing and reopening the device. The following sections describe the various I/O methods in more detail. - .. toctree:: :maxdepth: 1 diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst index e03280b35570..05690f2358ce 100644 --- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst +++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _libv4l-introduction: @@ -17,7 +18,6 @@ An example of using libv4l is provided by libv4l consists of 3 different libraries: - libv4lconvert ============= @@ -65,7 +65,6 @@ libv4lconvert/processing. These controls are stored application wide libv4lconvert/processing offers the actual video processing functionality. - libv4l1 ======= @@ -78,7 +77,6 @@ just pass calls through. Since those functions are emulations of the old V4L1 API, it shouldn't be used for new applications. - libv4l2 ======= @@ -105,7 +103,6 @@ available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>` keeps enumerating the hardware supported formats, plus the emulated formats offered by libv4l at the end. - .. _libv4l-ops: Libv4l device control functions @@ -115,17 +112,17 @@ The common file operation methods are provided by libv4l. Those functions operate just like the gcc function ``dup()`` and V4L2 functions -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`read() <v4l2-read>`, -:c:func:`mmap() <v4l2-mmap>` and :c:func:`munmap() <v4l2-munmap>`: +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`read()`, +:c:func:`mmap()` and :c:func:`munmap()`: .. c:function:: int v4l2_open(const char *file, int oflag, ...) - operates like the :c:func:`open() <v4l2-open>` function. + operates like the :c:func:`open()` function. .. c:function:: int v4l2_close(int fd) - operates like the :c:func:`close() <v4l2-close>` function. + operates like the :c:func:`close()` function. .. c:function:: int v4l2_dup(int fd) @@ -133,19 +130,19 @@ V4L2 functions .. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...) - operates like the :c:func:`ioctl() <v4l2-ioctl>` function. + operates like the :c:func:`ioctl()` function. .. c:function:: int v4l2_read (int fd, void* buffer, size_t n) - operates like the :c:func:`read() <v4l2-read>` function. + operates like the :c:func:`read()` function. .. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`munmap()` function. .. c:function:: int v4l2_munmap(void *_start, size_t length); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`munmap()` function. Those functions provide additional control: @@ -168,14 +165,13 @@ Those functions provide additional control: of the given v4l control id. when the cid does not exist, could not be accessed for some reason, or some error occurred 0 is returned. - v4l1compat.so wrapper library ============================= This library intercepts calls to -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`mmap() <v4l2-mmap>` and -:c:func:`munmap() <v4l2-munmap>` +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`mmap()` and +:c:func:`munmap()` operations and redirects them to the libv4l counterparts, by using ``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2 API. diff --git a/Documentation/userspace-api/media/v4l/mmap.rst b/Documentation/userspace-api/media/v4l/mmap.rst index 1cce31c6de79..16b1e13b029f 100644 --- a/Documentation/userspace-api/media/v4l/mmap.rst +++ b/Documentation/userspace-api/media/v4l/mmap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _mmap: @@ -35,22 +36,22 @@ This ioctl can also be used to change the number of buffers or to free the allocated memory, provided none of the buffers are still mapped. Before applications can access the buffers they must map them into their -address space with the :ref:`mmap() <func-mmap>` function. The +address space with the :c:func:`mmap()` function. The location of the buffers in device memory can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar API case, the ``m.offset`` and ``length`` returned in a struct :c:type:`v4l2_buffer` are passed as sixth and second -parameter to the :ref:`mmap() <func-mmap>` function. When using the +parameter to the :c:func:`mmap()` function. When using the multi-planar API, struct :c:type:`v4l2_buffer` contains an array of struct :c:type:`v4l2_plane` structures, each containing its own ``m.offset`` and ``length``. When using the multi-planar API, every plane of every buffer has to be mapped -separately, so the number of calls to :ref:`mmap() <func-mmap>` should +separately, so the number of calls to :c:func:`mmap()` should be equal to number of buffers times number of planes in each buffer. The offset and length values must not be modified. Remember, the buffers are allocated in physical memory, as opposed to virtual memory, which can be swapped out to disk. Applications should free the buffers as soon as -possible with the :ref:`munmap() <func-munmap>` function. +possible with the :c:func:`munmap()` function. Example: Mapping buffers in the single-planar API ================================================= @@ -122,7 +123,6 @@ Example: Mapping buffers in the single-planar API for (i = 0; i < reqbuf.count; i++) munmap(buffers[i].start, buffers[i].length); - Example: Mapping buffers in the multi-planar API ================================================ @@ -238,10 +238,10 @@ be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` -flag was given to the :ref:`open() <func-open>` function, +flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` -error code when no buffer is available. The :ref:`select() <func-select>` -or :ref:`poll() <func-poll>` functions are always available. +error code when no buffer is available. The :c:func:`select()` +or :c:func:`poll()` functions are always available. To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF @@ -259,15 +259,15 @@ Drivers implementing memory mapping I/O must support the <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() -<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select() -<func-select>` and :ref:`poll() <func-poll>` function. [#f3]_ +<func-mmap>`, :c:func:`munmap()`, :ref:`select() +<func-select>` and :c:func:`poll()` function. [#f3]_ [capture example] .. [#f1] One could use one file descriptor and set the buffer type field accordingly when calling :ref:`VIDIOC_QBUF` etc., - but it makes the :ref:`select() <func-select>` function ambiguous. We also + but it makes the :c:func:`select()` function ambiguous. We also like the clean approach of one file descriptor per logical stream. Video overlay for example is also a logical stream, although the CPU is not needed for continuous operation. @@ -280,6 +280,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() scatter-gather lists and the like. .. [#f3] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 4e8fd216a1b0..18bfb9b8137d 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _open: @@ -140,7 +141,6 @@ means applications cannot *reliably* scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names. - .. _related: Related Devices @@ -157,7 +157,7 @@ support all functions. However, in practice this never worked: this support it and if they did it was certainly never tested. In addition, switching a device node between different functions only works when using the streaming I/O API, not with the -:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. +:c:func:`read()`/\ :c:func:`write()` API. Today each V4L2 device node supports just one function. @@ -178,7 +178,6 @@ the Media Controller. If you want to work on this please write to the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Multiple Opens ============== @@ -192,8 +191,8 @@ device should not change the state of the device. [#f2]_ Once an application has allocated the memory buffers needed for streaming data (by calling the :ref:`VIDIOC_REQBUFS` or :ref:`VIDIOC_CREATE_BUFS` ioctls, or -implicitly by calling the :ref:`read() <func-read>` or -:ref:`write() <func-write>` functions) that application (filehandle) +implicitly by calling the :c:func:`read()` or +:c:func:`write()` functions) that application (filehandle) becomes the owner of the device. It is no longer allowed to make changes that would affect the buffer sizes (e.g. by calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are @@ -206,7 +205,6 @@ requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in :ref:`app-pri`. - Shared Data Streams =================== @@ -215,12 +213,11 @@ the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space. - Functions ========= To open and close V4L2 devices applications use the -:ref:`open() <func-open>` and :ref:`close() <func-close>` function, +:c:func:`open()` and :c:func:`close()` function, respectively. Devices are programmed using the :ref:`ioctl() <func-ioctl>` function as explained in the following sections. @@ -228,7 +225,7 @@ sections. .. [#f1] There are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such - drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code + drivers :c:func:`open()` can return an ``EBUSY`` error code when the device is already in use. .. [#f2] diff --git a/Documentation/userspace-api/media/v4l/rw.rst b/Documentation/userspace-api/media/v4l/rw.rst index 43609a27c3ec..64b85fb2a328 100644 --- a/Documentation/userspace-api/media/v4l/rw.rst +++ b/Documentation/userspace-api/media/v4l/rw.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rw: @@ -6,8 +7,8 @@ Read/Write ********** -Input and output devices support the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function, respectively, when the +Input and output devices support the :c:func:`read()` and +:c:func:`write()` function, respectively, when the ``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl is set. @@ -22,18 +23,17 @@ However this is also the simplest I/O method, requiring little or no setup to exchange data. It permits command line stunts like this (the vidctrl tool is fictitious): - .. code-block:: none $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 $ dd if=/dev/video of=myimage.422 bs=202752 count=1 -To read from the device applications use the :ref:`read() <func-read>` -function, to write the :ref:`write() <func-write>` function. Drivers +To read from the device applications use the :c:func:`read()` +function, to write the :c:func:`write()` function. Drivers must implement one I/O method if they exchange data with applications, but it need not be this. [#f1]_ When reading or writing is supported, the -driver must also support the :ref:`select() <func-select>` and -:ref:`poll() <func-poll>` function. [#f2]_ +driver must also support the :c:func:`select()` and +:c:func:`poll()` function. [#f2]_ .. [#f1] It would be desirable if applications could depend on drivers @@ -43,5 +43,5 @@ driver must also support the :ref:`select() <func-select>` and capturing still images. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. diff --git a/Documentation/userspace-api/media/v4l/streaming-par.rst b/Documentation/userspace-api/media/v4l/streaming-par.rst index cc2e8fcecc7e..806cbfdad0f1 100644 --- a/Documentation/userspace-api/media/v4l/streaming-par.rst +++ b/Documentation/userspace-api/media/v4l/streaming-par.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _streaming-par: @@ -14,13 +15,13 @@ The current video standard determines a nominal number of frames per second. If less than this number of frames is to be captured or output, applications can request frame skipping or duplicating on the driver side. This is especially useful when using the -:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are +:c:func:`read()` or :c:func:`write()`, which are not augmented by timestamps or sequence counters, and to avoid unnecessary data copying. Finally these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c:func:`read()` function. To get and set the streaming parameters applications call the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and diff --git a/Documentation/userspace-api/media/v4l/userp.rst b/Documentation/userspace-api/media/v4l/userp.rst index 5b7321907dab..db224f9b611e 100644 --- a/Documentation/userspace-api/media/v4l/userp.rst +++ b/Documentation/userspace-api/media/v4l/userp.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _userp: @@ -78,10 +79,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The :ref:`select() -<func-select>` or :ref:`poll() <func-poll>` function are always +<func-select>` or :c:func:`poll()` function are always available. To start and stop capturing or output applications call the @@ -101,7 +102,7 @@ Drivers implementing user pointer I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_ +:c:func:`select()` and :c:func:`poll()` function. [#f2]_ .. [#f1] We expect that frequently used buffers are typically not swapped out. @@ -116,6 +117,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the because an application may share them with other processes. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index d999028f47df..b06e5b528e11 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CREATE_BUFS: @@ -11,24 +12,22 @@ Name VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp ) - :name: VIDIOC_CREATE_BUFS +.. c:macro:: VIDIOC_CREATE_BUFS +``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_create_buffers`. - Description =========== @@ -71,7 +70,6 @@ the actual number allocated and the starting index in the ``count`` and the ``index`` fields respectively. On return ``count`` can be smaller than the number requested. - .. c:type:: v4l2_create_buffers .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -119,7 +117,6 @@ than the number requested. - A place holder for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index aa02c312824e..00c31410d4e4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CROPCAP: @@ -11,24 +12,22 @@ Name VIDIOC_CROPCAP - Information about the video cropping and scaling abilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp ) - :name: VIDIOC_CROPCAP +.. c:macro:: VIDIOC_CROPCAP +``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_cropcap`. - Description =========== @@ -95,7 +94,6 @@ overlay devices. Starting with kernel 4.13 both variations are allowed. - .. _v4l2-rect-crop: .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -120,7 +118,6 @@ overlay devices. - ``height`` - Height of the rectangle, in pixels. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst index a2541329b30a..bde6e952b267 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_CHIP_INFO: @@ -11,24 +12,22 @@ Name VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp ) - :name: VIDIOC_DBG_G_CHIP_INFO +.. c:macro:: VIDIOC_DBG_G_CHIP_INFO +``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_chip_info`. - Description =========== @@ -76,7 +75,6 @@ is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| .. _name-v4l2-dbg-match: @@ -103,7 +101,6 @@ instructions. - - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_dbg_chip_info @@ -130,7 +127,6 @@ instructions. - Reserved fields, both application and driver must set these to 0. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _name-chip-match-types: @@ -148,7 +144,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst index 350a04eb0e86..e1a6abe705bd 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_REGISTER: @@ -11,27 +12,26 @@ Name VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_G_REGISTER +.. c:macro:: VIDIOC_DBG_G_REGISTER + +``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_S_REGISTER +.. c:macro:: VIDIOC_DBG_S_REGISTER +``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_register`. - Description =========== @@ -85,7 +85,6 @@ It is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| .. c:type:: v4l2_dbg_match @@ -112,7 +111,6 @@ instructions. - - .. c:type:: v4l2_dbg_register .. flat-table:: struct v4l2_dbg_register @@ -133,7 +131,6 @@ instructions. - The value read from, or to be written into the register. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _chip-match-types: @@ -151,7 +148,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst index 0ef757f061e3..fd71ceece037 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DECODER_CMD: @@ -11,28 +12,26 @@ Name VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_DECODER_CMD +.. c:macro:: VIDIOC_DECODER_CMD +``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_TRY_DECODER_CMD +.. c:macro:: VIDIOC_TRY_DECODER_CMD +``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`v4l2_decoder_cmd`. - Description =========== @@ -47,11 +46,11 @@ this structure. The ``cmd`` field must contain the command code. Some commands use the ``flags`` field for additional information. -A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` +A :c:func:`write()` or :ref:`VIDIOC_STREAMON` call sends an implicit START command to the decoder if it has not been started yet. Applies to both queues of mem2mem decoders. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP command to the decoder, and all buffered data is discarded. Applies to both queues of mem2mem decoders. @@ -60,7 +59,6 @@ In principle, these ioctls are optional, not all drivers may support them. They introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders (as further documented in :ref:`decoder`). - .. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| .. c:type:: v4l2_decoder_cmd @@ -131,7 +129,6 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod - - .. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| .. _decoder-cmds: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index f0dfc8cf9b14..634af717c8ba 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DQEVENT: @@ -11,24 +12,22 @@ Name VIDIOC_DQEVENT - Dequeue event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) - :name: VIDIOC_DQEVENT +.. c:macro:: VIDIOC_DQEVENT +``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event`. - Description =========== @@ -38,7 +37,6 @@ structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. - .. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| .. c:type:: v4l2_event @@ -100,7 +98,6 @@ call. zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. cssclass:: longtable @@ -191,7 +188,6 @@ call. - Base event number for driver-private events. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_event_vsync @@ -206,7 +202,6 @@ call. - The upcoming field. See enum :c:type:`v4l2_field`. - .. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| .. c:type:: v4l2_event_ctrl @@ -257,7 +252,6 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_event_frame_sync @@ -272,7 +266,6 @@ call. - The sequence number of the frame being received. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_event_src_change @@ -288,7 +281,6 @@ call. :ref:`src-changes-flags`. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_event_motion_det @@ -318,7 +310,6 @@ call. automatically assigned to the default region 0. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _ctrl-changes-flags: @@ -344,7 +335,6 @@ call. step or the default value of the control changed. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _src-changes-flags: @@ -375,7 +365,6 @@ call. loss of signal and so restarting streaming I/O is required in order for the hardware to synchronize to the video signal. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst index 82bb732893be..27bd6a83e42c 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DV_TIMINGS_CAP: @@ -11,27 +12,26 @@ Name VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_DV_TIMINGS_CAP + +``int ioctl(int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_SUBDEV_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_SUBDEV_DV_TIMINGS_CAP +``int ioctl(int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings_cap`. - Description =========== @@ -55,7 +55,6 @@ the desired pad number in the struct zero the ``reserved`` array. Attempts to query capabilities on a pad that doesn't support them will return an ``EINVAL`` error code. - .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| .. c:type:: v4l2_bt_timings_cap @@ -97,7 +96,6 @@ that doesn't support them will return an ``EINVAL`` error code. Drivers must set the array to zero. - .. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}| .. c:type:: v4l2_dv_timings_cap @@ -153,7 +151,6 @@ that doesn't support them will return an ``EINVAL`` error code. - Can support non-standard timings, i.e. timings not belonging to the standards set in the ``standards`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 44aad55d9459..5673606711b4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENCODER_CMD: @@ -11,22 +12,22 @@ Name VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_ENCODER_CMD +.. c:macro:: VIDIOC_ENCODER_CMD + +``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_TRY_ENCODER_CMD +.. c:macro:: VIDIOC_TRY_ENCODER_CMD +``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_encoder_cmd`. @@ -47,16 +48,16 @@ this structure. The ``cmd`` field must contain the command code. Some commands use the ``flags`` field for additional information. -After a STOP command, :ref:`read() <func-read>` calls will read +After a STOP command, :c:func:`read()` calls will read the remaining data buffered by the driver. When the buffer is empty, -:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` +:c:func:`read()` will return zero and the next :c:func:`read()` call will restart the encoder. -A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` call sends an implicit START command to the encoder if it has not been started yet. Applies to both queues of mem2mem encoders. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP to the encoder, and all buffered data is discarded. Applies to both queues of mem2mem encoders. @@ -65,7 +66,6 @@ These ioctls are optional, not all drivers may support them. They were introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem encoders (as further documented in :ref:`encoder`). - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_encoder_cmd @@ -89,7 +89,6 @@ encoders (as further documented in :ref:`encoder`). the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _encoder-cmds: @@ -134,7 +133,6 @@ encoders (as further documented in :ref:`encoder`). the encoder is already running, this command does nothing. No flags are defined for this command. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _encoder-flags: @@ -151,7 +149,6 @@ encoders (as further documented in :ref:`encoder`). Does not apply to :ref:`encoder`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst index bb74096cfbd8..20730cd4f6ef 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_DV_TIMINGS: @@ -11,27 +12,26 @@ Name VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_ENUM_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enum_dv_timings`. - Description =========== @@ -65,7 +65,6 @@ pad number in the struct Attempts to enumerate timings on a pad that doesn't support them will return an ``EINVAL`` error code. - .. c:type:: v4l2_enum_dv_timings .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -91,7 +90,6 @@ return an ``EINVAL`` error code. - ``timings`` - The timings. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index b8347a96a554..2b3fa9c23146 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FMT: @@ -11,24 +12,22 @@ Name VIDIOC_ENUM_FMT - Enumerate image formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp ) - :name: VIDIOC_ENUM_FMT +.. c:macro:: VIDIOC_ENUM_FMT +``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_fmtdesc`. - Description =========== @@ -72,7 +71,6 @@ the ``mbus_code`` field is handled differently: formats shall not depend on the active configuration of the video device or device pipeline. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_fmtdesc @@ -137,7 +135,6 @@ the ``mbus_code`` field is handled differently: zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _fmtdesc-flags: @@ -227,7 +224,6 @@ the ``mbus_code`` field is handled differently: device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst index 68469756e6c7..1f0949726045 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMEINTERVALS: @@ -11,25 +12,23 @@ Name VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp ) - :name: VIDIOC_ENUM_FRAMEINTERVALS +.. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS +``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmivalenum` that contains a pixel format and size and receives a frame interval. - Description =========== @@ -91,7 +90,6 @@ other ioctl calls while it runs the frame interval enumeration. frame_rate = 1 / frame_interval - Structs ======= @@ -99,7 +97,6 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmival_stepwise .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -120,7 +117,6 @@ application should zero out all members except for the *IN* fields. - Frame interval step size [s]. - .. c:type:: v4l2_frmivalenum .. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| @@ -163,11 +159,9 @@ application should zero out all members except for the *IN* fields. applications. - Enums ===== - .. c:type:: v4l2_frmivaltypes .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| @@ -187,7 +181,6 @@ Enums - 3 - Step-wise defined frame interval. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst index dc4e0e216e7e..c9a36bcf699f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMESIZES: @@ -11,26 +12,24 @@ Name VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp ) - :name: VIDIOC_ENUM_FRAMESIZES +.. c:macro:: VIDIOC_ENUM_FRAMESIZES +``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmsizeenum` that contains an index and pixel format and receives a frame width and height. - Description =========== @@ -81,7 +80,6 @@ without any interaction from the application itself. This means that the enumeration data is consistent if the application does not perform any other ioctl calls while it runs the frame size enumeration. - Structs ======= @@ -89,7 +87,6 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmsize_discrete .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -107,7 +104,6 @@ application should zero out all members except for the *IN* fields. - Height of the frame [pixel]. - .. c:type:: v4l2_frmsize_stepwise .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -137,7 +133,6 @@ application should zero out all members except for the *IN* fields. - Frame height step size [pixel]. - .. c:type:: v4l2_frmsizeenum .. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}| @@ -173,11 +168,9 @@ application should zero out all members except for the *IN* fields. applications. - Enums ===== - .. c:type:: v4l2_frmsizetypes .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| @@ -197,7 +190,6 @@ Enums - 3 - Step-wise defined frame size. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst index 2dabf542b20f..a0764fca8d18 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FREQ_BANDS: @@ -11,24 +12,22 @@ Name VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp ) - :name: VIDIOC_ENUM_FREQ_BANDS +.. c:macro:: VIDIOC_ENUM_FREQ_BANDS +``int ioctl(int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency_band`. - Description =========== @@ -41,7 +40,6 @@ fields, and zero out the ``reserved`` array of a struct This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. - .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| .. c:type:: v4l2_frequency_band @@ -110,7 +108,6 @@ of the corresponding tuner/modulator is set. Applications and drivers must set the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _band-modulation: @@ -130,7 +127,6 @@ of the corresponding tuner/modulator is set. - 0x08 - Amplitude Modulation, commonly used for analog radio. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst index 6cf06ac0bb70..7873e5434d3e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDIO: @@ -11,24 +12,22 @@ Name VIDIOC_ENUMAUDIO - Enumerate audio inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_ENUMAUDIO +.. c:macro:: VIDIOC_ENUMAUDIO +``int ioctl(int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -43,7 +42,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct :c:type:`v4l2_audio`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst index b4a42ea397db..d4c3ba320834 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDOUT: @@ -11,24 +12,22 @@ Name VIDIOC_ENUMAUDOUT - Enumerate audio outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_ENUMAUDOUT +.. c:macro:: VIDIOC_ENUMAUDOUT +``int ioctl(int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -48,7 +47,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct :c:type:`v4l2_audioout`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst index 714688f81e23..0f62e681a827 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMINPUT: @@ -11,24 +12,22 @@ Name VIDIOC_ENUMINPUT - Enumerate video inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp ) - :name: VIDIOC_ENUMINPUT +.. c:macro:: VIDIOC_ENUMINPUT +``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_input`. - Description =========== @@ -39,7 +38,6 @@ fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_input @@ -103,7 +101,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _input-type: @@ -126,7 +123,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input is a touch device for capturing raw touch data. - .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| .. _input-status: @@ -198,7 +194,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - VTR time constant. [?] - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _input-capabilities: @@ -222,7 +217,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst index 272a0b2b475c..91fcf99094d2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMOUTPUT: @@ -11,24 +12,22 @@ Name VIDIOC_ENUMOUTPUT - Enumerate video outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp ) - :name: VIDIOC_ENUMOUTPUT +.. c:macro:: VIDIOC_ENUMOUTPUT +``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_output`. - Description =========== @@ -40,7 +39,6 @@ when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_output @@ -98,7 +96,6 @@ shall begin at index zero, incrementing by one until the driver returns zero. - .. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| .. _output-type: @@ -121,7 +118,6 @@ shall begin at index zero, incrementing by one until the driver returns - The video output will be copied to a :ref:`video overlay <overlay>`. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _output-capabilities: @@ -145,7 +141,6 @@ shall begin at index zero, incrementing by one until the driver returns ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst index 85bc6d0231f1..b5704e8cf909 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMSTD: @@ -11,27 +12,26 @@ Name VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_ENUMSTD +.. c:macro:: VIDIOC_ENUMSTD + +``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_SUBDEV_ENUMSTD +.. c:macro:: VIDIOC_SUBDEV_ENUMSTD +``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_standard`. - Description =========== @@ -45,7 +45,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. Drivers may enumerate a different set of standards after switching the video input or output. [#f1]_ - .. c:type:: v4l2_standard .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -85,7 +84,6 @@ or output. [#f1]_ zero. - .. c:type:: v4l2_fract .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -102,7 +100,6 @@ or output. [#f1]_ - ``denominator`` - - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. _v4l2-std-id: @@ -120,7 +117,6 @@ or output. [#f1]_ standards. - .. code-block:: c #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) @@ -142,7 +138,6 @@ rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some PAL video recorders can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic PAL TV. - .. code-block:: c #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) @@ -152,7 +147,6 @@ a 50/60 Hz agnostic PAL TV. ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC color modulation with a 4.43 MHz color subcarrier. - .. code-block:: c #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) @@ -175,7 +169,6 @@ terrestrial digital TV standards. Presently the V4L2 API does not support digital TV. See also the Linux DVB API at `https://linuxtv.org <https://linuxtv.org>`__. - .. code-block:: c #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | @@ -228,7 +221,6 @@ support digital TV. See also the Linux DVB API at #define V4L2_STD_ALL (V4L2_STD_525_60 | V4L2_STD_625_50) - .. raw:: latex \begingroup @@ -303,7 +295,6 @@ support digital TV. See also the Linux DVB API at \endgroup - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst index a2c475a83a58..212377c90442 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_EXPBUF: @@ -11,24 +12,22 @@ Name VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp ) - :name: VIDIOC_EXPBUF +.. c:macro:: VIDIOC_EXPBUF +``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_exportbuffer`. - Description =========== @@ -63,11 +62,9 @@ for details about importing DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it is no longer used to allow the associated memory to be reclaimed. - Examples ======== - .. code-block:: c int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd) @@ -87,7 +84,6 @@ Examples return 0; } - .. code-block:: c int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index, @@ -114,7 +110,6 @@ Examples return 0; } - .. c:type:: v4l2_exportbuffer .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -155,7 +150,6 @@ Examples - Reserved field for future use. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst index 38667864355a..4c93bd55bd97 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDIO: @@ -11,27 +12,26 @@ Name VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_G_AUDIO +.. c:macro:: VIDIOC_G_AUDIO + +``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp ) - :name: VIDIOC_S_AUDIO +.. c:macro:: VIDIOC_S_AUDIO +``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -49,7 +49,6 @@ ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_audio @@ -80,7 +79,6 @@ return the actual new audio mode. the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _audio-capability: @@ -101,7 +99,6 @@ return the actual new audio mode. - Automatic Volume Level mode is supported. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _audio-mode: @@ -115,7 +112,6 @@ return the actual new audio mode. - 0x00001 - AVL mode is on. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst index 5bf56723c7ba..194f22493517 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDOUT: @@ -11,27 +12,26 @@ Name VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_G_AUDOUT +.. c:macro:: VIDIOC_G_AUDOUT + +``int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp ) - :name: VIDIOC_S_AUDOUT +.. c:macro:: VIDIOC_S_AUDOUT +``int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -56,7 +56,6 @@ as ``VIDIOC_G_AUDOUT`` does. Connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense. - .. c:type:: v4l2_audioout .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -87,7 +86,6 @@ as ``VIDIOC_G_AUDOUT`` does. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst index 735a6bf5e025..0ac1509e41cc 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CROP: @@ -11,27 +12,26 @@ Name VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp ) - :name: VIDIOC_G_CROP +.. c:macro:: VIDIOC_G_CROP + +``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp ) - :name: VIDIOC_S_CROP +.. c:macro:: VIDIOC_S_CROP +``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_crop`. - Description =========== @@ -69,7 +69,6 @@ been negotiated. When cropping is not supported then no parameters are changed and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. - .. c:type:: v4l2_crop .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -100,7 +99,6 @@ When cropping is not supported then no parameters are changed and Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst index d863c849be95..4f1bed53fad5 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CTRL: @@ -11,27 +12,26 @@ Name VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_G_CTRL +.. c:macro:: VIDIOC_G_CTRL + +``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_S_CTRL +.. c:macro:: VIDIOC_S_CTRL +``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_control`. - Description =========== @@ -55,7 +55,6 @@ These ioctls work only with user controls. For other control classes the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. - .. c:type:: v4l2_control .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -72,7 +71,6 @@ These ioctls work only with user controls. For other control classes the - ``value`` - New value or current value. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst index e5a58db574d4..760a33d43b7d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_DV_TIMINGS: @@ -11,33 +12,34 @@ Name VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_G_DV_TIMINGS +.. c:macro:: VIDIOC_G_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` + +.. c:macro:: VIDIOC_S_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_S_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_G_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_S_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -60,7 +62,6 @@ the current input or output does not support DV timings (e.g. if :ref:`VIDIOC_ENUMINPUT` does not set the ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned. - Return Value ============ @@ -170,7 +171,6 @@ EPERM - Reserved for future extensions. Drivers and applications must set the array to zero. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| .. c:type:: v4l2_dv_timings diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst index 6a9ed2915cb9..39d523a449a7 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EDID: @@ -11,34 +12,34 @@ Name VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_G_EDID +.. c:macro:: VIDIOC_G_EDID + +``int ioctl(int fd, VIDIOC_G_EDID, struct v4l2_edid *argp)`` + +.. c:macro:: VIDIOC_S_EDID -.. c:function:: int ioctl( int fd, VIDIOC_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_S_EDID +``int ioctl(int fd, VIDIOC_S_EDID, struct v4l2_edid *argp)`` +.. c:macro:: VIDIOC_SUBDEV_G_EDID -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_G_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_S_EDID +.. c:macro:: VIDIOC_SUBDEV_S_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_edid`. - Description =========== @@ -97,7 +98,6 @@ this will drive the hotplug pin low and/or block the source from reading the EDID data in some way. In any case, the end result is the same: the EDID is no longer available. - .. c:type:: v4l2_edid .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -132,7 +132,6 @@ EDID is no longer available. - Pointer to memory that contains the EDID. The minimum size is ``blocks`` * 128. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst index 99cddf3b9888..7698e65ccccf 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_ENC_INDEX: @@ -11,24 +12,22 @@ Name VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp ) - :name: VIDIOC_G_ENC_INDEX +.. c:macro:: VIDIOC_G_ENC_INDEX +``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enc_idx`. - Description =========== @@ -55,7 +54,6 @@ will be zero. Currently this ioctl is only defined for MPEG-2 program streams and video elementary streams. - .. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| .. c:type:: v4l2_enc_idx @@ -83,7 +81,6 @@ video elementary streams. their ``offset``. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_enc_idx_entry @@ -116,7 +113,6 @@ video elementary streams. - Reserved for future extensions. Drivers must set the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _enc-idx-flags: @@ -140,7 +136,6 @@ video elementary streams. - *AND* the flags field with this mask to obtain the picture coding type. - Return Value ============ 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 0991af626591..f2173e310d67 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EXT_CTRLS: @@ -11,32 +12,30 @@ Name VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_G_EXT_CTRLS +.. c:macro:: VIDIOC_G_EXT_CTRLS +``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_S_EXT_CTRLS +.. c:macro:: VIDIOC_S_EXT_CTRLS +``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_TRY_EXT_CTRLS +.. c:macro:: VIDIOC_TRY_EXT_CTRLS +``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_ext_controls`. - Description =========== @@ -119,7 +118,6 @@ correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can still cause this situation. - .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| .. c:type:: v4l2_ext_control @@ -195,7 +193,6 @@ still cause this situation. * - } - - .. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}| .. c:type:: v4l2_ext_controls @@ -309,7 +306,6 @@ still cause this situation. Ignored if ``count`` equals zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _ctrl-class: @@ -363,7 +359,6 @@ still cause this situation. - The class containing RF tuner controls. These controls are described in :ref:`rf-tuner-controls`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index 7e1a0b812754..dc1f16343b22 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FBUF: @@ -11,27 +12,26 @@ Name VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp ) - :name: VIDIOC_G_FBUF +.. c:macro:: VIDIOC_G_FBUF + +``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp ) - :name: VIDIOC_S_FBUF +.. c:macro:: VIDIOC_S_FBUF +``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_framebuffer`. - Description =========== @@ -75,7 +75,6 @@ jeopardize the system security, its stability or even damage the hardware, therefore only the superuser can set the parameters for a destructive video overlay. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| .. c:type:: v4l2_framebuffer @@ -208,7 +207,6 @@ destructive video overlay. - ``priv`` - Reserved. Drivers and applications must set this field to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _framebuffer-cap: @@ -257,7 +255,6 @@ destructive video overlay. chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _framebuffer-flags: @@ -332,7 +329,6 @@ destructive video overlay. other, so same ``chromakey`` field of struct :c:type:`v4l2_window` is being used. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst index 7d113451bfbc..7e9f8475ea63 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FMT: @@ -11,29 +12,30 @@ Name VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp ) - :name: VIDIOC_G_FMT +.. c:macro:: VIDIOC_G_FMT + +``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)`` + +.. c:macro:: VIDIOC_S_FMT + +``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp ) - :name: VIDIOC_S_FMT +.. c:macro:: VIDIOC_TRY_FMT -.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp ) - :name: VIDIOC_TRY_FMT +``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_format`. - Description =========== @@ -85,7 +87,6 @@ recommended drivers are not required to implement this ioctl. The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. - .. c:type:: v4l2_format .. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| @@ -135,7 +136,6 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical * - } - - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst index da0d5dee72ff..5445a4a442e4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FREQUENCY: @@ -11,27 +12,26 @@ Name VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp ) - :name: VIDIOC_G_FREQUENCY +.. c:macro:: VIDIOC_G_FREQUENCY + +``int ioctl(int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp ) - :name: VIDIOC_S_FREQUENCY +.. c:macro:: VIDIOC_S_FREQUENCY +``int ioctl(int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency`. - Description =========== @@ -51,7 +51,6 @@ structure. When the requested frequency is not possible the driver assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a write-only ioctl, it does not return the actual new frequency. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_frequency @@ -89,7 +88,6 @@ write-only ioctl, it does not return the actual new frequency. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst index f4637bc464f6..eee9ce51c797 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_INPUT: @@ -11,27 +12,26 @@ Name VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_INPUT, int *argp ) - :name: VIDIOC_G_INPUT +.. c:macro:: VIDIOC_G_INPUT + +``int ioctl(int fd, VIDIOC_G_INPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_INPUT, int *argp ) - :name: VIDIOC_S_INPUT +.. c:macro:: VIDIOC_S_INPUT +``int ioctl(int fd, VIDIOC_S_INPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer an integer with input index. - Description =========== @@ -52,7 +52,6 @@ other parameters. Information about video inputs is available using the :ref:`VIDIOC_ENUMINPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst index 8721adc5ad70..93ed111dfcb9 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_JPEGCOMP: @@ -11,27 +12,26 @@ Name VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp ) - :name: VIDIOC_G_JPEGCOMP +.. c:macro:: VIDIOC_G_JPEGCOMP + +``int ioctl(int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp ) - :name: VIDIOC_S_JPEGCOMP +.. c:macro:: VIDIOC_S_JPEGCOMP +``int ioctl(int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_jpegcompression`. - Description =========== @@ -54,7 +54,6 @@ stored in the JPEG-encoded fields. These define how the JPEG field is encoded. If you omit them, applications assume you've used standard encoding. You usually do want to add them. - .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| .. c:type:: v4l2_jpegcompression @@ -92,7 +91,6 @@ encoding. You usually do want to add them. control is exposed by a driver applications should use it instead and ignore this field. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _jpeg-markers: @@ -118,7 +116,6 @@ encoding. You usually do want to add them. - (1<<7) - App segment, driver will always use APP0 - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst index baf499d0df74..2ac2473e341b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_MODULATOR: @@ -11,27 +12,26 @@ Name VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp ) - :name: VIDIOC_G_MODULATOR +.. c:macro:: VIDIOC_G_MODULATOR + +``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp ) - :name: VIDIOC_S_MODULATOR +.. c:macro:: VIDIOC_S_MODULATOR +``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_modulator`. - Description =========== @@ -60,7 +60,6 @@ context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| .. c:type:: v4l2_modulator @@ -121,7 +120,6 @@ To change the radio frequency the Drivers and applications must set the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _modulator-txsubchans: @@ -182,7 +180,6 @@ To change the radio frequency the - 0x0010 - Enable the RDS encoder for a radio FM transmitter. - 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 0afc55c67840..3138c4cc8fe3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_OUTPUT: @@ -11,27 +12,26 @@ Name VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_OUTPUT, int *argp ) - :name: VIDIOC_G_OUTPUT +.. c:macro:: VIDIOC_G_OUTPUT + +``int ioctl(int fd, VIDIOC_G_OUTPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_OUTPUT, int *argp ) - :name: VIDIOC_S_OUTPUT +.. c:macro:: VIDIOC_S_OUTPUT +``int ioctl(int fd, VIDIOC_S_OUTPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer with output index. - Description =========== @@ -53,7 +53,6 @@ negotiating any other parameters. Information about video outputs is available using the :ref:`VIDIOC_ENUMOUTPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 94f3af279bba..724f7fa7bae1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PARM: @@ -11,27 +12,26 @@ Name VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_G_PARM +.. c:macro:: VIDIOC_G_PARM + +``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_S_PARM +.. c:macro:: VIDIOC_S_PARM +``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_streamparm`. - Description =========== @@ -48,7 +48,7 @@ format, on the other hand, may change the frame interval. Further these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c:func:`read()` function. To get and set the streaming parameters applications call the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and @@ -56,7 +56,6 @@ To get and set the streaming parameters applications call the pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| .. c:type:: v4l2_streamparm @@ -89,7 +88,6 @@ union holding separate parameters for input and output devices. - - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_captureparm @@ -138,7 +136,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``readbuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`read() <func-read>` mode. + internally by the driver in :c:func:`read()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -149,7 +147,6 @@ union holding separate parameters for input and output devices. the array to zero. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_outputparm @@ -172,7 +169,7 @@ union holding separate parameters for input and output devices. * - :cspan:`2` The field is intended to repeat frames on the driver side in - :ref:`write() <func-write>` mode (in streaming mode timestamps + :c:func:`write()` mode (in streaming mode timestamps can be used to throttle the output), saving I/O bandwidth. For stateful encoders (see :ref:`encoder`) this represents the @@ -199,7 +196,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``writebuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`write() <func-write>` mode. Drivers + internally by the driver in :c:func:`write()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -210,7 +207,6 @@ union holding separate parameters for input and output devices. the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _parm-caps: @@ -226,7 +222,6 @@ union holding separate parameters for input and output devices. field. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _parm-flags: @@ -265,8 +260,7 @@ union holding separate parameters for input and output devices. - Moving objects in the image might have excessive motion blur. - - Capture might only work through the :ref:`read() <func-read>` call. - + - Capture might only work through the :c:func:`read()` call. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst index da3166ac6d08..d72a0c716fca 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PRIORITY: @@ -11,27 +12,26 @@ Name VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp ) - :name: VIDIOC_G_PRIORITY +.. c:macro:: VIDIOC_G_PRIORITY + +``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp ) - :name: VIDIOC_S_PRIORITY +.. c:macro:: VIDIOC_S_PRIORITY +``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an enum :c:type:`v4l2_priority` type. - Description =========== @@ -43,7 +43,6 @@ To request an access priority applications store the desired priority in an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to this variable. - .. c:type:: v4l2_priority .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| @@ -78,7 +77,6 @@ with a pointer to this variable. it blocks any other fd from changing device properties. Usually applications which must not be interrupted, like video recording. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst index cda7a69ea130..9a9e589cce77 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SELECTION: @@ -11,23 +12,22 @@ Name VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_G_SELECTION +.. c:macro:: VIDIOC_G_SELECTION +``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_S_SELECTION +.. c:macro:: VIDIOC_S_SELECTION +``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_selection`. @@ -115,7 +115,6 @@ constraints. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. _sel-const-adjust: .. kernel-figure:: constraints.svg @@ -128,7 +127,6 @@ Selection targets and flags are documented in - .. c:type:: v4l2_selection .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -168,7 +166,6 @@ Selection targets and flags are documented in Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst index a3a7fb00350f..752f7f5fae73 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SLICED_VBI_CAP: @@ -11,24 +12,22 @@ Name VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp ) - :name: VIDIOC_G_SLICED_VBI_CAP +.. c:macro:: VIDIOC_G_SLICED_VBI_CAP +``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_sliced_vbi_cap`. - Description =========== @@ -44,7 +43,6 @@ the sliced VBI API is unsupported or ``type`` is invalid. The ``type`` field was added, and the ioctl changed from read-only to write-read, in Linux 2.6.19. - .. c:type:: v4l2_sliced_vbi_cap .. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}| @@ -120,7 +118,6 @@ the sliced VBI API is unsupported or ``type`` is invalid. See also :ref:`vbi-525` and :ref:`vbi-625`. - .. raw:: latex \scriptsize @@ -183,7 +180,6 @@ the sliced VBI API is unsupported or ``type`` is invalid. \normalsize - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst index 8a659a873528..da91fe07d9e0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_STD: @@ -11,33 +12,34 @@ Name VIDIOC_G_STD - VIDIOC_S_STD - VIDIOC_SUBDEV_G_STD - VIDIOC_SUBDEV_S_STD - Query or select the video standard of the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_G_STD +.. c:macro:: VIDIOC_G_STD + +``int ioctl(int fd, VIDIOC_G_STD, v4l2_std_id *argp)`` + +.. c:macro:: VIDIOC_S_STD -.. c:function:: int ioctl( int fd, VIDIOC_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_S_STD +``int ioctl(int fd, VIDIOC_S_STD, const v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_G_STD +.. c:macro:: VIDIOC_SUBDEV_G_STD -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_S_STD +``int ioctl(int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp)`` +.. c:macro:: VIDIOC_SUBDEV_S_STD + +``int ioctl(int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst index e3ba5b18a357..116e66c01556 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_TUNER: @@ -11,27 +12,26 @@ Name VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp ) - :name: VIDIOC_G_TUNER +.. c:macro:: VIDIOC_G_TUNER + +``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp ) - :name: VIDIOC_S_TUNER +.. c:macro:: VIDIOC_S_TUNER +``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_tuner`. - Description =========== @@ -59,7 +59,6 @@ to zero. The term 'tuner' means SDR receiver in this context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}| .. c:type:: v4l2_tuner @@ -183,7 +182,6 @@ To change the radio frequency the Drivers and applications must set the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. c:type:: v4l2_tuner_type @@ -207,7 +205,6 @@ To change the radio frequency the - 5 - Tuner controls the RF part of a Software Digital Radio (SDR) - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _tuner-capability: @@ -299,7 +296,6 @@ To change the radio frequency the instead of 62.5 kHz. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _tuner-rxsubchans: @@ -338,7 +334,6 @@ To change the radio frequency the - The tuner receives an RDS channel. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _tuner-audmode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst index 74b06dc68109..c218747be762 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_LOG_STATUS: @@ -11,20 +12,18 @@ Name VIDIOC_LOG_STATUS - Log driver status information - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_LOG_STATUS) - :name: VIDIOC_LOG_STATUS +.. c:macro:: VIDIOC_LOG_STATUS +``int ioctl(int fd, VIDIOC_LOG_STATUS)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -40,7 +39,6 @@ Mismatches may give an indication where the problem is. This ioctl is optional and not all drivers support it. It was introduced in Linux 2.6.15. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst index 8553fc7a6d8b..f2efaaba24c0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_OVERLAY: @@ -11,24 +12,22 @@ Name VIDIOC_OVERLAY - Start or stop video overlay - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_OVERLAY, const int *argp ) - :name: VIDIOC_OVERLAY +.. c:macro:: VIDIOC_OVERLAY +``int ioctl(int fd, VIDIOC_OVERLAY, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. - Description =========== @@ -41,7 +40,6 @@ Drivers do not support :ref:`VIDIOC_STREAMON` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst index df003e5a65ac..45bb1eab2c2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_PREPARE_BUF: @@ -11,24 +12,22 @@ Name VIDIOC_PREPARE_BUF - Prepare a buffer for I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp ) - :name: VIDIOC_PREPARE_BUF +.. c:macro:: VIDIOC_PREPARE_BUF +``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -41,7 +40,6 @@ in advance saves time during the actual I/O. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst index cd920d0b6adf..fbf8c5962d8a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QBUF: @@ -11,27 +12,26 @@ Name VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QBUF +.. c:macro:: VIDIOC_QBUF + +``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_DQBUF +.. c:macro:: VIDIOC_DQBUF +``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -142,13 +142,12 @@ API is used the ``m.fd`` fields of the passed array of struct By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns +:c:func:`open()` function, ``VIDIOC_DQBUF`` returns immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst index 6942e7e76897..5afdc4b4dc2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERY_DV_TIMINGS: @@ -11,27 +12,26 @@ Name VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_QUERY_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -65,7 +65,6 @@ and returns ``ERANGE``. In that case the application can call found timings with the hardware's capabilities in order to give more precise feedback to the user. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst index 1d7ecf2697af..6c615e893866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYBUF: @@ -11,24 +12,22 @@ Name VIDIOC_QUERYBUF - Query the status of a buffer - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QUERYBUF +.. c:macro:: VIDIOC_QUERYBUF +``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -67,7 +66,6 @@ flags, they are meaningless in this context. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index 80b7b79561f5..b512b1fbf9a3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCAP: @@ -11,24 +12,22 @@ Name VIDIOC_QUERYCAP - Query device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp ) - :name: VIDIOC_QUERYCAP +.. c:macro:: VIDIOC_QUERYCAP +``int ioctl(int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_capability`. - Description =========== @@ -39,7 +38,6 @@ pointer to a struct :c:type:`v4l2_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an ``EINVAL`` error code. - .. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| .. c:type:: v4l2_capability @@ -132,7 +130,6 @@ specification the ioctl returns an ``EINVAL`` error code. zero. - .. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| .. _device-capabilities: @@ -243,8 +240,8 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`metadata` capture interface. * - ``V4L2_CAP_READWRITE`` - 0x01000000 - - The device supports the :ref:`read() <rw>` and/or - :ref:`write() <rw>` I/O methods. + - The device supports the :c:func:`read()` and/or + :c:func:`write()` I/O methods. * - ``V4L2_CAP_ASYNCIO`` - 0x02000000 - The device supports the :ref:`asynchronous <async>` I/O methods. @@ -269,7 +266,6 @@ specification the ioctl returns an ``EINVAL`` error code. only appear in the ``capabilities`` field and never in the ``device_caps`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 559ad849f7b9..9b8716f90f12 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCTRL: @@ -11,31 +12,29 @@ Name VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items - Synopsis ======== -.. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp ) - :name: VIDIOC_QUERYCTRL +``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)`` + +.. c:macro:: VIDIOC_QUERY_EXT_CTRL -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp ) - :name: VIDIOC_QUERY_EXT_CTRL +``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp ) - :name: VIDIOC_QUERYMENU +.. c:macro:: VIDIOC_QUERYMENU +``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` or :c:type:`v4l2_querymenu` (depending on the ioctl). - Description =========== @@ -95,7 +94,6 @@ inclusive. See also the examples in :ref:`control`. - .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| .. _v4l2-queryctrl: @@ -174,7 +172,6 @@ See also the examples in :ref:`control`. zero. - .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| .. _v4l2-query-ext-ctrl: @@ -275,7 +272,6 @@ See also the examples in :ref:`control`. the array to zero. - .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}| .. _v4l2-querymenu: @@ -311,7 +307,6 @@ See also the examples in :ref:`control`. zero. - .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| .. c:type:: v4l2_ctrl_type @@ -582,7 +577,6 @@ See also the examples in :ref:`control`. streaming is in progress since most drivers do not support changing the format in that case. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst index b043ec48cf9d..4a88287d8f61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYSTD: @@ -11,27 +12,26 @@ Name VIDIOC_QUERYSTD - VIDIOC_SUBDEV_QUERYSTD - Sense the video standard received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_QUERYSTD +.. c:macro:: VIDIOC_QUERYSTD + +``int ioctl(int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_QUERYSTD +.. c:macro:: VIDIOC_SUBDEV_QUERYSTD +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== @@ -58,7 +58,6 @@ or output. standard is valid they will have to stop streaming, set the new standard, allocate new buffers and start streaming again. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index afc35cd7b614..c1c88e00b106 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_REQBUFS: @@ -11,19 +12,18 @@ Name VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp ) - :name: VIDIOC_REQBUFS +.. c:macro:: VIDIOC_REQBUFS +``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_requestbuffers`. @@ -69,7 +69,6 @@ fds are closed. A ``count`` value of zero frees or orphans all buffers, after aborting or finishing any DMA in progress, an implicit :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. - .. c:type:: v4l2_requestbuffers .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -158,7 +157,6 @@ aborting or finishing any DMA in progress, an implicit :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst index fb09ea31cad7..1948f31c2dbc 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_S_HW_FREQ_SEEK: @@ -11,24 +12,22 @@ Name VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp ) - :name: VIDIOC_S_HW_FREQ_SEEK +.. c:macro:: VIDIOC_S_HW_FREQ_SEEK +``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_hw_freq_seek`. - Description =========== @@ -59,7 +58,6 @@ set. If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` error code is returned and no seek takes place. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_hw_freq_seek @@ -116,7 +114,6 @@ error code is returned and no seek takes place. - Reserved for future extensions. Applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst index d9623aa7c425..0bc86f06947b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_STREAMON: @@ -11,22 +12,22 @@ Name VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp ) - :name: VIDIOC_STREAMON +.. c:macro:: VIDIOC_STREAMON + +``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp ) - :name: VIDIOC_STREAMOFF +.. c:macro:: VIDIOC_STREAMOFF +``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. @@ -84,7 +85,6 @@ state as mentioned above. no notion of starting or stopping "now". Buffer timestamps can be used to synchronize with other events. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 932e8416f11c..17acf3fd8396 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: @@ -11,24 +12,22 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`. - Description =========== @@ -97,7 +96,6 @@ multiple pads of the same sub-device is not defined. - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index 3c480573df59..8016fba7023f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: @@ -11,24 +12,22 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`. - Description =========== @@ -62,7 +61,6 @@ current values of V4L2 controls. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about try formats. - .. c:type:: v4l2_subdev_frame_size_enum .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -103,7 +101,6 @@ information about try formats. - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 3b6a8044c391..1fd950e34a0b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_MBUS_CODE: @@ -11,24 +12,22 @@ Name VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_MBUS_CODE +.. c:macro:: VIDIOC_SUBDEV_ENUM_MBUS_CODE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_mbus_code_enum`. - Description =========== @@ -47,7 +46,6 @@ other pads of the sub-device, as well as on the current active links. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about the try formats. - .. c:type:: v4l2_subdev_mbus_code_enum .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index 45c988b13ba6..2d78b4f5928d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_CROP: @@ -11,27 +12,26 @@ Name VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_G_CROP +.. c:macro:: VIDIOC_SUBDEV_G_CROP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_S_CROP +.. c:macro:: VIDIOC_SUBDEV_S_CROP +``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_crop`. - Description =========== @@ -76,7 +76,6 @@ rectangle doesn't match the device capabilities. They must instead modify the rectangle to match what the hardware can provide. The modified format should be as close as possible to the original request. - .. c:type:: v4l2_subdev_crop .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -101,7 +100,6 @@ modified format should be as close as possible to the original request. - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 76ce46f53c76..90b9bbfb61dd 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FMT: @@ -11,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_G_FMT +.. c:macro:: VIDIOC_SUBDEV_G_FMT + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_S_FMT +.. c:macro:: VIDIOC_SUBDEV_S_FMT +``int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_format`. - Description =========== @@ -81,7 +81,6 @@ doesn't match the device capabilities. They must instead modify the format to match what the hardware can provide. The modified format should be as close as possible to the original request. - .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_subdev_format @@ -108,7 +107,6 @@ should be as close as possible to the original request. the array to zero. - .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _v4l2-subdev-format-whence: @@ -125,7 +123,6 @@ should be as close as possible to the original request. - 1 - Active formats, applied to the hardware. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index 7e0b177e70aa..3a50f8b2843d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FRAME_INTERVAL: @@ -11,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_G_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_S_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval`. - Description =========== @@ -74,7 +74,6 @@ Sub-devices that support the frame interval ioctls should implement them on a single pad only. Their behaviour when supported on multiple pads of the same sub-device is not defined. - .. c:type:: v4l2_subdev_frame_interval .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -95,7 +94,6 @@ the same sub-device is not defined. - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index 948903a34d6f..f35b9562df21 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_SELECTION: @@ -11,27 +12,26 @@ Name VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_G_SELECTION +.. c:macro:: VIDIOC_SUBDEV_G_SELECTION + +``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_S_SELECTION +.. c:macro:: VIDIOC_SUBDEV_S_SELECTION +``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_selection`. - Description =========== @@ -58,7 +58,6 @@ There are two types of selection targets: actual and bounds. The actual targets are the targets which configure the hardware. The BOUNDS target will return a rectangle that contain all possible actual rectangles. - Discovering supported features ------------------------------ @@ -69,7 +68,6 @@ return ``EINVAL``. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. c:type:: v4l2_subdev_selection .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -100,7 +98,6 @@ Selection targets and flags are documented in - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst index e806385ba176..949d9775b03d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_QUERYCAP: @@ -11,24 +12,22 @@ Name VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp ) - :name: VIDIOC_SUBDEV_QUERYCAP +.. c:macro:: VIDIOC_SUBDEV_QUERYCAP +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_capability`. - Description =========== diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst index 67827671bbaa..d1ad35164033 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBSCRIBE_EVENT: .. _VIDIOC_UNSUBSCRIBE_EVENT: @@ -12,34 +13,32 @@ Name VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_SUBSCRIBE_EVENT +.. c:macro:: VIDIOC_SUBSCRIBE_EVENT + +``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_UNSUBSCRIBE_EVENT +.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT +``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event_subscription`. - Description =========== Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by using the :ref:`VIDIOC_DQEVENT` ioctl. - .. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_event_subscription @@ -72,7 +71,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. the array to zero. - .. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}| .. _event-flags: @@ -107,7 +105,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. Think carefully when you set this flag so you won't get into situations like that. - Return Value ============ diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 1f26d83e6b16..e00a66d72372 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -4498,11 +4498,14 @@ Currently, the following list of CPUID leaves are returned: - HYPERV_CPUID_ENLIGHTMENT_INFO - HYPERV_CPUID_IMPLEMENT_LIMITS - HYPERV_CPUID_NESTED_FEATURES + - HYPERV_CPUID_SYNDBG_VENDOR_AND_MAX_FUNCTIONS + - HYPERV_CPUID_SYNDBG_INTERFACE + - HYPERV_CPUID_SYNDBG_PLATFORM_CAPABILITIES HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). -Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure +Userspace invokes KVM_GET_SUPPORTED_HV_CPUID by passing a kvm_cpuid2 structure with the 'nent' field indicating the number of entries in the variable-size array 'entries'. If the number of entries is too low to describe all Hyper-V feature leaves, an error (E2BIG) is returned. If the number is more or equal @@ -4704,6 +4707,106 @@ KVM_PV_VM_VERIFY Verify the integrity of the unpacked image. Only if this succeeds, KVM is allowed to start protected VCPUs. +4.126 KVM_X86_SET_MSR_FILTER +---------------------------- + +:Capability: KVM_X86_SET_MSR_FILTER +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_msr_filter +:Returns: 0 on success, < 0 on error + +:: + + struct kvm_msr_filter_range { + #define KVM_MSR_FILTER_READ (1 << 0) + #define KVM_MSR_FILTER_WRITE (1 << 1) + __u32 flags; + __u32 nmsrs; /* number of msrs in bitmap */ + __u32 base; /* MSR index the bitmap starts at */ + __u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */ + }; + + #define KVM_MSR_FILTER_MAX_RANGES 16 + struct kvm_msr_filter { + #define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0) + #define KVM_MSR_FILTER_DEFAULT_DENY (1 << 0) + __u32 flags; + struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES]; + }; + +flags values for ``struct kvm_msr_filter_range``: + +``KVM_MSR_FILTER_READ`` + + Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap + indicates that a read should immediately fail, while a 1 indicates that + a read for a particular MSR should be handled regardless of the default + filter action. + +``KVM_MSR_FILTER_WRITE`` + + Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap + indicates that a write should immediately fail, while a 1 indicates that + a write for a particular MSR should be handled regardless of the default + filter action. + +``KVM_MSR_FILTER_READ | KVM_MSR_FILTER_WRITE`` + + Filter both read and write accesses to MSRs using the given bitmap. A 0 + in the bitmap indicates that both reads and writes should immediately fail, + while a 1 indicates that reads and writes for a particular MSR are not + filtered by this range. + +flags values for ``struct kvm_msr_filter``: + +``KVM_MSR_FILTER_DEFAULT_ALLOW`` + + If no filter range matches an MSR index that is getting accessed, KVM will + fall back to allowing access to the MSR. + +``KVM_MSR_FILTER_DEFAULT_DENY`` + + If no filter range matches an MSR index that is getting accessed, KVM will + fall back to rejecting access to the MSR. In this mode, all MSRs that should + be processed by KVM need to explicitly be marked as allowed in the bitmaps. + +This ioctl allows user space to define up to 16 bitmaps of MSR ranges to +specify whether a certain MSR access should be explicitly filtered for or not. + +If this ioctl has never been invoked, MSR accesses are not guarded and the +default KVM in-kernel emulation behavior is fully preserved. + +Calling this ioctl with an empty set of ranges (all nmsrs == 0) disables MSR +filtering. In that mode, ``KVM_MSR_FILTER_DEFAULT_DENY`` is invalid and causes +an error. + +As soon as the filtering is in place, every MSR access is processed through +the filtering except for accesses to the x2APIC MSRs (from 0x800 to 0x8ff); +x2APIC MSRs are always allowed, independent of the ``default_allow`` setting, +and their behavior depends on the ``X2APIC_ENABLE`` bit of the APIC base +register. + +If a bit is within one of the defined ranges, read and write accesses are +guarded by the bitmap's value for the MSR index if the kind of access +is included in the ``struct kvm_msr_filter_range`` flags. If no range +cover this particular access, the behavior is determined by the flags +field in the kvm_msr_filter struct: ``KVM_MSR_FILTER_DEFAULT_ALLOW`` +and ``KVM_MSR_FILTER_DEFAULT_DENY``. + +Each bitmap range specifies a range of MSRs to potentially allow access on. +The range goes from MSR index [base .. base+nmsrs]. The flags field +indicates whether reads, writes or both reads and writes are filtered +by setting a 1 bit in the bitmap for the corresponding MSR index. + +If an MSR access is not permitted through the filtering, it generates a +#GP inside the guest. When combined with KVM_CAP_X86_USER_SPACE_MSR, that +allows user space to deflect and potentially handle various MSR accesses +into user space. + +If a vCPU is in running state while this ioctl is invoked, the vCPU may +experience inconsistent filtering behavior on MSR accesses. + 5. The kvm_run structure ======================== @@ -4869,14 +4972,13 @@ to the byte array. .. note:: - For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and - KVM_EXIT_EPR the corresponding - -operations are complete (and guest state is consistent) only after userspace -has re-entered the kernel with KVM_RUN. The kernel side will first finish -incomplete operations and then check for pending signals. Userspace -can re-enter the guest with an unmasked signal pending to complete -pending operations. + For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, + KVM_EXIT_EPR, KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding + operations are complete (and guest state is consistent) only after userspace + has re-entered the kernel with KVM_RUN. The kernel side will first finish + incomplete operations and then check for pending signals. Userspace + can re-enter the guest with an unmasked signal pending to complete + pending operations. :: @@ -5165,6 +5267,44 @@ if it decides to decode and emulate the instruction. :: + /* KVM_EXIT_X86_RDMSR / KVM_EXIT_X86_WRMSR */ + struct { + __u8 error; /* user -> kernel */ + __u8 pad[7]; + __u32 reason; /* kernel -> user */ + __u32 index; /* kernel -> user */ + __u64 data; /* kernel <-> user */ + } msr; + +Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is +enabled, MSR accesses to registers that would invoke a #GP by KVM kernel code +will instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR +exit for writes. + +The "reason" field specifies why the MSR trap occurred. User space will only +receive MSR exit traps when a particular reason was requested during through +ENABLE_CAP. Currently valid exit reasons are: + + KVM_MSR_EXIT_REASON_UNKNOWN - access to MSR that is unknown to KVM + KVM_MSR_EXIT_REASON_INVAL - access to invalid MSRs or reserved bits + KVM_MSR_EXIT_REASON_FILTER - access blocked by KVM_X86_SET_MSR_FILTER + +For KVM_EXIT_X86_RDMSR, the "index" field tells user space which MSR the guest +wants to read. To respond to this request with a successful read, user space +writes the respective data into the "data" field and must continue guest +execution to ensure the read data is transferred into guest register state. + +If the RDMSR request was unsuccessful, user space indicates that with a "1" in +the "error" field. This will inject a #GP into the guest when the VCPU is +executed again. + +For KVM_EXIT_X86_WRMSR, the "index" field tells user space which MSR the guest +wants to write. Once finished processing the event, user space must continue +vCPU execution. If the MSR write was unsuccessful, user space also sets the +"error" field to "1". + +:: + /* Fix the size of the union. */ char padding[256]; }; @@ -5852,6 +5992,28 @@ controlled by the kvm module parameter halt_poll_ns. This capability allows the maximum halt time to specified on a per-VM basis, effectively overriding the module parameter for the target VM. +7.21 KVM_CAP_X86_USER_SPACE_MSR +------------------------------- + +:Architectures: x86 +:Target: VM +:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report +:Returns: 0 on success; -1 on error + +This capability enables trapping of #GP invoking RDMSR and WRMSR instructions +into user space. + +When a guest requests to read or write an MSR, KVM may not implement all MSRs +that are relevant to a respective system. It also does not differentiate by +CPU type. + +To allow more fine grained control over MSR handling, user space may enable +this capability. With it enabled, MSR accesses that match the mask specified in +args[0] and trigger a #GP event inside the guest by KVM will instead trigger +KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications which user space +can then handle to implement model specific MSR handling and/or user notifications +to inform a user that an MSR was not handled. + 8. Other capabilities. ====================== @@ -6193,3 +6355,38 @@ distribution...) If this capability is available, then the CPNC and CPVC can be synchronized between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318). + +8.26 KVM_CAP_X86_USER_SPACE_MSR +------------------------------- + +:Architectures: x86 + +This capability indicates that KVM supports deflection of MSR reads and +writes to user space. It can be enabled on a VM level. If enabled, MSR +accesses that would usually trigger a #GP by KVM into the guest will +instead get bounced to user space through the KVM_EXIT_X86_RDMSR and +KVM_EXIT_X86_WRMSR exit notifications. + +8.27 KVM_X86_SET_MSR_FILTER +--------------------------- + +:Architectures: x86 + +This capability indicates that KVM supports that accesses to user defined MSRs +may be rejected. With this capability exposed, KVM exports new VM ioctl +KVM_X86_SET_MSR_FILTER which user space can call to specify bitmaps of MSR +ranges that KVM should reject access to. + +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.28 KVM_CAP_ENFORCE_PV_CPUID +----------------------------- + +Architectures: x86 + +When enabled, KVM will disable paravirtual features provided to the +guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf +(0x40000001). Otherwise, a guest may use the paravirtual features +regardless of what has actually been exposed through the CPUID leaf. diff --git a/Documentation/virt/kvm/cpuid.rst b/Documentation/virt/kvm/cpuid.rst index 9150e9d1c39b..cf62162d4be2 100644 --- a/Documentation/virt/kvm/cpuid.rst +++ b/Documentation/virt/kvm/cpuid.rst @@ -38,64 +38,68 @@ returns:: where ``flag`` is defined as below: -================================= =========== ================================ -flag value meaning -================================= =========== ================================ -KVM_FEATURE_CLOCKSOURCE 0 kvmclock available at msrs - 0x11 and 0x12 +================================== =========== ================================ +flag value meaning +================================== =========== ================================ +KVM_FEATURE_CLOCKSOURCE 0 kvmclock available at msrs + 0x11 and 0x12 -KVM_FEATURE_NOP_IO_DELAY 1 not necessary to perform delays - on PIO operations +KVM_FEATURE_NOP_IO_DELAY 1 not necessary to perform delays + on PIO operations -KVM_FEATURE_MMU_OP 2 deprecated +KVM_FEATURE_MMU_OP 2 deprecated -KVM_FEATURE_CLOCKSOURCE2 3 kvmclock available at msrs - 0x4b564d00 and 0x4b564d01 +KVM_FEATURE_CLOCKSOURCE2 3 kvmclock available at msrs + 0x4b564d00 and 0x4b564d01 -KVM_FEATURE_ASYNC_PF 4 async pf can be enabled by - writing to msr 0x4b564d02 +KVM_FEATURE_ASYNC_PF 4 async pf can be enabled by + writing to msr 0x4b564d02 -KVM_FEATURE_STEAL_TIME 5 steal time can be enabled by - writing to msr 0x4b564d03 +KVM_FEATURE_STEAL_TIME 5 steal time can be enabled by + writing to msr 0x4b564d03 -KVM_FEATURE_PV_EOI 6 paravirtualized end of interrupt - handler can be enabled by - writing to msr 0x4b564d04 +KVM_FEATURE_PV_EOI 6 paravirtualized end of interrupt + handler can be enabled by + writing to msr 0x4b564d04 -KVM_FEATURE_PV_UNHAULT 7 guest checks this feature bit - before enabling paravirtualized - spinlock support +KVM_FEATURE_PV_UNHALT 7 guest checks this feature bit + before enabling paravirtualized + spinlock support -KVM_FEATURE_PV_TLB_FLUSH 9 guest checks this feature bit - before enabling paravirtualized - tlb flush +KVM_FEATURE_PV_TLB_FLUSH 9 guest checks this feature bit + before enabling paravirtualized + tlb flush -KVM_FEATURE_ASYNC_PF_VMEXIT 10 paravirtualized async PF VM EXIT - can be enabled by setting bit 2 - when writing to msr 0x4b564d02 +KVM_FEATURE_ASYNC_PF_VMEXIT 10 paravirtualized async PF VM EXIT + can be enabled by setting bit 2 + when writing to msr 0x4b564d02 -KVM_FEATURE_PV_SEND_IPI 11 guest checks this feature bit - before enabling paravirtualized - sebd IPIs +KVM_FEATURE_PV_SEND_IPI 11 guest checks this feature bit + before enabling paravirtualized + send IPIs -KVM_FEATURE_POLL_CONTROL 12 host-side polling on HLT can - be disabled by writing - to msr 0x4b564d05. +KVM_FEATURE_POLL_CONTROL 12 host-side polling on HLT can + be disabled by writing + to msr 0x4b564d05. -KVM_FEATURE_PV_SCHED_YIELD 13 guest checks this feature bit - before using paravirtualized - sched yield. +KVM_FEATURE_PV_SCHED_YIELD 13 guest checks this feature bit + before using paravirtualized + sched yield. -KVM_FEATURE_ASYNC_PF_INT 14 guest checks this feature bit - before using the second async - pf control msr 0x4b564d06 and - async pf acknowledgment msr - 0x4b564d07. +KVM_FEATURE_ASYNC_PF_INT 14 guest checks this feature bit + before using the second async + pf control msr 0x4b564d06 and + async pf acknowledgment msr + 0x4b564d07. -KVM_FEATURE_CLOCSOURCE_STABLE_BIT 24 host will warn if no guest-side - per-cpu warps are expeced in - kvmclock -================================= =========== ================================ +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/devices/vcpu.rst b/Documentation/virt/kvm/devices/vcpu.rst index ca374d3fe085..2acec3b9ef65 100644 --- a/Documentation/virt/kvm/devices/vcpu.rst +++ b/Documentation/virt/kvm/devices/vcpu.rst @@ -25,8 +25,10 @@ Returns: ======= ======================================================== -EBUSY The PMU overflow interrupt is already set - -ENXIO The overflow interrupt not set when attempting to get it - -ENODEV PMUv3 not supported + -EFAULT Error reading interrupt number + -ENXIO PMUv3 not supported or the overflow interrupt not set + when attempting to get it + -ENODEV KVM_ARM_VCPU_PMU_V3 feature missing from VCPU -EINVAL Invalid PMU overflow interrupt number supplied or trying to set the IRQ number without using an in-kernel irqchip. @@ -45,9 +47,10 @@ all vcpus, while as an SPI it must be a separate number per vcpu. Returns: ======= ====================================================== + -EEXIST Interrupt number already used -ENODEV PMUv3 not supported or GIC not initialized - -ENXIO PMUv3 not properly configured or in-kernel irqchip not - configured as required prior to calling this attribute + -ENXIO PMUv3 not supported, missing VCPU feature or interrupt + number not set -EBUSY PMUv3 already initialized ======= ====================================================== @@ -55,6 +58,52 @@ Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel virtual GIC implementation, this must be done after initializing the in-kernel irqchip. +1.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER +----------------------------------------- + +:Parameters: in kvm_device_attr.addr the address for a PMU event filter is a + pointer to a struct kvm_pmu_event_filter + +:Returns: + + ======= ====================================================== + -ENODEV PMUv3 not supported or GIC not initialized + -ENXIO PMUv3 not properly configured or in-kernel irqchip not + configured as required prior to calling this attribute + -EBUSY PMUv3 already initialized + -EINVAL Invalid filter range + ======= ====================================================== + +Request the installation of a PMU event filter described as follows:: + + struct kvm_pmu_event_filter { + __u16 base_event; + __u16 nevents; + + #define KVM_PMU_EVENT_ALLOW 0 + #define KVM_PMU_EVENT_DENY 1 + + __u8 action; + __u8 pad[3]; + }; + +A filter range is defined as the range [@base_event, @base_event + @nevents), +together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The +first registered range defines the global policy (global ALLOW if the first +@action is DENY, global DENY if the first @action is ALLOW). Multiple ranges +can be programmed, and must fit within the event space defined by the PMU +architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards). + +Note: "Cancelling" a filter by registering the opposite action for the same +range doesn't change the default action. For example, installing an ALLOW +filter for event range [0:10) as the first filter and then applying a DENY +action for the same range will leave the whole range as disabled. + +Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn't count a +hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it +isn't strictly speaking an event. Filtering the cycle counter is possible +using event 0x11 (CPU_CYCLES). + 2. GROUP: KVM_ARM_VCPU_TIMER_CTRL ================================= diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index f70e6f5873c6..312e431695d9 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -679,6 +679,7 @@ Starting UML We can now run UML. :: + # linux mem=2048M umid=TEST \ ubd0=Filesystem.img \ vec0:transport=tap,ifname=tap0,depth=128,gro=1 \ diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index dd9f76a4ef29..09e28507f5b2 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -360,7 +360,7 @@ between device driver specific code and shared common code: system memory page, locks the page with ``lock_page()``, and fills in the ``dst`` array entry with:: - dst[i] = migrate_pfn(page_to_pfn(dpage)) | MIGRATE_PFN_LOCKED; + dst[i] = migrate_pfn(page_to_pfn(dpage)) | MIGRATE_PFN_LOCKED; Now that the driver knows that this page is being migrated, it can invalidate device private MMU mappings and copy device private memory diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst index d1b7270ad55c..9e37add068e6 100644 --- a/Documentation/vm/ksm.rst +++ b/Documentation/vm/ksm.rst @@ -26,7 +26,7 @@ tree. If a KSM page is shared between less than ``max_page_sharing`` VMAs, the node of the stable tree that represents such KSM page points to a -list of :c:type:`struct rmap_item` and the ``page->mapping`` of the +list of struct rmap_item and the ``page->mapping`` of the KSM page points to the stable tree node. When the sharing passes this threshold, KSM adds a second dimension to diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst index 769449734573..9daadf9faba1 100644 --- a/Documentation/vm/memory-model.rst +++ b/Documentation/vm/memory-model.rst @@ -24,7 +24,7 @@ whether it is possible to manually override that default. although it is still in use by several architectures. All the memory models track the status of physical page frames using -:c:type:`struct page` arranged in one or more arrays. +struct page arranged in one or more arrays. Regardless of the selected memory model, there exists one-to-one mapping between the physical page frame number (PFN) and the @@ -111,7 +111,7 @@ maps for non-volatile memory devices and deferred initialization of the memory map for larger systems. The SPARSEMEM model presents the physical memory as a collection of -sections. A section is represented with :c:type:`struct mem_section` +sections. A section is represented with struct mem_section that contains `section_mem_map` that is, logically, a pointer to an array of struct pages. However, it is stored with some other magic that aids the sections management. The section size and maximal number @@ -172,7 +172,7 @@ management. The virtually mapped memory map allows storing `struct page` objects for persistent memory devices in pre-allocated storage on those -devices. This storage is represented with :c:type:`struct vmem_altmap` +devices. This storage is represented with struct vmem_altmap that is eventually passed to vmemmap_populate() through a long chain of function calls. The vmemmap_populate() implementation may use the `vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to diff --git a/Documentation/vm/mmu_notifier.rst b/Documentation/vm/mmu_notifier.rst index 47baa1cf28c5..df5d7777fc6b 100644 --- a/Documentation/vm/mmu_notifier.rst +++ b/Documentation/vm/mmu_notifier.rst @@ -89,7 +89,7 @@ they are write protected for COW (other case of B apply too). So here because at time N+2 the clear page table entry was not pair with a notification to invalidate the secondary TLB, the device see the new value for -addrB before seing the new value for addrA. This break total memory ordering +addrB before seeing the new value for addrA. This break total memory ordering for the device. When changing a pte to write protect or to point to a new write protected page diff --git a/Documentation/vm/page_migration.rst b/Documentation/vm/page_migration.rst index 91a98a6b43bb..db9d7e5539cb 100644 --- a/Documentation/vm/page_migration.rst +++ b/Documentation/vm/page_migration.rst @@ -99,7 +99,7 @@ Steps: 2. Ensure that writeback is complete. 3. Lock the new page that we want to move to. It is locked so that accesses to - this (not yet uptodate) page immediately block while the move is in progress. + this (not yet up-to-date) page immediately block while the move is in progress. 4. All the page table references to the page are converted to migration entries. This decreases the mapcount of a page. If the resulting diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst index 079f3f8c4784..02deac76673f 100644 --- a/Documentation/vm/page_owner.rst +++ b/Documentation/vm/page_owner.rst @@ -18,7 +18,7 @@ Although we already have tracepoint for tracing page allocation/free, using it for analyzing who allocate each page is rather complex. We need to enlarge the trace buffer for preventing overlapping until userspace program launched. And, launched program continually dump out the trace -buffer for later analysis and it would change system behviour with more +buffer for later analysis and it would change system behaviour with more possibility rather than just keeping it in memory, so bad for debugging. page owner can also be used for various purposes. For example, accurate diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst index 289d231cee97..03f294a638bd 100644 --- a/Documentation/vm/slub.rst +++ b/Documentation/vm/slub.rst @@ -378,7 +378,7 @@ c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the can go unnoticed. To deal with that, ``slabinfo-gnuplot.sh`` has two options to 'zoom-in'/'zoom-out': - a) ``-s %d,%d`` -- overwrites the default image width and heigh + a) ``-s %d,%d`` -- overwrites the default image width and height b) ``-r %d,%d`` -- specifies a range of samples to use (for example, in ``slabinfo -X >> FOO_STATS; sleep 1;`` case, using a ``-r 40,60`` range will plot only samples collected between 40th and diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst index e5053404a1ae..ede1875719fb 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/x86/x86_64/mm.rst @@ -19,7 +19,7 @@ Complete virtual memory map with 4-level page tables Note that as we get closer to the top of the address space, the notation changes from TB to GB and then MB/KB. - - "16M TB" might look weird at first sight, but it's an easier to visualize size + - "16M TB" might look weird at first sight, but it's an easier way to visualize size notation than "16 EB", which few will recognize at first sight as 16 exabytes. It also shows it nicely how incredibly large 64-bit address space is. 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 |